create-ailk 0.24.0 → 0.25.1

package/templates/apps/api/vercel.json

@@ -1,7 +1,7 @@
 {
   "version": 2,
-  "ignoreCommand": "[ -n \"$VERCEL_GIT_PREVIOUS_SHA\" ] && cd ../.. && git diff --quiet \"$VERCEL_GIT_PREVIOUS_SHA\" HEAD -- apps/api packages database pnpm-lock.yaml package.json pnpm-workspace.yaml turbo.json 'tsconfig*.json' || exit 1",
-  "buildCommand": "cd ../.. && pnpm run --filter @working-theory/api build:vercel",
+  "ignoreCommand": "[ -n \"$VERCEL_GIT_PREVIOUS_SHA\" ] && cd ../.. && git diff --quiet \"$VERCEL_GIT_PREVIOUS_SHA\" HEAD -- apps/api packages packages-paid database pnpm-lock.yaml package.json pnpm-workspace.yaml turbo.json 'tsconfig*.json' || exit 1",
+  "buildCommand": "cd ../.. && pnpm run --filter @working-theory/app-api build:vercel",
   "installCommand": "cd ../.. && pnpm install --frozen-lockfile",
   "outputDirectory": "public",
   "framework": null,

package/templates/apps/mcp/CLAUDE.md

@@ -8,10 +8,37 @@ Inherits root `CLAUDE.md`. This file adds MCP-specific rules.
 - Transport: stdio at launch
 - Discovery: `/.well-known/mcp.json` published from `apps/web`
 
+## The server is a package; this app is a boot set (#9460)
+
+The server — the transports, the boot sequence, the abuse guard and the 15 free tools — is
+`@working-theory/mcp-server` (`packages/mcp-server`), with two entry points: `.` and `./hub`.
+Each paid module's tools ride that module's own package (`packages-paid/mcp-scheduling`,
+`mcp-signal-collectors`, `mcp-workspace`), which base code reaches only through the generated
+registry below. A version bump of those packages is the whole of taking an MCP change.
+
+`src/` holds exactly five files, and nothing else may be added to it (`__tests__/boot-file.test.ts`
+ships to every scaffold and fails on any other import):
+
+- **`index.ts`** and **`app.ts`** — the two deployment entries (next section).
+- **`site.ts`** — builds the `McpSite` the package runs for: `{ topology, paidToolPacks }`.
+- **`lib/topology.generated.ts`** — the topology seam create-ailk renders (hub or spoke).
+- **`lib/paid-tools.generated.ts`** — the paid MCP packs this site carries, one bundled
+  `import()` each, rendered by create-ailk from `MODULE_SLICES` (`paidMcpToolPackages`) and
+  `apps/mcp/package.json`; `// oss: false` on line 1 exactly when a pack is present. The
+  monorepo copy carries all three. A module-gated or signed-in tool resolves from the union of
+  the loaded packs at call time; a registered tool whose pack a site does not carry answers the
+  tool error `MCP slice drift: no installed package serves '<name>'`.
+
+The suites that stay here are the composition root's: `api-parity`, `pro-tool-call-gate`,
+`workspace-surface`, `write-tool-guard` and `create-booking-guard` (they call paid handlers through
+the real `site.ts`), `app-entry` (the Vercel entry's source text) and `boot-file`. Everything else
+runs in the package. Paths in the sections below that name `src/<file>` other than the five above
+now mean `packages/mcp-server/src/<file>`.
+
 ## Two entrypoints, one boot (#8070)
 
 - **`src/index.ts`** — run locally: stdio (the default), or HTTP on `MCP_HTTP_PORT` with
-  `MCP_TRANSPORT=http`.
+  `MCP_TRANSPORT=http`. It is `await runMcp(site)`; the transport branch is the package's `run.ts`.
 - **`src/app.ts`** — the Vercel entry. A Vercel project whose root directory is `apps/mcp`
   detects it (it imports Fastify) and calls its default export, `serverlessHandler(app)`: a
   `(req, res)` function, the shape Vercel's Node runtime runs — a bare Fastify instance is not
@@ -22,18 +49,30 @@ Inherits root `CLAUDE.md`. This file adds MCP-specific rules.
   reads it by static analysis). `tsconfig.json` names `module` and `moduleResolution` itself:
   Vercel's type-check edits the entry's nearest `tsconfig.json` as raw JSON before `extends`,
   and without its own `module` it switches `strict` off, which fails 11 narrowing sites.
-- Both call `bootMcp()` in `src/boot.ts` before building a transport, and read the HTTP
-  configuration through `httpTransportConfigFromEnv()` there. Add a boot step to `bootMcp()`,
-  never to one entry. `src/app.ts` stays thin; what a test needs is in `src/serverless-app.ts`.
+- Both call the package's `bootMcp(site)` before building a transport, and the package reads the
+  HTTP configuration through `httpTransportConfigFromEnv()` (`packages/mcp-server/src/boot.ts`).
+  Add a boot step to `bootMcp()`, never to one entry. `src/app.ts` stays thin; what a test needs
+  is in the package's `serverless-app.ts`.
 - **`MCP_HTTP_STATELESS`** picks the transport mode: `true`/`1` stateless (no sessions; any
   instance answers), `false`/`0` stateful (sessions in one process's memory). Unset, the
   Vercel entry is stateless and `src/index.ts` is stateful. Any other value fails the boot.
   The Vercel entry needs stateless: a session kept in one instance is lost on the next.
 - **Content root.** Every content tool and `audit` take their root from `mcpContentRoot()`
   (`lib/content-adapter.ts`): `AILK_CONTENT_ROOT`, else `<cwd>/content`, else
-  `<cwd>/../../content`. Never build a content path from `process.cwd()` in a tool.
+  `<cwd>/../../content`. Never build a content path from `process.cwd()` in a tool — the one
+  standing exception is `create_project`, whose `resolveCliBin()` has always spawned
+  `<cwd>/packages/create-ailk/dist/cli.js`; its release-scope read shares that root (next).
 - **`create_project`** is not served on a spoke: the generated seam's `UNSERVED_MCP_TOOLS`
-  keeps it out of registration, and the web manifest drops the same list.
+  keeps it out of registration, and the web manifest drops the same list. It is also not
+  served while the Free level is held (#9534): it spawns a keyless scaffold, so
+  `isFreeLevelReleased()` (`tools/create_project.ts`) registers it only when
+  `<cwd>/packages/create-ailk/release-scope.json` marks `levels.free` released, and re-applies
+  that at call time. The contract that implies: the tool exists only in a monorepo checkout
+  started from the repo root — anywhere else the file is absent and so is the tool, where it
+  could not run anyway (no `dist/cli.js`). The scope FILE alone decides — a release-scope
+  decision, never a licence check, and the CLI's `AILK_RELEASE_SCOPE=ignore` bypass is not
+  honoured; a missing or unreadable file fails closed with one stderr line. apps/web's
+  `/.well-known/mcp.json` drops it on the same read (`apps/web/lib/release-scope.ts`).
 
 ### What a spoke's MCP host on Vercel enforces
 
@@ -81,21 +120,24 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 **Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has. `submit_flow_step` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP`, default 50 — #8071)
 **Booking (4):** `list_availability`, `get_event_meta`, `list_meetings`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071). `list_meetings` (#8843 D5) twins `GET /v1/schedule/meetings`: it takes no argument and returns the site's Live meetings — slug, visibility, position and whether each can be booked, plus a bookable one's calLink, title, length, description and price; `private` means unlisted, not secret
 
-### Why the parity test counts 21 and a keyless server registers 20
+### Why the parity test counts 21 and a keyless server registers 19 (20 once Free is released)
 
 - **21 in the `TOOLS` array / parity test**: the `TOOLS` array in
   `packages/metadata/src/mcp-tool-catalog.ts` defines 21 anonymous tools; the
   parity test counts that full array. It also holds the eighteen signed-in
   workspace tools (#3591), which no anonymous view returns — see § The
   signed-in workspace surface below.
-- **20 registered on a KEYLESS deployment, 21 on a commerce-claimed one**
-  (#5971): `createMcpServer` (`apps/mcp/src/server.ts`) registers
-  `getMcpToolRegistrations()` minus `OSS_DISABLED_TOOLS` (now empty), minus
-  module-gated tools whose module is off, minus any `addon`-tagged tool whose
-  claim this deployment does not hold. `start_purchase` carries
-  `addon: "commerce"`, so it is the one entry whose presence depends on the
-  licence — 20 without the claim, 21 with it.
-- **20 free anonymous tools**: since #5853 retired the three content-write
+- **19 registered on a KEYLESS deployment, 20 on a commerce-claimed one,
+  while the Free level is held — 20 and 21 once it is released**
+  (#5971, #9534): `createMcpServer` (`apps/mcp/src/server.ts`) registers
+  `getMcpToolRegistrations()` minus the topology seam's `UNSERVED_MCP_TOOLS`,
+  minus `create_project` while create-ailk's `release-scope.json` holds
+  `levels.free` (the release-scope filter, #9534), minus `OSS_DISABLED_TOOLS`
+  (now empty), minus module-gated tools whose module is off, minus any
+  `addon`-tagged tool whose claim this deployment does not hold.
+  `start_purchase` carries `addon: "commerce"`, so it is the one entry whose
+  presence depends on the licence — one fewer without the claim.
+- **19 free anonymous tools while Free is held (20 released)**: since #5853 retired the three content-write
   tools, every registered tool remains anonymous — call-time gating checks a
   licence claim, never an identity. The six carrying `tier: "pro"`
   (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
@@ -145,10 +187,11 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
   price is refused `proposal_needs_person` (a person prices). Each takes its route's params, query and body and returns the route's
   `data`. They are in the parity guard like every other tool, and never in
   `/.well-known/mcp.json`.
-- **Handlers forward, nothing else.** `workspace-server.ts` resolves each tool to a paid-slice
-  handler file (`tools/agent_context.ts`, `inbox_messages.ts`, `inbox_submissions.ts`,
-  `inbox_applications.ts`, `person_notes.ts`, `proposals.ts`, all `// oss: false`) through a
-  specifier table, as `server.ts` does. Each calls `@working-theory/api-client`'s `inbox` surface
+- **Handlers forward, nothing else.** `workspace-server.ts` resolves each tool from
+  `@working-theory/mcp-workspace`'s `workspaceTools` (`agent_context.ts`, `inbox_messages.ts`,
+  `inbox_submissions.ts`, `inbox_applications.ts`, `person_notes.ts`, `proposals.ts`, all
+  `// oss: false`), loaded through the site's generated registry, as `server.ts` resolves the
+  module-gated tools from their packs (#9460). Each calls `@working-theory/api-client`'s `inbox` surface
   (the notes and proposals tools, its `people` surface) with the key. A refusal from the
   route is an MCP tool error naming the route's `error.code` and HTTP status only.
 - **Never log or return the key.** Don't log or serialise `extra`, `extra.authInfo` or
@@ -225,7 +268,11 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-10-20 — #7171, #7172, #7173: the three lead writes adopted their routes' bodies and 201 results and are parity `twin`s — the Conversion-write line records the adopted shapes — verified against `apps/mcp/src/tools/{capture_lead,subscribe_newsletter,request_callback}.ts`, `packages/validation/src/schemas/leads.ts` and `tests/parity/api-parity/kinds/site.ts`.
+Last updated: 2026-10-22 — #9460: the server is `@working-theory/mcp-server` and the paid tools ride `packages-paid/mcp-*`; `src/` is the five-file boot set, `lib/paid-tools.generated.ts` is the one door to a paid MCP package, and the specifier tables are gone — verified against `packages/mcp-server/src/{server,workspace-server,boot,run,site}.ts`, `apps/mcp/src/{index,app,site}.ts` and `packages/create-ailk/src/paid-sections.ts`.
+
+Prior: 2026-10-22 — #9534: `create_project` registers only while create-ailk's `release-scope.json` marks the Free level released (the release-scope filter in `shouldRegister`, re-applied at call time) — 19 registered keyless and 20 claimed while Free is held — and the content-root rule names the tool's `<cwd>/packages/create-ailk` root as its standing exception — verified against `apps/mcp/src/tools/create_project.ts`, `apps/mcp/src/server.ts` and `apps/web/app/.well-known/mcp.json/route.ts`.
+
+Prior: 2026-10-20 — #7171, #7172, #7173: the three lead writes adopted their routes' bodies and 201 results and are parity `twin`s — the Conversion-write line records the adopted shapes — verified against `apps/mcp/src/tools/{capture_lead,subscribe_newsletter,request_callback}.ts`, `packages/validation/src/schemas/leads.ts` and `tests/parity/api-parity/kinds/site.ts`.
 
 Prior: 2026-10-20 — #7167, #7168, #7169: the three content reads adopted their routes' arguments and results and are parity `twin`s — the Read line records the adopted shapes — verified against `apps/mcp/src/tools/{search_content,list_pages,read_content}.ts`, `packages/validation/src/schemas/content-reads.ts`, `packages/content-adapters/src/content-reads.ts` and `tests/parity/api-parity/kinds/site.ts`.
 

package/templates/apps/mcp/__tests__/app-entry.test.ts

@@ -24,124 +24,8 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { createServer, type Server } from "node:http";
-import type { AddressInfo } from "node:net";
 import { resolve } from "node:path";
 
-import Fastify, { type FastifyInstance } from "fastify";
-
-import { buildHttpTransportApp } from "../src/http-transport.js";
-import {
-  configureServerlessApp,
-  SERVERLESS_FASTIFY_OPTIONS,
-  serverlessHandler,
-  trustOneHop,
-} from "../src/serverless-app.js";
-
-// The hub call capture_lead makes after the guard is stubbed, as
-// http-transport.test.ts stubs checkout: only the guard's verdict is asserted.
-jest.mock("@working-theory/api-client", () => {
-  const actual = jest.requireActual("@working-theory/api-client");
-  return {
-    ...actual,
-    apiClient: {
-      ...actual.apiClient,
-      leads: {
-        ...actual.apiClient.leads,
-        submit: jest.fn().mockResolvedValue({
-          ok: true,
-          body: {
-            id: "lead_00000000-0000-7000-8000-000000008070",
-            persisted: "db",
-          },
-        }),
-      },
-    },
-  };
-});
-
-const VARS = [
-  "MCP_HTTP_STATELESS",
-  "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
-  "MCP_CORS_WRITE_ALLOWED_ORIGINS",
-] as const;
-
-const saved: Partial<Record<(typeof VARS)[number], string | undefined>> = {};
-
-beforeEach(() => {
-  for (const name of VARS) {
-    saved[name] = process.env[name];
-    delete process.env[name];
-  }
-});
-
-afterEach(() => {
-  for (const name of VARS) {
-    const value = saved[name];
-    if (value === undefined) delete process.env[name];
-    else process.env[name] = value;
-  }
-});
-
-async function mcpPost(
-  port: number,
-  payload: object,
-  headers: Record<string, string> = {},
-): Promise<Response> {
-  return fetch(`http://127.0.0.1:${port}/mcp`, {
-    method: "POST",
-    body: JSON.stringify(payload),
-    headers: {
-      "content-type": "application/json",
-      accept: "application/json, text/event-stream",
-      ...headers,
-    },
-  });
-}
-
-async function listen(app: FastifyInstance): Promise<number> {
-  await app.listen({ host: "127.0.0.1", port: 0 });
-  return (app.server.address() as AddressInfo).port;
-}
-
-/** The app src/app.ts builds, minus the boot and the default export. */
-async function serverlessApp(): Promise<FastifyInstance> {
-  const app = Fastify(SERVERLESS_FASTIFY_OPTIONS);
-  await configureServerlessApp(app);
-  await app.ready();
-  return app;
-}
-
-/** Serve the app through the exact function Vercel's Node runtime calls. */
-async function serveHandler(
-  app: FastifyInstance,
-): Promise<{ server: Server; port: number }> {
-  const server = createServer(serverlessHandler(app));
-  await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
-  return { server, port: (server.address() as AddressInfo).port };
-}
-
-async function stop(server: Server | undefined): Promise<void> {
-  if (!server) return;
-  await new Promise<void>((done) => server.close(() => done()));
-}
-
-function captureLead(id: number, name: string): object {
-  return {
-    jsonrpc: "2.0",
-    id,
-    method: "tools/call",
-    params: {
-      name: "capture_lead",
-      arguments: {
-        source: "mcp",
-        email: `${name.toLowerCase()}@example.com`,
-        payload: { name, message: "Interested in your services." },
-      },
-    },
-  };
-}
-
 describe("AC-4 — src/app.ts, read as source text", () => {
   const src = readFileSync(resolve(__dirname, "../src/app.ts"), "utf-8");
 
@@ -150,17 +34,17 @@ describe("AC-4 — src/app.ts, read as source text", () => {
   });
 
   it("awaits the shared boot, builds Fastify from the serverless options and configures it", () => {
-    expect(src).toContain("await bootMcp()");
+    expect(src).toContain("await bootMcp(site)");
     expect(src).toContain("Fastify(SERVERLESS_FASTIFY_OPTIONS)");
-    expect(src).toContain("configureServerlessApp(app)");
+    expect(src).toContain("configureServerlessApp(app, site)");
   });
 
   it("boots before it builds the app, and readies it before it exports", () => {
-    expect(src.indexOf("await bootMcp()")).toBeLessThan(
+    expect(src.indexOf("await bootMcp(site)")).toBeLessThan(
       src.indexOf("Fastify(SERVERLESS_FASTIFY_OPTIONS)"),
     );
     expect(src).toContain("await app.ready()");
-    expect(src.indexOf("configureServerlessApp(app)")).toBeLessThan(
+    expect(src.indexOf("configureServerlessApp(app, site)")).toBeLessThan(
       src.indexOf("await app.ready()"),
     );
   });
@@ -189,137 +73,3 @@ describe("AC-13 — Vercel's type-check keeps strict", () => {
     expect(existsSync(resolve(__dirname, "../vercel.json"))).toBe(false);
   });
 });
-
-describe("AC-4 — the serverless options and the configured app", () => {
-  let app: FastifyInstance | undefined;
-  let server: Server | undefined;
-  let port = 0;
-
-  afterEach(async () => {
-    await stop(server);
-    await app?.close();
-    app = undefined;
-    server = undefined;
-  });
-
-  it("SERVERLESS_FASTIFY_OPTIONS is { logger: false, trustProxy: trustOneHop }", () => {
-    expect(SERVERLESS_FASTIFY_OPTIONS).toEqual({
-      logger: false,
-      trustProxy: trustOneHop,
-    });
-  });
-
-  it("trustOneHop trusts the immediate peer (hop 0) and nothing behind it, whatever its address", () => {
-    expect(trustOneHop("127.0.0.1", 0)).toBe(true);
-    expect(trustOneHop("10.0.0.1", 0)).toBe(true);
-    expect(trustOneHop("9.9.9.9", 1)).toBe(false);
-    expect(trustOneHop("1.1.1.1", 2)).toBe(false);
-  });
-
-  it("why not trustProxy: 1 — this Fastify treats a numeric hop count as trust-nothing", async () => {
-    const numeric = Fastify({ logger: false, trustProxy: 1 });
-    numeric.get("/ip", async (request) => ({ ip: request.ip }));
-    const res = await numeric.inject({
-      url: "/ip",
-      remoteAddress: "127.0.0.1",
-      headers: { "x-forwarded-for": "3.3.3.3, 8.8.8.8" },
-    });
-    await numeric.close();
-
-    // Every caller would key on the edge's address.
-    expect(res.json()).toEqual({ ip: "127.0.0.1" });
-  });
-
-  it("serverlessHandler(app) is a (req, res) function", async () => {
-    app = await serverlessApp();
-    expect(typeof serverlessHandler(app)).toBe("function");
-  });
-
-  it("with MCP_HTTP_STATELESS unset, an http.createServer serving serverlessHandler(app) answers initialize and then a session-less tools/list", async () => {
-    app = await serverlessApp();
-    ({ server, port } = await serveHandler(app));
-
-    const init = await mcpPost(port, {
-      jsonrpc: "2.0",
-      id: 1,
-      method: "initialize",
-      params: {
-        protocolVersion: "2025-03-26",
-        capabilities: {},
-        clientInfo: { name: "app-entry-test", version: "1.0.0" },
-      },
-    });
-    expect(init.status).toBe(200);
-    const initBody = (await init.json()) as {
-      result?: { serverInfo?: { name?: string } };
-    };
-    expect(initBody.result?.serverInfo).toMatchObject({ name: "ailk" });
-
-    const list = await mcpPost(port, {
-      jsonrpc: "2.0",
-      id: 2,
-      method: "tools/list",
-      params: {},
-    });
-    expect(list.status).toBe(200);
-  });
-});
-
-describe("AC-5 — the daily cap keys on the last X-Forwarded-For hop", () => {
-  let app: FastifyInstance | undefined;
-  let server: Server | undefined;
-
-  afterEach(async () => {
-    await stop(server);
-    await app?.close();
-    app = undefined;
-    server = undefined;
-  });
-
-  it("serverless app: two callers sharing a last hop are one caller; a different last hop is another", async () => {
-    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] = "1";
-    // Set explicitly so the write-origin check is never what refuses a call.
-    process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] = "*";
-    app = await serverlessApp();
-    const { server: served, port } = await serveHandler(app);
-    server = served;
-
-    const first = await mcpPost(port, captureLead(10, "First"), {
-      "x-forwarded-for": "1.1.1.1, 9.9.9.9",
-    });
-    expect(first.status).toBe(200);
-
-    const second = await mcpPost(port, captureLead(11, "Second"), {
-      "x-forwarded-for": "2.2.2.2, 9.9.9.9",
-    });
-    expect(second.status).toBe(403);
-    const refusal = (await second.json()) as { error?: string };
-    expect(refusal.error).toBe("daily capture_lead cap reached for this IP");
-
-    const third = await mcpPost(port, captureLead(12, "Third"), {
-      "x-forwarded-for": "3.3.3.3, 8.8.8.8",
-    });
-    expect(third.status).toBe(200);
-  });
-
-  it("long-running app (no trustProxy): the header is ignored — every call is the socket's address", async () => {
-    app = await buildHttpTransportApp({
-      path: "/mcp",
-      stateless: true,
-      rateLimits: { readPerMin: 60, writePerMin: 10 },
-      cors: { writeAllowedOrigins: ["*"] },
-      abuse: { captureLeadDailyCapPerIp: 1, blockedUserAgents: "" },
-    });
-    const port = await listen(app);
-
-    const first = await mcpPost(port, captureLead(20, "First"), {
-      "x-forwarded-for": "3.3.3.3",
-    });
-    expect(first.status).toBe(200);
-
-    const second = await mcpPost(port, captureLead(21, "Second"), {
-      "x-forwarded-for": "4.4.4.4",
-    });
-    expect(second.status).toBe(403);
-  });
-});

package/templates/apps/mcp/__tests__/boot-file.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The boot set is a boot set (#9460 AC-1 (a)).
+ *
+ * Every file under `src/` may import only `@working-theory/mcp-server`, its
+ * `/hub` entry, `fastify`, the type-only `@working-theory/content-adapters`,
+ * the site's own `./site.js` and `./lib/*.generated.js` — and, inside
+ * `lib/paid-tools.generated.ts` alone, the paid MCP packs. A boot file that
+ * imported `@working-theory/validation`, `@working-theory/api-client` or a
+ * tool module would rebuild the coupling that broke 0.45.0; a deep import
+ * such as `@working-theory/mcp-server/dist/tools/get_faq.js` is one a bump
+ * would not keep stable. This suite ships to every scaffold, so a keyless
+ * site re-checks itself.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const SRC = resolve(__dirname, "../src");
+
+const ALLOWED = new Set([
+  "@working-theory/mcp-server",
+  "@working-theory/mcp-server/hub",
+  "fastify",
+  "@working-theory/content-adapters",
+]);
+const PAID_PACKS = new Set([
+  "@working-theory/mcp-scheduling",
+  "@working-theory/mcp-signal-collectors",
+  "@working-theory/mcp-workspace",
+]);
+const REGISTRY = "lib/paid-tools.generated.ts";
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) walk(p, out);
+    else if (p.endsWith(".ts")) out.push(p);
+  }
+  return out;
+}
+
+/** Every static and dynamic import specifier in `text`. */
+function specifiers(text: string): string[] {
+  return [...text.matchAll(/(?:from|import)\s*\(?\s*"([^"]+)"/g)].map(
+    (m) => m[1]!,
+  );
+}
+
+function allowedFor(file: string, spec: string): boolean {
+  if (ALLOWED.has(spec)) return true;
+  if (spec === "./site.js" || /^\.\/lib\/[\w-]+\.generated\.js$/.test(spec))
+    return true;
+  return file === REGISTRY && PAID_PACKS.has(spec);
+}
+
+describe("apps/mcp/src is the boot set (#9460 AC-1)", () => {
+  const files = walk(SRC).map((p) => relative(SRC, p).split("\\").join("/"));
+
+  it("holds exactly the five boot files", () => {
+    expect(files.sort()).toEqual([
+      "app.ts",
+      "index.ts",
+      "lib/paid-tools.generated.ts",
+      "lib/topology.generated.ts",
+      "site.ts",
+    ]);
+  });
+
+  it.each(files)(
+    "%s imports only the package, fastify and the site's own files",
+    (file) => {
+      const text = readFileSync(join(SRC, file), "utf8");
+      const specs = specifiers(text);
+      expect(specs.filter((spec) => !allowedFor(file, spec))).toEqual([]);
+    },
+  );
+
+  it("no boot file imports a tool, a schema or the api client", () => {
+    for (const file of files) {
+      const specs = specifiers(readFileSync(join(SRC, file), "utf8"));
+      expect(
+        specs.filter(
+          (spec) =>
+            spec.includes("/dist/") ||
+            spec.includes("/tools/") ||
+            spec === "@working-theory/validation" ||
+            spec === "@working-theory/api-client",
+        ),
+      ).toEqual([]);
+    }
+  });
+});

package/templates/apps/mcp/jest.config.cjs

@@ -1,6 +1,11 @@
+// Only so the handler suite's spawned create-ailk CLI scaffolds keyless (Free
+// is held): the registration gate (`isFreeLevelReleased`) never reads it (#9534).
+process.env.AILK_RELEASE_SCOPE = "ignore";
+
 module.exports = {
   preset: 'ts-jest',
   globalSetup: require.resolve('../../tools/jest/pin-timezone.cjs'),
+  reporters: require('../../tools/jest/reporters.cjs'),
   testEnvironment: 'node',
   // Workaround: @hono/node-server@1.19.14 (transitive via
   // @modelcontextprotocol/sdk's StreamableHTTPServerTransport) calls
@@ -21,7 +26,7 @@ module.exports = {
     // fresh checkout, and the published dist is ESM, which Jest's CJS preset
     // can't load. The CLIENT root (`@working-theory/database`) stays
     // deliberately UNMAPPED — see apps/mcp/src/lib/prisma.ts.
-    '^@working-theory/database/tenancy$': '<rootDir>/../../database/tenancy.ts',
+    '^@working-theory/database/tenancy$': '<rootDir>/node_modules/@working-theory/database/dist/tenancy.js',
     '^(\\.{1,2}/.*)\\.js$': '$1',
   },
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],

package/templates/apps/mcp/package.json

@@ -16,25 +16,17 @@
     "test:coverage": "jest --coverage"
   },
   "dependencies": {
-    "@fastify/cors": "^11.2.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@modelcontextprotocol/sdk": "^1.31.0",
     "@prisma/adapter-pg": "^7.8.0",
-    "@working-theory/aeo": "workspace:*",
-    "@working-theory/api-client": "workspace:*",
     "@working-theory/content-adapters": "workspace:*",
     "@working-theory/database": "workspace:*",
-    "@working-theory/license": "workspace:*",
-    "@working-theory/metadata": "workspace:*",
-    "@working-theory/schema": "workspace:*",
-    "@working-theory/site-config": "workspace:*",
-    "@working-theory/validation": "workspace:*",
-    "fastify": "^5.12.5",
-    "yaml": "^2.9.0",
-    "zod": "^4.2.1"
+    "@working-theory/mcp-server": "workspace:*",
+    "fastify": "^5.12.5"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@types/jest": "^30.0.0",
+    "@working-theory/api-client": "workspace:*",
+    "@working-theory/metadata": "workspace:*",
     "@types/node": "^22.20.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",

package/templates/apps/mcp/src/app.ts

@@ -10,23 +10,24 @@
  * warm instance reuses the booted app.
  *
  * Run locally, use `src/index.ts` (stdio, or HTTP on MCP_HTTP_PORT) instead.
- * Everything testable lives in `serverless-app.ts`.
+ * Everything testable lives in `@working-theory/mcp-server` (#9460).
  */
 
-import Fastify from "fastify";
-
-import { bootMcp } from "./boot.js";
 import {
+  bootMcp,
   configureServerlessApp,
   SERVERLESS_FASTIFY_OPTIONS,
   serverlessHandler,
-} from "./serverless-app.js";
+} from "@working-theory/mcp-server";
+import Fastify from "fastify";
+
+import { site } from "./site.js";
 
 /** Read statically by Vercel's Node builder; caps one request (S8070-03). */
 export const config = { maxDuration: 30 };
 
-await bootMcp();
+await bootMcp(site);
 const app = Fastify(SERVERLESS_FASTIFY_OPTIONS);
-await configureServerlessApp(app);
+await configureServerlessApp(app, site);
 await app.ready();
 export default serverlessHandler(app);

package/templates/apps/mcp/src/index.ts

@@ -23,41 +23,13 @@
  *   CONTENT_ADAPTER=mdx|projection|database
  *   DATABASE_URL=  (required only when CONTENT_ADAPTER=database)
  *
- * The boot sequence and the HTTP env reading live in `boot.ts`, shared with
- * the Vercel entry `app.ts` (#8070 D2).
+ * The server is `@working-theory/mcp-server` (#9460): the boot sequence, the
+ * transports and every tool come from the package, so a version bump of it is
+ * the whole of taking an MCP change. This file hands it the site.
  */
 
-import {
-  bootMcp,
-  httpTransportConfigFromEnv,
-  readStatelessEnv,
-} from "./boot.js";
+import { runMcp } from "@working-theory/mcp-server";
 
-// The workspace, the licence-key store, the commerce claim, its re-read loop
-// and the licence boot warning — before either transport branch below.
-await bootMcp();
+import { site } from "./site.js";
 
-const transport = process.env["MCP_TRANSPORT"] ?? "stdio";
-
-if (transport === "http") {
-  const { startHttpTransport } = await import("./http-transport.js");
-
-  const config = httpTransportConfigFromEnv();
-  await startHttpTransport({
-    ...config,
-    stateless: readStatelessEnv(false),
-  });
-
-  console.log(
-    `MCP HTTP transport listening on port ${config.port} at ${config.path}`,
-  );
-} else {
-  // Default: stdio transport
-  const { StdioServerTransport } =
-    await import("@modelcontextprotocol/sdk/server/stdio.js");
-  const { createMcpServer } = await import("./server.js");
-
-  const server = createMcpServer();
-  const stdioTransport = new StdioServerTransport();
-  await server.connect(stdioTransport);
-}
+await runMcp(site);