Where Are Zod Schemas for Tool Arguments Defined in DesktopCommanderMCP?

All Zod schemas that validate tool arguments in DesktopCommanderMCP are centralized in src/tools/schemas.ts, which exports individual schemas and a unified toolArgSchemas map for runtime validation.

DesktopCommanderMCP is a Model Context Protocol server that exposes filesystem, terminal, and PDF manipulation tools to AI agents. Every tool call must be validated against strict type definitions to ensure safety and prevent malformed inputs. According to the source code, all Zod schemas for tool arguments are defined in a single location, making it easy to audit validation rules and extend the system with new capabilities.

Centralized Schema Definitions in src/tools/schemas.ts

The file [src/tools/schemas.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) serves as the single source of truth for argument validation. It imports the Zod library (import { z } from "zod") and declares a z.object() schema for every available tool.

Key characteristics of this file include:

• Functional grouping: Schemas are organized by domain, such as filesystem operations (ReadFileArgsSchema, WriteFileArgsSchema), terminal management (StartProcessArgsSchema, StopProcessArgsSchema), and PDF editing (EditPdfArgsSchema).
• Strict typing: Each schema precisely defines required fields, optional parameters, default values, and union types (e.g., mode: z.enum(["rewrite", "append"])).
• Reusable helpers: Lower-level schemas like PdfInsertOperationSchema and PdfDeleteOperationSchema are composed into higher-level argument definitions to maintain DRY principles.

The toolArgSchemas Map

Beyond individual exports, the file aggregates all schemas into a single record called toolArgSchemas. This map links tool names (such as "read_file" or "edit_block") to their corresponding Zod schemas, enabling the server to perform dynamic validation without hardcoding tool-specific logic.

Runtime Validation Examples

The following patterns demonstrate how to utilize these schemas when building or extending DesktopCommanderMCP functionality.

Direct Schema Validation

Import specific schemas to validate arguments before passing them to tool implementations:

import { ReadFileArgsSchema } from "./src/tools/schemas";

const rawInput = {
  path: "/home/user/document.txt",
  offset: 0,
  length: 1024
};

// Throws ZodError if validation fails; returns typed object on success
const validatedArgs = ReadFileArgsSchema.parse(rawInput);

Generic Validation via the Map

Use the centralized map to build a generic validation dispatcher that handles any registered tool:

import { toolArgSchemas } from "./src/tools/schemas";

function validateToolCall(toolName: string, payload: unknown) {
  const schema = toolArgSchemas[toolName];
  if (!schema) {
    throw new Error(`Unknown tool requested: ${toolName}`);
  }
  return schema.parse(payload);
}

// Validate a "write_file" call
const result = validateToolCall("write_file", {
  path: "/tmp/output.txt",
  content: "Validated content",
  mode: "rewrite"
});

Adding New Tool Schemas

When extending DesktopCommanderMCP with custom tools, you must register new schemas in src/tools/schemas.ts before they become available to the server dispatcher:

import { z } from "zod";

// 1. Define the argument structure
export const CompressDirectoryArgsSchema = z.object({
  sourcePath: z.string(),
  outputFormat: z.enum(["zip", "tar", "gz"]),
  compressionLevel: z.number().min(1).max(9).optional()
});

// 2. Register in the aggregated map
export const toolArgSchemas = {
  // ... existing schemas
  compress_directory: CompressDirectoryArgsSchema
};

Summary

• All tool argument validation lives in src/tools/schemas.ts, creating a single audit point for security review.
• Individual schemas like ReadFileArgsSchema use z.object() to enforce type safety on every incoming tool call.
• The toolArgSchemas map enables generic dispatch logic in the server without coupling validation to specific tool implementations.
• Helper schemas for complex operations (PDF insertions, filesystem patterns) are composed and reused across multiple tool definitions.

Frequently Asked Questions

Why are Zod schemas centralized in a single file rather than co-located with tool implementations?

Centralizing schemas in src/tools/schemas.ts creates a clear security boundary where all input validation rules are visible at a glance. This pattern prevents accidental type mismatches between the server dispatcher and tool handlers, and it simplifies auditing when adding new capabilities to the DesktopCommanderMCP server.

How does the server use the toolArgSchemas map during request processing?

When the MCP server receives a tool call, it looks up the tool name in toolArgSchemas and invokes .parse() on the incoming arguments. If validation passes, the typed object is passed to the tool's execution function; if it fails, a ZodError is returned to the client before any system-side effects occur.

Can I override validation behavior for existing tools without modifying the source?

While the source code requires modifying src/tools/schemas.ts to change validation rules, you can wrap tool implementations with additional runtime checks. However, for structural changes (adding new parameters or changing types), you must update the corresponding Zod schema in the centralized file and rebuild the server.

What Zod features are supported in these argument schemas?

The schemas utilize standard Zod primitives including z.string(), z.number(), z.boolean(), z.enum(), z.array(), and z.object(). They also leverage advanced features like .optional(), .default(), .min(), .max(), and union types (z.union()) to handle complex validation scenarios such as optional file offsets or constrained enumeration values.

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