How Desktop Commander Uses the @modelcontextprotocol/sdk

Desktop Commander leverages the @modelcontextprotocol/sdk to implement a Model-Context Protocol server for exposing system tools and a client for remote device integration via STDIO transport.

Desktop Commander (wonderwhy-er/DesktopCommanderMCP) is an open-source implementation of the Model-Context Protocol (MCP) that enables AI assistants to execute file operations, manage processes, and perform system searches. The project builds its entire architecture on the @modelcontextprotocol/sdk package (version ^1.9.0 as specified in package.json) to handle protocol negotiation, JSON-RPC communication, and request validation. By utilizing both the server and client components provided by the SDK, Desktop Commander creates a complete bidirectional bridge between AI models and local desktop environments.

Server-Side Architecture Using @modelcontextprotocol/sdk

The core MCP server implementation resides in src/server.ts, where Desktop Commander instantiates a protocol-compliant server that advertises capabilities and handles tool invocations.

Creating the MCP Server Instance

The server initialization imports the Server class from @modelcontextprotocol/sdk/server/index.js and configures it with identity metadata and capability declarations.

// src/server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

export const server = new Server(
  { name: "desktop-commander", version: VERSION },
  { capabilities: { tools: {}, resources: {}, prompts: {}, logging: {} } }
);

The capabilities object informs connecting clients which feature sets are available—tools for file system operations, resources for data access, prompts for templating, and logging for telemetry. The server relies on the SDK to manage protocol version negotiation and JSON-schema conversion through utilities like zodToJsonSchema.

Registering Tool Handlers and Request Schemas

Desktop Commander registers specific handlers for each MCP request schema imported from @modelcontextprotocol/sdk/types.js. These handlers validate incoming requests and route them to internal implementations.

import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{ name: "read_file", description: "Read a file", /* ... */ }],
}));

Each handler receives protocol-compliant requests (such as CallToolRequestSchema for tool execution or ReadResourceRequestSchema for resource access) and returns standardized responses. The SDK manages request validation, ensuring that all communication follows the Model-Context Protocol specification.

Client Implementation for Remote Integration

For remote device scenarios, Desktop Commander implements an MCP client in src/remote-device/desktop-commander-integration.ts that communicates with the local server via STDIO transport.

STDIO Transport Configuration

The client utilizes StdioClientTransport from @modelcontextprotocol/sdk/client/stdio.js to spawn the local Desktop Commander CLI as a child process and establish a bidirectional byte stream.

// src/remote-device/desktop-commander-integration.ts
import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';

this.mcpTransport = new StdioClientTransport({
  ...config,
  env: { ...getDefaultEnvironment(), ...config.env, DC_REMOTE_DEVICE: 'true' },
});

The transport handles message framing, JSON parsing, and request-response correlation automatically. The getDefaultEnvironment function ensures proper environment variable inheritance while adding the DC_REMOTE_DEVICE flag to identify remote origins.

Client Connection and Tool Invocation

After establishing transport, the code creates a Client instance from @modelcontextprotocol/sdk/client/index.js and initiates the protocol handshake.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

this.mcpClient = new Client(
  { name: "desktop-commander-client", version: "1.0.0" },
  { capabilities: {} }
);
await this.mcpClient.connect(this.mcpTransport);

Once connected, the client can invoke callTool, listTools, and other MCP operations. The client wrapper adds metadata (_meta: { remote: true }) to each tool call, allowing the server to attribute actions to remote clients appropriately.

Complete Protocol Workflow

The end-to-end integration between the SDK's server and client components follows this sequence:

1. Server Startup: The local Desktop Commander server (src/server.ts) launches and begins listening on STDIO for incoming connections.
2. Client Initialization: A remote UI (such as a VS Code extension) loads the DesktopCommanderIntegration class, spawns the local CLI, and creates a StdioClientTransport.
3. Handshake: The Client connects via client.connect(transport), performing protocol version negotiation through the SDK's built-in mechanisms.
4. Tool Execution: When the UI requests a tool (e.g., read_file), it executes client.callTool({ name: "read_file", arguments: { path: "/etc/hosts" } }).
5. Server Processing: The server receives the request, validates it against CallToolRequestSchema, executes the internal file system operation, and returns a protocol-compliant response.
6. Result Delivery: The SDK transport decodes the response and resolves the original promise back to the remote UI.

This workflow demonstrates how @modelcontextprotocol/sdk handles all transport plumbing, request validation, and JSON-RPC message formatting, allowing Desktop Commander to focus on business logic.

Key SDK Components and File References

Component	SDK Path	Purpose in Desktop Commander
Server	@modelcontextprotocol/sdk/server/index.js	Creates the MCP server instance in src/server.ts
Client	@modelcontextprotocol/sdk/client/index.js	Implements remote device connectivity in src/remote-device/desktop-commander-integration.ts
STDIO Transport	@modelcontextprotocol/sdk/client/stdio.js	Provides StdioClientTransport and getDefaultEnvironment for process-based communication
Request Schemas	@modelcontextprotocol/sdk/types.js	Supplies validation schemas like ListToolsRequestSchema and CallToolRequestSchema

The test suite in test/test-conditional-tools.js additionally verifies remote tool behavior using the same Client and StdioClientTransport classes, ensuring protocol compliance across versions.

Summary

• Desktop Commander uses @modelcontextprotocol/sdk version ^1.9.0 to implement both MCP server and client functionality.
• The Server class in src/server.ts handles tool registration, capability advertisement, and request validation using SDK-provided schemas.
• The Client class with StdioClientTransport enables remote device integration by proxying tool calls from external UIs to the local server.
• The SDK manages all protocol-level concerns including JSON-RPC framing, version negotiation, and message validation, allowing the project to focus on file system and process management logic.

Frequently Asked Questions

What version of @modelcontextprotocol/sdk does Desktop Commander require?

Desktop Commander specifies "@modelcontextprotocol/sdk": "^1.9.0" in its package.json dependency list. This version provides the Server, Client, and StdioClientTransport classes along with the request schema types used throughout the codebase.

How does Desktop Commander handle transport layer communication?

The project uses StdioClientTransport from the SDK's client module to wrap the Desktop Commander CLI as a child process. This transport handles bidirectional byte streaming over standard input/output, managing message framing and JSON parsing automatically while the SDK correlates requests with responses.

Can the Desktop Commander server handle multiple simultaneous client connections?

While the SDK supports multiple transport types, Desktop Commander's current implementation in src/server.ts primarily operates via STDIO, which naturally supports one active client connection per process instance. For remote scenarios, each remote device spawns its own server process and client transport pair, as implemented in src/remote-device/desktop-commander-integration.ts.

What is the purpose of the DC_REMOTE_DEVICE environment variable?

The DC_REMOTE_DEVICE flag is injected into the environment via getDefaultEnvironment() when initializing StdioClientTransport. This metadata allows the server to identify incoming connections as originating from remote clients, enabling it to apply appropriate security policies or logging attribution for actions performed through the remote device integration layer.

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