Support framed stdio MCP transport

Accept Content-Length framed JSON-RPC messages in addition to the existing newline-delimited transport so Copilot CLI can initialize the standalone MCP server.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Ross Story

src/mcp/transport.ts

@@ -1,5 +1,3 @@
-import { createInterface } from "node:readline";
-
 export interface JsonRpcRequest {
   jsonrpc: "2.0";
   id?: string | number;
@@ -19,6 +17,11 @@ export type RequestHandler = (
   params: Record<string, unknown>,
 ) => Promise<unknown>;
 
+export interface StdioMessageParser {
+  push: (chunk: Buffer | string) => void;
+  isFramed: () => boolean;
+}
+
 // JSON-RPC 2.0 notifications are messages without an `id` field. The spec
 // (and the MCP transport contract) requires the server to NOT send a
 // response for notifications. Some clients tolerate spurious responses;
@@ -130,26 +133,131 @@ export async function processLine(
   }
 }
 
+function findHeaderEnd(buffer: Buffer): { headerEnd: number; bodyStart: number } | null {
+  const crlf = buffer.indexOf("\r\n\r\n");
+  const lf = buffer.indexOf("\n\n");
+  if (crlf === -1 && lf === -1) return null;
+  if (crlf !== -1 && (lf === -1 || crlf <= lf)) {
+    return { headerEnd: crlf, bodyStart: crlf + 4 };
+  }
+  return { headerEnd: lf, bodyStart: lf + 2 };
+}
+
+function parseContentLength(header: string): number | null {
+  for (const line of header.split(/\r?\n/)) {
+    const match = line.match(/^content-length:\s*(\d+)\s*$/i);
+    if (match) return Number(match[1]);
+  }
+  return null;
+}
+
+export function formatResponse(
+  response: JsonRpcResponse,
+  framed: boolean,
+): string | Buffer[] {
+  const body = JSON.stringify(response);
+  if (!framed) return `${body}\n`;
+  const bytes = Buffer.from(body, "utf8");
+  return [Buffer.from(`Content-Length: ${bytes.length}\r\n\r\n`, "ascii"), bytes];
+}
+
+export function createMessageParser(
+  onMessage: (message: string) => void,
+  writeErr: (msg: string) => void = (msg) => process.stderr.write(msg),
+): StdioMessageParser {
+  let buffer = Buffer.alloc(0);
+  let framed = false;
+
+  function processBuffer(): void {
+    while (buffer.length > 0) {
+      if (buffer[0] === 10 || buffer[0] === 13) {
+        buffer = buffer.subarray(1);
+        continue;
+      }
+
+      const preview = buffer.toString("ascii", 0, Math.min(buffer.length, 32));
+      if (/^content-length:/i.test(preview)) {
+        const header = findHeaderEnd(buffer);
+        if (!header) return;
+
+        const headerText = buffer.subarray(0, header.headerEnd).toString("ascii");
+        const contentLength = parseContentLength(headerText);
+        if (contentLength === null) {
+          writeErr("[mcp-transport] missing Content-Length header\n");
+          buffer = buffer.subarray(header.bodyStart);
+          continue;
+        }
+
+        const messageEnd = header.bodyStart + contentLength;
+        if (buffer.length < messageEnd) return;
+
+        framed = true;
+        const message = buffer.subarray(header.bodyStart, messageEnd).toString("utf8");
+        buffer = buffer.subarray(messageEnd);
+        onMessage(message);
+        continue;
+      }
+
+      const newline = buffer.indexOf(10);
+      if (newline === -1) return;
+      const line = buffer
+        .subarray(0, newline)
+        .toString("utf8")
+        .replace(/\r$/, "");
+      buffer = buffer.subarray(newline + 1);
+      onMessage(line);
+    }
+  }
+
+  return {
+    push(chunk) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+      buffer = Buffer.concat([buffer, bytes]);
+      processBuffer();
+    },
+    isFramed() {
+      return framed;
+    },
+  };
+}
+
 export function createStdioTransport(handler: RequestHandler): {
   start: () => void;
   stop: () => void;
 } {
-  let rl: ReturnType<typeof createInterface> | null = null;
+  let parser: StdioMessageParser | null = null;
+  let queue = Promise.resolve();
 
   const writeResponse = (response: JsonRpcResponse) => {
-    process.stdout.write(JSON.stringify(response) + "\n");
+    const formatted = formatResponse(response, parser?.isFramed() ?? false);
+    if (typeof formatted === "string") {
+      process.stdout.write(formatted);
+      return;
+    }
+    for (const chunk of formatted) {
+      process.stdout.write(chunk);
+    }
   };
 
-  const onLine = (line: string) => processLine(line, handler, writeResponse);
+  const onData = (chunk: Buffer) => parser?.push(chunk);
 
   return {
     start() {
-      rl = createInterface({ input: process.stdin });
-      rl.on("line", onLine);
+      parser = createMessageParser((message) => {
+        queue = queue.then(() => processLine(message, handler, writeResponse));
+        void queue.catch((err) => {
+          process.stderr.write(
+            `[mcp-transport] request processing failed: ${
+              err instanceof Error ? err.message : String(err)
+            }\n`,
+          );
+        });
+      });
+      process.stdin.on("data", onData);
     },
     stop() {
-      rl?.close();
-      rl = null;
+      process.stdin.off("data", onData);
+      parser = null;
     },
   };
 }

test/mcp-transport.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 import {
+  createMessageParser,
+  formatResponse,
   processLine,
   type JsonRpcResponse,
   type RequestHandler,
@@ -227,3 +229,47 @@ describe("processLine — id type validation (JSON-RPC §4)", () => {
     expect(c.out[0].result).toEqual({ method: "ping" });
   });
 });
+
+describe("stdio framing", () => {
+  it("parses Content-Length framed MCP messages split across chunks", () => {
+    const messages: string[] = [];
+    const parser = createMessageParser((message) => messages.push(message));
+    const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize" });
+    const framed = `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`;
+
+    parser.push(framed.slice(0, 12));
+    parser.push(framed.slice(12));
+
+    expect(messages).toEqual([body]);
+    expect(parser.isFramed()).toBe(true);
+  });
+
+  it("parses newline-delimited JSON for existing clients", () => {
+    const messages: string[] = [];
+    const parser = createMessageParser((message) => messages.push(message));
+    const first = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+    const second = JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" });
+
+    parser.push(`${first}\n${second}\n`);
+
+    expect(messages).toEqual([first, second]);
+    expect(parser.isFramed()).toBe(false);
+  });
+
+  it("formats responses with Content-Length framing when requested", () => {
+    const response: JsonRpcResponse = {
+      jsonrpc: "2.0",
+      id: 1,
+      result: { ok: true },
+    };
+    const formatted = formatResponse(response, true);
+
+    expect(Array.isArray(formatted)).toBe(true);
+    if (!Array.isArray(formatted)) throw new Error("expected framed response");
+    const header = formatted[0].toString("ascii");
+    const body = formatted[1].toString("utf8");
+
+    expect(header).toBe(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n`);
+    expect(JSON.parse(body)).toEqual(response);
+  });
+});