create-ailk 0.17.0 → 0.19.0

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

@@ -7,15 +7,22 @@
  *   - abuse heuristics — UA deny list, honeypot, email validation, daily cap
  *
  * Decision references:
- *   Decision 1 — same binary, env-var transport selection (apps/mcp/src/index.ts)
+ *   Decision 1 — same binary, env-var transport selection (apps/mcp/src/index.ts;
+ *                the Vercel entry, apps/mcp/src/app.ts, serves HTTP only — #8070)
  *   Decision 2 — configurable path, default /mcp, standalone root-mounted
  *   Decision 3 — @fastify/rate-limit per-IP token bucket
  *   Decision 4 — in-process abuse heuristics for write tools
  *   Decision 5 — @fastify/cors open reads, allowlist writes
  *
- * 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).
+ * Two modes, chosen by `config.stateless` (#8070 D1; the entries read it from
+ * `MCP_HTTP_STATELESS` through `readStatelessEnv`, src/boot.ts):
+ *   - stateful (the long-running entry's default): an `initialize` creates a
+ *     StreamableHTTPServerTransport + McpServer pair kept in an in-memory map
+ *     keyed by its Mcp-Session-Id. Sessions live in ONE process's memory and
+ *     are not persisted across restarts, so this mode needs a single instance.
+ *   - stateless (the Vercel entry's default): every POST gets a fresh
+ *     transport + server and no session ID; GET and DELETE answer 400. Any
+ *     instance can answer any request.
  *
  * The anonymous `config.path` never reads `Authorization`. Beside it,
  * `${config.path}/workspace` serves the signed-in workspace tools (#3591 D15):
@@ -44,6 +51,7 @@ import {
   AbuseReasonCode,
   type AbuseConfig,
 } from "./abuse/index.js";
+import { trustedCallerAddress } from "./request-context.js";
 import { createMcpServer } from "./server.js";
 import { createWorkspaceMcpServer } from "./workspace-server.js";
 
@@ -78,6 +86,13 @@ export const ABUSE_REFUSAL_STATUS: Record<AbuseReasonCode, 403 | 422> = {
  * worth money to abuse, so it takes the write branch — the origin allow-list,
  * the write CORS posture, and `abuseGuard.validate()` — rather than the read
  * branch's UA check alone.
+ *
+ * `create_booking` and `submit_flow_step` joined in #8071: each forwards
+ * caller-chosen data to the hub — a real booking on the seller's calendar
+ * that emails the attendee an invite, and a flow step whose completing call
+ * can create a Lead — so they take the same branch, each on its own daily
+ * cap. `__tests__/write-tool-guard.test.ts` fails when a catalog tool that
+ * sends a non-GET request to the hub is missing from this set.
  */
 // Any name added here MUST be enforced through the batch-aware path in
 // writeToolCalls() below — a request body can be a JSON-RPC ARRAY, and a
@@ -89,6 +104,8 @@ export const WRITE_TOOLS = new Set([
   "subscribe_newsletter",
   "request_callback",
   "start_purchase",
+  "create_booking",
+  "submit_flow_step",
 ]);
 
 export interface HttpTransportCorsConfig {
@@ -118,9 +135,10 @@ export interface HttpTransportConfig {
   abuse: AbuseConfig;
   /**
    * When true, use stateless transport mode: no session IDs, every request
-   * creates a fresh McpServer + transport. Useful for testing and simple
-   * deployments that don't need resumable sessions.
-   * Default: false (stateful).
+   * creates a fresh McpServer + transport. Needed on a host that runs several
+   * instances (the Vercel entry), and used by tests.
+   * Default: false (stateful). The entries set it from `MCP_HTTP_STATELESS`
+   * (`readStatelessEnv`, src/boot.ts — #8070 D1).
    */
   stateless?: boolean;
 }
@@ -274,24 +292,25 @@ function registerWorkspaceRoute(
 }
 
 /**
- * Build and return a configured Fastify instance that exposes the MCP HTTP
- * transport at `config.path`. The instance is not yet listening — callers
- * call `.listen()` or `.inject()` (tests).
+ * Register the MCP HTTP transport at `config.path` on an existing Fastify
+ * instance: CORS, the per-IP rate limit, the abuse guard, the anonymous MCP
+ * route and the signed-in workspace route (#8070 D2). The caller owns the
+ * instance — and so its options, such as the Vercel entry's `trustProxy`
+ * (src/serverless-app.ts).
  *
+ * @param app - The Fastify instance to register on (not yet listening)
  * @param config - HTTP transport configuration
- * @returns Configured Fastify instance (ready to listen or inject)
  */
-export async function buildHttpTransportApp(
+export async function registerHttpTransport(
+  app: FastifyInstance,
   config: HttpTransportConfig,
-): Promise<FastifyInstance> {
+): Promise<void> {
   const mcpPath = config.path ?? "/mcp";
   const abuseGuard = new AbuseGuard(config.abuse);
 
   // Active transports keyed by session ID (stateful mode only).
   const transports = new Map<string, StreamableHTTPServerTransport>();
 
-  const app = Fastify({ logger: false });
-
   // ── CORS ──────────────────────────────────────────────────────────────────
   // Read tools: open (origin: true — reflect the caller's Origin).
   // Write tools: enforced per-request in the preHandler below.
@@ -373,83 +392,93 @@ export async function buildHttpTransportApp(
         }
       }
     },
-    handler: async (request, reply) => {
-      const body = request.body as unknown;
-      const sessionId = request.headers["mcp-session-id"] as string | undefined;
-
-      try {
-        let transport: StreamableHTTPServerTransport;
-
-        if (config.stateless) {
-          // Stateless mode: each request gets a fresh transport + server.
-          // enableJsonResponse: true ensures plain JSON responses (no SSE).
-          // sessionIdGenerator is intentionally omitted (stateless = no sessions).
-          transport = new StreamableHTTPServerTransport({
-            enableJsonResponse: true,
-          });
-          const server = createMcpServer();
-          // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
-          // as `(() => void) | undefined`, which conflicts with Transport.onclose
-          // under exactOptionalPropertyTypes: true. The runtime behaviour is
-          // identical; the cast is safe.
-          await server.connect(transport as unknown as Transport);
-          try {
-            await transport.handleRequest(request.raw, reply.raw, body);
-          } finally {
-            // Close the per-request transport + server to release internal
-            // handles. Without this, the MCP SDK's transport leaves open
-            // sockets that surface as `socket.destroySoon is not a function`
-            // during Jest teardown on Node 20.x (@hono/node-server compat).
-            await transport.close().catch(() => undefined);
-            await server.close().catch(() => undefined);
+    handler: async (request, reply) =>
+      // The lead-write tools read this address (#8073) through
+      // `visitorForwardHeadersForThisCall()` while the SDK dispatches their
+      // call, somewhere inside `transport.handleRequest()` below — the whole
+      // handler body runs inside the store so every path reaches it.
+      trustedCallerAddress.run(request.ip, async () => {
+        const body = request.body as unknown;
+        const sessionId = request.headers["mcp-session-id"] as
+          | string
+          | undefined;
+
+        try {
+          let transport: StreamableHTTPServerTransport;
+
+          if (config.stateless) {
+            // Stateless mode: each request gets a fresh transport + server.
+            // enableJsonResponse: true ensures plain JSON responses (no SSE).
+            // sessionIdGenerator is intentionally omitted (stateless = no sessions).
+            transport = new StreamableHTTPServerTransport({
+              enableJsonResponse: true,
+            });
+            const server = createMcpServer();
+            // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
+            // as `(() => void) | undefined`, which conflicts with Transport.onclose
+            // under exactOptionalPropertyTypes: true. The runtime behaviour is
+            // identical; the cast is safe.
+            await server.connect(transport as unknown as Transport);
+            try {
+              await transport.handleRequest(request.raw, reply.raw, body);
+            } finally {
+              // Close the per-request transport + server to release internal
+              // handles. Without this, the MCP SDK's transport leaves open
+              // sockets that surface as `socket.destroySoon is not a function`
+              // during Jest teardown on Node 20.x (@hono/node-server compat).
+              await transport.close().catch(() => undefined);
+              await server.close().catch(() => undefined);
+            }
+            return;
           }
-          return;
-        }
-
-        if (sessionId && transports.has(sessionId)) {
-          // Existing session — reuse transport
-          transport = transports.get(sessionId)!;
-        } else if (!sessionId && isInitializeRequest(body)) {
-          // New initialization — create a stateful transport + fresh server
-          transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            onsessioninitialized: (sid) => {
-              transports.set(sid, transport);
-            },
-          });
 
-          transport.onclose = () => {
-            const sid = transport.sessionId;
-            if (sid) transports.delete(sid);
-          };
-
-          const server = createMcpServer();
-          // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
-          // as `(() => void) | undefined`, which conflicts with Transport.onclose
-          // under exactOptionalPropertyTypes: true. The runtime behaviour is
-          // identical; the cast is safe.
-          await server.connect(transport as unknown as Transport);
-        } else {
-          reply.code(400).send({
-            jsonrpc: "2.0",
-            error: { code: -32000, message: "Bad Request: no valid session" },
-            id: null,
-          });
-          return;
-        }
+          if (sessionId && transports.has(sessionId)) {
+            // Existing session — reuse transport
+            transport = transports.get(sessionId)!;
+          } else if (!sessionId && isInitializeRequest(body)) {
+            // New initialization — create a stateful transport + fresh server
+            transport = new StreamableHTTPServerTransport({
+              sessionIdGenerator: () => randomUUID(),
+              onsessioninitialized: (sid) => {
+                transports.set(sid, transport);
+              },
+            });
+
+            transport.onclose = () => {
+              const sid = transport.sessionId;
+              if (sid) transports.delete(sid);
+            };
+
+            const server = createMcpServer();
+            // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
+            // as `(() => void) | undefined`, which conflicts with Transport.onclose
+            // under exactOptionalPropertyTypes: true. The runtime behaviour is
+            // identical; the cast is safe.
+            await server.connect(transport as unknown as Transport);
+          } else {
+            reply.code(400).send({
+              jsonrpc: "2.0",
+              error: {
+                code: -32000,
+                message: "Bad Request: no valid session",
+              },
+              id: null,
+            });
+            return;
+          }
 
-        await transport.handleRequest(request.raw, reply.raw, body);
-      } catch (err) {
-        if (!reply.sent) {
-          reply.code(500).send({
-            jsonrpc: "2.0",
-            error: { code: -32603, message: "Internal server error" },
-            id: null,
-          });
+          await transport.handleRequest(request.raw, reply.raw, body);
+        } catch (err) {
+          if (!reply.sent) {
+            reply.code(500).send({
+              jsonrpc: "2.0",
+              error: { code: -32603, message: "Internal server error" },
+              id: null,
+            });
+          }
+          throw err;
         }
-        throw err;
-      }
-    },
+      }),
   });
 
   // DELETE — session termination
@@ -465,7 +494,22 @@ export async function buildHttpTransportApp(
 
   // ── Signed-in workspace route (#3591 D15) ─────────────────────────────────
   registerWorkspaceRoute(app, `${mcpPath}/workspace`, abuseGuard);
+}
 
+/**
+ * Build and return a configured Fastify instance that exposes the MCP HTTP
+ * transport at `config.path`. The instance is not yet listening — callers
+ * call `.listen()` or `.inject()` (tests). Sets no `trustProxy`, so
+ * `request.ip` is the socket's address.
+ *
+ * @param config - HTTP transport configuration
+ * @returns Configured Fastify instance (ready to listen or inject)
+ */
+export async function buildHttpTransportApp(
+  config: HttpTransportConfig,
+): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  await registerHttpTransport(app, config);
   return app;
 }
 

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

@@ -9,155 +9,48 @@
  * HTTP transport configuration (all optional, shown with defaults):
  *   MCP_HTTP_PORT=8080
  *   MCP_HTTP_PATH=/mcp
+ *   MCP_HTTP_STATELESS=false           (true = no sessions; any instance answers)
  *   MCP_RATE_LIMIT_READ_PER_MIN=60
  *   MCP_RATE_LIMIT_WRITE_PER_MIN=10
  *   MCP_CORS_WRITE_ALLOWED_ORIGINS=   (empty = no cross-origin writes)
  *   MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP=50
  *   MCP_ABUSE_START_PURCHASE_DAILY_CAP=20
+ *   MCP_ABUSE_CREATE_BOOKING_DAILY_CAP=20
+ *   MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP=50
  *   MCP_ABUSE_BLOCKED_USER_AGENTS=    (comma-separated substrings)
  *
  * Content adapter (all optional; `CONTENT_ADAPTER` default: mdx):
  *   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).
  */
 
 import {
-  initMcpCommerceClaim,
-  startMcpClaimRefresh,
-} from "./lib/commerce-claim.js";
-import {
-  initPublicWorkspace,
-  registerLicenseKeyStore,
-} from "./lib/topology.generated.js";
-
-// Resolves the MCP server's own workspace ONCE, before either transport
-// branch below — a no-op unless CONTENT_ADAPTER=database (#5876 spec D4/D6).
-// This is the one `await` that covers both arms: `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 either
-// transport branch — 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,
-  );
-}
+  bootMcp,
+  httpTransportConfigFromEnv,
+  readStatelessEnv,
+} from "./boot.js";
 
-// 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, both transport
-// branches load 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,
-  );
-}
+// 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();
 
 const transport = process.env["MCP_TRANSPORT"] ?? "stdio";
 
 if (transport === "http") {
   const { startHttpTransport } = await import("./http-transport.js");
 
-  const port = parseInt(process.env["MCP_HTTP_PORT"] ?? "8080", 10);
-  const path = process.env["MCP_HTTP_PATH"] ?? "/mcp";
-  const readPerMin = parseInt(
-    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] ?? "60",
-    10,
-  );
-  const writePerMin = parseInt(
-    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] ?? "10",
-    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 {
-    readPositiveIntEnv,
-    DEFAULT_CAPTURE_LEAD_DAILY_CAP,
-    DEFAULT_START_PURCHASE_DAILY_CAP,
-  } = await import("./abuse/index.js");
-  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"] ?? "";
-
+  const config = httpTransportConfigFromEnv();
   await startHttpTransport({
-    port,
-    path,
-    rateLimits: { readPerMin, writePerMin },
-    cors: { writeAllowedOrigins },
-    abuse: {
-      captureLeadDailyCapPerIp,
-      startPurchaseDailyCapPerIp,
-      blockedUserAgents,
-    },
+    ...config,
+    stateless: readStatelessEnv(false),
   });
 
