create-ailk 0.17.0 → 0.18.0

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

@@ -0,0 +1,203 @@
+/**
+ * The shared boot module (#8070 D1, D2): `readStatelessEnv` and
+ * `httpTransportConfigFromEnv`, which both entrypoints read the environment
+ * through.
+ *
+ * Acceptance criteria verified here (spec docs/specs/8070-spoke-mcp-vercel-backend-spec.md):
+ * - AC-1: MCP_HTTP_STATELESS=true selects the stateless transport — a
+ *   session-less tools/list answers 200 and lists list_pages.
+ * - AC-2: each entry's default, and the accepted spellings.
+ * - AC-3: a bad value throws naming the variable; a blank per-minute rate
+ *   falls back to its default rather than disabling the limit.
+ *
+ * Real sockets on port 0, the pattern of `http-transport.test.ts`.
+ */
+
+import type { AddressInfo } from "node:net";
+
+import type { FastifyInstance } from "fastify";
+
+import { httpTransportConfigFromEnv, readStatelessEnv } from "../src/boot.js";
+import { buildHttpTransportApp } from "../src/http-transport.js";
+
+const VARS = [
+  "MCP_HTTP_STATELESS",
+  "MCP_HTTP_PORT",
+  "MCP_HTTP_PATH",
+  "MCP_RATE_LIMIT_READ_PER_MIN",
+  "MCP_RATE_LIMIT_WRITE_PER_MIN",
+  "MCP_CORS_WRITE_ALLOWED_ORIGINS",
+  "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+  "MCP_ABUSE_START_PURCHASE_DAILY_CAP",
+  "MCP_ABUSE_BLOCKED_USER_AGENTS",
+] 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;
+  }
+});
+
+const TOOLS_LIST = { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} };
+
+async function listen(app: FastifyInstance): Promise<number> {
+  await app.listen({ host: "127.0.0.1", port: 0 });
+  return (app.server.address() as AddressInfo).port;
+}
+
+async function postToolsList(port: number): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: "POST",
+    body: JSON.stringify(TOOLS_LIST),
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    },
+  });
+}
+
+/** The app the long-running entry builds, from the environment as it stands. */
+async function appFromEnv(defaultStateless: boolean): Promise<FastifyInstance> {
+  const { port: _port, ...config } = httpTransportConfigFromEnv();
+  return buildHttpTransportApp({
+    ...config,
+    stateless: readStatelessEnv(defaultStateless),
+  });
+}
+
+describe("AC-1 — MCP_HTTP_STATELESS=true selects the stateless transport", () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it("answers a tools/list with no Mcp-Session-Id with 200, listing list_pages", async () => {
+    process.env["MCP_HTTP_STATELESS"] = "true";
+    app = await appFromEnv(false);
+    const port = await listen(app);
+
+    const res = await postToolsList(port);
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      result?: { tools?: Array<{ name: string }> };
+    };
+    const names = (body.result?.tools ?? []).map((tool) => tool.name);
+    expect(names).toContain("list_pages");
+  });
+});
+
+describe("AC-2 — each entry's default, and the accepted spellings", () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it("unset, the long-running default is false — and a session-less tools/list is 400 (today's stateful behaviour)", async () => {
+    expect(readStatelessEnv(false)).toBe(false);
+
+    app = await appFromEnv(false);
+    const port = await listen(app);
+
+    const res = await postToolsList(port);
+    expect(res.status).toBe(400);
+  });
+
+  it("unset, the serverless default is true", () => {
+    expect(readStatelessEnv(true)).toBe(true);
+  });
+
+  it("an empty value takes the default", () => {
+    process.env["MCP_HTTP_STATELESS"] = "";
+    expect(readStatelessEnv(true)).toBe(true);
+    expect(readStatelessEnv(false)).toBe(false);
+  });
+
+  it.each(["false", "0", "FALSE"])("%s reads as false", (value) => {
+    process.env["MCP_HTTP_STATELESS"] = value;
+    expect(readStatelessEnv(true)).toBe(false);
+  });
+
+  it.each(["1", "True"])("%s reads as true", (value) => {
+    process.env["MCP_HTTP_STATELESS"] = value;
+    expect(readStatelessEnv(false)).toBe(true);
+  });
+
+  it("surrounding whitespace is trimmed", () => {
+    process.env["MCP_HTTP_STATELESS"] = "  true ";
+    expect(readStatelessEnv(false)).toBe(true);
+  });
+});
+
+describe("AC-3 — a bad value fails the boot; a blank rate does not disable the limit", () => {
+  it("a value outside the four spellings throws an Error naming MCP_HTTP_STATELESS", () => {
+    process.env["MCP_HTTP_STATELESS"] = "yes";
+    expect(() => readStatelessEnv(true)).toThrow(Error);
+    expect(() => readStatelessEnv(true)).toThrow(/MCP_HTTP_STATELESS/);
+  });
+
+  it("MCP_RATE_LIMIT_READ_PER_MIN='' yields the default 60, never NaN", () => {
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] = "";
+    expect(httpTransportConfigFromEnv().rateLimits.readPerMin).toBe(60);
+  });
+
+  it("MCP_RATE_LIMIT_WRITE_PER_MIN='' yields the default 10, never NaN", () => {
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] = "";
+    expect(httpTransportConfigFromEnv().rateLimits.writePerMin).toBe(10);
+  });
+});
+
+describe("httpTransportConfigFromEnv — today's reading of every other variable", () => {
+  it("unset, it returns today's defaults", () => {
+    expect(httpTransportConfigFromEnv()).toEqual({
+      port: 8080,
+      path: "/mcp",
+      rateLimits: { readPerMin: 60, writePerMin: 10 },
+      cors: { writeAllowedOrigins: [] },
+      abuse: {
+        captureLeadDailyCapPerIp: 50,
+        startPurchaseDailyCapPerIp: 20,
+        blockedUserAgents: "",
+      },
+    });
+  });
+
+  it("set, it reads each variable as src/index.ts did", () => {
+    process.env["MCP_HTTP_PORT"] = "9090";
+    process.env["MCP_HTTP_PATH"] = "/agents";
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] = "120";
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] = "5";
+    process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] =
+      "https://a.example, https://b.example";
+    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] = "3";
+    process.env["MCP_ABUSE_START_PURCHASE_DAILY_CAP"] = "2";
+    process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] = "BadBot";
+
+    expect(httpTransportConfigFromEnv()).toEqual({
+      port: 9090,
+      path: "/agents",
+      rateLimits: { readPerMin: 120, writePerMin: 5 },
+      cors: { writeAllowedOrigins: ["https://a.example", "https://b.example"] },
+      abuse: {
+        captureLeadDailyCapPerIp: 3,
+        startPurchaseDailyCapPerIp: 2,
+        blockedUserAgents: "BadBot",
+      },
+    });
+  });
+});

