create-ailk 0.17.0 → 0.19.0

package/templates/apps/mcp/CLAUDE.md

@@ -8,6 +8,51 @@ 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, `start_purchase` 20 a day,
+  `create_booking` 20 a day and `submit_flow_step` 50 a day, each on its own budget.
+  `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
@@ -26,11 +71,13 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 
 ## The free anonymous tools (enabled at launch)
 
+**The HTTP write branch (6).** `WRITE_TOOLS` in `src/http-transport.ts` — `capture_lead`, `subscribe_newsletter`, `request_callback`, `start_purchase`, `create_booking`, `submit_flow_step` — takes the write-origin allow-list and the AbuseGuard (UA, honeypot, email format, per-IP daily cap); every other tool takes the read branch (UA only). A tool that sends caller-chosen data to the hub belongs in it: `__tests__/write-tool-guard.test.ts` fails when a catalog tool that sends a non-GET request through `@working-theory/api-client` is missing, and makes every new catalog tool pick a branch (#8071).
+
 **Read (9):** `list_pages`, `read_content`, `search_content`, `get_site_info`, `get_business_hours`, `get_locations`, `get_offerings`, `get_pricing`, `get_faq`
 **Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback`
 **Maintenance (2):** `audit`, `create_project`
-**Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has
-**Booking (3):** `list_availability`, `get_event_meta`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`
+**Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has. `submit_flow_step` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP`, default 50 — #8071)
+**Booking (3):** `list_availability`, `get_event_meta`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071)
 
 ### Why the parity test counts 20 and a keyless server registers 19
 
@@ -56,14 +103,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 +165,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 +211,11 @@ 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 — #8071: `create_booking` and `submit_flow_step` join the HTTP write branch — § The free anonymous tools names its six members, the Booking and Flow rows record it, and § What a spoke's MCP host on Vercel enforces lists the two new daily caps — verified against `apps/mcp/src/http-transport.ts` and `apps/mcp/src/abuse/index.ts`.
+
+Prior: 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/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -137,8 +138,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each
@@ -162,7 +163,7 @@
       other commercial damages or losses), even if such Contributor
       has been advised of the possibility of such damages.
 
-   9. Accepting Warranty or Support. While redistributing
+   9. Accepting Warranty or Additional Liability. While redistributing
       the Work or Derivative Works thereof, You may choose to offer,
       and charge a fee for, acceptance of support, warranty, indemnity,
       or other liability obligations and/or rights consistent with this
@@ -171,7 +172,7 @@
       of any other Contributor, and only if You agree to indemnify,
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or support.
+      of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
 
@@ -186,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 Tailwind AI
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/templates/apps/mcp/NOTICE

@@ -0,0 +1,2 @@
+AI Launch Kit
+Copyright 2026 SalesSmyth LLC

