# Desktop Commander MCP Architecture: A Deep Dive into the 6-Layer TypeScript Platform

> Explore the Desktop Commander MCP architecture a 6-layer TypeScript platform. Understand its modular design using JSON RPC over WebSocket for efficient desktop automation.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: architecture
- Published: 2026-07-18

---

**Desktop Commander MCP architecture consists of six distinct layers—Server & Runtime, Core Managers, Handlers & Tools, UI, Plugin System, and Utilities—wired together via JSON-RPC over WebSocket to provide a modular desktop automation platform.**

Desktop Commander MCP, developed by wonderwhy-er, is a powerful desktop automation platform built in TypeScript. The architecture follows a clean separation of concerns between backend services, frontend interfaces, and extensible plugin capabilities, enabling developers to orchestrate terminals, file systems, and custom commands through a unified interface.

## Six-Layer Architecture Overview

The source code in `wonderwhy-er/DesktopCommanderMCP` organizes functionality into six explicit layers, each with distinct responsibilities and well-defined APIs.

### Server & Runtime Layer

The foundation of Desktop Commander MCP architecture starts with the runtime environment. The **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)** file creates an Express server that hosts the JSON-RPC API and attaches the WebSocket endpoint used for real-time communication. **[`src/bootstrap.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/bootstrap.ts)** serves as the application entry point that bootstraps the runtime, loads user configuration, and instantiates the core managers before launching the server process.

### Core Managers Layer

Three primary managers orchestrate system resources and provide clean APIs for upper layers. **[`src/command-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/command-manager.ts)** parses incoming user commands and dispatches them to appropriate handlers, while **[`src/terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts)** spawns and tracks PTY (pseudo-terminal) shells using `node-pty`, handling all I/O streaming. **[`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts)** manages the lifecycle of the user's [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json), including validation and file watching for hot-reloading.

### Handlers & Tools Layer

