Shortcut MCP Server

# MCP Proxy Architecture ## Overview The MCP proxy enables hot reloading of the Shortcut MCP server without losing the connection to Claude. This is achieved by creating an intermediate process that maintains the stdin/stdout pipes while the actual server can be restarted. ## Architecture ``` Claude <--> stdin/stdout <--> Proxy Process <--> Server Process | ├── Buffers messages during restart ├── Handles SIGHUP for reload └── Manages server lifecycle ``` ## Components ### 1. Proxy Process (`src/proxy.ts`) - Maintains persistent stdin/stdout connection with Claude - Spawns and manages the actual MCP server process - Buffers input/output during server restarts - Handles signals (SIGHUP for reload, SIGTERM/SIGINT for cleanup) - Rebuilds the project before restarting the server ### 2. Start Script (`start_mcp_with_proxy.sh`) - Sets up environment - Performs initial build - Compiles proxy if needed - Launches proxy process with exec (replaces shell process) ### 3. Reload Script (`reload_mcp.sh`) - Detects whether proxy or standard mode is running - Sends SIGHUP signal to trigger reload - Provides user feedback ## How It Works 1. **Initial Start**: - Claude launches `start_mcp_with_proxy.sh` - Script builds project and starts proxy - Proxy spawns actual server and connects pipes 2. **During Operation**: - Messages from Claude go through proxy to server - Server responses go through proxy to Claude - Proxy transparently forwards all communication 3. **Hot Reload**: - User runs `./reload_mcp.sh` - SIGHUP signal sent to proxy - Proxy: - Sets `isRestarting` flag - Buffers incoming messages from Claude - Kills current server process - Runs `pnpm run build` - Spawns new server process - Replays buffered messages - Resumes normal operation 4. **Benefits**: - No connection loss during reload - Messages aren't lost during restart - Automatic rebuild on reload - Seamless development experience ## Signal Handling - **SIGHUP**: Triggers hot reload - **SIGTERM/SIGINT**: Graceful shutdown - **Server crashes**: Automatic restart with 1s delay ## Debug Logging When `DEBUG=true`: - Proxy logs to `/tmp/shortcut-mcp-proxy.log` - Server logs to `/tmp/shortcut-mcp-debug.log` - Detailed message flow visible for troubleshooting