## Executive overview

Server-Sent Events (SSE) let the server stream a unidirectional, text-based event feed over plain HTTP. Compared with raw “streaming-HTTP” hacks or a full WebSocket upgrade, SSE provides automatic reconnection, built-in last-event IDs, and works through most corporate proxies—all while piggy-backing on the existing MCP REST port.➀ The upgrade path below adds a lightweight `SseTransport` alongside your existing HTTP and (paused) WebSocket modules, keeping the public MCP API unchanged for callers that still prefer request/response semantics. This document walks through the spec, code additions, and testing so an offline agent can implement the feature end-to-end.

---

## 1  Why SSE for MCPControl?

* **Standards-based.** Defined in the HTML Standard as the `text/event-stream` MIME type and the `EventSource` API, so every browser—and many Node polyfills—“just work”.➁ ➂  
* **Cheaper than WebSockets.** No HTTP upgrade handshake (+1 RTT) and no full-duplex buffering; the server can flush whenever data is ready.➆ ➉  
* **Auto-reconnect & backfill.** Clients resend `Last-Event-ID`; server can replay missed messages.➃  
* **Fits MCP’s mostly-server-to-client traffic.** Tool-invocation responses, progress updates, and logs stream *out*; inbound commands remain normal POSTs.

---

## 2  High-level upgrade checklist

| Step | Owner | Key files |
|------|-------|-----------|
| 1. Add `SSE` to `TransportType` enum | `src/types/transport.ts` | |
| 2. Create `src/transports/sseTransport.ts` | new | |
| 3. Register route in `src/server.ts` (`/mcp/sse`) | server | |
| 4. Emit heartbeat & ID tracking | transport | |
| 5. Client polyfill docs (`eventsource` npm) | docs | |
| 6. Unit tests with Vitest | `test/sse.spec.ts` | |
| 7. Update README badges / docs | docs | |

(A diff view appears in §5.)

---

## 3  Protocol specification (SSE flavour)

### 3.1 Endpoint

```
GET /mcp/sse?auth=<jwt>&v=2025-04-30 HTTP/1.1
Accept: text/event-stream
```

Headers returned:

```
HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache
Connection: keep-alive
```

> **Auth** – Re-use the existing bearer/JWT query param logic used by your REST calls; if OAuth tokens are in headers today, mirror that here.

### 3.2 Event grammar

```
:id:<ULID>
:event:<mcp-event-name>    # optional; default "message"
:data:<JSON-encoded payload without newlines>
```

*Send exactly one JSON payload per event block.* An empty line terminates the event, per spec.➁ Events relevant to MCP:

| `event` | Payload schema | Direction |
|---------|----------------|-----------|
| `mcp.log` | `{ level, message, ts }` | → client |
| `mcp.response` | `{ requestId, data }` | → client |
| `mcp.heartbeat` | `{ ts }` | → client (every 25 s) |
| *(custom)* | free-form | – |

### 3.3 Keep-alive & reconnection

* Send a `comment` ping (`":\n\n"`) every 25 seconds (well under common 60 s proxy idle-timeout).➆  
* Clients that disconnect will auto-reconnect after `retry:<ms>`; you may emit `retry: 3000` once at start to suggest 3 s back-off.➂  
* On `Last-Event-ID`, replay from your in-memory ring buffer (configurable depth; 100 events default).

---

## 4  Mermaid diagrams

### 4.1 Connection handshake

```mermaid
sequenceDiagram
    participant C as Client
    participant S as MCPControl<br/>SSE Endpoint
    C->>S: GET /mcp/sse (Accept: text/event-stream)
    S-->>C: 200 OK + initial event stream
    loop every 25 s
        S-->>C: ":keep-alive\\n\\n"
    end
    Note over C,S: Any POST /mcp/tool remains<br/>separate HTTP request
```

### 4.2 State flow

```mermaid
stateDiagram-v2
    [*] --> Disconnected
    Disconnected --> Connecting: open()
    Connecting --> Open: 200 OK
    Open --> Reconnecting: network error
    Reconnecting --> Connecting: back-off expires
    Open --> Closed: evtSource.close()
    Closed --> [*]
```

---

## 5  Reference TypeScript implementation

<details>
<summary><code>src/transports/sseTransport.ts</code></summary>

```ts
import { Response } from 'express';
import { ULID } from 'ulid';
import { Transport } from './baseTransport';

export class SseTransport extends Transport {
  private clients = new Set<Response>();
  private replayBuffer: { id: string; data: string }[] = [];

  attach(app: import('express').Express) {
    app.get('/mcp/sse', (req, res) => {
      res.set({
        'Content-Type': 'text/event-stream; charset=utf-8',
        'Cache-Control': 'no-cache',
        Connection: 'keep-alive',
      });
      res.flushHeaders(); // send headers right away

      this.clients.add(res);

      // replay missed events if Last-Event-ID is present
      const lastId = req.header('Last-Event-ID');
      if (lastId) {
        this.replayBuffer
          .filter(e => e.id > lastId)
          .forEach(e => res.write(e.data));
      }

      req.on('close', () => this.clients.delete(res));
    });

    // ping loop
    setInterval(() => this.broadcast(':\n\n'), 25_000);
  }

  /** Broadcasts a JSON payload under the given event name */
  emitEvent(evt: string, payload: unknown) {
    const id = ULID();
    const data =
      `id:${id}\n` +
      (evt ? `event:${evt}\n` : '') +
      `data:${JSON.stringify(payload)}\n\n`;

    this.replayBuffer.push({ id, data });
    if (this.replayBuffer.length > 100) this.replayBuffer.shift();

    this.broadcast(data);
  }

  private broadcast(chunk: string) {
    for (const res of this.clients) res.write(chunk);
  }
}
```