-  console.log(`MCP HTTP transport listening on port ${port} at ${path}`);
+  console.log(
+    `MCP HTTP transport listening on port ${config.port} at ${config.path}`,
+  );
 } else {
   // Default: stdio transport
   const { StdioServerTransport } =

package/templates/apps/mcp/src/lib/audit-single-page.ts

@@ -20,8 +20,6 @@
  * Session/scope: none — read-only filesystem access via content adapter.
  */
 
-import { join } from "node:path";
-
 import {
   READINESS_SCAN_TYPES,
   chassisSectionIds,
@@ -44,7 +42,10 @@ import {
   pageTypeRegistry,
 } from "@working-theory/schema";
 
-import { getMcpContentAdapter } from "./content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "./content-adapter.js";
 import { resolveLocale } from "./resolve-locale.js";
 import { readStripeTaxSignal } from "./stripe-tax-signal.js";
 
@@ -221,10 +222,10 @@ async function scanSitePages(
  * Builds an `AuditInput` for a single page.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  *
  * `projectRoot` is the matching seam for the project.yaml the Stripe-Tax signal
- * is read from (#5949 D9); it likewise defaults to the process cwd.
+ * is read from (#5949 D9); it defaults to the process cwd.
  */
 export async function buildSinglePageAuditInput(
   input: SinglePageInput,
@@ -244,7 +245,7 @@ export async function buildSinglePageAuditInput(
     throw new Error("Either slug or url is required.");
   }
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

package/templates/apps/mcp/src/lib/content-adapter.ts

@@ -15,7 +15,7 @@
  * `projection` paths below are byte-identical to before this issue — no
  * `workspaceId`, no `await import()`, no workspace read (D6, NFR-1/NFR-2). On
  * `database`, this seam reads `mcpPublicWorkspace()` — the resolution
- * `apps/mcp/src/index.ts` already awaited once at bootstrap
+ * `bootMcp()` (`apps/mcp/src/boot.ts`) already awaited once at bootstrap
  * (`public-workspace.ts`, D4) — and forwards `workspaceId` + `prisma` to the
  * resolver on a resolved deployment; every other arm (unresolved, or a tool
  * invoked before bootstrap resolved) returns the fail-closed
@@ -27,10 +27,12 @@
  *
  * The `contentRoot` argument is the test-override seam every tool already
  * exposes as its optional second parameter — tests inject a fixture root
- * through it, and that keeps working unchanged.
+ * through it, and that keeps working unchanged. Absent, every tool and
+ * `audit-single-page` take {@link mcpContentRoot} (#8070 D3).
  */
 
-import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 import {
   resolveContentAdapter,
@@ -46,12 +48,39 @@ import {
 import { publicWorkspace } from "./topology.generated.js";
 
 export interface McpContentAdapterOptions {
-  /** Filesystem content root. Defaults to `<cwd>/content` — the tools' prior default. */
+  /** Filesystem content root. Defaults to {@link mcpContentRoot}. */
   contentRoot?: string;
   /** Locale already resolved against the project allowlist (`resolveLocale()`). */
   locale?: string;
 }
 
+/**
+ * The MCP server's content root — the ONE place apps/mcp derives it (#8070 D3).
+ *
+ * In order: `AILK_CONTENT_ROOT` when set and non-empty (absolute, or resolved
+ * against the working directory); else `<cwd>/content` when it exists (the
+ * server started from the repo root); else `<cwd>/../../content` when it
+ * exists (the server started from `apps/mcp` — a Vercel project whose root
+ * directory is `apps/mcp`); else `<cwd>/content`, the prior default, so a
+ * missing root keeps serving the same empty result it always did.
+ *
+ * Read on every call, never cached: it is two `existsSync` probes, and a
+ * cached value would pin the first working directory a test or a host used.
+ */
+export function mcpContentRoot(): string {
+  const cwd = process.cwd();
+  const override = process.env["AILK_CONTENT_ROOT"]?.trim();
+  if (override) return resolve(cwd, override);
+
+  const local = join(cwd, "content");
+  if (existsSync(local)) return local;
+
+  const repo = join(cwd, "..", "..", "content");
+  if (existsSync(repo)) return repo;
+
+  return local;
+}
+
 /**
  * Returns the `ContentAdapter` the environment selects, rooted at the caller's
  * content root. The resolver memoises per distinct option set, so this is safe
@@ -60,7 +89,7 @@ export interface McpContentAdapterOptions {
 export function getMcpContentAdapter(
   options: McpContentAdapterOptions = {},
 ): ContentAdapter {
-  const contentRoot = options.contentRoot ?? join(process.cwd(), "content");
+  const contentRoot = options.contentRoot ?? mcpContentRoot();
   const defaultLocale = options.locale;
 
   if (resolvedAdapterKind() !== "database") {

package/templates/apps/mcp/src/lib/topology.generated.ts

@@ -4,6 +4,8 @@
 // every scaffold rewrites it. A hub resolves its workspace through the
 // database; a spoke (`--topology spoke`) has none, so its content tools
 // read the spoke's own MDX and its writes go to the hub at AILK_API_URL.
+// UNSERVED_MCP_TOOLS names the tools this server does not register on this
+// topology (#8070).
 import {
   initMcpPublicWorkspace,
   mcpPublicWorkspace,
@@ -14,6 +16,7 @@ export { registerLicenseKeyStore } from "./license-key-store.js";
 export type { McpWorkspaceResolution };
 
 export const TOPOLOGY: "hub" | "spoke" = "hub";
+export const UNSERVED_MCP_TOOLS: readonly string[] = [];
 
 export async function initPublicWorkspace(): Promise<void> {
   await initMcpPublicWorkspace();

package/templates/apps/mcp/src/request-context.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-request context for @working-theory/mcp, shared by the HTTP transport
+ * and the MCP lead-write tools (#8073).
+ *
+ * Deliberately dependency-free beyond `@working-theory/api-client` (already
+ * loaded by every tool): `http-transport.ts` imports Fastify and the full
+ * HTTP stack, and `src/index.ts`'s stdio branch dynamic-imports `server.js`
+ * specifically to avoid loading that stack for a local stdio caller. A tool
+ * importing `trustedCallerAddress` straight from `http-transport.ts` would
+ * pull Fastify into every stdio boot and, worse, close an import cycle
+ * (`http-transport.ts` → `server.ts` → `tools/*.ts` → `http-transport.ts`).
+ * This module sits below both: `http-transport.ts` populates the store,
+ * the tools read it, neither imports the other.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import { visitorForwardHeaders } from "@working-theory/api-client";
+
+/**
+ * The caller address the transport trusted for the POST request currently
+ * being handled — `request.ip`, Fastify's own `trustProxy`-resolved value
+ * (the Vercel entry trusts exactly one hop, #8070 D5), never the raw,
+ * caller-forgeable leftmost `X-Forwarded-For` entry. Populated by
+ * `http-transport.ts` for the duration of one `transport.handleRequest()`
+ * call and read by the three MCP lead-write tools (#8073) so they can
+ * forward it to the hub without the tool gaining an identity argument.
+ * `undefined` outside an HTTP request — stdio has no client address to
+ * forward.
+ */
+export const trustedCallerAddress = new AsyncLocalStorage<string>();
+
+/**
+ * The two visitor-forwarding headers (`x-ailk-visitor-ip`,
+ * `x-ailk-visitor-forward-key`) for the request this call is running inside,
+ * or `undefined` when there is no trusted address for this call (not an HTTP
+ * request), no `AILK_VISITOR_FORWARD_KEY`, or `visitorForwardHeaders` itself
+ * declines (an unsafe transport, an unsafe key value). Read by the lead-write
+ * tools right before they call the hub (#8073).
+ */
+export function visitorForwardHeadersForThisCall():
+  | Record<string, string>
+  | undefined {
+  const address = trustedCallerAddress.getStore();
+  if (!address) return undefined;
+  return visitorForwardHeaders(
+    {
+      get: (name: string) => (name === "x-forwarded-for" ? address : null),
+    },
+    process.env.AILK_VISITOR_FORWARD_KEY,
+  );
+}