package/templates/apps/mcp/__tests__/abuse/guard.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Guard-level tests for abuse/index.ts — the AbuseGuard as a whole, where
+ * daily-cap.test.ts and its siblings test one rule each (#8071).
+ *
+ * Pins:
+ * - AC-4: the four daily-capped tools (capture_lead, start_purchase,
+ *   create_booking, submit_flow_step) each spend their OWN tracker — spending
+ *   one tool's budget from an IP leaves the other three callable from it.
+ * - AC-5: a blank or non-numeric MCP_ABUSE_CREATE_BOOKING_DAILY_CAP /
+ *   MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP yields the default cap (20 / 50),
+ *   never an unlimited one: the call at default + 1 is refused.
+ * - D3: create_booking's attendee.email is format-checked, and a non-object
+ *   attendee is treated as a missing email rather than throwing.
+ */
+
+import type { FastifyRequest } from "fastify";
+
+import {
+  AbuseGuard,
+  AbuseReasonCode,
+  createAbuseGuardFromEnv,
+  DEFAULT_CREATE_BOOKING_DAILY_CAP,
+  DEFAULT_SUBMIT_FLOW_STEP_DAILY_CAP,
+} from "../../src/abuse/index.js";
+
+/** A stub carrying only the two members the guard reads. */
+function requestFrom(ip: string): FastifyRequest {
+  // @ts-expect-error: a full FastifyRequest cannot be built without a server.
+  return {
+    headers: { "user-agent": "Mozilla/5.0 (compatible; TestAgent/1.0)" },
+    ip,
+  };
+}
+
+const CAPPED_TOOLS = [
+  "capture_lead",
+  "start_purchase",
+  "create_booking",
+  "submit_flow_step",
+] as const;
+
+describe("AbuseGuard — each daily-capped tool spends its own tracker (AC-4)", () => {
+  it.each(CAPPED_TOOLS)(
+    "exhausting %s leaves the other three callable from the same IP",
+    (spent) => {
+      const guard = new AbuseGuard({
+        captureLeadDailyCapPerIp: 1,
+        startPurchaseDailyCapPerIp: 1,
+        createBookingDailyCapPerIp: 1,
+        submitFlowStepDailyCapPerIp: 1,
+        blockedUserAgents: "",
+      });
+      const request = requestFrom("198.51.100.4");
+
+      expect(guard.validate(spent, {}, request).allowed).toBe(true);
+      const refused = guard.validate(spent, {}, request);
+      expect(refused).toMatchObject({
+        allowed: false,
+        code: AbuseReasonCode.DAILY_CAP_REACHED,
+      });
+
+      for (const other of CAPPED_TOOLS.filter((t) => t !== spent)) {
+        expect(guard.validate(other, {}, request).allowed).toBe(true);
+      }
+    },
+  );
+});
+
+describe("createAbuseGuardFromEnv — a blank or non-numeric cap falls back to the default (AC-5)", () => {
+  const CASES = [
+    {
+      toolName: "create_booking",
+      envVar: "MCP_ABUSE_CREATE_BOOKING_DAILY_CAP",
+      defaultCap: DEFAULT_CREATE_BOOKING_DAILY_CAP,
+    },
+    {
+      toolName: "submit_flow_step",
+      envVar: "MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP",
+      defaultCap: DEFAULT_SUBMIT_FLOW_STEP_DAILY_CAP,
+    },
+  ] as const;
+
+  afterEach(() => {
+    for (const { envVar } of CASES) delete process.env[envVar];
+  });
+
+  it("the defaults are 20 bookings and 50 flow steps per IP per day", () => {
+    expect(DEFAULT_CREATE_BOOKING_DAILY_CAP).toBe(20);
+    expect(DEFAULT_SUBMIT_FLOW_STEP_DAILY_CAP).toBe(50);
+  });
+
+  describe.each(CASES)("$envVar", ({ toolName, envVar, defaultCap }) => {
+    it.each(["", "abc"])("set to %p refuses the call at default + 1", (raw) => {
+      process.env[envVar] = raw;
+      const guard = createAbuseGuardFromEnv();
+      const request = requestFrom("198.51.100.5");
+
+      for (let i = 0; i < defaultCap; i += 1) {
+        expect(guard.validate(toolName, {}, request).allowed).toBe(true);
+      }
+      expect(guard.validate(toolName, {}, request)).toMatchObject({
+        allowed: false,
+        code: AbuseReasonCode.DAILY_CAP_REACHED,
+      });
+    });
+
+    it("set to a positive integer uses that cap", () => {
+      process.env[envVar] = "3";
+      const guard = createAbuseGuardFromEnv();
+      const request = requestFrom("198.51.100.6");
+
+      for (let i = 0; i < 3; i += 1) {
+        expect(guard.validate(toolName, {}, request).allowed).toBe(true);
+      }
+      expect(guard.validate(toolName, {}, request).allowed).toBe(false);
+    });
+  });
+});
+
+describe("AbuseGuard — create_booking's attendee.email (D3)", () => {
+  const guard = () =>
+    new AbuseGuard({ captureLeadDailyCapPerIp: 50, blockedUserAgents: "" });
+
+  it("refuses a malformed attendee.email with INVALID_EMAIL", () => {
+    const result = guard().validate(
+      "create_booking",
+      { attendee: { name: "Ada", email: "not-an-email" } },
+      requestFrom("198.51.100.7"),
+    );
+
+    expect(result).toMatchObject({
+      allowed: false,
+      code: AbuseReasonCode.INVALID_EMAIL,
+    });
+  });
+
+  it("allows a well-formed attendee.email", () => {
+    const result = guard().validate(
+      "create_booking",
+      { attendee: { name: "Ada", email: "ada@example.com" } },
+      requestFrom("198.51.100.8"),
+    );
+
+    expect(result.allowed).toBe(true);
+  });
+
+  it("does not read a top-level email for create_booking", () => {
+    const result = guard().validate(
+      "create_booking",
+      { email: "not-an-email", attendee: { email: "ada@example.com" } },
+      requestFrom("198.51.100.9"),
+    );
+
+    expect(result.allowed).toBe(true);
+  });
+
+  it.each([undefined, null, "ada@example.com", ["not-an-email"], 7, {}])(
+    "treats attendee %p as a missing email — allowed, never a throw",
+    (attendee) => {
+      expect(() =>
+        guard().validate(
+          "create_booking",
+          { attendee },
+          requestFrom("198.51.100.10"),
+        ),
+      ).not.toThrow();
+      expect(
+        guard().validate(
+          "create_booking",
+          { attendee },
+          requestFrom("198.51.100.10"),
+        ).allowed,
+      ).toBe(true);
+    },
+  );
+
+  it("tolerates a non-object input", () => {
+    for (const input of [null, "x", 3]) {
+      expect(
+        guard().validate("create_booking", input, requestFrom("198.51.100.11"))
+          .allowed,
+      ).toBe(true);
+    }
+  });
+
+  it("still reads capture_lead's top-level email", () => {
+    const result = guard().validate(
+      "capture_lead",
+      { email: "not-an-email" },
+      requestFrom("198.51.100.12"),
+    );
+
+    expect(result).toMatchObject({
+      allowed: false,
+      code: AbuseReasonCode.INVALID_EMAIL,
+    });
+  });
+});

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