package/templates/apps/mcp/__tests__/index.test.ts

@@ -1,10 +1,16 @@
 /**
  * Structural ordering guard for apps/mcp's bootstrap (#5876 spec D4, AC-3;
- * #7156 AC-1, AC-2).
+ * #7156 AC-1, AC-2; #8070 D2).
  *
- * `apps/mcp/src/index.ts` has real side effects at import time (starts a
- * transport, opens a stdio/HTTP listener) — it cannot safely be imported by
- * a test. This reads its source text instead, mirroring the existing
+ * The boot sequence moved from `src/index.ts` into `bootMcp()` in
+ * `src/boot.ts` (#8070), so both entrypoints — `index.ts` (stdio, or HTTP on
+ * a port) and `app.ts` (Vercel) — run the same one. The ordering assertions
+ * below read `boot.ts`, retargeted from `index.ts`: "before the transport
+ * branch" is now "inside `bootMcp()`", and one check on `index.ts` pins that
+ * `bootMcp()` itself runs before the transport branch.
+ *
+ * `index.ts` and `app.ts` await at module level, which ts-jest's CommonJS
+ * compile cannot load, so these read source text — the existing
  * "architectural guard" pattern (`__tests__/read_content.test.ts`).
  */
 import { readFileSync } from "node:fs";
