# ttommyth/interactive-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ttommyth/interactive-mcp
- Repository: https://github.com/ttommyth/interactive-mcp

## Overview

##### Project type and purpose
- This is an **open-source Node.js/TypeScript CLI server** implementing the Model Context Protocol (MCP).
- Its purpose is to expose “tools” (user prompts, OS notifications, intensive CLI chats) to LLM clients (e.g., Claude Desktop, VS Code), running locally so it can call OS APIs and display interactive prompts.

##### File structure
- **Entry point**: `src/index.ts`
- **Tool definitions**: `src/tool-definitions/*.ts` (defines metadata for each MCP tool)
- **Command handlers**: `src/commands/{input,intensive-chat}/*` (implements the runtime logic for each tool)
- **UI layer**: `src/components` & `src/ui` (TSX-based interactive CLI components)
- **Utilities**: `src/utils/logger.ts`
- **Configuration & tooling**: `package.json`, CLI flags in `index.ts`, build/lint scripts.

##### Extract insights from the README
- The server registers five MCP tools:
- `request_user_input`
- `message_complete_notification`
- `start_intensive_chat`
- `ask_intensive_chat`
- `stop_intensive_chat`
- Runs locally alongside an MCP client over STDIN/STDOUT.
- Uses command-line flags (`--timeout`, `--disable-tools`) to configure behavior.

a. **MCP Client** (external):
- Examples: Claude Desktop, VS Code MCP extension
- Communicates over STDIN/STDOUT with the server
b. **interactive-mcp Server** (Node.js process):
1. **CLI Frontend**
– Parses arguments (timeout, disabled tools)
– Bootstraps the MCP server
2. **Tool Registry**
– Loads `tool-definitions`
– Registers handlers from `src/commands`
3. **Command Handlers**
– `request_user_input` → renders `InteractiveInput` UI, reads user input
– `message_complete_notification` → invokes OS notification API
– `start/ask/stop_intensive_chat` → manages a long-running CLI chat session
4. **UI Components**
– React-style TSX in `src/components` and `src/ui` to render interactive prompts in terminal (e.g., via Ink)
5. **Utilities & Logging**
– `src/utils/logger.ts` for structured logs
c. **Operating System** (host):
– Terminal I/O (stdin/stdout)
– Notification center (macOS/Linux/Windows)

##### Relationships and data flow
- **MCP Client → Server**: incoming MCP requests (JSON RPC or protocol messages)
- **Server → Tool Registry**: look up tool definition, select handler
- **Handler → UI Layer**: render prompt or chat UI, await user input
- **Handler → OS Notification API**: fire system notification
- **Handler → Handler (intensive chat)**: maintain stateful REPL session
- **Handler → Server → MCP Client**: return result payload to client

##### Architectural patterns & design principles
- **Plugin-style tool registry**: easy to add new tools by dropping a definition + handler
- **Separation of concerns**:
– Definitions (metadata) vs. Handlers (logic) vs. UI (presentation)
- **CLI/reactive UI**: TSX components decoupled from protocol logic
- **Stateless vs. stateful tools**: single prompts vs. persistent chat sessions

