create-ailk 0.16.0 → 0.18.0

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);

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

@@ -0,0 +1,185 @@
+/**
+ * The boot sequence and the HTTP env→config reader both entrypoints share
+ * (#8070 D1, D2).
+ *
+ * `src/index.ts` (stdio, or HTTP on `MCP_HTTP_PORT`) and `src/app.ts` (the
+ * Vercel entry) each call {@link bootMcp} before they build a transport, and
+ * read the HTTP configuration through {@link httpTransportConfigFromEnv} and
+ * {@link readStatelessEnv}. One copy of each, so the two entries cannot drift.
+ *
+ * Nothing here loads Fastify: the HTTP transport's config type is imported as
+ * a type only, so the stdio entry still never loads the HTTP stack.
+ */
+
+import {
+  DEFAULT_CAPTURE_LEAD_DAILY_CAP,
+  DEFAULT_START_PURCHASE_DAILY_CAP,
+  readPositiveIntEnv,
+} from "./abuse/index.js";
+import type { HttpTransportConfig } from "./http-transport.js";
+import {
+  initMcpCommerceClaim,
+  startMcpClaimRefresh,
+} from "./lib/commerce-claim.js";
+import {
+  initPublicWorkspace,
+  registerLicenseKeyStore,
+} from "./lib/topology.generated.js";
+
+/**
+ * Runs the boot sequence, in order: the workspace resolution, the licence-key
+ * store, the commerce claim, the claim re-read loop and the one-release
+ * licence warning. Each step that can fail is guarded so one failure never
+ * takes the other tools down.
+ */
+export async function bootMcp(): Promise<void> {
+  // Resolves the MCP server's own workspace ONCE, before any transport is
+  // built — a no-op unless CONTENT_ADAPTER=database (#5876 spec D4/D6).
+  // This is the one `await` that covers every transport:
+  // `getMcpContentAdapter()` (content-adapter.ts) stays synchronous and reads
+  // the memoised result.
+  //
+  // A REJECTION here (a transient DB error — unreachable at boot, a migration
+  // in progress, a bad DATABASE_URL) is caught rather than left to crash the
+  // process: every OTHER tool (lead capture, scheduling, …) has nothing to do
+  // with the content adapter and must keep serving. The module's un-resolved
+  // `{ kind: "not-required" }` state is left in place on a caught failure —
+  // the SAME fail-closed shape an ambiguous workspace count already produces
+  // (D5) — so content tools serve their empty/not-found shape rather than the
+  // whole server going dark over one adapter's connectivity.
+  try {
+    await initPublicWorkspace();
+  } catch (err) {
+    console.error(
+      "[mcp] initPublicWorkspace() failed — content tools will serve their " +
+        "fail-closed empty shape under CONTENT_ADAPTER=database until this " +
+        "resolves; every other tool is unaffected:",
+      err,
+    );
+  }
+
+  // Registers the renewed licence key's durable home (#6677 DD-6) BEFORE the
+  // commerce claim below memoises the licence: with a database, the key a
+  // sibling app renewed lives in one SiteSetting row, and the claim must read
+  // it. Never throws; without DATABASE_URL the file store stays in place.
+  await registerLicenseKeyStore();
+
+  // Resolves the deployment's `commerce` add-on claim at boot, before any
+  // transport is built — the sibling of the workspace resolution above and
+  // the same #5876 idiom (#5971 spec D2). Without this await the memoised
+  // claim is never resolved and `start_purchase` is invisible on a KEYED
+  // site too. The same single licence read now also resolves the licence
+  // features the deployment holds, which gate the five `feature`-tagged
+  // tools (#7136). The re-read loop below runs every `MCP_CLAIM_REFRESH_MS`
+  // thereafter (#7156), so the server's origin agrees with the manifest
+  // route's origin response within that bound; the route answers
+  // `cache-control: public, max-age=86400`, so a downstream cache may serve
+  // an older manifest for up to 24 hours.
+  //
+  // A REJECTION is caught for the same reason: a licence read that fails
+  // must not take the other 19 tools down. `initMcpCommerceClaim()` already
+  // resolves to the fail-closed "unclaimed" internally, so this catch is
+  // belt-and-braces for anything thrown outside its own try.
+  try {
+    await initMcpCommerceClaim();
+  } catch (err) {
+    console.error(
+      "[mcp] initMcpCommerceClaim() failed — start_purchase stays unregistered " +
+        "(fail-closed) until this resolves; every other tool is unaffected:",
+      err,
+    );
+  }
+
+  // Starts the bounded re-read (#7156 spec D1), after the boot read resolves
+  // so the first re-read never races it. Never throws; the timer is unref'd.
+  startMcpClaimRefresh();
+
+  // The one-release warning cycle (#7136): once per process, whichever
+  // transport follows, one stderr line per tool served without its licence
+  // feature. After the claim resolves, or it would warn for every tool.
+  //
+  // A throw here must not stop the server (#7156 spec D2, L1) — only the call
+  // is guarded, not the import: if `./server.js` fails to load, every
+  // transport loads it again and the server could not start anyway.
+  const { reportUnlicensedProTools } = await import("./server.js");
+  try {
+    reportUnlicensedProTools();
+  } catch (err) {
+    console.error(
+      "[mcp] reportUnlicensedProTools() failed — the licence boot warning was " +
+        "not written; every tool is served as registered:",
+      err,
+    );
+  }
+}
+
+/**
+ * Whether the HTTP transport runs stateless, from `MCP_HTTP_STATELESS`
+ * (#8070 D1). Trimmed and case-insensitive: `true`/`1` → on, `false`/`0` →
+ * off, unset or empty → `defaultValue`. Anything else throws, so a typo fails
+ * the boot rather than silently picking a mode.
+ *
+ * Each entry passes its own default: `src/index.ts` passes `false` (today's
+ * stateful server, unchanged); the Vercel entry passes `true`, because a
+ * stateful transport keeps its sessions in one instance's memory and cannot
+ * work across the instances a serverless host runs.
+ */
+export function readStatelessEnv(defaultValue: boolean): boolean {
+  // A literal read, so create-ailk's declared-env scan finds it (#7874).
+  const raw = process.env["MCP_HTTP_STATELESS"];
+  const value = (raw ?? "").trim().toLowerCase();
+  if (value === "") return defaultValue;
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  throw new Error(
+    `MCP_HTTP_STATELESS must be one of true, false, 1 or 0 (got "${raw}")`,
+  );
+}
+
+/**
+ * The HTTP transport's configuration, read from the environment as
+ * `src/index.ts` has always read it — with one change: the two per-minute
+ * rates go through {@link readPositiveIntEnv}, as the daily caps already do,
+ * so a blank or non-numeric value falls back to its default instead of
+ * yielding `NaN` and silently disabling the limit (#8070 S8070-06).
+ *
+ * Every variable is optional; the defaults are shown in
+ * `apps/mcp/.env.example`. Stateless mode is not read here: each entry reads
+ * it through {@link readStatelessEnv} with its own default.
+ */
+export function httpTransportConfigFromEnv(): HttpTransportConfig & {
+  port: number;
+} {
+  const port = parseInt(process.env["MCP_HTTP_PORT"] ?? "8080", 10);
+  const path = process.env["MCP_HTTP_PATH"] ?? "/mcp";
+  const readPerMin = readPositiveIntEnv("MCP_RATE_LIMIT_READ_PER_MIN", 60);
+  const writePerMin = readPositiveIntEnv("MCP_RATE_LIMIT_WRITE_PER_MIN", 10);
+  const writeOriginsRaw = process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] ?? "";
+  const writeAllowedOrigins = writeOriginsRaw
+    ? writeOriginsRaw.split(",").map((o) => o.trim())
+    : [];
+  // Both caps go through readPositiveIntEnv rather than a bare parseInt: a
+  // BLANK env var would otherwise yield NaN and silently disable the cap
+  // (#5971 security review round 2).
+  const captureLeadDailyCapPerIp = readPositiveIntEnv(
+    "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+    DEFAULT_CAPTURE_LEAD_DAILY_CAP,
+  );
+  const startPurchaseDailyCapPerIp = readPositiveIntEnv(
+    "MCP_ABUSE_START_PURCHASE_DAILY_CAP",
+    DEFAULT_START_PURCHASE_DAILY_CAP,
+  );
+  const blockedUserAgents = process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] ?? "";
+
+  return {
+    port,
+    path,
+    rateLimits: { readPerMin, writePerMin },
+    cors: { writeAllowedOrigins },
+    abuse: {
+      captureLeadDailyCapPerIp,
+      startPurchaseDailyCapPerIp,
+      blockedUserAgents,
+    },
+  };
+}