How ttommyth/interactive-mcp works
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.