</details>

### 5.1 Server hook (`src/server.ts` delta)

```diff
 import { HttpTransport } from './transports/httpTransport';
+import { SseTransport } from './transports/sseTransport';

 const app = express();
 const httpTransport = new HttpTransport(app);
+const sseTransport  = new SseTransport(app);
```

Everywhere you currently call `transport.emit(...)`, inject the SSE transport as well.

---

## 6  Offline client examples

### 6.1 Browser / WebView

```js
const es = new EventSource('/mcp/sse?auth=' + jwt);
es.onopen    = () => console.log('open');
es.onmessage = (e) => console.log(JSON.parse(e.data));
es.addEventListener('mcp.response', ({ data }) => {
  const { requestId, data: body } = JSON.parse(data);
});
```

### 6.2 Node 18+ (CommonJS) – no native `EventSource`

```bash
npm i eventsource  # vendored in repo for offline use
```

```js
const EventSource = require('eventsource');
const es = new EventSource('http://localhost:3232/mcp/sse?auth=' + token);
```

(Offline agents should symlink `node_modules/eventsource` or embed a minimal polyfill; the official package is 600 lines, no deps.)➂

---

## 7  Testing recipes

| Tool | Command | Expect |
|------|---------|--------|
| `curl` | `curl -N http://localhost:3232/mcp/sse` | continuous stream with `data:` lines |
| Browser dev-tools | `new EventSource('/mcp/sse')` | `readyState === 1` |
| Vitest | mock Response objects; assert write calls | heartbeat every 25 s |

---

## 8  Security considerations

1. **CORS** – mirror REST settings; disallow “*” in prod.  
2. **Bearer token leakage** – prefer `Authorization: Bearer` header; avoid query if referrers might log.  
3. **Denial-of-service** – cap open connections (`MAX_SSE_CLIENTS=100` env); shed oldest if exceeded.  
4. **Sensitive clipboard/mouse data** – enforce existing MCP permission model before emitting events.

---

## 9  Further reading (offline mirrors recommended)

* WHATWG HTML Standard § 9.2 Server-Sent Events➁  
* MDN “Using server-sent events” guide➆  
* MCP 2025-03-26 spec (core message envelope)➅  
* “Understanding SSE with Node.js” tutorial➂  
* `eventsource` npm README➂  
* Ably blog: WebSockets vs SSE trade-offs➉  
* StackOverflow answers on auto-reconnect➃ and Express setup➈  
* MCPControl source tree for hook points➄  

---

## 10  Changelog template

```md
### Added
* **SSE Transport** (`/mcp/sse`) providing real-time event streaming.
  * Auto-reconnect, heartbeat, last-event replay.
  * New `TransportType.SSE` enum.
```

---

> **Footnotes / Citations**

1. Streaming-over-HTTP workaround noted in earlier MCPControl discussions.  
2. WHATWG SSE spec ([HTML Standard](https://html.spec.whatwg.org/multipage/server-sent-events.html?utm_source=chatgpt.com))  
3. “Understanding SSE with Node.js” Medium guide ([Medium](https://itsfuad.medium.com/understanding-server-sent-events-sse-with-node-js-3e881c533081?utm_source=chatgpt.com))  
4. StackOverflow: automatic reconnect behaviour ([Stack Overflow](https://stackoverflow.com/questions/61541750/server-sent-events-sse-automatic-reconnect?utm_source=chatgpt.com))  
5. MCPControl GitHub repository root ([GitHub](https://github.com/Cheffromspace/MCPControl?utm_source=chatgpt.com))  
6. MCP formal spec 2025-03-26 ([Model Context Protocol](https://modelcontextprotocol.io/specification/2025-03-26?utm_source=chatgpt.com))  
7. MDN server-sent events reference ([MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events?utm_source=chatgpt.com))  
8. StackOverflow Express SSE example ([Stack Overflow](https://stackoverflow.com/questions/34657222/how-to-use-server-sent-events-in-express-js?utm_source=chatgpt.com))  
9. `eventsource` npm package docs ([npm](https://www.npmjs.com/package/eventsource?utm_source=chatgpt.com))  
10. Ably engineering blog comparison of WebSockets vs SSE ([Ably Realtime](https://ably.com/blog/websockets-vs-sse?utm_source=chatgpt.com))  
11. StackOverflow performance discussion ([Stack Overflow](https://stackoverflow.com/questions/63583989/performance-difference-between-websocket-and-server-sent-events-sse-for-chat-r?utm_source=chatgpt.com))