DesktopCommanderMCP

Executes long-running terminal commands through a FilteredStdioServerTransport that intercepts and buffers stdout/stderr to prevent non-JSON data from corrupting the MCP protocol stream. The transport layer filters output in real-time, ensuring only valid JSON messages reach Claude Desktop while capturing command output separately for streaming back to the AI model. Supports interactive sessions with output pagination and persistent background task management.

Performs targeted text replacements using fuzzy matching algorithms to locate and replace specific code blocks or text sections without requiring exact string matches. The system identifies target text by semantic proximity rather than character-perfect matching, enabling Claude to make precise edits even when whitespace, formatting, or minor variations differ. Supports multi-line replacements and integrates with the text editing toolset for surgical code modifications.

Automatically detects the host operating system and shell environment, abstracting platform-specific differences to provide a unified interface for terminal commands. The system identifies available shells (bash, zsh, PowerShell, cmd.exe) and adapts command execution accordingly, handling path separators, environment variable syntax, and shell-specific features transparently.

Lists and traverses directory structures recursively with configurable depth limits to prevent context window exhaustion when exploring large codebases. The implementation includes automatic safeguards that truncate or paginate results when directory listings exceed token budgets, protecting the MCP connection from being overwhelmed. Supports filtering by file type and provides metadata (size, modification time) for each entry.

Parses and extracts content from specialized document formats (.xlsx, .pdf, .docx) using native libraries (exceljs, pdf-lib, docx) rather than treating them as opaque binary files. Enables Claude to read spreadsheet data, extract text from PDFs, and access Word document structure directly, making these formats accessible for analysis and modification through the MCP interface.

Leverages @vscode/ripgrep for fast, regex-capable recursive content search across directories, providing Claude with the ability to find code patterns, text matches, and file contents at scale. The implementation uses ripgrep's native performance optimizations (parallel scanning, gitignore awareness) to deliver search results orders of magnitude faster than naive string matching, with support for complex regex patterns and file type filtering.

Implements a specialized FilteredStdioServerTransport that wraps the standard MCP stdio transport to intercept, filter, and buffer all messages flowing between the MCP server and Claude Desktop. The transport ensures only valid JSON-RPC messages reach the client while capturing non-JSON output (logs, debug prints, command output) in a deferred message buffer that gets flushed once the connection is fully initialized. This prevents common failure modes where terminal output or logging corrupts the MCP protocol stream.

Provides a separate remote-device module that bridges local Desktop Commander tools to web-based AI services, enabling Claude to control local machines from cloud-hosted environments. The bridge establishes a secure connection between the local MCP server and remote AI services, forwarding tool requests and responses while maintaining protocol compliance across the network boundary.

Implements a deferredMessages buffer that captures logs and output generated during the MCP server's early initialization phase before the client connection is fully established. Once the connection handshake completes, buffered messages are flushed to the client, ensuring no diagnostic information is lost during startup. This pattern prevents logs from being silently dropped or corrupting the protocol stream during the critical initialization window.

Provides a capture utility that instruments tool execution to track usage patterns, measure performance, and log errors. The utility wraps tool handlers to record metadata about each invocation (duration, success/failure, parameters) and forwards this telemetry to monitoring systems. Enables observability into which tools Claude uses most frequently and where failures occur.

Manages persistent interactive terminal sessions where Claude can execute multiple commands in sequence while maintaining shell state (environment variables, working directory, command history). Output pagination automatically chunks large command outputs to prevent context overflow, with support for retrieving additional pages on demand. The session manager handles TTY-like behavior within the constraints of the stdio transport.