create-ailk 0.12.0 → 0.13.0

package/templates/apps/mcp/__tests__/workspace-surface.test.ts

@@ -0,0 +1,364 @@
+// oss: false
+/**
+ * The signed-in workspace surface at the transport (#3591 D15, D16 — spec
+ * AC-5 and AC-6).
+ *
+ * Two real servers on ephemeral ports: apps/mcp's HTTP transport, and a stub
+ * of apps/api that answers every twin route and REFUSES any request whose
+ * `Authorization` header is not the caller's key — so a tool that forwarded
+ * no key, or another one, fails here rather than passing on a mock.
+ *
+ * - each of the eleven tools forwards the caller's key to its twin route's
+ *   path, with its query and body, and returns the twin's `data`;
+ * - a POST to `/mcp/workspace` with no key, a personal-token-shaped key or
+ *   another scheme is 401, and the stub sees no call;
+ * - GET and DELETE are 405; a JSON-RPC batch is 400;
+ * - when the stub answers 403 the tool error carries the code and status,
+ *   never the key;
+ * - `/mcp` is unchanged: a key sent there changes nothing, and it lists no
+ *   workspace tool.
+ *
+ * No fixture holds a key-shaped literal: the key is built at run time.
+ */
+
+import { createServer, type IncomingMessage, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+
+import type { FastifyInstance } from "fastify";
+
+import { SITE_ARGS, SITE_WIRE } from "../../../tests/parity/api-parity/fixtures/site-wire";
+import { buildHttpTransportApp } from "../src/http-transport.js";
+import { listRegisteredTools } from "../src/server.js";
+import { listWorkspaceTools } from "../src/workspace-server.js";
+
+const KEY = ["ailk", "agt", "w".repeat(43)].join("_");
+const PERSONAL_TOKEN = ["tok", "x".repeat(40)].join("_");
+
+const CONFIG = {
+  path: "/mcp",
+  stateless: true,
+  rateLimits: { readPerMin: 1000, writePerMin: 1000 },
+  cors: { writeAllowedOrigins: [] as string[] },
+  abuse: { captureLeadDailyCapPerIp: 50, blockedUserAgents: "" },
+} as const;
+
+const WS = SITE_ARGS.get_inbox_message.workspaceId;
+const LEAD = SITE_ARGS.get_inbox_message.leadId;
+const LISTING = SITE_ARGS.get_inbox_application.id;
+
+/** Each tool: the twin request the stub must see, and the `data` it answers. */
+const TWINS: ReadonlyArray<{
+  tool: keyof typeof SITE_WIRE;
+  method: string;
+  path: string;
+  body?: unknown;
+}> = [
+  { tool: "get_agent_context", method: "GET", path: "/v1/agent/context" },
+  {
+    tool: "list_inbox_messages",
+    method: "GET",
+    path: `/v1/workspaces/${WS}/messages?limit=25`,
+  },
+  {
+    tool: "get_inbox_message",
+    method: "GET",
+    path: `/v1/workspaces/${WS}/messages/${LEAD}`,
+  },
+  {
+    tool: "mark_inbox_message_done",
+    method: "PATCH",
+    path: `/v1/workspaces/${WS}/messages/${LEAD}`,
+    body: { handled: true },
+  },
+  {
+    tool: "accept_inbox_message",
+    method: "POST",
+    path: `/v1/workspaces/${WS}/messages/${LEAD}/accept`,
+    body: { accept: true },
+  },
+  {
+    tool: "list_inbox_submissions",
+    method: "GET",
+    path: `/v1/workspaces/${WS}/submissions?limit=25&state=unhandled`,
+  },
+  {
+    tool: "get_inbox_submission",
+    method: "GET",
+    path: `/v1/workspaces/${WS}/submissions/${LEAD}`,
+  },
+  {
+    tool: "mark_inbox_submission_done",
+    method: "PATCH",
+    path: `/v1/workspaces/${WS}/submissions/${LEAD}`,
+    body: { handled: true },
+  },
+  {
+    tool: "list_inbox_applications",
+    method: "GET",
+    path: "/v1/project-listings",
+  },
+  {
+    tool: "get_inbox_application",
+    method: "GET",
+    path: `/v1/project-listings/${LISTING}`,
+  },
+  {
+    tool: "decide_inbox_application",
+    method: "PATCH",
+    path: `/v1/project-listings/${LISTING}`,
+    body: { status: "active" },
+  },
+];
+
+// ── The apps/api stub ────────────────────────────────────────────────────────
+
+interface SeenCall {
+  method: string;
+  path: string;
+  authorization: string | undefined;
+  body: unknown;
+}
+
+let api: Server;
+let seen: SeenCall[] = [];
+/** When set, every call is answered with this refusal instead. */
+let refuseWith: { status: number; code: string } | null = null;
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  let text = "";
+  for await (const chunk of req) text += chunk;
+  return text === "" ? undefined : JSON.parse(text);
+}
+
+function startApiStub(): Promise<Server> {
+  const server = createServer(async (req, res) => {
+    const body = await readBody(req);
+    seen.push({
+      method: req.method ?? "",
+      path: req.url ?? "",
+      authorization: req.headers["authorization"],
+      body,
+    });
+    const send = (status: number, payload: unknown) => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(payload));
+    };
+    // The stub is apps/api's one check: no key, no data.
+    if (req.headers["authorization"] !== `Bearer ${KEY}`) {
+      return send(401, {
+        ok: false,
+        error: { code: "unauthorized", message: "Authentication required" },
+      });
+    }
+    if (refuseWith) {
+      return send(refuseWith.status, {
+        ok: false,
+        error: { code: refuseWith.code, message: "Refused" },
+      });
+    }
+    const twin = TWINS.find(
+      (t) => t.method === req.method && t.path === req.url,
+    );
+    if (!twin) {
+      return send(404, {
+        ok: false,
+        error: { code: "not_found", message: "No such route" },
+      });
+    }
+    return send(200, { ok: true, data: SITE_WIRE[twin.tool] });
+  });
+  return new Promise((resolve) =>
+    server.listen(0, "127.0.0.1", () => resolve(server)),
+  );
+}
+
+// ── The apps/mcp transport ───────────────────────────────────────────────────
+
+let app: FastifyInstance;
+let port: number;
+const priorModules = process.env.AILK_ENABLED_MODULES;
+const priorApiUrl = process.env.AILK_API_URL;
+
+beforeAll(async () => {
+  process.env.AILK_ENABLED_MODULES = "workspace,multi-tenant,signal-collectors";
+  api = await startApiStub();
+  process.env.AILK_API_URL = `http://127.0.0.1:${(api.address() as AddressInfo).port}`;
+  app = await buildHttpTransportApp(CONFIG);
+  await app.listen({ host: "127.0.0.1", port: 0 });
+  port = (app.server.address() as AddressInfo).port;
+});
+
+afterAll(async () => {
+  await app.close();
+  await new Promise((resolve) => api.close(resolve));
+  if (priorModules === undefined) delete process.env.AILK_ENABLED_MODULES;
+  else process.env.AILK_ENABLED_MODULES = priorModules;
+  if (priorApiUrl === undefined) delete process.env.AILK_API_URL;
+  else process.env.AILK_API_URL = priorApiUrl;
+});
+
+beforeEach(() => {
+  seen = [];
+  refuseWith = null;
+});
+
+type JsonRpcResponse = {
+  result?: {
+    tools?: { name: string }[];
+    content?: { type: string; text: string }[];
+    isError?: boolean;
+  };
+  error?: { code: number; message: string };
+};
+
+function rpc(method: string, params: object = {}, id = 1) {
+  return { jsonrpc: "2.0", id, method, params };
+}
+
+function post(
+  path: string,
+  payload: unknown,
+  headers: Record<string, string> = {},
+): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}${path}`, {
+    method: "POST",
+    body: JSON.stringify(payload),
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+      ...headers,
+    },
+  });
+}
+
+const withKey = { authorization: `Bearer ${KEY}` };
+
+async function callTool(name: string, args: object) {
+  const res = await post(
+    "/mcp/workspace",
+    rpc("tools/call", { name, arguments: args }),
+    withKey,
+  );
+  expect(res.status).toBe(200);
+  const text = await res.text();
+  const body = JSON.parse(text) as JsonRpcResponse;
+  return { text, result: body.result! };
+}
+
+// ── AC-5 — the eleven tools forward the key to their twins ───────────────────
+
+describe("/mcp/workspace — each tool forwards the caller's key to its twin (AC-5)", () => {
+  it("lists exactly the eleven signed-in tools", async () => {
+    const res = await post("/mcp/workspace", rpc("tools/list"), withKey);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as JsonRpcResponse;
+    const names = body.result!.tools!.map((t) => t.name);
+    expect(names).toEqual(TWINS.map((t) => t.tool));
+    expect(names).toEqual(listWorkspaceTools());
+  });
+
+  it.each(TWINS)(
+    "$tool → $method $path, with the key, returning the twin's data",
+    async ({ tool, method, path, body }) => {
+      const { result } = await callTool(tool, SITE_ARGS[tool]);
+      expect(seen).toEqual([
+        { method, path, authorization: `Bearer ${KEY}`, body },
+      ]);
+      expect(result.isError).toBeFalsy();
+      expect(JSON.parse(result.content![0]!.text)).toEqual({
+        ok: true,
+        data: SITE_WIRE[tool],
+      });
+    },
+  );
+});
+
+describe("/mcp/workspace — refused before any tool runs (AC-5)", () => {
+  const call = rpc("tools/call", {
+    name: "list_inbox_messages",
+    arguments: SITE_ARGS.list_inbox_messages,
+  });
+
+  it.each<[string, Record<string, string>]>([
+    ["no Authorization header", {}],
+    [
+      "a personal-token-shaped bearer",
+      { authorization: `Bearer ${PERSONAL_TOKEN}` },
+    ],
+    ["an agent key under another scheme", { authorization: `Basic ${KEY}` }],
+    ["a truncated agent key", { authorization: `Bearer ${KEY.slice(0, -1)}` }],
+  ])("%s is 401, and apps/api sees no call", async (_label, headers) => {
+    const res = await post("/mcp/workspace", call, headers);
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: "unauthorized" });
+    expect(seen).toEqual([]);
+  });
+
+  it.each(["GET", "DELETE"])("%s is 405 — the path keeps no session", async (method) => {
+    const res = await fetch(`http://127.0.0.1:${port}/mcp/workspace`, {
+      method,
+      headers: withKey,
+    });
+    expect(res.status).toBe(405);
+    expect(res.headers.get("allow")).toBe("POST");
+  });
+
+  it("a JSON-RPC batch is 400, and no call in it runs", async () => {
+    const res = await post(
+      "/mcp/workspace",
+      [call, { ...call, id: 2 }],
+      withKey,
+    );
+    expect(res.status).toBe(400);
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("/mcp/workspace — a refusal from apps/api (AC-5)", () => {
+  it("a 403 becomes a tool error carrying the code and status, never the key", async () => {
+    refuseWith = { status: 403, code: "forbidden" };
+    const { text, result } = await callTool(
+      "decide_inbox_application",
+      SITE_ARGS.decide_inbox_application,
+    );
+    expect(seen).toHaveLength(1);
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content![0]!.text)).toEqual({
+      ok: false,
+      error: { code: "forbidden", status: 403 },
+    });
+    expect(text).not.toContain(KEY);
+  });
+});
+
+// ── AC-6 — the anonymous /mcp is unchanged ───────────────────────────────────
+
+describe("/mcp — the anonymous surface never reads Authorization (AC-6)", () => {
+  async function listAt(headers: Record<string, string>) {
+    const res = await post("/mcp", rpc("tools/list"), headers);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as JsonRpcResponse;
+    return body.result!.tools!.map((t) => t.name);
+  }
+
+  it("lists the same anonymous tools with or without an agent key, and no workspace tool", async () => {
+    const bare = await listAt({});
+    expect(await listAt(withKey)).toEqual(bare);
+    expect(bare.sort()).toEqual(listRegisteredTools().map((t) => t.name).sort());
+    for (const name of TWINS.map((t) => t.tool)) {
+      expect(bare).not.toContain(name);
+    }
+  });
+
+  it("does not serve a workspace tool, even to a caller holding a key", async () => {
+    const res = await post(
+      "/mcp",
+      rpc("tools/call", { name: "get_agent_context", arguments: {} }),
+      withKey,
+    );
+    const text = await res.text();
+    expect(text).toMatch(/get_agent_context/);
+    expect(text).toMatch(/not found/i);
+    expect(seen).toEqual([]);
+  });
+});

