@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/mcp/__tests__/downstream-pool.test.ts

@@ -0,0 +1,278 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  DEFAULT_DOWNSTREAM_IDLE_TTL_MS,
+  DEFAULT_DOWNSTREAM_MAX_ENTRIES,
+  DownstreamPool,
+} from '../downstream-pool.js';
+
+/**
+ * The downstream pool's own contract, isolated from MCP: single-flight
+ * creation, failures never cached, idle eviction and the size cap — each of
+ * which must CLOSE what it drops — invalidation that reaches a creation still
+ * in flight, and leases that keep a connection in use from being closed.
+ */
+
+/** Let fire-and-forget disposals run. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function makePool(opts: { idleTtlMs?: number; maxEntries?: number } = {}) {
+  let now = 0;
+  const disposed: string[] = [];
+  const pool = new DownstreamPool<string>({
+    ...opts,
+    now: () => now,
+    dispose: async (value) => {
+      disposed.push(value);
+    },
+  });
+  /** One completed use: acquire, release at once, return the value. */
+  const use = async (key: string, create: () => Promise<string>) => {
+    const lease = await pool.acquire(key, create);
+    lease.release();
+    return lease.value;
+  };
+  return { pool, use, disposed, advance: (ms: number) => (now += ms) };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('DownstreamPool', () => {
+  it("defaults to the retired session store's numbers: 4 hours idle, 5000 entries", () => {
+    expect(DEFAULT_DOWNSTREAM_IDLE_TTL_MS).toBe(4 * 60 * 60 * 1000);
+    expect(DEFAULT_DOWNSTREAM_MAX_ENTRIES).toBe(5000);
+  });
+
+  it('single-flight: concurrent first acquires share ONE creation', async () => {
+    const { use } = makePool();
+    const gate = deferred<string>();
+    const create = vi.fn(() => gate.promise);
+    const waiters = [use('k', create), use('k', create), use('k', create)];
+    gate.resolve('conn-1');
+    expect(await Promise.all(waiters)).toEqual(['conn-1', 'conn-1', 'conn-1']);
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses a pooled value until it is evicted', async () => {
+    const { pool, use } = makePool();
+    const create = vi.fn(async () => 'conn');
+    await use('k', create);
+    await use('k', create);
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(pool.size()).toBe(1);
+  });
+
+  it('keys are independent: (user, server) pairs never share a value', async () => {
+    const { use } = makePool();
+    expect(await use('user-A/notion', async () => 'a')).toBe('a');
+    expect(await use('user-B/notion', async () => 'b')).toBe('b');
+  });
+
+  it('a failed creation is not cached: every waiter sees it, the next acquire retries', async () => {
+    const { pool, use } = makePool();
+    const gate = deferred<string>();
+    const failing = vi.fn(() => gate.promise);
+    const waiters = [use('k', failing), use('k', failing)];
+    gate.reject(new Error('dial failed'));
+    for (const w of waiters) await expect(w).rejects.toThrow('dial failed');
+    expect(pool.size()).toBe(0);
+
+    const create = vi.fn(async () => 'conn');
+    expect(await use('k', create)).toBe('conn');
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('idle eviction closes an entry unused past the TTL; the next acquire re-creates it', async () => {
+    const { use, disposed, advance } = makePool({ idleTtlMs: 1000 });
+    let n = 0;
+    const create = vi.fn(async () => `conn-${++n}`);
+    await use('k', create);
+    advance(1001);
+    expect(await use('k', create)).toBe('conn-2');
+    await flush();
+    expect(disposed).toEqual(['conn-1']);
+  });
+
+  it('use keeps an entry alive: idleness is measured from the LAST use', async () => {
+    const { use, disposed, advance } = makePool({ idleTtlMs: 1000 });
+    const create = vi.fn(async () => 'conn');
+    await use('k', create);
+    advance(800);
+    await use('k', create);
+    advance(800); // 1600 since creation, 800 since last use
+    await use('k', create);
+    await flush();
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(disposed).toEqual([]);
+  });
+
+  it('the size cap evicts (and closes) the least-recently-used entry', async () => {
+    const { pool, use, disposed, advance } = makePool({ maxEntries: 2 });
+    await use('a', async () => 'A');
+    advance(1);
+    await use('b', async () => 'B');
+    advance(1);
+    await use('a', async () => 'A-again'); // touch a → b is now the oldest
+    advance(1);
+    await use('c', async () => 'C');
+    await flush();
+    expect(disposed).toEqual(['B']);
+    expect(pool.size()).toBe(2);
+  });
+
+  it('evictWhere closes matching entries and leaves the rest', async () => {
+    const { pool, use, disposed } = makePool();
+    await use('user-A\u0000x', async () => 'ax');
+    await use('user-A\u0000y', async () => 'ay');
+    await use('user-B\u0000x', async () => 'bx');
+    pool.evictWhere((key) => key.startsWith('user-A\u0000'));
+    await flush();
+    expect(disposed.sort()).toEqual(['ax', 'ay']);
+    expect(pool.size()).toBe(1);
+  });
+
+  it('an invalidation that lands mid-creation closes the stale result and builds a fresh one', async () => {
+    const { pool, use, disposed } = makePool();
+    const gate = deferred<string>();
+    const create = vi
+      .fn<() => Promise<string>>()
+      .mockImplementationOnce(() => gate.promise)
+      .mockImplementationOnce(async () => 'fresh');
+    const first = use('k', create);
+    const joiner = use('k', create);
+    pool.evictWhere(() => true);
+    gate.resolve('stale');
+    expect(await first).toBe('fresh');
+    expect(await joiner).toBe('fresh');
+    await flush();
+    expect(disposed).toEqual(['stale']);
+    expect(create).toHaveBeenCalledTimes(2);
+  });
+
+  it('a dispose that throws is logged, never thrown into the request that swept', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let now = 0;
+    const pool = new DownstreamPool<string>({
+      idleTtlMs: 10,
+      now: () => now,
+      dispose: async () => {
+        throw new Error('close failed');
+      },
+    });
+    (await pool.acquire('user\u0000manual\u0000fp', async () => 'old')).release();
+    now = 100;
+    const lease = await pool.acquire('user\u0000manual\u0000fp', async () => 'new');
+    expect(lease.value).toBe('new');
+    await flush();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('user=user manual=manual'), expect.any(Error));
+  });
+
+  describe('leases', () => {
+    it('an entry in use outlives the idle TTL; idleness restarts when the use ends', async () => {
+      const { pool, use, disposed, advance } = makePool({ idleTtlMs: 1000 });
+      const lease = await pool.acquire('k', async () => 'conn');
+      advance(5000); // a long call, well past the TTL
+      await use('other', async () => 'other'); // sweeps
+      await flush();
+      expect(disposed).toEqual([]);
+
+      lease.release();
+      advance(999);
+      await use('other', async () => 'other');
+      await flush();
+      expect(disposed).toEqual([]);
+
+      advance(2);
+      await use('other', async () => 'other');
+      await flush();
+      expect(disposed).toEqual(['conn']);
+    });
+
+    it('the size cap never evicts an entry in use: the idle LRU goes instead', async () => {
+      const { pool, use, disposed, advance } = makePool({ maxEntries: 2 });
+      const held = await pool.acquire('a', async () => 'A'); // oldest, but in use
+      advance(1);
+      await use('b', async () => 'B');
+      advance(1);
+      await use('c', async () => 'C');
+      await flush();
+      expect(disposed).toEqual(['B']);
+      expect(held.value).toBe('A');
+      held.release();
+    });
+
+    it('when every entry is in use, the cap is exceeded rather than closing a live call', async () => {
+      const { pool, disposed } = makePool({ maxEntries: 1 });
+      const a = await pool.acquire('a', async () => 'A');
+      const b = await pool.acquire('b', async () => 'B');
+      await flush();
+      expect(disposed).toEqual([]);
+      expect(pool.size()).toBe(2);
+      a.release();
+      b.release();
+    });
+
+    it('an invalidated entry in use leaves the pool at once but is closed only on its last release', async () => {
+      const { pool, disposed } = makePool();
+      const create = vi
+        .fn<() => Promise<string>>()
+        .mockImplementationOnce(async () => 'old')
+        .mockImplementationOnce(async () => 'new');
+      const first = await pool.acquire('k', create);
+      const second = await pool.acquire('k', create);
+      pool.evictWhere(() => true);
+      await flush();
+      expect(disposed).toEqual([]);
+
+      // New callers get a connection built from the current state.
+      const fresh = await pool.acquire('k', create);
+      expect(fresh.value).toBe('new');
+
+      first.release();
+      first.release(); // idempotent: does not count as the second lease ending
+      await flush();
+      expect(disposed).toEqual([]);
+      second.release();
+      await flush();
+      expect(disposed).toEqual(['old']);
+      fresh.release();
+    });
+  });
+});
+
+describe('cap after an all-leased overflow', () => {
+  it('re-applies the cap when a lease ends, instead of waiting for the next acquire', async () => {
+    const { pool, disposed } = makePool({ maxEntries: 2 });
+    const a = await pool.acquire('a', async () => 'A');
+    const b = await pool.acquire('b', async () => 'B');
+    // Every entry is leased, so this insert cannot evict: the pool overflows.
+    const c = await pool.acquire('c', async () => 'C');
+    expect(pool.size()).toBe(3);
+    expect(disposed).toEqual([]);
+
+    // Ending A's lease makes it the only idle entry — and the cap applies now,
+    // with no acquire in sight. A is the least recently used idle entry.
+    a.release();
+    await flush();
+    expect(disposed).toEqual(['A']);
+    expect(pool.size()).toBe(2);
+
+    // Back within the cap: further releases evict nothing.
+    b.release();
+    c.release();
+    await flush();
+    expect(disposed).toEqual(['A']);
+    expect(pool.size()).toBe(2);
+  });
+});

