XHS MCP

# HTTP Transports Support XHS MCP Server now supports both SSE (Server-Sent Events) and Streamable HTTP transports, in addition to the traditional stdio transport. ## Transport Options ### 1. Streamable HTTP (Recommended) - **Protocol Version**: 2025-03-26 - **Endpoint**: `/mcp` - **Methods**: GET, POST, DELETE - **Features**: - Unified endpoint for all operations - Session management with resumability - On-demand streaming - Stateless server support ### 2. HTTP + SSE (Legacy) - **Protocol Version**: 2024-11-05 - **Endpoints**: - `/sse` (GET) - Establish SSE stream - `/messages` (POST) - Send messages - **Features**: - Traditional SSE implementation - Backward compatibility ### 3. Stdio (Default) - **Protocol**: Standard MCP stdio transport - **Usage**: Direct process communication - **Features**: - Zero configuration - Process-based communication ## Usage ### Starting the HTTP Server ```bash # Start HTTP server on default port 3000 npm run start:http # Start HTTP server on custom port npm run start:http -- --port 8080 # Development mode with HTTP server npm run dev:http # Development mode with custom port npm run dev:http -- --port 8080 ``` ### Command Line Options ```bash # Show help node dist/index.js --help # Start in stdio mode (default) node dist/index.js --mode stdio # Start in HTTP mode node dist/index.js --mode http --port 3000 ``` ## API Endpoints ### Health Check ``` GET /health ``` Returns server status and supported transports. **Response:** ```json { "status": "healthy", "server": "xhs-mcp", "version": "0.2.10", "transports": ["streamable-http", "sse"] } ``` ### Streamable HTTP Transport #### Initialize Session ``` POST /mcp Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": { "name": "client-name", "version": "1.0.0" } } } ``` **Response Headers:** ``` Mcp-Session-Id: <session-id> ``` #### Send Requests ``` POST /mcp Content-Type: application/json Mcp-Session-Id: <session-id> { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } ``` #### Establish SSE Stream ``` GET /mcp Mcp-Session-Id: <session-id> ``` #### Terminate Session ``` DELETE /mcp Mcp-Session-Id: <session-id> ``` ### SSE Transport (Legacy) #### Establish SSE Stream ``` GET /sse ``` #### Send Messages ``` POST /messages?sessionId=<session-id> Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "client-name", "version": "1.0.0" } } } ``` ## Testing A test script is provided to verify the HTTP server functionality: ```bash # Start the HTTP server in one terminal npm run dev:http # Run tests in another terminal node test-http-server.js ``` ## Configuration ### Environment Variables - `XHS_ENABLE_LOGGING=true` - Enable detailed logging - `PORT` - HTTP server port (default: 3000) ### CORS Configuration The HTTP server is configured with permissive CORS settings for development: ```javascript app.use(cors({ origin: '*', // Allow all origins exposedHeaders: ['Mcp-Session-Id'] })); ``` For production, you should restrict the `origin` to specific domains. ## Security Considerations ### DNS Rebinding Protection Both SSE and Streamable HTTP transports support DNS rebinding protection: ```javascript const transport = new SSEServerTransport('/messages', res, { allowedHosts: ['localhost', '127.0.0.1'], allowedOrigins: ['http://localhost:3000'], enableDnsRebindingProtection: true }); ``` ### Session Management - Session IDs are generated using cryptographically secure UUIDs - Sessions are automatically cleaned up when connections close - Invalid session IDs are rejected with appropriate error responses ## Migration Guide ### From Stdio to HTTP 1. **Update client configuration** to use HTTP endpoints instead of stdio 2. **Handle session management** for stateful operations 3. **Implement proper error handling** for HTTP-specific errors 4. **Consider CORS requirements** for browser-based clients ### From SSE to Streamable HTTP 1. **Update protocol version** from `2024-11-05` to `2025-03-26` 2. **Use unified `/mcp` endpoint** instead of separate `/sse` and `/messages` 3. **Implement session ID handling** in request headers 4. **Update client to handle** both streaming and direct responses ## Troubleshooting ### Common Issues 1. **Port already in use**: Change the port using `--port` option 2. **CORS errors**: Configure allowed origins in production 3. **Session not found**: Ensure session ID is properly included in headers 4. **Connection timeouts**: Check network configuration and firewall ### Debug Mode Enable detailed logging: ```bash XHS_ENABLE_LOGGING=true npm run dev:http ``` ### Health Check Always verify server status: ```bash curl http://localhost:3000/health ```