@@ -13,26 +19,46 @@ import vm from "node:vm";
 
 import * as ts from "typescript";
 
-describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
-  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+const indexSrc = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+const bootSrc = readFileSync(resolve(__dirname, "../src/boot.ts"), "utf-8");
 
-  it("awaits initPublicWorkspace()", () => {
-    expect(src).toMatch(/await initPublicWorkspace\(\)/);
-  });
+/** The text of `bootMcp()` — from its declaration to its closing brace. */
+function bootBody(): string {
+  const start = bootSrc.indexOf("export async function bootMcp(");
+  expect(start).toBeGreaterThan(-1);
+  const end = bootSrc.indexOf("\n}\n", start);
+  expect(end).toBeGreaterThan(start);
+  return bootSrc.slice(start, end + 2);
+}
 
-  it("awaits initPublicWorkspace() before either transport branch", () => {
-    const initIdx = src.indexOf("await initPublicWorkspace()");
-    const transportBranchIdx = src.indexOf('if (transport === "http")');
+describe("apps/mcp/src/index.ts — the shared boot runs before the transport (#8070 D2)", () => {
+  it("awaits bootMcp() exactly once, before either transport branch", () => {
+    const calls = [...indexSrc.matchAll(/^await bootMcp\(\);$/gm)];
+    const transportBranchIdx = indexSrc.indexOf('if (transport === "http")');
 
-    expect(initIdx).toBeGreaterThan(-1);
+    expect(calls).toHaveLength(1);
     expect(transportBranchIdx).toBeGreaterThan(-1);
-    expect(initIdx).toBeLessThan(transportBranchIdx);
+    expect(calls[0]!.index!).toBeLessThan(transportBranchIdx);
+  });
+
+  it("the HTTP branch keeps today's stateful default (readStatelessEnv(false))", () => {
+    const transportBranchIdx = indexSrc.indexOf('if (transport === "http")');
+    const readIdx = indexSrc.indexOf("readStatelessEnv(false)");
+
+    expect(readIdx).toBeGreaterThan(transportBranchIdx);
+  });
+});
+
+describe("apps/mcp/src/boot.ts — bootstrap ordering", () => {
+  it("awaits initPublicWorkspace()", () => {
+    expect(bootBody()).toMatch(/await initPublicWorkspace\(\)/);
   });
 
   it("wraps the await in try/catch — a rejection (DB down at boot) must not crash the whole server (code review, #5876)", () => {
-    const tryIdx = src.indexOf("try {");
-    const initIdx = src.indexOf("await initPublicWorkspace()");
-    const catchIdx = src.indexOf("} catch");
+    const body = bootBody();
+    const tryIdx = body.indexOf("try {");
+    const initIdx = body.indexOf("await initPublicWorkspace()");
+    const catchIdx = body.indexOf("} catch");
 
     expect(tryIdx).toBeGreaterThan(-1);
     expect(catchIdx).toBeGreaterThan(-1);
@@ -40,54 +66,65 @@ describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
     expect(tryIdx).toBeLessThan(initIdx);
     expect(initIdx).toBeLessThan(catchIdx);
   });
-});
 
-describe("apps/mcp/src/index.ts — the claim refresh loop starts in production (#7156 AC-1)", () => {
-  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+  it("runs the five boot steps in today's order", () => {
+    const body = bootBody();
+    const steps = [
+      "await initPublicWorkspace()",
+      "await registerLicenseKeyStore()",
+      "await initMcpCommerceClaim()",
+      "startMcpClaimRefresh();",
+      "reportUnlicensedProTools();",
+    ].map((step) => body.indexOf(step));
+
+    for (const idx of steps) expect(idx).toBeGreaterThan(-1);
+    expect([...steps].sort((a, b) => a - b)).toEqual(steps);
+  });
+});
 
-  it("starts after the boot read and before the transport branch", () => {
-    const initIdx = src.indexOf("await initMcpCommerceClaim()");
-    const callMatches = [...src.matchAll(/^startMcpClaimRefresh\(\);$/gm)];
-    const transportBranchIdx = src.indexOf('if (transport === "http")');
+describe("apps/mcp/src/boot.ts — the claim refresh loop starts in production (#7156 AC-1)", () => {
+  it("starts after the boot read and before bootMcp() returns", () => {
+    const body = bootBody();
+    const initIdx = body.indexOf("await initMcpCommerceClaim()");
+    const callMatches = [...body.matchAll(/^\s*startMcpClaimRefresh\(\);$/gm)];
 
     expect(initIdx).toBeGreaterThan(-1);
     expect(callMatches).toHaveLength(1);
-    expect(transportBranchIdx).toBeGreaterThan(-1);
 
     const callIdx = callMatches[0]!.index!;
     expect(initIdx).toBeLessThan(callIdx);
-    expect(callIdx).toBeLessThan(transportBranchIdx);
   });
 });
 
-describe("apps/mcp/src/index.ts — the boot warning cannot stop the server (#7156 AC-2, D2)", () => {
-  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
-
+describe("apps/mcp/src/boot.ts — the boot warning cannot stop the server (#7156 AC-2, D2)", () => {
   /**
    * The exact behavioural slice AC-2 specifies: from the last `try {` before
-   * the `reportUnlicensedProTools();` call statement, up to `const transport
-   * =`. Transpiled and run in a fresh vm context so a real throw from the
-   * stubbed function proves the guard, not a mock of the guard itself.
+   * the `reportUnlicensedProTools();` call statement, up to the end of
+   * `bootMcp()`. Transpiled and run in a fresh vm context so a real throw
+   * from the stubbed function proves the guard, not a mock of the guard
+   * itself.
    */
   function guardedSlice(): string {
+    const body = bootBody();
     const callMatches = [
-      ...src.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+      ...body.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
     ];
     expect(callMatches).toHaveLength(1);
     const callIdx = callMatches[0]!.index!;
-    const tryIdx = src.lastIndexOf("try {", callIdx);
-    const transportIdx = src.indexOf("const transport =");
+    const tryIdx = body.lastIndexOf("try {", callIdx);
+    // The closing brace of bootMcp() — the last character of `body`.
+    const endIdx = body.lastIndexOf("}");
 
     expect(tryIdx).toBeGreaterThan(-1);
-    expect(transportIdx).toBeGreaterThan(callIdx);
+    expect(endIdx).toBeGreaterThan(callIdx);
 
-    const slice = src.slice(tryIdx, transportIdx);
+    const slice = body.slice(tryIdx, endIdx);
     // The extracted try block must be the one that immediately wraps the
     // call, not an earlier try{}/await pair (code review, #7156): the two
-    // other try blocks in this file each await a boot call, so a regressed
-    // boundary would carry "await" into the slice. Asserting that here
-    // turns a boundary regression into a clear failure instead of an opaque
-    // vm ReferenceError from the un-injected awaited function.
+    // other try blocks each await a boot call, so a regressed boundary would
+    // carry "await" into the slice. Asserting that here turns a boundary
+    // regression into a clear failure instead of an opaque vm ReferenceError
+    // from the un-injected awaited function.
     expect(slice).not.toContain("await");
 
     return slice;
@@ -137,14 +174,16 @@ describe("apps/mcp/src/index.ts — the boot warning cannot stop the server (#71
     expect(errorSpy).not.toHaveBeenCalled();
   });
 
-  it("the call statement occurs exactly once, before the transport branch", () => {
-    const callMatches = [
-      ...src.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+  it("the call statement occurs exactly once, inside bootMcp()", () => {
+    const fileMatches = [
+      ...bootSrc.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+    ];
+    const bodyMatches = [
+      ...bootBody().matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
     ];
-    const transportBranchIdx = src.indexOf('if (transport === "http")');
 
-    expect(callMatches).toHaveLength(1);
-    expect(callMatches[0]!.index!).toBeLessThan(transportBranchIdx);
+    expect(fileMatches).toHaveLength(1);
+    expect(bodyMatches).toHaveLength(1);
   });
 
   it("logs to stderr only — the guarded slice never writes stdout", () => {

package/templates/apps/mcp/__tests__/lib/content-adapter.test.ts

@@ -10,7 +10,8 @@
  *   adapter itself;
  * - it forwards the caller's `contentRoot` test-override verbatim;
  * - it forwards the caller's resolved `locale` as `defaultLocale`;
- * - it defaults `contentRoot` to `<cwd>/content` when the caller passes none;
+ * - it defaults `contentRoot` to `mcpContentRoot()` when the caller passes
+ *   none (#8070 D3; the resolver's order is pinned in `content-root.test.ts`);
  * - its MDX-narrowed twin `getMcpMdxContentAdapter()` (which `read_content`
  *   needs for `getPageSource()`) resolves the same way and raises a named
  *   error rather than a TypeError when the selected adapter is not MDX;
@@ -21,8 +22,6 @@
  *   ALL and returns the fail-closed empty adapter instead.
  */
 
-import { join } from "node:path";
-
 const mockResolveContentAdapter = jest.fn();
 
 jest.mock("@working-theory/content-adapters", () => ({
@@ -36,6 +35,7 @@ import type { ArtifactPrismaClient } from "@working-theory/content-adapters";
 import {
   getMcpContentAdapter,
   getMcpMdxContentAdapter,
+  mcpContentRoot,
 } from "../../src/lib/content-adapter.js";
 import {
   __setMcpPublicWorkspaceForTest,
@@ -72,15 +72,14 @@ describe("getMcpContentAdapter", () => {
     });
   });
 
-  it("defaults contentRoot to <cwd>/content when none is given", () => {
+  it("defaults contentRoot to mcpContentRoot() when none is given (#8070 D3)", () => {
     getMcpContentAdapter();
 
     expect(mockResolveContentAdapter).toHaveBeenCalledWith({
-      contentRoot: join(process.cwd(), "content"),
+      contentRoot: mcpContentRoot(),
       defaultLocale: undefined,
     });
   });
-
   it("passes no workspaceId on CONTENT_ADAPTER=mdx — the MDX path stays byte-identical", () => {
     getMcpContentAdapter({ contentRoot: "/fixtures/content", locale: "en-US" });
 

package/templates/apps/mcp/__tests__/lib/content-root.test.ts

@@ -0,0 +1,93 @@
+/**
+ * `mcpContentRoot()` — the one content-root resolver (#8070 D3, AC-6).
+ *
+ * The order, against temp directories:
+ *   1. AILK_CONTENT_ROOT when set and non-empty (absolute, or resolved
+ *      against the working directory);
+ *   2. <cwd>/content when it exists (the server started from the repo root);
+ *   3. <cwd>/../../content when it exists (the server started from apps/mcp,
+ *      a Vercel project whose root directory is apps/mcp);
+ *   4. else <cwd>/content — today's value, so a missing root keeps today's
+ *      empty result.
+ *
+ * The working directory is stubbed through `process.cwd`, never changed.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { mcpContentRoot } from "../../src/lib/content-adapter.js";
+
+let base: string;
+let savedRoot: string | undefined;
+
+beforeEach(() => {
+  base = realpathSync(mkdtempSync(join(tmpdir(), "mcp-content-root-")));
+  savedRoot = process.env["AILK_CONTENT_ROOT"];
+  delete process.env["AILK_CONTENT_ROOT"];
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+  if (savedRoot === undefined) delete process.env["AILK_CONTENT_ROOT"];
+  else process.env["AILK_CONTENT_ROOT"] = savedRoot;
+  rmSync(base, { recursive: true, force: true });
+});
+
+/** Make `dir` (under the temp base) the working directory the resolver sees. */
+function cwdIs(dir: string): string {
+  const abs = join(base, dir);
+  mkdirSync(abs, { recursive: true });
+  jest.spyOn(process, "cwd").mockReturnValue(abs);
+  return abs;
+}
+
+describe("mcpContentRoot", () => {
+  it("AILK_CONTENT_ROOT wins when set — even over an existing <cwd>/content", () => {
+    const cwd = cwdIs("repo");
+    mkdirSync(join(cwd, "content"));
+    const override = join(base, "elsewhere", "content");
+    process.env["AILK_CONTENT_ROOT"] = override;
+
+    expect(mcpContentRoot()).toBe(override);
+  });
+
+  it("a relative AILK_CONTENT_ROOT resolves against the working directory", () => {
+    const cwd = cwdIs("repo/apps/mcp");
+    process.env["AILK_CONTENT_ROOT"] = "../../content";
+
+    expect(mcpContentRoot()).toBe(join(cwd, "..", "..", "content"));
+    expect(mcpContentRoot()).toBe(join(base, "repo", "content"));
+  });
+
+  it("an empty AILK_CONTENT_ROOT is ignored", () => {
+    const cwd = cwdIs("repo");
+    mkdirSync(join(cwd, "content"));
+    process.env["AILK_CONTENT_ROOT"] = "  ";
+
+    expect(mcpContentRoot()).toBe(join(cwd, "content"));
+  });
+
+  it("else <cwd>/content when it exists", () => {
+    const cwd = cwdIs("repo");
+    mkdirSync(join(cwd, "content"));
+    // A repo-level content two levels up must not win over the local one.
+    mkdirSync(join(base, "content"));
+
+    expect(mcpContentRoot()).toBe(join(cwd, "content"));
+  });
+
+  it("else <cwd>/../../content when it exists", () => {
+    cwdIs("repo/apps/mcp");
+    mkdirSync(join(base, "repo", "content"));
+
+    expect(mcpContentRoot()).toBe(join(base, "repo", "content"));
+  });
+
+  it("else <cwd>/content — today's value, when neither exists", () => {
+    const cwd = cwdIs("repo/apps/mcp");
+
+    expect(mcpContentRoot()).toBe(join(cwd, "content"));
+  });
+});

package/templates/apps/mcp/__tests__/server.test.ts

@@ -37,6 +37,23 @@ import {
   reportUnlicensedProTools,
 } from "../src/server.js";
 
+// The topology seam's UNSERVED_MCP_TOOLS (#8070 D7), made switchable so one
+// suite can stand in for a hub ([] — the committed seam, and every other
+// case in this file) and a spoke (["create_project"]).
+const mockSeam: { unserved: readonly string[] } = { unserved: [] };
+// eslint-disable-next-line no-restricted-syntax -- the generated topology seam IS the boundary under test (spec 8070 AC-8b mocks its list); every other export passes through from the real module
+jest.mock("../src/lib/topology.generated.js", () => {
+  const actual = jest.requireActual("../src/lib/topology.generated.js");
+  // A getter defined, not spread: the factory runs before `mockSeam` is
+  // initialised, so the list must be read at use, never at mock time.
+  const mocked = { ...actual };
+  Object.defineProperty(mocked, "UNSERVED_MCP_TOOLS", {
+    enumerable: true,
+    get: () => mockSeam.unserved,
+  });
+  return mocked;
+});
+
 describe("createMcpServer", () => {
   it("creates an McpServer without throwing", () => {
     expect(() => createMcpServer()).not.toThrow();
@@ -180,6 +197,40 @@ describe("start_purchase registration — gated on the commerce claim (#5971)",
   });
 });
 
+describe("create_project on a spoke — the seam's UNSERVED_MCP_TOOLS (#8070 D7, AC-8b)", () => {
+  afterEach(() => {
+    mockSeam.unserved = [];
+  });
+
+  it("a spoke's list (['create_project']) keeps it out of registration", () => {
+    mockSeam.unserved = ["create_project"];
+
+    expect(listRegisteredTools().map((t) => t.name)).not.toContain(
+      "create_project",
+    );
+    const server = createMcpServer();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the SDK exposes no public tool listing; same cast as the suites above
+    const tools = (server as any)._registeredTools as Record<string, unknown>;
+    expect("create_project" in tools).toBe(false);
+  });
+
+  it("a hub's list ([]) registers it", () => {
+    mockSeam.unserved = [];
+
+    expect(listRegisteredTools().map((t) => t.name)).toContain(
+      "create_project",
+    );
+  });
+
+  it("withholding it changes nothing else", () => {
+    const hub = listRegisteredTools().map((t) => t.name);
+    mockSeam.unserved = ["create_project"];
+    const spoke = listRegisteredTools().map((t) => t.name);
+
+    expect(spoke).toEqual(hub.filter((name) => name !== "create_project"));
+  });
+});
+
 describe("the five licence-feature tools — one-release warning cycle (#7136)", () => {
   const FLOW_PAIR = ["get_flow", "submit_flow_step"];
   const BOOKING_TRIO = [
@@ -311,15 +362,21 @@ describe("the five licence-feature tools — one-release warning cycle (#7136)",
     expect(consoleWarn).not.toHaveBeenCalled();
   });
 
-  it("index.ts reports after the claim resolves and before either transport starts", () => {
-    const index = readFileSync(join(__dirname, "../src/index.ts"), "utf8");
-    const init = index.indexOf("await initMcpCommerceClaim()");
-    const report = index.indexOf("reportUnlicensedProTools(");
-    const transport = index.indexOf('if (transport === "http")');
+  it("the boot reports after the claim resolves, and index.ts boots before either transport starts", () => {
+    // The boot sequence lives in boot.ts's bootMcp() since #8070 D2.
+    const boot = readFileSync(join(__dirname, "../src/boot.ts"), "utf8");
+    const init = boot.indexOf("await initMcpCommerceClaim()");
+    const report = boot.indexOf("reportUnlicensedProTools(");
 
     expect(init).toBeGreaterThan(-1);
     expect(report).toBeGreaterThan(init);
-    expect(transport).toBeGreaterThan(report);
+
+    const index = readFileSync(join(__dirname, "../src/index.ts"), "utf8");
+    const bootCall = index.indexOf("await bootMcp()");
+    const transport = index.indexOf('if (transport === "http")');
+
+    expect(bootCall).toBeGreaterThan(-1);
+    expect(transport).toBeGreaterThan(bootCall);
   });
 
   it("server.ts never writes to stdout — the stdio transport's JSON-RPC channel", () => {

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

@@ -0,0 +1,32 @@
+/**
+ * @working-theory/mcp — the Vercel entry (#8070 D2).
+ *
+ * A Vercel project whose root directory is `apps/mcp` detects this file
+ * (`src/app` precedes `src/index` in its Node-backend search, and the chosen
+ * file must import the framework), builds it, and calls the default export —
+ * the `serverlessHandler(app)` request function, which Vercel's Node runtime
+ * accepts where a bare Fastify instance is not a shape it runs.
+ * It never listens; the module-level `await` runs once per instance, so a
+ * 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`.
+ */
+
+import Fastify from "fastify";
+
+import { bootMcp } from "./boot.js";
+import {
+  configureServerlessApp,
+  SERVERLESS_FASTIFY_OPTIONS,
+  serverlessHandler,
+} from "./serverless-app.js";
+
+/** Read statically by Vercel's Node builder; caps one request (S8070-03). */
+export const config = { maxDuration: 30 };
+
+await bootMcp();
+const app = Fastify(SERVERLESS_FASTIFY_OPTIONS);
+await configureServerlessApp(app);
+await app.ready();
+export default serverlessHandler(app);