package/src/modules/mcp/__tests__/downstream-token-refresh.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { DownstreamRefreshGuard, isDownstreamTokenRejection } from '../downstream-token-refresh.js';
+
+describe('isDownstreamTokenRejection', () => {
+  it('reads a failed call: the SDK error carries the HTTP status', () => {
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(401, 'Error POSTing to endpoint: '))).toBe(true);
+  });
+
+  it('reads a failed registration: @utcp/mcp flattens it to prose with only the body left', () => {
+    expect(
+      isDownstreamTokenRejection(
+        new Error(`Server 'srv': Streamable HTTP error: Error POSTing to endpoint: {"error":"invalid_token"}`),
+      ),
+    ).toBe(true);
+    expect(isDownstreamTokenRejection('HTTP 401 Unauthorized')).toBe(true);
+  });
+
+  it('follows the cause chain', () => {
+    expect(isDownstreamTokenRejection(new Error('tool failed', { cause: { status: 401 } }))).toBe(true);
+  });
+
+  it('is not fooled by anything that is not a token rejection', () => {
+    // 403: the token is fine, it just is not permitted — a refresh changes nothing.
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(403, 'Forbidden'))).toBe(false);
+    // Session loss, a JSON-RPC code, an ordinary tool failure.
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(404, '{"code":-32001,"message":"Session not found"}'))).toBe(false);
+    expect(isDownstreamTokenRejection(new McpError(ErrorCode.RequestTimeout, 'Request timed out'))).toBe(false);
+    expect(isDownstreamTokenRejection(new Error('kaboom'))).toBe(false);
+    // Digits inside a URL are not a status.
+    expect(isDownstreamTokenRejection(new Error('connect ECONNREFUSED https://api.example.com/v1/401/x'))).toBe(false);
+  });
+
+  it('a stated non-401 status outranks its own prose', () => {
+    // Providers do answer 403 with an OAuth error body. The status is the
+    // verdict — refreshing would swap a valid token for another equally
+    // unpermitted one, once a minute, forever.
+    expect(isDownstreamTokenRejection(new StreamableHTTPError(403, '{"error":"invalid_token"}'))).toBe(false);
+    expect(isDownstreamTokenRejection({ status: 403, message: 'Unauthorized' })).toBe(false);
+    expect(isDownstreamTokenRejection({ response: { status: 500 }, message: 'invalid_token' })).toBe(false);
+    // …and a 403 shell does not let its own body be re-read one link up.
+    expect(
+      isDownstreamTokenRejection(new Error('call failed', { cause: { status: 403, message: 'invalid_token' } })),
+    ).toBe(false);
+    // A status is still only a number in the HTTP range: `code` as a syscall
+    // name or a JSON-RPC code leaves the status unknown, so the message decides.
+    expect(isDownstreamTokenRejection({ code: 'ECONNRESET', message: 'invalid_token' })).toBe(true);
+    expect(isDownstreamTokenRejection({ code: -32000, message: 'invalid_token' })).toBe(true);
+  });
+
+  it('reads "unauthorized" as a word, not as the start of some other OAuth error', () => {
+    // `unauthorized_client` is about the client registration; a refreshed
+    // token changes nothing about it, so it must not cost a refresh (or, for
+    // a grant with no refresh token, the sign-in).
+    expect(
+      isDownstreamTokenRejection(new Error(`Server 'srv': Streamable HTTP error: Error POSTing to endpoint: {"error":"unauthorized_client"}`)),
+    ).toBe(false);
+    expect(isDownstreamTokenRejection(new Error('Error POSTing to endpoint: {"error":"unauthorized"}'))).toBe(true);
+  });
+});
+
+describe('DownstreamRefreshGuard — at most once per (user, manual) per minute', () => {
+  it('refuses a second refresh inside the window and allows one after it', async () => {
+    let now = 0;
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => now);
+    let runs = 0;
+    const refresh = async () => `run-${++runs}`;
+
+    await expect(guard.run('u\0notion', refresh)).resolves.toBe('run-1');
+    now += 59_999;
+    expect(guard.run('u\0notion', refresh)).toBeUndefined();
+    // Another (user, manual) pair has a window of its own.
+    await expect(guard.run('u\0linear', refresh)).resolves.toBe('run-2');
+    now += 1;
+    await expect(guard.run('u\0notion', refresh)).resolves.toBe('run-3');
+    expect(runs).toBe(3);
+  });
+
+  it('a rejection that arrives while the refresh runs shares its outcome instead of being refused', async () => {
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => 0);
+    let release!: (v: string) => void;
+    let runs = 0;
+    const refresh = () => {
+      runs += 1;
+      return new Promise<string>((r) => (release = r));
+    };
+    const first = guard.run('k', refresh);
+    const second = guard.run('k', refresh);
+    expect(second).toBeDefined();
+    release('refreshed');
+    await expect(Promise.all([first, second])).resolves.toEqual(['refreshed', 'refreshed']);
+    expect(runs).toBe(1);
+    // Settled, still inside the window: no more.
+    expect(guard.run('k', refresh)).toBeUndefined();
+  });
+
+  it('a refresh that never settles does not pin its key past the window', async () => {
+    let now = 0;
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => now);
+    let runs = 0;
+    // A token request with no timeout, hanging forever.
+    const hang = () => {
+      runs += 1;
+      return new Promise<string>(() => {});
+    };
+    expect(guard.run('k', hang)).toBeDefined();
+    now += 59_999;
+    expect(guard.run('k', hang)).toBeDefined(); // still in flight — shared, not re-run
+    expect(runs).toBe(1);
+    now += 1;
+    // The window is over. The hung attempt is forgotten rather than holding
+    // this key — and this map entry — for the life of the process.
+    await expect(guard.run('k', async () => 'recovered')).resolves.toBe('recovered');
+    expect(runs).toBe(1);
+  });
+
+  it('a clock that steps backward does not stretch the window by the step', async () => {
+    let now = 1_000_000;
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => now);
+    let runs = 0;
+    const refresh = async () => `run-${++runs}`;
+    await expect(guard.run('k', refresh)).resolves.toBe('run-1');
+
+    // An NTP step of ten minutes into the past. Measured from the old stamp
+    // this window would now hold for eleven minutes, not one.
+    now -= 600_000;
+    await expect(guard.run('k', refresh)).resolves.toBe('run-2');
+    // …and from there the usual minute applies.
+    now += 59_999;
+    expect(guard.run('k', refresh)).toBeUndefined();
+    now += 1;
+    await expect(guard.run('k', refresh)).resolves.toBe('run-3');
+  });
+
+  it('clearWhere forgets the windows it selects, by key and by outcome', async () => {
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => 0);
+    await guard.run('u1\0notion', async () => 'transient');
+    await guard.run('u1\0linear', async () => 'refreshed');
+    await guard.run('u2\0notion', async () => 'transient');
+
+    guard.clearWhere((key, outcome) => key.startsWith('u1\0') && outcome !== 'refreshed');
+
+    // Forgotten: u1's failed window. Kept: u1's successful one, and u2 entirely.
+    await expect(guard.run('u1\0notion', async () => 'again')).resolves.toBe('again');
+    expect(guard.run('u1\0linear', async () => 'again')).toBeUndefined();
+    expect(guard.run('u2\0notion', async () => 'again')).toBeUndefined();
+  });
+
+  it('a refresh still in flight is not cleared by the predicate the proxy uses', async () => {
+    const guard = new DownstreamRefreshGuard<string>(60_000, () => 0);
+    let runs = 0;
+    let release!: (v: string) => void;
+    const refresh = () => {
+      runs += 1;
+      return new Promise<string>((r) => (release = r));
+    };
+    const first = guard.run('u1\0notion', refresh);
+
+    // Exactly what `forgetStaleRefreshWindows` passes. A refresh of our own is
+    // itself a secrets mutation, and it notifies BEFORE it settles — so an
+    // in-flight window (outcome still undefined) must survive this, or the
+    // guard would be reset by the very refresh it issued and a provider that
+    // keeps minting refused tokens would get one refresh per call.
+    guard.clearWhere((key, outcome) => key.startsWith('u1\0') && outcome !== undefined && outcome !== 'refreshed');
+
+    // Still the same attempt: shared, not re-run, and not refused either.
+    const second = guard.run('u1\0notion', refresh);
+    expect(second).toBeDefined();
+    release('refreshed');
+    await expect(Promise.all([first, second])).resolves.toEqual(['refreshed', 'refreshed']);
+    expect(runs).toBe(1);
+    // And once it HAS settled as 'refreshed', the window still stands.
+    guard.clearWhere((key, outcome) => key.startsWith('u1\0') && outcome !== undefined && outcome !== 'refreshed');
+    expect(guard.run('u1\0notion', refresh)).toBeUndefined();
+    expect(runs).toBe(1);
+  });
+});

