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

Desktop Commander uses a TypeScript-centric configuration schema defined in 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 and the application logic.

Central Configuration Schema Definition

The entire configuration schema lives in 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:

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 reads 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 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:

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:

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 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, which reads from and writes to 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. 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 enforces type constraints and assigns defaults for missing properties when loading 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}