##### Detail
- Protocol channel (STDIN/STDOUT) as the transport layer between client and server.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Client
    MCPClient(["MCP Client"]):::external
    TerminalIO(["Terminal I/O\n(STDIN/STDOUT)"]):::os
    NotificationCenter(["Notification Center"]):::os

    %% Server Boundary
    subgraph "interactive-mcp Codebase" 
        direction TB
        CLIFrontend(["CLI Frontend"]):::module
        ToolRegistry(["Tool Registry"]):::module

        subgraph "Tool Definitions" 
            direction TB
            def_request_input(["request_user_input"]):::module
            def_message_notification(["message_complete_notification"]):::module
            def_intensive_chat(["intensive-chat"]):::module
            def_types(["types"]):::module
        end

        subgraph "Command Handlers"
            direction TB
            handler_request_input(["request_user_input Handler"]):::module
            handler_message_notification(["message_complete_notification Handler"]):::module
            handler_intensive_chat(["intensive-chat Handler"]):::module
            handler_input_ui(["Input UI Logic"]):::module
            handler_chat_ui(["Chat UI Logic"]):::module
        end

        subgraph "UI Components"
            direction TB
            comp_InteractiveInput(["InteractiveInput Component"]):::module
            comp_interactive_input_ui(["interactive-input UI"]):::module
        end

        subgraph "Utilities & Constants"
            direction TB
            Utils(["Logger"]):::module
            Constants(["Constants"]):::module
        end

        subgraph "Configuration & Tooling"
            direction TB
            pkg(["package.json"]):::config
            tsconfig(["tsconfig.json"]):::config
            eslintcfg(["eslint.config.js"]):::config
            prettier([".prettierrc"]):::config
            publish([".github/workflows/publish.yml"]):::config
        end
    end

    %% Flow
    MCPClient -->|requests| TerminalIO
    TerminalIO -->|transport| CLIFrontend
    CLIFrontend -->|bootstrap| ToolRegistry

    ToolRegistry --> def_request_input
    ToolRegistry --> def_message_notification
    ToolRegistry --> def_intensive_chat
    ToolRegistry --> def_types

    def_request_input --> handler_request_input
    def_message_notification --> handler_message_notification
    def_intensive_chat --> handler_intensive_chat

    handler_request_input --> handler_input_ui
    handler_request_input --> comp_InteractiveInput
    handler_input_ui --> comp_interactive_input_ui

    handler_message_notification --> NotificationCenter

    handler_intensive_chat --> handler_chat_ui
    handler_intensive_chat --> TerminalIO

    handler_request_input -->|response| TerminalIO
    handler_message_notification -->|response| TerminalIO
    handler_intensive_chat -->|response| TerminalIO
    TerminalIO -->|response| MCPClient

    CLIFrontend --> Utils
    CLIFrontend --> Constants

    CLIFrontend --> pkg
    CLIFrontend --> tsconfig
    CLIFrontend --> eslintcfg
    CLIFrontend --> prettier
    CLIFrontend --> publish

    %% Click events
    click CLIFrontend "https://github.com/ttommyth/interactive-mcp/blob/main/src/index.ts"
    click def_request_input "https://github.com/ttommyth/interactive-mcp/blob/main/src/tool-definitions/request-user-input.ts"
    click def_message_notification "https://github.com/ttommyth/interactive-mcp/blob/main/src/tool-definitions/message-complete-notification.ts"
    click def_intensive_chat "https://github.com/ttommyth/interactive-mcp/blob/main/src/tool-definitions/intensive-chat.ts"
    click def_types "https://github.com/ttommyth/interactive-mcp/blob/main/src/tool-definitions/types.ts"
    click handler_request_input "https://github.com/ttommyth/interactive-mcp/blob/main/src/commands/input/index.ts"
    click handler_input_ui "https://github.com/ttommyth/interactive-mcp/blob/main/src/commands/input/ui.tsx"
    click handler_intensive_chat "https://github.com/ttommyth/interactive-mcp/blob/main/src/commands/intensive-chat/index.ts"
    click handler_chat_ui "https://github.com/ttommyth/interactive-mcp/blob/main/src/commands/intensive-chat/ui.tsx"
    click comp_InteractiveInput "https://github.com/ttommyth/interactive-mcp/blob/main/src/components/InteractiveInput.tsx"
    click comp_interactive_input_ui "https://github.com/ttommyth/interactive-mcp/blob/main/src/ui/interactive-input.tsx"
    click Utils "https://github.com/ttommyth/interactive-mcp/blob/main/src/utils/logger.ts"
    click pkg "https://github.com/ttommyth/interactive-mcp/blob/main/package.json"
    click tsconfig "https://github.com/ttommyth/interactive-mcp/blob/main/tsconfig.json"
    click eslintcfg "https://github.com/ttommyth/interactive-mcp/blob/main/eslint.config.js"
    click prettier "https://github.com/ttommyth/interactive-mcp/blob/main/.prettierrc"
    click publish "https://github.com/ttommyth/interactive-mcp/blob/main/.github/workflows/publish.yml"
    click Constants "https://github.com/ttommyth/interactive-mcp/blob/main/src/constants.ts"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef os fill:#ff9,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
    classDef module fill:#9f9,stroke:#333,stroke-width:1px
    classDef config fill:#99f,stroke:#333,stroke-width:1px
```
