Katamari MCP Server

# Katamari MCP Transport Layer Guide ## Overview Katamari MCP now supports multiple transport protocols for different use cases, following the recommendations from the analysis of MCP/ACP interaction patterns. ## Available Transports ### 1. SSE Transport (Server-Sent Events) - **Use Case**: Web-based clients, remote access, streaming updates - **Pros**: Native streaming, easy multiplexing, observable - **Cons**: Unidirectional (server→client), HTTP overhead - **Default Port**: 49152 - **Endpoints**: - `GET /mcp` - SSE stream - `POST /mcp` - Bidirectional communication - `GET /status` - Transport status ### 2. WebSocket Transport - **Use Case**: Real-time bidirectional ACP communication, multi-agent systems - **Pros**: Full duplex, multiplexable, persistent connections - **Cons**: More complex, heavier dependencies - **Default Port**: 49153 - **Requirements**: `websockets` package ## Configuration ### Transport Configuration (config.yaml) ```yaml transport: sse: enabled: true host: "localhost" port: 49152 websocket: enabled: false # Set to true to enable host: "localhost" port: 49153 ``` ### Environment Variables ```bash # Enable specific transports (stdio removed) KATAMARI_TRANSPORTS=sse,websocket # Configure ports KATAMARI_SSE_PORT=49152 KATAMARI_WS_PORT=49153 ``` ## Usage Examples ### Start with Default Transports (SSE only) ```bash python -m katamari_mcp.server ``` ### Start with Specific Transports ```bash # Start with SSE and WebSocket python -m katamari_mcp.server sse,websocket # ~~Start with stdio and SSE~~ (stdio removed) # ~~python -m katamari_mcp.server stdio,sse~~ # ~~Start with all transports~~ (stdio removed) # ~~python -m katamari_mcp.server stdio,sse,websocket~~ ``` ### Client Connection Examples #### ~~MCP Client (stdio)~~ ~~(REMOVED)~~ ~~```json { "mcpServers": { "katamari": { "command": "python", "args": ["-m", "katamari_mcp.server", "stdio"] } } } ```~~ **Note**: stdio transport has been removed. Use remote SSE/WebSocket connections instead. #### Web Client (SSE) ```javascript // Connect to SSE stream const eventSource = new EventSource('http://localhost:49152/mcp'); eventSource.onmessage = function(event) { const message = JSON.parse(event.data); console.log('Received:', message); }; // Send messages via POST fetch('http://localhost:49152/mcp', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ id: '123', method: 'tools/list', params: {} }) }); ``` #### WebSocket Client ```javascript const ws = new WebSocket('ws://localhost:49153'); ws.onopen = function() { console.log('Connected to Katamari MCP'); }; ws.onmessage = function(event) { const message = JSON.parse(event.data); console.log('Received:', message); }; // Send message ws.send(JSON.stringify({ id: '123', method: 'tools/call', params: { name: 'web_search', arguments: {query: 'test'} } })); ``` ## Transport Selection Guide | Use Case | Recommended Transport | Reason | |----------|---------------------|--------| | ~~Local CLI tools~~ | ~~stdio~~ | ~~Simplicity, low latency~~ | | ~~Claude Desktop~~ | ~~stdio~~ | ~~MCP compatibility~~ | | Web integration | SSE | HTTP compatibility, streaming | | Remote access | SSE | Works behind proxies | | Multi-agent systems | WebSocket | Bidirectional, persistent | | Real-time collaboration | WebSocket | Low latency, full duplex | | Development/debugging | SSE | Easy observability | **Note**: stdio transport has been removed. Local CLI tools and Claude Desktop now require remote connections. ## Session Management The transport manager includes session persistence: - **Session Creation**: Automatic on client connection - **Session Tracking**: Message count, last activity, client info - **Session Cleanup**: Automatic expiration (default 1 hour) - **Cross-Transport Sessions**: Sessions persist across transport types ## Security Considerations - ~~**Stdio**: Secure by isolation (no network exposure)~~ ~~(REMOVED)~~ - **SSE**: Configure CORS, authentication headers - **WebSocket**: Implement authentication, rate limiting - **All Transports**: Input validation via SecurityValidator ## Performance Characteristics | Transport | Latency | Throughput | Connections | Memory | Default Port | |-----------|---------|------------|-------------|--------|-------------| | ~~stdio~~ | ~~~1ms~~ | ~~High~~ | ~~1~~ | ~~Low~~ | ~~N/A~~ ~~(REMOVED)~~ | | SSE | ~5-10ms | Medium | Many | Medium | 49152 | | WebSocket | ~2-5ms | High | Many | Medium | 49153 | ## Troubleshooting ### Common Issues 1. **Port Already in Use** ```bash # Check what's using the port lsof -i :8080 # Change port in config KATAMARI_SSE_PORT=49154 python -m katamari_mcp.server ``` 2. **WebSocket Not Available** ```bash # Install websockets package pip install websockets ``` 3. **CORS Issues (SSE)** - Configure proper headers in reverse proxy - Use authentication middleware 4. **Connection Drops** - Check firewall settings - Verify transport configuration - Monitor logs for errors ### Debug Mode ```bash # Enable debug logging KATAMARI_LOG_LEVEL=DEBUG python -m katamari_mcp.server # Check transport status curl http://localhost:49152/status ``` ## Migration Guide ### ~~From stdio-only to Multi-Transport~~ ~~(HISTORICAL)~~ ~~1. **No Breaking Changes**: Existing stdio clients continue to work~~ ~~2. **Gradual Migration**: Enable additional transports as needed~~ ~~3. **Configuration**: Add transport settings to config file~~ ~~4. **Testing**: Test each transport independently~~ **Current Status**: stdio transport has been removed. Only SSE and WebSocket transports are available. ### Client Migration 1. **MCP Clients**: ~~No changes needed (stdio remains default)~~ ~~(REMOVED - stdio no longer supported)~~ 2. **Web Clients**: Migrate from direct API calls to SSE/WebSocket 3. **Custom Clients**: Use transport manager for connection handling ## Future Enhancements - **gRPC Transport**: For high-performance scenarios - **Message Queuing**: Redis/RabbitMQ integration - **Load Balancing**: Multi-instance support - **Service Discovery**: Dynamic transport registration - **Metrics**: Per-transport performance monitoring