@ezmcpz/transport-sse

Server-Sent Events (SSE) transport for EZMCPZ. Enables real-time, server-to-client streaming communication.

Installation

npm install @ezmcpz/transport-sse
# or
pnpm add @ezmcpz/transport-sse

Usage

import { McpServer } from '@ezmcpz/core';
import { sseTransport } from '@ezmcpz/transport-sse';

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0'
});

// Add SSE transport
server.use(sseTransport({
  port: 3000,
  endpoint: '/sse',
  heartbeat: 30000
}));

await server.start();

Configuration

sseTransport({
  port: 3000,              // Port to listen on (default: 3000)
  host: '0.0.0.0',         // Host to bind to (default: '0.0.0.0')
  endpoint: '/sse',        // SSE endpoint path (default: '/sse')
  heartbeat: 30000,        // Heartbeat interval in ms (default: 30000)
  https: {                 // Optional HTTPS configuration
    cert: './cert.pem',
    key: './key.pem'
  },
  cors: {                  // CORS configuration
    origin: '*'
  }
})

How It Works

The SSE transport uses a two-endpoint model:

1. GET /sse - Client connects and receives server-sent events
2. POST /sse/message - Client sends messages to the server

This allows bidirectional communication while maintaining the SSE connection for server-to-client streaming.

Client Example

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:3000/sse?clientId=my-client');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

// Send a message
async function callTool(name: string, args: any) {
  const response = await fetch('http://localhost:3000/sse/message', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: 'my-client',
      message: {
        jsonrpc: '2.0',
        id: 1,
        method: 'tools/call',
        params: { name, arguments: args }
      }
    })
  });
  
  return response.json();
}

// Call a tool
await callTool('my_tool', { arg: 'value' });

Features

• Real-time streaming: Server can push updates to clients
• Automatic reconnection: SSE clients automatically reconnect
• Heartbeat: Keeps connections alive with periodic pings
• Multiple clients: Supports multiple concurrent client connections
• HTTPS support: Optional SSL/TLS encryption
• CORS support: Configurable cross-origin resource sharing

Endpoints

GET /sse

Establish SSE connection.

Query Parameters:

• clientId (optional): Client identifier

Response: Event stream

POST /sse/message

Send a message to the server.

Request:

{
  "clientId": "my-client",
  "message": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "my_tool",
      "arguments": { "arg": "value" }
    }
  }
}

Response:

{
  "status": "sent",
  "messageId": 1
}

The actual result will be sent via the SSE connection.

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "name": "my-server",
  "version": "1.0.0",
  "connectedClients": 5
}

Use Cases

• Real-time notifications
• Long-running operations with progress updates
• ChatGPT and other AI assistants
• Web-based MCP clients
• Dashboard applications

License

MIT