create-ailk 0.17.0 → 0.18.0

package/dist/lib/env-catalog.js

@@ -24,7 +24,7 @@ export const ENV_CATALOG = {
         secret: false,
     },
     AILK_CONTENT_ROOT: {
-        description: "Overrides the on-disk content root; defaults to <repo-root>/content.",
+        description: "Overrides the on-disk content root (absolute, or relative to the working directory). Unset, the MCP server tries <cwd>/content, then <cwd>/../../content; the web app defaults to <repo-root>/content.",
         secret: false,
     },
     AILK_ENABLED_MODULES: {
@@ -143,16 +143,12 @@ export const ENV_CATALOG = {
         description: "The port the MCP HTTP transport binds; defaults to 8080.",
         secret: false,
     },
-    MCP_PUBLIC_HTTP_URL: {
-        description: "The public URL of the MCP HTTP transport, advertised by /.well-known/mcp.json.",
-        secret: false,
-    },
-    MCP_RATE_LIMIT_READ_PER_MIN: {
-        description: "Maximum MCP read-tool requests per minute per IP; defaults to 60.",
+    MCP_HTTP_STATELESS: {
+        description: 'Set to "true" or "1" for an MCP HTTP transport with no sessions, which any instance can answer; "false" or "0" keeps sessions in one process. Unset means stateless on Vercel (src/app.ts) and stateful on a port (src/index.ts).',
         secret: false,
     },
-    MCP_RATE_LIMIT_WRITE_PER_MIN: {
-        description: "Maximum MCP write-tool requests per minute per IP; defaults to 10.",
+    MCP_PUBLIC_HTTP_URL: {
+        description: "The public URL of the MCP HTTP transport, advertised by /.well-known/mcp.json.",
         secret: false,
     },
     MCP_TRANSPORT: {

package/dist/topology.d.ts

@@ -122,6 +122,14 @@ export declare function isSpokeExcluded(path: string, opts: IsSpokeExcludedOptio
  * install passes no remap.
  */
 export declare function spokeDestination(destination: string): string;
+/**
+ * The MCP tools a spoke does not serve (#8070 D7). `create_project` spawns
+ * `packages/create-ailk/dist/cli.js` from the MCP host's working directory,
+ * which a spoke does not carry. Both seams carry the list, so the MCP
+ * server's registration and the web discovery manifest agree; a hub's is
+ * empty.
+ */
+export declare const SPOKE_UNSERVED_MCP_TOOLS: readonly string[];
 /**
  * `apps/web/lib/topology.generated.ts` for `topology` (D5) and, on a spoke,
  * its sign-in mode (#7894 D8). The hub render loads `auth.ts` only when a

package/dist/topology.js

@@ -269,13 +269,30 @@ const WEB_SEAM_HEADER = `// topology.generated.ts — how this site reads a sess
 // every scaffold rewrites it. A hub reads the session through Better Auth.
 // A spoke (\`--topology spoke\`) has no database of its own: by default it
 // has no sign-in, so its render reads no session and imports nothing; with
-// \`--hub-sign-in\` (#7894) it reads the sealed hub-session cookie.`;
+// \`--hub-sign-in\` (#7894) it reads the sealed hub-session cookie.
+// UNSERVED_MCP_TOOLS names the MCP tools /.well-known/mcp.json leaves out
+// on this topology (#8070).`;
 const MCP_SEAM_HEADER = `// topology.generated.ts — how this MCP server resolves its workspace store.
 //
 // GENERATED by create-ailk for this site's topology (#7426). Do not edit:
 // 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.`;
+// 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).`;
+/**
+ * The MCP tools a spoke does not serve (#8070 D7). `create_project` spawns
+ * `packages/create-ailk/dist/cli.js` from the MCP host's working directory,
+ * which a spoke does not carry. Both seams carry the list, so the MCP
+ * server's registration and the web discovery manifest agree; a hub's is
+ * empty.
+ */
+export const SPOKE_UNSERVED_MCP_TOOLS = ["create_project"];
+/** The `UNSERVED_MCP_TOOLS` export every web and mcp seam render carries. */
+function unservedToolsExport(topology) {
+    const list = topology === "spoke" ? SPOKE_UNSERVED_MCP_TOOLS : [];
+    return `export const UNSERVED_MCP_TOOLS: readonly string[] = ${JSON.stringify(list)};`;
+}
 const SITE_SESSION_TYPE = `export type SiteSession = {
   user: {
     name?: string | null;
@@ -304,6 +321,7 @@ export function renderWebSeam(topology, signIn = "off") {
         return `${WEB_SEAM_HEADER}
 
 export const TOPOLOGY: "hub" | "spoke" = "hub";
+${unservedToolsExport("hub")}
 ${signInExports({ enabled: true, provider: "site", signInPath: "/sign-in", signUpPath: "/sign-up", signOutEndpoint: null })}
 
 ${SITE_SESSION_TYPE}
@@ -324,6 +342,7 @@ export async function registerSiteStores(): Promise<void> {
 import { readHubSession } from "./hub-session/session";
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${unservedToolsExport("spoke")}
 ${signInExports({ enabled: true, provider: "hub", signInPath: "/account", signUpPath: null, signOutEndpoint: "/api/hub-session/sign-out" })}
 
 ${SITE_SESSION_TYPE}
@@ -340,6 +359,7 @@ export function registerSiteStores(): Promise<void> {
     return `${WEB_SEAM_HEADER}
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${unservedToolsExport("spoke")}
 ${signInExports({ enabled: false, provider: "none", signInPath: null, signUpPath: null, signOutEndpoint: null })}
 
 ${SITE_SESSION_TYPE}
@@ -504,6 +524,7 @@ export { registerLicenseKeyStore } from "./license-key-store.js";
 export type { McpWorkspaceResolution };
 
 export const TOPOLOGY: "hub" | "spoke" = "hub";
+${unservedToolsExport("hub")}
 
 export async function initPublicWorkspace(): Promise<void> {
   await initMcpPublicWorkspace();
@@ -523,6 +544,7 @@ export type McpWorkspaceResolution =
   | { kind: "unresolved"; reason: "ambiguous" };
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${unservedToolsExport("spoke")}
 
 export function initPublicWorkspace(): Promise<void> {
   return Promise.resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",

package/templates/apps/mcp/CLAUDE.md

@@ -8,6 +8,50 @@ Inherits root `CLAUDE.md`. This file adds MCP-specific rules.
 - Transport: stdio at launch
 - Discovery: `/.well-known/mcp.json` published from `apps/web`
 
+## Two entrypoints, one boot (#8070)
+
+- **`src/index.ts`** — run locally: stdio (the default), or HTTP on `MCP_HTTP_PORT` with
+  `MCP_TRANSPORT=http`.
+- **`src/app.ts`** — the Vercel entry. A Vercel project whose root directory is `apps/mcp`
+  detects it (it imports Fastify) and calls its default export, `serverlessHandler(app)`: a
+  `(req, res)` function, the shape Vercel's Node runtime runs — a bare Fastify instance is not
+  one and answers every request with a 500. It never listens. There is **no `vercel.json`**: a
+  `functions` pattern for `src/app.ts` is rejected for the `fastify` builder, so the site's
+  `content/` reaches the function by the builder's file tracing, and the 30-second request cap
+  is `export const config = { maxDuration: 30 }` in `app.ts` (a literal object — the builder
+  reads it by static analysis). `tsconfig.json` names `module` and `moduleResolution` itself:
+  Vercel's type-check edits the entry's nearest `tsconfig.json` as raw JSON before `extends`,
+  and without its own `module` it switches `strict` off, which fails 11 narrowing sites.
+- Both call `bootMcp()` in `src/boot.ts` before building a transport, and read the HTTP
+  configuration through `httpTransportConfigFromEnv()` there. Add a boot step to `bootMcp()`,
+  never to one entry. `src/app.ts` stays thin; what a test needs is in `src/serverless-app.ts`.
+- **`MCP_HTTP_STATELESS`** picks the transport mode: `true`/`1` stateless (no sessions; any
+  instance answers), `false`/`0` stateful (sessions in one process's memory). Unset, the
+  Vercel entry is stateless and `src/index.ts` is stateful. Any other value fails the boot.
+  The Vercel entry needs stateless: a session kept in one instance is lost on the next.
+- **Content root.** Every content tool and `audit` take their root from `mcpContentRoot()`
+  (`lib/content-adapter.ts`): `AILK_CONTENT_ROOT`, else `<cwd>/content`, else
+  `<cwd>/../../content`. Never build a content path from `process.cwd()` in a tool.
+- **`create_project`** is not served on a spoke: the generated seam's `UNSERVED_MCP_TOOLS`
+  keeps it out of registration, and the web manifest drops the same list.
+
+### What a spoke's MCP host on Vercel enforces
+
+- **The address is the caller's, behind exactly one proxy.** The Vercel entry trusts one hop
+  (`trustOneHop`, `src/serverless-app.ts`), so the limits key on the address Vercel's edge
+  saw and a caller's own `X-Forwarded-For` cannot move the key. This holds when the MCP host
+  name points straight at the Vercel project; a second proxy in front keys every caller on
+  that proxy. It is a function, not `trustProxy: 1`, because Fastify 5.12 treats a numeric
+  hop count as trusting nothing. The long-running entry trusts no proxy.
+- **Per address, per instance.** 60 requests a minute across reads and writes (the write rate
+  is parsed but not enforced); `capture_lead` 50 a day and `start_purchase` 20 a day.
+  `subscribe_newsletter` and `request_callback` have no daily cap. Each warm instance counts
+  on its own and a cold start resets the counts, so a caller reaching N instances gets up to
+  N times each limit.
+- **At the hub, one shared bucket.** The MCP lead tools forward no visitor address, so the
+  hub's lead limiter counts every MCP lead write from a spoke against the MCP host's egress
+  address (#8073).
+
 ## Identity-blind by design (hard rule)
 
 This rule governs the anonymous surface, `/mcp` (and stdio) — every tool the catalog returns with
@@ -56,14 +100,14 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   server-wide gate and its own Gate 2 in `tools/purchase.ts`.
   `MCP_FEATURE_GATE_MODE` (`packages/metadata`) decides what an unheld
   feature does. In `"warn"` mode (this release) the five register on module
-  presence alone, and `index.ts` logs one boot warning (stderr) per tool
+  presence alone, and the boot (`bootMcp()`) logs one warning (stderr) per tool
   served without its feature. In `"refuse"` mode (the next release) they
   also need the deployment's licence to hold the feature, and
   `/.well-known/mcp.json` drops them in step. The claim is resolved at boot
   and re-read every `MCP_CLAIM_REFRESH_MS` through `checkLicense()`
   (`lib/commerce-claim.ts`) and fails closed.
-  `index.ts` is the transport entry point and exports no tools — registration
-  is entirely via `createMcpServer`.
+  `index.ts` and `app.ts` are the transport entry points and export no tools —
+  registration is entirely via `createMcpServer`.
 
 ## The signed-in workspace surface (`/mcp/workspace`, #3591)
 
@@ -118,7 +162,7 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
   server's tool list, and calling it by name there returns the module-disabled
   `not_found` body. The claim is resolved at boot and re-read every
   `MCP_CLAIM_REFRESH_MS`
-  (`src/lib/commerce-claim.ts`, awaited in `src/index.ts`) and read
+  (`src/lib/commerce-claim.ts`, awaited in `bootMcp()`, `src/boot.ts`) and read
   synchronously by both the registration filter and the handler's own
   re-check. Calls are rate-limited per IP by the AbuseGuard
   (`MCP_ABUSE_START_PURCHASE_DAILY_CAP`, default 20, on its own tracker).
@@ -164,7 +208,9 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-10-04 — #3591 PR-E (#7684): the identity-blind rule is scoped to the anonymous `/mcp`, and the new § The signed-in workspace surface records `/mcp/workspace` — POST-only and stateless, an agent key per request forwarded to each tool's apps/api twin, eleven `surface: "workspace"` catalog rows that are parity `twin`s and never in the discovery manifest — verified against `apps/mcp/src/http-transport.ts`, `apps/mcp/src/workspace-server.ts` and `packages/metadata/src/mcp-tool-catalog.ts`.
+Last updated: 2026-10-10 — #8070 (amendment 2): the Vercel entry exports a handler, no `vercel.json`; § Two entrypoints, one boot — the Vercel entry `src/app.ts`, the shared `src/boot.ts`, `MCP_HTTP_STATELESS`, `mcpContentRoot()`, `create_project` withheld on a spoke, and what a spoke's MCP host enforces — verified against `apps/mcp/src/{app,boot,serverless-app,index,http-transport,server}.ts` and `lib/content-adapter.ts`.
+
+Prior: 2026-10-04 — #3591 PR-E (#7684): the identity-blind rule is scoped to the anonymous `/mcp`, and the new § The signed-in workspace surface records `/mcp/workspace` — POST-only and stateless, an agent key per request forwarded to each tool's apps/api twin, eleven `surface: "workspace"` catalog rows that are parity `twin`s and never in the discovery manifest — verified against `apps/mcp/src/http-transport.ts`, `apps/mcp/src/workspace-server.ts` and `packages/metadata/src/mcp-tool-catalog.ts`.
 
 Prior: 2026-09-29 — #7136: the five `tier: "pro"` tools name their licence `feature:` (`scheduling`, `flows-deliverables`) and gate on the deployment's own claim under `MCP_FEATURE_GATE_MODE` — `"warn"` this release (served, one boot warning each), `"refuse"` the next. The unused call-time paid-tier guard is deleted.
 

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

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