How Desktop Commander MCP Server Detects Unsupported Parameters and Generates Warnings

Desktop Commander MCP server uses AJV schema validation with removeAdditional: "all" to strip unknown tool arguments, then prepends a structured warning block to the response that names both the ignored parameters and supported alternatives.

The Desktop Commander MCP server handles tool calls like read_file by first validating incoming arguments against strict JSON schemas. When callers supply parameters not defined in a tool's schema—such as view_range for read_file—the server detects these unsupported parameters, removes them, and returns a helpful warning without failing the request. This article explains the detection mechanism, warning construction, and response format based on the source code implementation.

---

Detecting Unsupported Parameters with AJV Schema Validation

The server validates every tool call through a centralized validation layer in src/dispatcher.ts. This module uses the AJV (Another JSON Schema Validator) library with aggressive additional-properties handling.

AJV Configuration for Parameter Stripping

The validator is configured with removeAdditional: "all":

// src/dispatcher.ts
import Ajv from "ajv";

const ajv = new Ajv({ 
  removeAdditional: "all",  // Strip any property not in schema
  allErrors: true           // Collect all validation errors
});

This configuration ensures that extra parameters are automatically removed from the arguments object rather than causing validation failures.

Identifying Stripped Properties

After validation, the server examines AJV's error collection to find which properties were removed:

// src/dispatcher.ts (validation logic)
export function validateToolArgs(toolName: string, args: any) {
  const schema = toolSchemas[toolName];
  const validate = ajv.compile(schema);
  const ok = validate(args);

  // Filter for additionalProperties errors to find stripped params
  const stripped = (validate.errors || [])
    .filter(e => e.keyword === "additionalProperties")
    .map(e => e.params.additionalProperty);

  // ... warning generation if stripped.length > 0
}

The additionalProperties keyword indicates a property that existed in the input but not in the schema. By collecting these, the server builds a complete list of unsupported parameters the caller attempted to use.

---

Generating and Structuring Warning Content

When stripped parameters are detected, the server constructs a warning content block that becomes the first element of the response.

Warning Block Construction

// src/dispatcher.ts (warning generation)
if (stripped.length) {
  const supportedParams = Object.keys(schema.properties).join(", ");
  
  const warning = {
    type: "warning",
    text: `The following parameters are not supported: ${stripped.join(", ")}. ` +
          `Supported parameters are: ${supportedParams}.`
  };
  
  return { stripped, warning };
}

The warning includes:

• Named unsupported parameters—the exact keys that were stripped
• Complete list of supported parameters—drawn from schema.properties keys

Response Structure with Warning

The warning is prepended to the normal tool response:

{
  "content": [
    {
      "type": "warning",
      "text": "The following parameters are not supported: view_range, foo_bar. Supported parameters are: path, offset, length."
    },
    {
      "type": "text",
      "text": "actual file content here..."
    }
  ],
  "isError": false
}

Critical behavior: isError remains false—the request succeeds because valid parameters were processed, with the warning serving as informational feedback.

---

Integration Test Verification

The warning behavior is explicitly verified in test/integration/read-file-unknown-params.js. This test demonstrates the complete detection and warning flow:

// test/integration/read-file-unknown-params.js
const response = await client.callTool({
  name: "read_file",
  arguments: {
    path: "/tmp/example.txt",
    view_range: [5, 10],   // unsupported parameter
    foo_bar: true          // unsupported parameter
  }
});

// Assert: request does not fail
assert.ok(!response.isError, 'unsupported params should NOT cause isError');

// Assert: warning appears as first content block
const firstBlock = response.content[0].text;
assert.ok(/not supported|ignored/i.test(firstBlock),
  'first content block should be the unsupported-params warning');

// Assert: warning names the ignored parameters
assert.ok(/view_range/.test(firstBlock) && /foo_bar/.test(firstBlock),
  'warning should name the ignored params');

// Assert: warning lists supported parameters
assert.ok(/path/.test(firstBlock) && /offset/.test(firstBlock) && /length/.test(firstBlock),
  'warning should list the supported params');

These assertions confirm that:

• Detection happens before tool execution
• Warning content is structured and complete
• Original tool functionality remains intact

---

Schema Sources and Tool Definitions

Tool schemas defining valid parameters are sourced from plugin.yaml and plugin.json. For read_file, the schema specifies only path, offset, and length as valid properties, making any additional parameter trigger the warning mechanism.

The dispatcher references these schemas through toolSchemas[toolName], enabling consistent validation across all server tools without duplicating schema definitions.

---

Summary

• Detection mechanism: AJV with removeAdditional: "all" strips unknown properties and reports them via additionalProperties errors
• Warning construction: Server builds a structured warning naming both ignored and supported parameters
• Response handling: Warning prepended as first content block; isError remains false; tool executes normally
• Key source files: src/dispatcher.ts (validation), test/integration/read-file-unknown-params.js (verification), plugin.yaml/plugin.json (schema definitions)

---

Frequently Asked Questions

What happens if I send an unsupported parameter to a Desktop Commander MCP tool?

The server removes the unsupported parameter, processes your request with valid parameters, and returns a warning as the first content block explaining which parameters were ignored and which are supported. The request succeeds with isError: false.

Where does the parameter validation logic live in the source code?

The core validation logic resides in src/dispatcher.ts, specifically in the validateToolArgs function. This function uses AJV to compile tool schemas and detect additional properties that need removal.

Does the server reject requests with unsupported parameters?

No—the server does not reject these requests. It follows a "lenient validation" pattern where unknown parameters are stripped and reported via warning, allowing backward compatibility and graceful degradation when schemas evolve.

How can I see which parameters a tool supports?

Either consult the tool schema in plugin.yaml or trigger a warning intentionally by sending a dummy unsupported parameter. The warning response will list all supported parameter names.

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