This layer implements concrete functionality exposed through the RPC interface. Terminal operations bridge through **[`src/handlers/terminal-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts)**, while search capabilities reside in **[`src/handlers/search-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/search-handlers.ts)** providing fast ripgrep-based code search. Low-level utilities include **[`src/tools/fuzzySearch.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/fuzzySearch.ts)** and **[`src/tools/fuzzySearchCore.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/fuzzySearchCore.ts)** for fuzzy-matching algorithms, **`src/tools/pdf/*`** for PDF-to-Markdown conversion, and **[`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts)** for high-level file system abstractions.

### UI Layer

The frontend consists of a React-based application rendered in a Chromium window that consumes the RPC API. Components in **`src/ui/file-preview/*`** render Markdown, images, PDFs, and directory trees, while **`src/ui/config-editor/*`** provides the configuration editing interface. Shared widgets live in **`src/ui/shared/*`**, including the tool-shell and event-tracker components.

### Plugin System

Extensions integrate through a declarative manifest system. The **[`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml)** file declares plugin capabilities, entry points, and metadata, allowing runtime loading of new commands or UI panels. **[`src/custom-stdio.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/custom-stdio.ts)** provides hooks for plugins to replace standard input/output streams, enabling deep integration with the terminal management system.

### Utility & Support

Cross-cutting concerns reside in **`src/utils/*`**, including [`logger.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/logger.ts) for structured logging, [`withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/withTimeout.ts) for timeout handling, and [`ab-test.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/ab-test.ts) for A/B testing functionality. These utilities support all other layers without introducing circular dependencies.

## Component Interaction Flow

Understanding how these layers interact clarifies the Desktop Commander MCP architecture execution model.

1. **Initialization**: **[`src/bootstrap.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/bootstrap.ts)** reads [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json), instantiates **CommandManager**, **TerminalManager**, and **ConfigManager**, then launches the server defined in **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)**.

2. **Connection**: The server opens a WebSocket that the React UI connects to. All UI actions transmit as JSON-RPC messages across this socket.

3. **Terminal Spawning**: When the UI requests a terminal, **TerminalManager** spawns a PTY process, registers it with the internal ToolBridge, and streams I/O back over the WebSocket via **[`src/handlers/terminal-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts)**.

4. **Command Execution**: Commands entered in the UI route through **CommandManager** to the appropriate handler (e.g., **[`src/handlers/search-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/search-handlers.ts)** for ripgrep searches). Handlers invoke low-level tools like fuzzy search or PDF extraction, then return structured results to the UI.

5. **Plugin Integration**: Plugins defined in [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) load via **[`src/custom-stdio.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/custom-stdio.ts)**, registering new handlers with the core managers and potentially injecting UI panels into the React frontend.

## Practical Implementation Examples

### Bootstrapping the Application

Start the platform from the command line to observe the layer initialization sequence:

```bash

# Install dependencies (once)

npm ci

# Run the main entry point

npm start   # executes src/index.ts → bootstrap → server

```

Behind the scenes, [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) imports `bootstrap()` which creates the Server, initializes all three core managers, and opens the WebSocket endpoint before loading the UI window.

### Executing a Fuzzy Search

Plugins and internal components leverage the tool layer directly for file discovery:

```typescript
import { fuzzySearch } from '../tools/fuzzySearch';

// Example: find files/folders that match "config"
const results = await fuzzySearch('config', {
  cwd: process.cwd(),
  maxResults: 20,
});

console.log(results);

```

The implementation in **[`src/tools/fuzzySearch.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/fuzzySearch.ts)** delegates matching logic to **[`src/tools/fuzzySearchCore.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/fuzzySearchCore.ts)**, which runs the core algorithm against the file system.

### Spawning a Terminal Session

The UI communicates with the backend through the JSON-RPC layer managed by **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)**:

```typescript
// From the UI (React) – send a JSON-RPC request
window.api.invoke('terminal.spawn', { shell: '/bin/bash' })
  .then((sessionId) => {
    // Attach UI component to the new session
    terminalComponent.attach(sessionId);
  });

```

This request routes through **[`src/handlers/terminal-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts)**, which calls `TerminalManager.spawn()` to create the PTY session and return the unique session identifier.

## Summary

- Desktop Commander MCP architecture implements a **six-layer separation** between runtime, managers, tools, UI, plugins, and utilities.
- Communication flows through **JSON-RPC over WebSocket**, with **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)** managing the transport layer.
- **Core managers** in [`src/command-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/command-manager.ts), [`src/terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts), and [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) centralize business logic.
- The **plugin system** uses [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) and **[`src/custom-stdio.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/custom-stdio.ts)** to enable runtime extensibility without core modifications.
- **Handlers and tools** provide concrete functionality ranging from ripgrep search to PDF conversion, all exposed through the manager APIs.

## Frequently Asked Questions

### What communication protocol connects the UI to the backend in Desktop Commander MCP?

The architecture uses **JSON-RPC over WebSocket** for all UI-to-backend communication. The server implementation in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) creates the WebSocket endpoint, while the React UI sends RPC messages to invoke methods on [`src/command-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/command-manager.ts) and other handlers. This design enables real-time bidirectional streaming required for terminal I/O and file previews.

### How does the plugin system extend Desktop Commander MCP functionality?

Plugins extend the platform through a **declarative manifest** ([`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml)) that declares capabilities and entry points. The runtime loads these via [`src/custom-stdio.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/custom-stdio.ts), which provides hooks for replacing standard I/O streams and registering new command handlers with the **CommandManager**. This allows third-party extensions to add terminal commands, UI panels, or custom search providers without modifying core source files.

### What manages terminal sessions in the Desktop Commander MCP architecture?

**[`src/terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts)** orchestrates all terminal sessions using `node-pty` to spawn PTY processes. It maintains session state, handles process lifecycle management, and streams I/O between the shell and the UI through the WebSocket layer. When the UI requests a new terminal via [`src/handlers/terminal-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts), the TerminalManager creates the session and returns a unique identifier for subsequent operations.

### Where is configuration handled in the Desktop Commander MCP codebase?

Configuration management is centralized in **[`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts)**, which loads, validates, and watches the user's [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) file. It provides hot-reloading capabilities so changes to configuration reflect immediately without restarting the application. The manager exposes a typed API used by both core services and plugins to access user preferences and system settings.