create-ailk 0.16.0 → 0.18.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):
@@ -118,9 +125,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 +282,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.
@@ -465,7 +474,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,6 +9,7 @@
  * 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)
@@ -19,145 +20,35 @@
  * 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/server.ts

@@ -27,6 +27,7 @@ import {
   mcpHeldFeatures,
 } from "./lib/commerce-claim.js";
 import { notFoundError } from "./lib/errors.js";
+import { UNSERVED_MCP_TOOLS } from "./lib/topology.generated.js";
 import { ailkAudit } from "./tools/audit.js";
 import { ailkCaptureLead } from "./tools/capture_lead.js";
 import { ailkCreateProject } from "./tools/create_project.js";
@@ -169,8 +170,12 @@ export interface RegisteredToolDescriptor {
 
 /**
  * Whether a catalog registration entry should register on this build/boot —
- * three filters:
+ * four filters:
  *
+ *  0. the topology filter (#8070 D7): a name in the generated seam's
+ *     `UNSERVED_MCP_TOOLS` is never served — `create_project` on a spoke,
+ *     which carries no create-ailk CLI for it to spawn. `[]` on a hub. The
+ *     web manifest drops the same list, so the two surfaces agree;
  *  1. the OSS-disabled filter (static per-name set; empty since #5971);
  *  2. the module-presence filter (S1, #5088): a tool tagged with `module`
  *     (e.g. `create_booking` carrying `module: "scheduling"`) registers only
@@ -200,6 +205,7 @@ function shouldRegister(reg: {
   module?: string;
   addon?: "commerce";
 }): boolean {
+  if (UNSERVED_MCP_TOOLS.includes(reg.name)) return false;
   if (OSS_DISABLED_TOOLS.has(reg.name)) return false;
   if (reg.module && !isModuleEnabled(reg.module)) return false;
   if (reg.addon === "commerce" && mcpCommerceClaim() !== "claimed")
@@ -240,7 +246,8 @@ function catalogOptionsForThisBoot(): McpCatalogOptions {
  * boot serves whose licence `feature` the deployment does not hold, calls
  * `warn` once, naming the tool and the feature, and returns their names.
  *
- * Called ONCE per process from `index.ts`, after the claim resolves — never
+ * Called ONCE per process from `bootMcp()` (`boot.ts`, which both `index.ts`
+ * and the Vercel entry `app.ts` await), after the claim resolves — never
  * from {@link createMcpServer}, which runs once per HTTP session. In refuse
  * mode it finds nothing: the upstream catalog filter has already dropped
  * every such tool, so it needs no mode check of its own. Defaults to
@@ -283,6 +290,7 @@ export function listRegisteredTools(): RegisteredToolDescriptor[] {
 
 /**
  * Creates a configured McpServer with all AILK tools registered, less any
+ * tool this topology does not serve (`UNSERVED_MCP_TOOLS`, #8070 D7), less any
  * tool name in {@link OSS_DISABLED_TOOLS}, less any tool whose `module` is
  * not enabled on this build (S1, #5088), and less any `addon`-tagged tool
  * whose claim this deployment does not hold (#5971) — see

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

@@ -0,0 +1,88 @@
+/**
+ * The testable part of the Vercel entry (#8070 D2, D5).
+ *
+ * `src/app.ts` is the thin file Vercel's Node-backend detection finds: it
+ * awaits the boot at module level and default-exports the
+ * {@link serverlessHandler} for the app. A module-level
+ * `await` does not compile under the package's ts-jest CommonJS preset, so
+ * everything app.ts does beyond that lives here, where a test can build the
+ * same app (`__tests__/app-entry.test.ts`).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { FastifyInstance } from "fastify";
+
+import { httpTransportConfigFromEnv, readStatelessEnv } from "./boot.js";
+import { registerHttpTransport } from "./http-transport.js";
+
+/**
+ * Trust exactly one proxy hop — the immediate peer — and nothing behind it
+ * (D5). Fastify then takes `request.ip` from the LAST `X-Forwarded-For`
+ * entry, the address Vercel's edge saw, and a value a caller writes earlier
+ * in the header cannot move it.
+ *
+ * A function, not `trustProxy: 1`: Fastify 5.12 treats a numeric hop count as
+ * trust-nothing ("hop-count-only trust cannot validate the immediate peer"),
+ * so `1` would silently key every caller on the edge's address. A hop-only
+ * function is safe here for the reason Fastify's warning names: a Vercel
+ * function cannot be reached except through Vercel's edge, so its immediate
+ * peer is always the edge. It would NOT be safe on a host a client can reach
+ * directly — which is why the long-running entry (`buildHttpTransportApp`)
+ * sets no `trustProxy` at all.
+ *
+ * Trusting hop 0 also makes `request.host` and `request.protocol` follow
+ * `X-Forwarded-Host` / `X-Forwarded-Proto`. Nothing in apps/mcp reads either
+ * today; anything that starts to must remember they come from the edge.
+ */
+export function trustOneHop(_address: string, hop: number): boolean {
+  return hop === 0;
+}
+
+/**
+ * The Fastify options the Vercel entry builds its app with: no logger, and
+ * {@link trustOneHop} — so the per-IP rate limit and the daily caps key on
+ * the real caller. That holds for the topology the sites deploy: the MCP host
+ * name points straight at the Vercel project. A second proxy in front
+ * (Cloudflare in proxied mode, a rewrite from another Vercel project) would
+ * make every caller that proxy's address.
+ */
+export const SERVERLESS_FASTIFY_OPTIONS = {
+  logger: false,
+  trustProxy: trustOneHop,
+} as const;
+
+/**
+ * Register the MCP HTTP transport on the Vercel entry's app, from the
+ * environment. Stateless unless `MCP_HTTP_STATELESS` says otherwise (D1): a
+ * stateful transport keeps its sessions in one instance's memory, which a
+ * multi-instance host cannot honour. The port is read and ignored — Vercel
+ * calls the exported {@link serverlessHandler} and nothing listens.
+ */
+export async function configureServerlessApp(
+  app: FastifyInstance,
+): Promise<void> {
+  const { port: _port, ...config } = httpTransportConfigFromEnv();
+  await registerHttpTransport(app, {
+    ...config,
+    stateless: readStatelessEnv(true),
+  });
+}
+
+/**
+ * The `(req, res)` function the Vercel entry default-exports (#8070 D2,
+ * amendment 2). Vercel's Node runtime accepts a request function, an object of
+ * web handlers, or an `http.Server` the module starts listening — a Fastify
+ * instance is none of these, and exporting one answered every request with a
+ * 500. `app.server` is the `http.Server` Fastify builds without listening;
+ * emitting `request` on it is Fastify's own request path, so routing,
+ * `trustProxy` and every hook behave as on a listening server. The app must
+ * already be `ready()`.
+ */
+export function serverlessHandler(
+  app: FastifyInstance,
+): (req: IncomingMessage, res: ServerResponse) => void {
+  return (req, res) => {
+    app.server.emit("request", req, res);
+  };
+}

package/templates/apps/mcp/src/tools/get_business_hours.ts

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   getBusinessHoursInputSchema,
   getBusinessHoursOutputSchema,
@@ -24,7 +22,10 @@ import {
   type GetBusinessHoursOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getBusinessHoursInputSchema, getBusinessHoursOutputSchema };
@@ -36,7 +37,7 @@ const DEFAULT_SLUG = "home";
  * get_business_hours handler.
  *
  * 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).
  */
 export async function ailkGetBusinessHours(
   input: GetBusinessHoursInput,
@@ -44,7 +45,7 @@ export async function ailkGetBusinessHours(
 ): Promise<GetBusinessHoursOutput> {
   getBusinessHoursInputSchema.parse(input);
 
-  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/tools/get_faq.ts

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   getFaqInputSchema,
   getFaqOutputSchema,
@@ -24,7 +22,10 @@ import {
   type GetFaqOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getFaqInputSchema, getFaqOutputSchema };
@@ -36,7 +37,7 @@ const DEFAULT_SLUG = "faq";
  * get_faq handler.
  *
  * 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).
  */
 export async function ailkGetFaq(
   input: GetFaqInput,
@@ -44,7 +45,7 @@ export async function ailkGetFaq(
 ): Promise<GetFaqOutput> {
   getFaqInputSchema.parse(input);
 
-  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/tools/get_locations.ts

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
 import {
   getLocationsInputSchema,
@@ -25,7 +23,10 @@ import {
   type GetLocationsOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getLocationsInputSchema, getLocationsOutputSchema };
@@ -35,7 +36,7 @@ export type { GetLocationsInput, GetLocationsOutput };
  * get_locations handler.
  *
  * 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).
  */
 export async function ailkGetLocations(
   input: GetLocationsInput,
@@ -43,7 +44,7 @@ export async function ailkGetLocations(
 ): Promise<GetLocationsOutput> {
   getLocationsInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });