# Desktop Commander Configuration Schema: Understanding Config-Field-Definitions Structure

> Explore the Desktop Commander configuration schema and understand the structure of config-field-definitions. Learn how TypeScript ensures type safety for its robust configuration.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: api-reference
- Published: 2026-07-25

---

**Desktop Commander uses a TypeScript-centric configuration schema defined in [`src/config-field-definitions.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-field-definitions.ts) that enforces type safety through the `CONFIG_FIELD_DEFINITIONS` object, `CONFIG_FIELD_KEYS` array, and `isConfigFieldKey` type guard.**

Desktop Commander (wonderwhy-er/DesktopCommanderMCP) persists user preferences in a JSON file governed by a strict **configuration schema**. This schema is centralized in a single TypeScript module that leverages `as const` assertions to provide compile-time validation of configuration fields. By defining metadata for every editable setting—including value types, labels, and descriptions—the system ensures runtime consistency between [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) and the application logic.

## Central Configuration Schema Definition

The entire **configuration schema** lives in [`src/config-field-definitions.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-field-definitions.ts). This module exports three critical components that work together to define, enumerate, and validate configuration fields across the application.

### Core Type Definitions

The foundation of the schema rests on two type definitions that describe the shape of each configurable property:

```ts
export type ConfigFieldValueType = 'string' | 'number' | 'boolean' | 'array' | 'null';

export type ConfigFieldDefinition = {
  label: string;
  description: string;
  valueType: ConfigFieldValueType;
};

```

The `ConfigFieldValueType` union restricts values to specific JSON primitives, while `ConfigFieldDefinition` provides the metadata structure required for UI generation and validation.

### The CONFIG_FIELD_DEFINITIONS Object

The `CONFIG_FIELD_DEFINITIONS` constant serves as the single source of truth for all user-editable settings. Declared with `as const` and satisfying `Record<string, ConfigFieldDefinition>`, it maps each configuration key to its corresponding metadata:

- **blockedCommands**: Label "Blocked Commands", valueType `'array'` — Personal safety blocklist for commands the tool refuses to execute.
- **allowedDirectories**: Label "Allowed Folders", valueType `'array'` — Permitted filesystem paths; an empty array grants full access.
- **defaultShell**: Label "Default Shell", valueType `'string'` — Executable path for command sessions (e.g., `/bin/bash`).
- **telemetryEnabled**: Label "Anonymous Telemetry", valueType `'boolean'` — Toggle for usage data collection.
- **fileReadLineLimit**: Label "File Read Limit", valueType `'number'` — Maximum lines returned per read operation.
- **fileWriteLineLimit**: Label "File Write Limit", valueType `'number'` — Maximum lines written per edit operation.

Because the object uses `as const`, TypeScript infers each `valueType` as a literal string rather than the broad union, enabling exact type matching in consuming code.

### Runtime Type Safety Utilities

To safely iterate over configuration keys at runtime, the module exports `CONFIG_FIELD_KEYS`, derived via `Object.keys(CONFIG_FIELD_DEFINITIONS) as ConfigFieldKey[]`. This typed array contains all valid configuration keys as string literals.

For defensive programming, the `isConfigFieldKey(value)` type guard checks whether an arbitrary string exists within the schema. This prevents typos and injection of arbitrary properties when accessing the configuration object dynamically.

## Loading and Validating Configuration

When Desktop Commander initializes, the logic in [`src/tools/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/config.ts) reads [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) and validates each property against its declared `valueType` in `CONFIG_FIELD_DEFINITIONS`. The validation process ensures that:

1. Only keys passing the `isConfigFieldKey` check are processed.
2. Values conform to their expected JSON types (`string`, `number`, `boolean`, `array`, or `null`).
3. Missing keys receive sensible defaults defined in the configuration loader.

This architecture separates the schema definition from persistence, allowing the `config-field-definitions` module to remain a pure type declaration while [`src/tools/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/config.ts) handles I/O and validation.

## Working with Config-Field-Definitions in Code

Developers can leverage the **config-field-definitions** structure to build type-safe configuration interfaces or validation layers.

### Iterating Over Configuration Fields

To generate a dynamic settings UI or documentation:

```ts
import {
  CONFIG_FIELD_DEFINITIONS,
  CONFIG_FIELD_KEYS,
  isConfigFieldKey,
} from './config-field-definitions.js';

// Generate configuration form fields
for (const key of CONFIG_FIELD_KEYS) {
  const def = CONFIG_FIELD_DEFINITIONS[key];
  console.log(`${def.label} (${def.valueType}): ${def.description}`);
}

```

### Type-Safe Property Access

For strongly typed configuration retrieval with runtime validation:

```ts
function getConfigValue<T extends keyof typeof CONFIG_FIELD_DEFINITIONS>(
  config: Record<string, unknown>,
  key: T,
): typeof CONFIG_FIELD_DEFINITIONS[T]['valueType'] extends 'array' ? unknown[] : unknown {
  if (!isConfigFieldKey(key)) {
    throw new Error(`Unknown config key: ${key}`);
  }
  return config[key];
}

// Usage with inferred types
const cfg = JSON.parse(await Deno.readTextFile('config.json'));
const allowedDirs = getConfigValue(cfg, 'allowedDirectories'); // typed as unknown[]
const shell = getConfigValue(cfg, 'defaultShell'); // typed as unknown

```

## Summary

- The **configuration schema** is centralized in [`src/config-field-definitions.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-field-definitions.ts) and exports `CONFIG_FIELD_DEFINITIONS`, `CONFIG_FIELD_KEYS`, and `isConfigFieldKey`.
- Each field definition includes a `label`, `description`, and `valueType` restricted to `'string'`, `'number'`, `'boolean'`, `'array'`, or `'null'`.
- TypeScript's `as const` assertion ensures literal type inference for compile-time validation of configuration values.
- The `isConfigFieldKey` runtime guard prevents access to unknown properties, maintaining schema integrity.
- Six fields define the current schema: `blockedCommands`, `allowedDirectories`, `defaultShell`, `telemetryEnabled`, `fileReadLineLimit`, and `fileWriteLineLimit`.
- Configuration loading and validation occur in [`src/tools/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/config.ts), which reads from and writes to [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) in the project root.

## Frequently Asked Questions

### What file defines the configuration schema in Desktop Commander?

The **configuration schema** is defined in [`src/config-field-definitions.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-field-definitions.ts). This file exports the `CONFIG_FIELD_DEFINITIONS` object that contains metadata for every editable setting, along with the `CONFIG_FIELD_KEYS` array and `isConfigFieldKey` type guard for safe access.

### How does Desktop Commander validate configuration values at runtime?

The system validates values by checking each property against its declared `valueType` in `CONFIG_FIELD_DEFINITIONS`. The `isConfigFieldKey` type guard ensures only known keys are accessed, while [`src/tools/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/config.ts) enforces type constraints and assigns defaults for missing properties when loading [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json).

### What value types are supported in the config-field-definitions schema?

The schema supports five **value types**: `'string'`, `'number'`, `'boolean'`, `'array'`, and `'null'`. These are defined in the `ConfigFieldValueType` union and used to validate JSON values in the user configuration file.

### Can I extend the configuration schema with custom fields?

Yes, you can extend the schema by adding new entries to the `CONFIG_FIELD_DEFINITIONS` object in [`src/config-field-definitions.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-field-definitions.ts). Each new field requires a `ConfigFieldDefinition` with `label`, `description`, and `valueType`. The `as const` assertion and `isConfigFieldKey` guard will automatically include the new field in TypeScript checking and runtime validation.