# ferrislucas/iterm-mcp architecture

> Architecture diagram of the GitHub repository ferrislucas/iterm-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ferrislucas/iterm-mcp
- Repository: https://github.com/ferrislucas/iterm-mcp

## Overview

##### Project type and purpose
- iterm-mcp is a command-line–invoked MCP (Model Context Protocol) server written in TypeScript/Node.js.
- Its purpose is to expose an existing iTerm session to an external “model” by implementing three core tools over stdio:
- write_to_terminal
- read_terminal_output
- send_control_character

##### File structure
- Top-level:
- package.json, tsconfig.json, jest.config.cjs, LICENSE.md, README.md
- .github directory contains images and CI/GitHub configs
- src/ directory: the main TypeScript source files:
- index.ts (bootstraps the MCP stdio server, loads command handlers)
- CommandExecutor.ts (runs shell commands in the TTY)
- ProcessTracker.ts (tracks processes spawned by CommandExecutor)
- SendControlCharacter.ts (issues control keys to the terminal)
- TtyOutputReader.ts (reads output from the terminal)
- test/ directory:
- unit/ (unit tests for each module)
- e2e/ (end-to-end tests simulating real iTerm interactions)

##### README for additional insights
- Confirms that it’s purely a backend tool with no frontend UI.
- Describes its three “tools” as distinct logical services.
- Notes that it communicates solely over stdio following MCP conventions.

##### Main components and interactions
a. External MCP client (e.g., Claude Desktop)
b. Node.js + TypeScript runtime hosting the MCP server (index.ts)
c. Command Dispatcher (inside index.ts)
d. Module handlers:
– CommandExecutor (spawns shell commands in iTerm’s TTY)
– TtyOutputReader (captures output lines)
– SendControlCharacter (sends ctrl-c, ctrl-z, etc.)
– ProcessTracker (manages child processes’ lifecycle)
e. External dependency: iTerm2 application / the user’s terminal session

Flow of data:
1. MCP client → stdio JSON request → Node MCP server
2. Server routes the request to the appropriate handler module
3. Handler interacts with the iTerm TTY (via direct PTY or AppleScript)
4. TTY returns output or acknowledgement
5. Handler formats response → stdio JSON response → MCP client

##### Architectural patterns and design principles
- Single‐process, event-driven I/O model (Node.js)
- Command Handler pattern: each tool = one module
- Separation of concerns: dispatching, process management, I/O, control characters
- Minimal external dependencies: ease of distribution via npx

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External MCP Client
    MCPClient["MCP Client"]:::external

    %% Node.js Server Core
    subgraph "Node.js MCP Server"
        direction TB
        Dispatcher["Command Dispatcher"]:::internal
        CE["CommandExecutor"]:::internal
        TR["TtyOutputReader"]:::internal
        SC["SendControlCharacter"]:::internal
        PT["ProcessTracker"]:::internal
    end

    %% External iTerm2 / TTY
    iTerm["iTerm2 / TTY"]:::external

    %% Build / Deploy Flow
    subgraph "Build & Deploy"
        direction TB
        Config["package.json, tsconfig.json, jest.config.cjs, README.md"]:::config
        Build["yarn build"]:::internal
        JS["transpiled JS"]:::internal
        NPX["npx invocation"]:::internal
    end

    %% Test Suites
    subgraph "Tests"
        direction TB
        U1["CommandExecutor.test.ts"]:::test
        U2["ProcessTracker.test.ts"]:::test
        U3["SendControlCharacter.test.ts"]:::test
        E2E["CommandExecutor e2e test"]:::test
    end

    %% Data Flows
    MCPClient -->|"stdio JSON request"| Dispatcher
    Dispatcher -->|"write_to_terminal request"| CE
    Dispatcher -->|"read_terminal_output request"| TR
    Dispatcher -->|"send_control_character request"| SC
    CE -->|"spawn shell command"| PT
    CE -->|"PTY write"| iTerm
    SC -->|"control sequence"| iTerm
    TR -->|"PTY read (stdout lines)"| iTerm
    iTerm -->|"stdout lines"| TR
    CE -->|"command result"| Dispatcher
    TR -->|"output lines"| Dispatcher
    SC -->|"acknowledgement"| Dispatcher
    PT -->|"process events"| Dispatcher
    Dispatcher -->|"JSON response"| MCPClient

    %% Build & Deploy Flows
    Config --> Build --> JS --> NPX --> Dispatcher

    %% Tests Relationships
    U1 --> CE
    U2 --> PT
    U3 --> SC
    E2E --> CE

    %% Click Events
    click Dispatcher "https://github.com/ferrislucas/iterm-mcp/blob/main/src/index.ts"
    click CE "https://github.com/ferrislucas/iterm-mcp/blob/main/src/CommandExecutor.ts"
    click TR "https://github.com/ferrislucas/iterm-mcp/blob/main/src/TtyOutputReader.ts"
    click SC "https://github.com/ferrislucas/iterm-mcp/blob/main/src/SendControlCharacter.ts"
    click PT "https://github.com/ferrislucas/iterm-mcp/blob/main/src/ProcessTracker.ts"
    click U1 "https://github.com/ferrislucas/iterm-mcp/blob/main/test/unit/CommandExecutor.test.ts"
    click U2 "https://github.com/ferrislucas/iterm-mcp/blob/main/test/unit/ProcessTracker.test.ts"
    click U3 "https://github.com/ferrislucas/iterm-mcp/blob/main/test/unit/SendControlCharacter.test.ts"
    click E2E "https://github.com/ferrislucas/iterm-mcp/blob/main/test/e2e/CommandExecutor.test.ts"
    click Config "https://github.com/ferrislucas/iterm-mcp/blob/main/package.json"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#388E3C,stroke-width:1px,stroke-dasharray: 5 5
    classDef test fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px
    classDef config fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
```
