@bevel-software/platform-core-backend 0.1.0

package/src/modules/mcp/__tests__/mcp-proxy-helpers.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from 'vitest';
+import type { Tool as UtcpTool } from '@utcp/sdk';
+import {
+  sanitizeInputSchema,
+  describeToolFailure,
+  flattenDiscoveredTool,
+  toCallToolResult,
+  toListedTool,
+} from '../mcp.service.js';
+import type { ProxiedTool } from '../mcp.service.js';
+
+function utcpTool(name: string, bodyProps: Record<string, unknown>, required: string[] = []): UtcpTool {
+  return {
+    name,
+    description: `the ${name} tool`,
+    inputs: {
+      type: 'object',
+      properties: { body: { type: 'object', properties: bodyProps, required } },
+      required: ['body'],
+    },
+    outputs: { type: 'object', properties: {} },
+    tags: [],
+    tool_call_template: { call_template_type: 'http' } as never,
+  } as UtcpTool;
+}
+
+describe('flattenDiscoveredTool', () => {
+  it('strips the manual prefix and keeps the {body} envelope verbatim', () => {
+    const tool = utcpTool(
+      'KNOWLEDGE_BASE.ask',
+      { prompt: { type: 'string' }, sessionId: { type: 'string' } },
+      ['prompt'],
+    );
+    const flat = flattenDiscoveredTool('KNOWLEDGE_BASE.', tool);
+
+    expect(flat.mcpName).toBe('ask');
+    expect(flat.utcpName).toBe('KNOWLEDGE_BASE.ask');
+    // The schema passes through untouched — callers see the same `{body}`
+    // envelope UTCP dispatches on (and that `call_tool_chain` documents).
+    expect(flat.inputSchema).toEqual(tool.inputs);
+  });
+
+  it('keeps a remote MCP tool schema (no envelope) verbatim too', () => {
+    const tool = {
+      name: 'notion.search',
+      description: 'search',
+      inputs: {
+        type: 'object',
+        properties: { query: { type: 'string' } },
+      },
+      outputs: { type: 'object', properties: {} },
+      tags: [],
+      tool_call_template: { call_template_type: 'mcp' } as never,
+    } as UtcpTool;
+    const flat = flattenDiscoveredTool('notion.', tool);
+    expect(flat.mcpName).toBe('search');
+    expect(flat.inputSchema).toEqual(tool.inputs);
+  });
+});
+
+describe('toListedTool', () => {
+  const proxied = (over: Partial<ProxiedTool>): ProxiedTool => ({
+    utcpName: 'm.t',
+    mcpName: 'm_t',
+    description: 'a tool',
+    inputSchema: { type: 'object', properties: {} },
+    manualName: 'm',
+    ...over,
+  });
+
+  it('passes a conforming tool through', () => {
+    const listed = toListedTool(proxied({ mcpName: 'gmail_send_email' }));
+    expect(listed).toEqual({
+      name: 'gmail_send_email',
+      description: 'a tool',
+      inputSchema: { type: 'object', properties: {} },
+    });
+  });
+
+  it('drops a tool whose name is too long or has illegal chars (so it cannot blank the whole list)', () => {
+    expect(toListedTool(proxied({ mcpName: 'has spaces' }))).toBeNull();
+    expect(toListedTool(proxied({ mcpName: 'a'.repeat(129) }))).toBeNull();
+    expect(toListedTool(proxied({ mcpName: '' }))).toBeNull();
+  });
+
+  it('inlines $defs/$ref (Google-MCP style) so no downstream layer sees them', () => {
+    // Shape of Google's gmail `create_draft` schema: $defs + $ref in a property.
+    const googleStyle = {
+      type: 'object',
+      $defs: {
+        Recipient: {
+          type: 'object',
+          properties: { email: { type: 'string' } },
+          required: ['email'],
+        },
+      },
+      properties: {
+        to: { type: 'array', items: { $ref: '#/$defs/Recipient' } },
+        subject: { type: 'string' },
+      },
+      required: ['to'],
+    };
+    const listed = toListedTool(proxied({ inputSchema: googleStyle as never }))!;
+    const json = JSON.stringify(listed.inputSchema);
+    expect(json).not.toContain('$ref');
+    expect(json).not.toContain('$defs');
+    // The reference target was inlined, not dropped.
+    expect(listed.inputSchema).toMatchObject({
+      properties: {
+        to: {
+          items: { type: 'object', properties: { email: { type: 'string' } }, required: ['email'] },
+        },
+      },
+    });
+  });
+
+  it('forces top-level type "object" + properties even when the remote declared otherwise', () => {
+    // A remote server that put type: "string" (or a union) at the top would
+    // otherwise fail the client's `type: "object"` check for the whole list.
+    const listed = toListedTool(proxied({ inputSchema: { type: 'string', description: 'oops' } as never }))!;
+    expect(listed.inputSchema).toMatchObject({ type: 'object', properties: {}, description: 'oops' });
+    const union = toListedTool(proxied({ inputSchema: { type: ['object', 'null'], properties: { a: {} } } as never }))!;
+    expect((union.inputSchema as { type: unknown }).type).toBe('object');
+  });
+
+  it('normalizes an odd inputSchema to a valid object schema, keeping declared properties', () => {
+    // Missing `type` → added; existing properties preserved.
+    const noType = toListedTool(proxied({ inputSchema: { properties: { q: { type: 'string' } } } as never }));
+    expect(noType!.inputSchema).toEqual({ type: 'object', properties: { q: { type: 'string' } } });
+
+    // Non-object schema (null / array) → replaced with an empty object schema.
+    expect(toListedTool(proxied({ inputSchema: null as never }))!.inputSchema).toEqual({
+      type: 'object',
+      properties: {},
+    });
+    expect(toListedTool(proxied({ inputSchema: [] as never }))!.inputSchema).toEqual({
+      type: 'object',
+      properties: {},
+    });
+  });
+});
+
+describe('sanitizeInputSchema', () => {
+  it('resolves nested and repeated refs', () => {
+    const schema = {
+      type: 'object',
+      $defs: {
+        A: { type: 'string' },
+        B: { type: 'object', properties: { a: { $ref: '#/$defs/A' } } },
+      },
+      properties: { x: { $ref: '#/$defs/B' }, y: { $ref: '#/$defs/A' } },
+    };
+    expect(sanitizeInputSchema(schema)).toEqual({
+      type: 'object',
+      properties: {
+        x: { type: 'object', properties: { a: { type: 'string' } } },
+        y: { type: 'string' },
+      },
+    });
+  });
+
+  it('degrades a recursive schema to a permissive node instead of hanging', () => {
+    const schema = {
+      type: 'object',
+      $defs: { Node: { type: 'object', properties: { child: { $ref: '#/$defs/Node' } } } },
+      properties: { root: { $ref: '#/$defs/Node' } },
+    };
+    const out = sanitizeInputSchema(schema) as Record<string, unknown>;
+    expect(JSON.stringify(out)).not.toContain('$ref');
+    expect(out.type).toBe('object'); // finished, didn't hang
+  });
+
+  it('degrades unresolvable and external refs without dropping siblings', () => {
+    const out = sanitizeInputSchema({
+      type: 'object',
+      properties: {
+        a: { $ref: '#/$defs/missing', description: 'kept' },
+        b: { $ref: 'https://elsewhere.example/schema.json' },
+      },
+    }) as never;
+    expect(JSON.stringify(out)).not.toContain('$ref');
+    expect(out).toMatchObject({ properties: { a: { description: 'kept' } } });
+  });
+
+  it('drops non-standard `format` (OpenAPI int32/byte) but keeps standard ones', () => {
+    // Google's gmail/calendar schemas carry format: int32 / byte, which the
+    // Anthropic tool validator rejects — poisoning the whole tools/list.
+    const out = sanitizeInputSchema({
+      type: 'object',
+      properties: {
+        pageSize: { type: 'integer', format: 'int32' },
+        content: { type: 'string', format: 'byte' },
+        when: { type: 'string', format: 'date-time' }, // standard — kept
+        who: { type: 'string', format: 'email' }, // standard — kept
+      },
+    }) as { properties: Record<string, unknown> };
+    expect(out.properties.pageSize).toEqual({ type: 'integer' });
+    expect(out.properties.content).toEqual({ type: 'string' });
+    expect(out.properties.when).toEqual({ type: 'string', format: 'date-time' });
+    expect(out.properties.who).toEqual({ type: 'string', format: 'email' });
+  });
+});
+
+describe('describeToolFailure', () => {
+  it('surfaces the REST endpoint error body over the bare axios status message', () => {
+    const axiosLike = Object.assign(new Error('Request failed with status code 500'), {
+      response: { data: { error: 'kaboom' } },
+    });
+    expect(describeToolFailure(axiosLike)).toBe('kaboom');
+  });
+
+  it('uses a string response body when there is one', () => {
+    const err = Object.assign(new Error('boom'), { response: { data: 'plain text error' } });
+    expect(describeToolFailure(err)).toBe('plain text error');
+  });
+
+  it('falls back to the error message when no response body is present', () => {
+    expect(describeToolFailure(new Error('socket hang up'))).toBe('socket hang up');
+  });
+});
+
+describe('toCallToolResult', () => {
+  it('uses a bare string as the text', () => {
+    expect(toCallToolResult('hello')).toEqual({ content: [{ type: 'text', text: 'hello' }] });
+  });
+
+  it('passes a tool that already returns MCP agentic content through unchanged', () => {
+    const agentic = { content: [{ type: 'text', text: 'already formatted' }], isError: false };
+    expect(toCallToolResult(agentic)).toBe(agentic);
+  });
+
+  it('JSON-stringifies a structured object so every field survives (ask poll contract)', () => {
+    // No collapsing to `text`: the whole object is stringified, so status and the
+    // sessionId the caller must echo back to poll both reach the client.
+    const result = toCallToolResult({ text: 'Still working…', status: 'running', sessionId: 'abc-123' });
+    const out = (result.content[0] as { type: string; text: string });
+    expect(out.type).toBe('text');
+    expect(JSON.parse(out.text)).toEqual({ text: 'Still working…', status: 'running', sessionId: 'abc-123' });
+  });
+
+  it('JSON-stringifies any object (including one with a text field)', () => {
+    expect(toCallToolResult({ text: 'answer' })).toEqual({
+      content: [{ type: 'text', text: '{"text":"answer"}' }],
+    });
+    expect(toCallToolResult({ hits: [1] })).toEqual({
+      content: [{ type: 'text', text: '{"hits":[1]}' }],
+    });
+  });
+
+  it('falls back to a placeholder for empty output', () => {
+    expect((toCallToolResult('').content[0] as { text: string }).text).toBe('(tool produced no output)');
+  });
+});