package/templates/apps/mcp/src/http-transport.ts

@@ -16,16 +16,28 @@
  * The server is stateless: each initialize request creates a fresh
  * StreamableHTTPServerTransport + McpServer pair. Session IDs are not
  * persisted across restarts (acceptable for OSS; paid layer adds durability).
+ *
+ * The anonymous `config.path` never reads `Authorization`. Beside it,
+ * `${config.path}/workspace` serves the signed-in workspace tools (#3591 D15):
+ * POST only and always stateless, each request carrying an agent key that is
+ * handed to that request's tools and nothing else — see
+ * {@link registerWorkspaceRoute}.
  */
 
 import { randomUUID } from "node:crypto";
+import type { IncomingMessage } from "node:http";
 
 import cors from "@fastify/cors";
 import rateLimit from "@fastify/rate-limit";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import Fastify, { type FastifyInstance, type FastifyRequest } from "fastify";
+import Fastify, {
+  type FastifyInstance,
+  type FastifyReply,
+  type FastifyRequest,
+} from "fastify";
 
 import {
   AbuseGuard,
@@ -33,6 +45,7 @@ import {
   type AbuseConfig,
 } from "./abuse/index.js";
 import { createMcpServer } from "./server.js";
+import { createWorkspaceMcpServer } from "./workspace-server.js";
 
 /**
  * HTTP status for each {@link AbuseReasonCode} an AbuseGuard refusal can
@@ -170,6 +183,96 @@ function isOriginAllowedForWrite(
   return allowedOrigins.includes(origin);
 }
 
+/**
+ * An agent key's shape (#3591 D2): `ailk_agt_` plus 32 random bytes in
+ * base64url. apps/mcp checks only this; apps/api is where the key is checked.
+ */
+const AGENT_BEARER = /^Bearer (ailk_agt_[A-Za-z0-9_-]{43})$/;
+
+/** The agent key an `Authorization` header carries, or null. */
+function agentKeyOf(header: string | string[] | undefined): string | null {
+  if (typeof header !== "string") return null;
+  return AGENT_BEARER.exec(header)?.[1] ?? null;
+}
+
+/**
+ * The signed-in workspace surface (#3591 D15) at `path`: POST only, always
+ * stateless — a fresh transport and `createWorkspaceMcpServer()` per request,
+ * closed when the response ends, and no session map, so GET and DELETE are
+ * 405. In order, a POST must:
+ *
+ *  1. carry `Authorization: Bearer ailk_agt_<43 base64url>` — else 401 in
+ *     `onRequest`, before the body is read and before any tool runs. A
+ *     personal token (`tok_…`) is refused here like any other shape;
+ *  2. be one JSON-RPC message — a batch (array) body is 400;
+ *  3. pass the abuse guard's User-Agent check.
+ *
+ * Rate limiting is apps/api's per-agent limiter, which every forwarded call
+ * meets after the key is verified (D4); the app-wide per-IP limit still
+ * applies here. The key is attached as the SDK's `req.auth` for this request
+ * only, which the SDK hands each tool as `extra.authInfo`.
+ */
+function registerWorkspaceRoute(
+  app: FastifyInstance,
+  path: string,
+  abuseGuard: AbuseGuard,
+): void {
+  const notAllowed = async (_request: FastifyRequest, reply: FastifyReply) =>
+    reply
+      .code(405)
+      .header("allow", "POST")
+      .send({ error: "method_not_allowed" });
+  app.get(path, notAllowed);
+  app.delete(path, notAllowed);
+
+  app.post(path, {
+    onRequest: async (request, reply) => {
+      if (agentKeyOf(request.headers["authorization"]) === null) {
+        return reply.code(401).send({ error: "unauthorized" });
+      }
+    },
+    preHandler: async (request, reply) => {
+      if (Array.isArray(request.body)) {
+        return reply.code(400).send({ error: "batch_not_supported" });
+      }
+      const ua = abuseGuard.validate("__read__", {}, request);
+      if (!ua.allowed) {
+        return reply.code(403).send({ error: ua.reason });
+      }
+    },
+    handler: async (request, reply) => {
+      const raw = request.raw as IncomingMessage & { auth?: AuthInfo };
+      raw.auth = {
+        token: agentKeyOf(request.headers["authorization"])!,
+        clientId: "ailk-agent",
+        scopes: [],
+      };
+      const transport = new StreamableHTTPServerTransport({
+        enableJsonResponse: true,
+      });
+      const server = createWorkspaceMcpServer();
+      try {
+        // The cast is the same exactOptionalPropertyTypes one the anonymous
+        // route carries.
+        await server.connect(transport as unknown as Transport);
+        await transport.handleRequest(raw, reply.raw, request.body);
+      } catch (err) {
+        if (!reply.sent) {
+          reply.code(500).send({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Internal server error" },
+            id: null,
+          });
+        }
+        throw err;
+      } finally {
+        await transport.close().catch(() => undefined);
+        await server.close().catch(() => undefined);
+      }
+    },
+  });
+}
+
 /**
  * Build and return a configured Fastify instance that exposes the MCP HTTP
  * transport at `config.path`. The instance is not yet listening — callers
@@ -360,6 +463,9 @@ export async function buildHttpTransportApp(
     await transport.handleRequest(request.raw, reply.raw);
   });
 
+  // ── Signed-in workspace route (#3591 D15) ─────────────────────────────────
+  registerWorkspaceRoute(app, `${mcpPath}/workspace`, abuseGuard);
+
   return app;
 }
 

package/templates/apps/mcp/src/workspace-server.ts

@@ -0,0 +1,193 @@
+/**
+ * The signed-in workspace MCP server (#3591 D15, D16).
+ *
+ * Serves the catalog's `surface: "workspace"` tools — the agent's own context
+ * and the inbox actions — at `/mcp/workspace` (`http-transport.ts`), one
+ * fresh server per request. Each tool is the twin of one apps/api route: its
+ * handler forwards the caller's agent key to that route through
+ * `@working-theory/api-client` and returns the route's `data`.
+ *
+ * The key reaches a handler only as `extra.authInfo.token`, which the
+ * transport sets from the request's `Authorization` header for that request
+ * alone. Nothing here logs or serialises `extra`, `extra.authInfo` or
+ * `extra.requestInfo` (the SDK puts the raw `authorization` header there,
+ * SEC-3591-12), and no result carries the key: a refusal from the route is
+ * an MCP tool error naming the route's `error.code` and HTTP status only.
+ * apps/mcp checks nothing about the key beyond its shape; apps/api is the one
+ * place it is checked.
+ *
+ * A tool registers exactly when its route does: when any module in its
+ * catalog `modulesAnyOf` is enabled, the same disjunction the route's
+ * `server.ts` gate in apps/api is. The anonymous server (`server.ts`) never
+ * sees these entries — the catalog returns them only for
+ * `surface: "workspace"`.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  getMcpToolRegistrations,
+  type McpToolRegistration,
+} from "@working-theory/metadata";
+
+import { isModuleEnabled } from "./config/modules.js";
+
+/** What a twin call answers — `@working-theory/api-client`'s `ApiResult`. */
+type ForwardResult =
+  | { ok: true; body: unknown }
+  | { ok: false; status: number; body: unknown };
+
+type WorkspaceToolHandler = (
+  key: string,
+  input: unknown,
+) => Promise<ForwardResult>;
+
+/**
+ * Tool name → its handler's file and export. Every file is a paid slice the
+ * OSS strip deletes, so — exactly as `server.ts`'s `MODULE_TOOL_ENTRIES` — the
+ * specifier is read from this table, never written at an `import()` call
+ * site, which `tsc` would resolve on the stripped tree.
+ */
+const WORKSPACE_TOOL_ENTRIES: Record<
+  string,
+  { readonly specifier: string; readonly exportName: string }
+> = {
+  get_agent_context: {
+    specifier: "./tools/agent_context.js",
+    exportName: "ailkGetAgentContext",
+  },
+  list_inbox_messages: {
+    specifier: "./tools/inbox_messages.js",
+    exportName: "ailkListInboxMessages",
+  },
+  get_inbox_message: {
+    specifier: "./tools/inbox_messages.js",
+    exportName: "ailkGetInboxMessage",
+  },
+  mark_inbox_message_done: {
+    specifier: "./tools/inbox_messages.js",
+    exportName: "ailkMarkInboxMessageDone",
+  },
+  accept_inbox_message: {
+    specifier: "./tools/inbox_messages.js",
+    exportName: "ailkAcceptInboxMessage",
+  },
+  list_inbox_submissions: {
+    specifier: "./tools/inbox_submissions.js",
+    exportName: "ailkListInboxSubmissions",
+  },
+  get_inbox_submission: {
+    specifier: "./tools/inbox_submissions.js",
+    exportName: "ailkGetInboxSubmission",
+  },
+  mark_inbox_submission_done: {
+    specifier: "./tools/inbox_submissions.js",
+    exportName: "ailkMarkInboxSubmissionDone",
+  },
+  list_inbox_applications: {
+    specifier: "./tools/inbox_applications.js",
+    exportName: "ailkListInboxApplications",
+  },
+  get_inbox_application: {
+    specifier: "./tools/inbox_applications.js",
+    exportName: "ailkGetInboxApplication",
+  },
+  decide_inbox_application: {
+    specifier: "./tools/inbox_applications.js",
+    exportName: "ailkDecideInboxApplication",
+  },
+};
+
+async function resolveWorkspaceHandler(
+  name: string,
+): Promise<WorkspaceToolHandler> {
+  const entry = WORKSPACE_TOOL_ENTRIES[name];
+  if (!entry) {
+    throw new Error(`MCP catalog drift: no handler for tool '${name}'`);
+  }
+  const mod = (await import(entry.specifier)) as Record<
+    string,
+    WorkspaceToolHandler | undefined
+  >;
+  const fn = mod[entry.exportName];
+  if (!fn) {
+    throw new Error(
+      `MCP slice drift: '${entry.specifier}' does not export '${entry.exportName}'`,
+    );
+  }
+  return fn;
+}
+
+/** Whether this build registers the tool: any of its modules is enabled. */
+function isWorkspaceToolEnabled(reg: McpToolRegistration): boolean {
+  return (reg.modulesAnyOf ?? []).some((name) => isModuleEnabled(name));
+}
+
+/** The names {@link createWorkspaceMcpServer} registers on this build. */
+export function listWorkspaceTools(): string[] {
+  return getMcpToolRegistrations({ surface: "workspace" })
+    .filter(isWorkspaceToolEnabled)
+    .map((reg) => reg.name);
+}
+
+/** The route's `error.code`, or a fixed code when the body carries none. */
+function errorCodeOf(body: unknown): string {
+  if (typeof body === "object" && body !== null) {
+    const error = (body as { error?: unknown }).error;
+    if (typeof error === "object" && error !== null) {
+      const code = (error as { code?: unknown }).code;
+      if (typeof code === "string") return code;
+    }
+  }
+  return "api_error";
+}
+
+function toolError(code: string, status: number) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ ok: false, error: { code, status } }),
+      },
+    ],
+  };
+}
+
+/**
+ * Creates the signed-in workspace server: every `surface: "workspace"` catalog
+ * entry whose module is enabled, each forwarding the caller's key to its twin
+ * route. Unconnected — the transport attaches one per request.
+ */
+export function createWorkspaceMcpServer(): McpServer {
+  const server = new McpServer({ name: "ailk-workspace", version: "0.1.0" });
+
+  for (const reg of getMcpToolRegistrations({ surface: "workspace" })) {
+    if (!isWorkspaceToolEnabled(reg)) continue;
+    // Boot-time drift detection, as `server.ts` does it.
+    if (!WORKSPACE_TOOL_ENTRIES[reg.name]) {
+      throw new Error(`MCP catalog drift: no handler for tool '${reg.name}'`);
+    }
+    server.tool(
+      reg.name,
+      reg.description,
+      reg.inputShape,
+      async (input, extra) => {
+        const key = extra.authInfo?.token;
+        if (!key) return toolError("unauthorized", 401);
+        const handler = await resolveWorkspaceHandler(reg.name);
+        const res = await handler(key, input);
+        if (!res.ok) return toolError(errorCodeOf(res.body), res.status);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ ok: true, data: res.body }),
+            },
+          ],
+        };
+      },
+    );
+  }
+
+  return server;
+}