Feat/w 18481168

[justinwilaby]

MCP SSE Transport Server Implementation

Overview

This PR implements a Model Context Protocol (MCP) SSE transport server that enables Cursor to communicate with remote MCP servers over the network. The implementation follows the MCP specification for establishing and maintaining SSE connections, handling tool execution, and managing session state.

Changes

• Added MCPStdioToSSEProxy class to handle SSE transport layer
• Implemented MCP handshake protocol (initialize → initialized → ready)
• Added session management with Mcp-Session-Id header
• Implemented SSE streaming for tool responses
• Added message queuing during handshake
• Added timeout handling (60s default)
• Added graceful error handling and session recovery

Technical Details

• Uses Node.js 20+ native fetch and Headers
• Implements JSON-RPC 2.0 protocol for tool execution
• Supports both JSON and SSE response formats
• Maintains session state for persistent connections
• Queues messages during handshake to prevent data loss

Testing

• Unit tests for handshake protocol
• Unit tests for SSE streaming
• Unit tests for session management
• Integration tests for full MCP workflow
• Error handling and recovery tests

Limitations

• Currently only supports tools (not resources)
• Limited to 40 tools per MCP server
• Requires direct machine communication (may not work over SSH)

Documentation

• Added inline code documentation
• Updated README with setup instructions
• Added example configuration

Checklist

• Code follows project style guidelines
• All tests pass
• Documentation is updated
• No new dependencies added
• No breaking changes

sequenceDiagram
    participant Client
    participant Proxy as MCPStdioToSSEProxy
    participant Remote as Remote Server

    Note over Proxy: Initialize with remoteUrl

    loop Main Processing Loop
        Client->>Proxy: Read stdin line
        
        alt Handshake State: awaiting-initialize
            Proxy->>Remote: POST initialize request
            Remote-->>Proxy: Response with session-id
            Note over Proxy: Set handshakeState to awaiting-initialized
        else Handshake State: awaiting-initialized
            Proxy->>Remote: POST notifications/initialized
            Remote-->>Proxy: Response
            Note over Proxy: Set handshakeState to ready
        else Handshake State: ready
            Proxy->>Remote: POST message
            alt Response is SSE
                Remote-->>Proxy: Stream SSE events
                Proxy-->>Client: Write events to stdout
            else Response is JSON
                Remote-->>Proxy: JSON response
                Proxy-->>Client: Write response to stdout
            end
        end

        alt Session Lost (404)
            Note over Proxy: Reset session and restart handshake
        end
    end

    Note over Proxy: Error handling throughout

Loading