package/src/modules/mcp/__tests__/mcp-session-store.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest';
+import { McpSessionStore } from '../mcp-session-store.js';
+
+/**
+ * Builds a store with a controllable clock so the idle-TTL and eviction
+ * paths don't depend on real time. Tests bump `clock.ts` directly between
+ * operations.
+ */
+function makeStore(opts: { idleTtlMs?: number; maxSessions?: number } = {}) {
+  const clock = { ts: 1_000_000 };
+  const store = new McpSessionStore({
+    idleTtlMs: opts.idleTtlMs ?? 60_000,
+    maxSessions: opts.maxSessions ?? 100,
+    now: () => clock.ts,
+  });
+  return { store, clock };
+}
+
+describe('McpSessionStore', () => {
+  it('create + get round-trips the session', () => {
+    const { store } = makeStore();
+    store.create('sess-1', 'user-A');
+
+    const session = store.get('sess-1');
+    expect(session?.userId).toBe('user-A');
+  });
+
+  it('get bumps lastTouchedAt so an active session never ages out under steady use', () => {
+    const { store, clock } = makeStore({ idleTtlMs: 1000 });
+    store.create('sess-1', 'user-A');
+
+    // Advance just below TTL and touch; advance again just below TTL and
+    // touch. Total elapsed > TTL, but no single gap exceeds it.
+    clock.ts += 900;
+    expect(store.get('sess-1')).not.toBeNull();
+    clock.ts += 900;
+    expect(store.get('sess-1')).not.toBeNull();
+  });
+
+  it('get returns null and drops the session once idle longer than ttl', () => {
+    const { store, clock } = makeStore({ idleTtlMs: 1000 });
+    store.create('sess-1', 'user-A');
+
+    clock.ts += 1500;
+    expect(store.get('sess-1')).toBeNull();
+    // The sweep ran during the get, so the entry is actually gone.
+    expect(store.size()).toBe(0);
+  });
+
+  it('evicts the oldest-touched session when the size cap is hit', () => {
+    const { store, clock } = makeStore({ maxSessions: 2 });
+
+    store.create('old', 'user-A');
+    clock.ts += 10;
+    store.create('middle', 'user-B');
+    clock.ts += 10;
+    // Touch `middle` so `old` is the oldest-touched.
+    store.get('middle');
+
+    clock.ts += 10;
+    store.create('new', 'user-C');
+
+    expect(store.get('old')).toBeNull();
+    expect(store.get('middle')).not.toBeNull();
+    expect(store.get('new')).not.toBeNull();
+    expect(store.size()).toBe(2);
+  });
+
+  it('delete removes an entry immediately', () => {
+    const { store } = makeStore();
+    store.create('sess-1', 'user-A');
+    store.delete('sess-1');
+    expect(store.get('sess-1')).toBeNull();
+  });
+
+  describe('onEvict', () => {
+    it('fires the listener with the session id when the TTL sweep drops an entry', () => {
+      const { store, clock } = makeStore({ idleTtlMs: 1000 });
+      const evicted: string[] = [];
+      store.onEvict((id) => evicted.push(id));
+      store.create('sess-1', 'user-A');
+
+      clock.ts += 1500;
+      store.get('sess-1'); // triggers sweep
+
+      expect(evicted).toEqual(['sess-1']);
+    });
+
+    it('fires the listener with the session id when the size cap evicts the oldest', () => {
+      const { store, clock } = makeStore({ maxSessions: 2 });
+      const evicted: string[] = [];
+      store.onEvict((id) => evicted.push(id));
+
+      store.create('old', 'user-A');
+      clock.ts += 10;
+      store.create('middle', 'user-B');
+      clock.ts += 10;
+      store.get('middle'); // bumps middle, so `old` is oldest-touched
+
+      clock.ts += 10;
+      store.create('new', 'user-C');
+
+      expect(evicted).toEqual(['old']);
+    });
+
+    it('does NOT fire on explicit delete() — that path is the consumer asking for removal', () => {
+      const { store } = makeStore();
+      const evicted: string[] = [];
+      store.onEvict((id) => evicted.push(id));
+      store.create('sess-1', 'user-A');
+
+      store.delete('sess-1');
+
+      expect(evicted).toEqual([]);
+    });
+
+    it('keeps sweeping the remaining entries when a listener throws', () => {
+      const { store, clock } = makeStore({ idleTtlMs: 1000 });
+      const evicted: string[] = [];
+      store.onEvict((id) => {
+        if (id === 'sess-1') throw new Error('bad listener');
+        evicted.push(id);
+      });
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      store.create('sess-1', 'user-A');
+      store.create('sess-2', 'user-B');
+      clock.ts += 1500;
+      store.create('trigger', 'user-C'); // sweep runs at create time too
+
+      // Both 'sess-1' (listener threw) and 'sess-2' must have been swept;
+      // we observe sess-2 in `evicted` and sess-1 via the warn spy.
+      expect(evicted).toContain('sess-2');
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
+
+    it('returns an unsubscribe function that stops further notifications', () => {
+      const { store, clock } = makeStore({ idleTtlMs: 1000 });
+      const evicted: string[] = [];
+      const off = store.onEvict((id) => evicted.push(id));
+
+      store.create('sess-1', 'user-A');
+      off();
+      clock.ts += 1500;
+      store.get('sess-1');
+
+      expect(evicted).toEqual([]);
+    });
+  });
+});

package/src/modules/mcp/__tests__/mcp.e2e.test.ts

@@ -0,0 +1,150 @@
+import type { Server as HttpServer } from 'node:http';
+import type { RequestHandler } from 'express';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { McpService } from '../mcp.service.js';
+import { McpSessionStore } from '../mcp-session-store.js';
+import { SpillStore } from '../../workspace/spill-store.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { toolDef } from '../../tool-helpers/tool-def.js';
+
+/**
+ * True end-to-end test over the REAL Streamable-HTTP MCP transport. A real MCP
+ * `Client` talks to the real `createMcpRoutes` HTTP surface, which drives the
+ * real `McpService` proxy, which discovers and dispatches against the real
+ * `createExternalToolsRoutes` surface over loopback — all on one express app.
+ * Nothing is faked except the two auth middlewares (we're testing the transport
+ * + proxy wiring, not credential verification). This is the closest automated
+ * coverage to a production MCP client connecting in.
+ */
+
+const TEST_BEARER = 'bevel_e2e_testkey';
+
+let httpServer: HttpServer | undefined;
+const cleanups: Array<() => Promise<void>> = [];
+
+// Stand-in auth: bind a user + token like the real middlewares do, accepting
+// the test bearer. Used for the /mcp surface; the loopback tool endpoints are
+// hosted directly below.
+const fakeAuth: RequestHandler = (req, _res, next) => {
+  req.userId = 'user-A';
+  req.externalApiKeyId = 'tok-1';
+  next();
+};
+
+async function connectClient(): Promise<Client> {
+  const registry = new ToolRegistry();
+  // Echo `ask` (reflects the received sessionId so continuity is observable) +
+  // an erroring `boom`, registered as defs and hosted as endpoints.
+  registry.registerExternalTool(
+    toolDef({
+      name: 'ask',
+      description: 'echo the prompt',
+      path: '/api/agent/tools/ask',
+      inputs: {
+        type: 'object',
+        properties: { prompt: { type: 'string' }, sessionId: { type: 'string' } },
+        required: ['prompt'],
+      },
+    }),
+  );
+  registry.registerExternalTool(
+    toolDef({ name: 'boom', description: 'always errors', path: '/api/agent/tools/boom', inputs: { type: 'object', properties: {} } }),
+  );
+
+  const app = express();
+  app.use(express.json());
+  app.post('/api/agent/tools/ask', (req, res) => {
+    const b = (req.body ?? {}) as { prompt?: string; sessionId?: string };
+    const incoming = typeof b.sessionId === 'string' ? b.sessionId : undefined;
+    res.json({ text: `echo: ${b.prompt} sid=${incoming ?? 'NONE'}`, sessionId: incoming ?? 'sess-1' });
+  });
+  app.post('/api/agent/tools/boom', (_req, res) => res.status(500).json({ error: 'kaboom' }));
+
+  // Listen first so we know the port, then construct the proxy pointed at our
+  // own loopback address and mount the routes (Express allows post-listen use).
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  const mcpService = new McpService(new McpSessionStore(), {
+    loopbackBaseUrl: baseUrl,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+  });
+  const stub = {} as never;
+  app.use('/api', createMcpRoutes(mcpService, stub, fakeAuth, fakeAuth, stub));
+  app.use('/api', createManualRoutes(registry, fakeAuth));
+
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {
+    requestInit: { headers: { Authorization: `Bearer ${TEST_BEARER}` } },
+  });
+  const client = new Client({ name: 'e2e-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(transport);
+  cleanups.push(async () => {
+    await client.close();
+  });
+  return client;
+}
+
+afterEach(async () => {
+  for (const c of cleanups.splice(0)) await c().catch(() => {});
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+describe('MCP over real Streamable-HTTP transport', () => {
+  it('initializes, discovers, and lists the proxied tools with their schemas verbatim', async () => {
+    const client = await connectClient();
+    const { tools } = await client.listTools();
+    const byName = Object.fromEntries(tools.map((t) => [t.name, t]));
+
+    expect(Object.keys(byName).sort()).toEqual(['ask', 'boom', 'call_tool_chain', 'list_tools', 'tools_info']);
+    // The {body} envelope the manual carries reaches the client untouched.
+    expect((byName.ask.inputSchema as any).properties.body.properties.prompt).toBeDefined();
+  });
+
+  it('calls a tool end-to-end and returns the result text', async () => {
+    const client = await connectClient();
+    const res = await client.callTool({ name: 'ask', arguments: { body: { prompt: 'hello' } } });
+    // The whole structured result is stringified, so the answer text and the
+    // returned sessionId both survive for a client without proxy auto-inject.
+    const payload = JSON.parse((res.content as Array<{ text: string }>)[0].text);
+    expect(payload.text).toBe('echo: hello sid=NONE');
+    expect(payload.sessionId).toBe('sess-1');
+    expect(res.isError).toBeFalsy();
+  });
+
+  it('continuity is the caller\'s: an echoed sessionId reaches the tool verbatim', async () => {
+    const client = await connectClient();
+    // First call: no sessionId → the tool starts a conversation and returns
+    // 'sess-1' in the (fully stringified) result for the caller to read.
+    const res1 = await client.callTool({ name: 'ask', arguments: { body: { prompt: 'one' } } });
+    const first = JSON.parse((res1.content as Array<{ text: string }>)[0].text);
+    expect(first.text).toBe('echo: one sid=NONE');
+    expect(first.sessionId).toBe('sess-1');
+    // Second call: the CALLER echoes the id per the tool's schema — the proxy
+    // passes it through untouched, no server-side injection.
+    const res2 = await client.callTool({
+      name: 'ask',
+      arguments: { body: { prompt: 'two', sessionId: first.sessionId } },
+    });
+    expect(JSON.parse((res2.content as Array<{ text: string }>)[0].text).text).toBe('echo: two sid=sess-1');
+  });
+
+  it('surfaces a downstream tool failure as an MCP isError result', async () => {
+    const client = await connectClient();
+    const res = await client.callTool({ name: 'boom', arguments: {} });
+    expect(res.isError).toBe(true);
+    expect((res.content as Array<{ text: string }>)[0].text).toMatch(/kaboom/i);
+  });
+});

package/src/modules/mcp/__tests__/mcp.routes.delete.test.ts

@@ -0,0 +1,92 @@
+import type { Server as HttpServer } from 'node:http';
+import type { RequestHandler } from 'express';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { TokenNotFoundError, TokenStillActiveError } from '../../tool-auth/external-api-key.errors.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+
+/**
+ * Focused coverage for the status mapping of
+ *   DELETE /api/mcp/external-api-keys/:id/permanent
+ * The MCP e2e test exercises transport/proxy behaviour but never this route, so
+ * this locks down how the handler translates the service's error types into
+ * HTTP status codes (404 / 409 / 500) and the success shape.
+ */
+
+// Stand-in auth: bind a user like the real jwtAuthMiddleware does.
+const fakeAuth: RequestHandler = (req, _res, next) => {
+  req.userId = 'user-A';
+  next();
+};
+
+let httpServer: HttpServer | undefined;
+
+afterEach(async () => {
+  if (httpServer) {
+    await new Promise<void>((resolve) => httpServer!.close(() => resolve()));
+    httpServer = undefined;
+  }
+  vi.restoreAllMocks();
+});
+
+async function mountWithRemove(
+  remove: IExternalApiKeyService['remove'],
+): Promise<{ baseUrl: string; remove: ReturnType<typeof vi.fn> }> {
+  const spy = vi.fn(remove);
+  const externalApiKeyService = { remove: spy } as unknown as IExternalApiKeyService;
+  // createMcpRoutes only touches mcpService.onSessionEvicted at construction.
+  const mcpService = { onSessionEvicted: () => {} } as never;
+  const stub = {} as never;
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createMcpRoutes(mcpService, externalApiKeyService, fakeAuth, fakeAuth, stub));
+
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return { baseUrl: `http://127.0.0.1:${port}`, remove: spy };
+}
+
+async function del(baseUrl: string, id: string): Promise<Response> {
+  return fetch(`${baseUrl}/api/mcp/external-api-keys/${id}/permanent`, { method: 'DELETE' });
+}
+
+describe('DELETE /mcp/external-api-keys/:id/permanent', () => {
+  it('returns 200 { status: "deleted" } and forwards id + userId on success', async () => {
+    const { baseUrl, remove } = await mountWithRemove(async () => {});
+    const res = await del(baseUrl, 'tok-1');
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toEqual({ status: 'deleted' });
+    expect(remove).toHaveBeenCalledWith('tok-1', 'user-A');
+  });
+
+  it('maps TokenNotFoundError to 404', async () => {
+    const { baseUrl } = await mountWithRemove(async () => {
+      throw new TokenNotFoundError('nope');
+    });
+    const res = await del(baseUrl, 'missing');
+    expect(res.status).toBe(404);
+    await expect(res.json()).resolves.toEqual({ error: 'nope' });
+  });
+
+  it('maps TokenStillActiveError to 409', async () => {
+    const { baseUrl } = await mountWithRemove(async () => {
+      throw new TokenStillActiveError('still active');
+    });
+    const res = await del(baseUrl, 'live');
+    expect(res.status).toBe(409);
+    await expect(res.json()).resolves.toEqual({ error: 'still active' });
+  });
+
+  it('maps any other error to 500', async () => {
+    const { baseUrl } = await mountWithRemove(async () => {
+      throw new Error('boom');
+    });
+    const res = await del(baseUrl, 'oops');
+    expect(res.status).toBe(500);
+    await expect(res.json()).resolves.toEqual({ error: 'boom' });
+  });
+});