package/src/modules/mcp/__tests__/fake-downstream-mcp-server.ts

@@ -0,0 +1,156 @@
+import { createServer, type IncomingMessage, type Server as HttpServer, type ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import type { AddressInfo } from 'node:net';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  isInitializeRequest,
+  type CallToolResult,
+} from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * A SESSION-FUL third-party MCP server over real HTTP — the kind an `mcp.json`
+ * manual points at — for driving the proxy's downstream pool.
+ *
+ * Real, not stubbed, for the same reason as mcp-core's recovery fixture: the
+ * pool's healing rests on a live server's session-loss shape (404 / `-32001`)
+ * travelling intact through the SDK transport and `@utcp/mcp`.
+ *
+ * Not collected by vitest: the include pattern is `**\/*.test.ts`.
+ */
+export interface FakeDownstreamMcpServer {
+  url: string;
+  /** Forget every session, as a restart does. The process stays up. */
+  restart(): Promise<void>;
+  /** Stop listening and drop every connection. */
+  stop(): Promise<void>;
+  /** `initialize` requests served — one per downstream connection that reached the server. */
+  initializations(): number;
+  /** Times `echo` actually executed. */
+  executions(): number;
+  /** Sessions currently live on the server. */
+  liveSessions(): number;
+  /** Requests answered 401 because `acceptsToken` refused their bearer. */
+  rejections(): number;
+}
+
+export interface FakeDownstreamOptions {
+  /**
+   * When set, every request must carry `Authorization: Bearer <token>` with a
+   * token this accepts; anything else is answered 401 with an RFC 6750
+   * `invalid_token` challenge — what an OAuth-protected MCP server answers a
+   * revoked or expired token with.
+   */
+  acceptsToken?: (token: string) => boolean;
+}
+
+export async function startFakeDownstreamMcpServer(opts: FakeDownstreamOptions = {}): Promise<FakeDownstreamMcpServer> {
+  const sessions = new Map<string, StreamableHTTPServerTransport>();
+  let initializations = 0;
+  let executions = 0;
+  let rejections = 0;
+
+  function buildServer(): Server {
+    const server = new Server({ name: 'downstream', version: '0.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'echo',
+          description: 'Return the text it was given.',
+          inputSchema: { type: 'object' as const, properties: { text: { type: 'string' } } },
+        },
+      ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
+      executions += 1;
+      const text = String((request.params.arguments as { text?: unknown } | undefined)?.text ?? '');
+      return { content: [{ type: 'text', text: JSON.stringify({ echoed: text }) }] };
+    });
+    return server;
+  }
+
+  function jsonRpcError(res: ServerResponse, status: number, code: number, message: string): void {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+  }
+
+  async function readBody(req: IncomingMessage): Promise<unknown> {
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) chunks.push(chunk as Buffer);
+    if (chunks.length === 0) return undefined;
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    } catch {
+      return undefined;
+    }
+  }
+
+  const http: HttpServer = createServer((req, res) => {
+    void (async () => {
+      if (opts.acceptsToken) {
+        const token = String(req.headers.authorization ?? '').replace(/^Bearer\s+/i, '');
+        if (!opts.acceptsToken(token)) {
+          rejections += 1;
+          res.writeHead(401, {
+            'Content-Type': 'application/json',
+            'WWW-Authenticate': 'Bearer error="invalid_token", error_description="The access token is invalid"',
+          });
+          res.end(JSON.stringify({ error: 'invalid_token', error_description: 'The access token is invalid' }));
+          return;
+        }
+      }
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+      const body = req.method === 'POST' ? await readBody(req) : undefined;
+      const live = sessionId ? sessions.get(sessionId) : undefined;
+      if (live) {
+        await live.handleRequest(req, res, body);
+        return;
+      }
+      if (req.method === 'POST' && isInitializeRequest(body)) {
+        initializations += 1;
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          onsessioninitialized: (id: string) => {
+            sessions.set(id, transport);
+          },
+        });
+        await buildServer().connect(transport);
+        await transport.handleRequest(req, res, body);
+        return;
+      }
+      if (sessionId) {
+        jsonRpcError(res, 404, -32001, 'Session not found');
+        return;
+      }
+      jsonRpcError(res, 400, -32000, 'Bad Request: Mcp-Session-Id header is required');
+    })().catch(() => {
+      if (!res.headersSent) jsonRpcError(res, 500, -32603, 'Internal error');
+      else res.end();
+    });
+  });
+
+  await new Promise<void>((resolve) => http.listen(0, '127.0.0.1', resolve));
+  const { port } = http.address() as AddressInfo;
+
+  async function dropSessions(): Promise<void> {
+    const live = [...sessions.values()];
+    sessions.clear();
+    await Promise.all(live.map((t) => t.close().catch(() => {})));
+  }
+
+  return {
+    url: `http://127.0.0.1:${port}/mcp`,
+    restart: dropSessions,
+    async stop() {
+      await dropSessions();
+      http.closeAllConnections();
+      await new Promise<void>((resolve) => http.close(() => resolve()));
+    },
+    initializations: () => initializations,
+    executions: () => executions,
+    liveSessions: () => sessions.size,
+    rejections: () => rejections,
+  };
+}