create-ailk 0.1.0 → 0.2.0

package/templates/apps/mcp/__tests__/schedule_tools.test.ts

@@ -0,0 +1,242 @@
+// oss: false
+/**
+ * Tests for the list_availability + get_event_meta + create_booking MCP
+ * tools (#4416, #4633).
+ *
+ * The claim these tools make is PARITY OF CODE, not just of endpoint: an
+ * agent that hits a taken slot must read `slot_unavailable`, the same word
+ * the route emitted and the same word the booker section branches on. Most of
+ * what follows pins that mapping.
+ */
+
+import { ailkCreateBooking } from "../src/tools/create_booking.js";
+import { ailkGetEventMeta } from "../src/tools/get_event_meta.js";
+import {
+  ailkListAvailability,
+  schedulingKindFromStatus,
+} from "../src/tools/list_availability.js";
+
+jest.mock("@working-theory/api-client", () => ({
+  apiClient: {
+    schedule: {
+      availability: jest.fn(),
+      eventMeta: jest.fn(),
+      book: jest.fn(),
+    },
+  },
+}));
+
+const { apiClient } = require("@working-theory/api-client") as {
+  apiClient: {
+    schedule: { availability: jest.Mock; eventMeta: jest.Mock; book: jest.Mock };
+  };
+};
+
+const VALID_RANGE = {
+  calLink: "sam/fit-check",
+  from: "2026-08-26T00:00:00.000Z",
+  to: "2026-09-02T00:00:00.000Z",
+};
+
+const AVAILABILITY = {
+  event: {
+    title: "15-Minute Call with Sam",
+    durationMinutes: 15,
+    meetingType: "Google Meet",
+    timeZone: "America/Denver",
+  },
+  slots: [
+    { start: "2026-08-27T16:00:00.000Z", end: "2026-08-27T16:15:00.000Z" },
+  ],
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe("schedulingKindFromStatus", () => {
+  it.each([
+    [400, "invalid_input"],
+    [404, "event_not_found"],
+    [409, "slot_unavailable"],
+    [503, "not_configured"],
+    [502, "provider_error"],
+    [500, "provider_error"],
+  ])("maps %i to %s", (status, kind) => {
+    expect(schedulingKindFromStatus(status as number)).toBe(kind);
+  });
+});
+
+describe("ailkListAvailability", () => {
+  it("rejects a malformed calLink without calling api-client", async () => {
+    const result = await ailkListAvailability({
+      ...VALID_RANGE,
+      calLink: "https://cal.com/sam/fit-check",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.kind).toBe("invalid_input");
+    expect(apiClient.schedule.availability).not.toHaveBeenCalled();
+  });
+
+  it("rejects a range wider than the 60-day cap without calling api-client", async () => {
+    const result = await ailkListAvailability({
+      ...VALID_RANGE,
+      to: "2027-08-26T00:00:00.000Z",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(apiClient.schedule.availability).not.toHaveBeenCalled();
+  });
+
+  it("forwards the validated range and returns the derived event meta", async () => {
+    apiClient.schedule.availability.mockResolvedValueOnce({
+      ok: true,
+      body: AVAILABILITY,
+    });
+
+    const result = await ailkListAvailability(VALID_RANGE);
+
+    expect(apiClient.schedule.availability).toHaveBeenCalledWith(VALID_RANGE);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.event.durationMinutes).toBe(15);
+      expect(result.data.slots).toHaveLength(1);
+    }
+  });
+
+  it("surfaces an unconfigured deploy as not_configured, not a bare status", async () => {
+    apiClient.schedule.availability.mockResolvedValueOnce({
+      ok: false,
+      status: 503,
+      body: null,
+    });
+
+    const result = await ailkListAvailability(VALID_RANGE);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.kind).toBe("not_configured");
+  });
+});
+
+describe("ailkGetEventMeta", () => {
+  const EVENTS = {
+    events: [
+      {
+        calLink: "sam/fit-check",
+        event: {
+          title: "15-Minute Call with Sam",
+          durationMinutes: 15,
+          price: { amountMinor: 0, currency: "usd" },
+          timeZone: "America/Denver",
+        },
+      },
+      {
+        calLink: "sam/power-hour",
+        event: {
+          title: "Power Hour",
+          durationMinutes: 60,
+          description: "Sixty focused minutes on your positioning.",
+          price: { amountMinor: 25000, currency: "usd" },
+          timeZone: "America/Denver",
+        },
+      },
+    ],
+  };
+
+  it("rejects a malformed link in the list without calling api-client", async () => {
+    const result = await ailkGetEventMeta({
+      calLinks: "sam/fit-check,https://cal.com/sam/power-hour",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.kind).toBe("invalid_input");
+    expect(apiClient.schedule.eventMeta).not.toHaveBeenCalled();
+  });
+
+  it("forwards the links and returns meta only — a free and a priced event", async () => {
+    apiClient.schedule.eventMeta.mockResolvedValueOnce({
+      ok: true,
+      body: EVENTS,
+    });
+
+    const result = await ailkGetEventMeta({
+      calLinks: "sam/fit-check,sam/power-hour",
+    });
+
+    expect(apiClient.schedule.eventMeta).toHaveBeenCalledWith({
+      calLinks: "sam/fit-check,sam/power-hour",
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.events).toHaveLength(2);
+      expect(result.data.events[0]?.event.price?.amountMinor).toBe(0);
+      expect(result.data.events[1]?.event.price?.amountMinor).toBe(25000);
+      expect(result.data.events[1]?.event.description).toBe(
+        "Sixty focused minutes on your positioning.",
+      );
+    }
+  });
+
+  it("surfaces an unconfigured deploy as not_configured, not a bare status", async () => {
+    apiClient.schedule.eventMeta.mockResolvedValueOnce({
+      ok: false,
+      status: 503,
+      body: null,
+    });
+
+    const result = await ailkGetEventMeta({ calLinks: "sam/fit-check" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.kind).toBe("not_configured");
+  });
+});
+
+describe("ailkCreateBooking", () => {
+  const VALID_BOOKING = {
+    calLink: "sam/fit-check",
+    start: "2026-08-27T16:00:00.000Z",
+    attendee: { name: "Sam Rivera", email: "sam@example.com" },
+  };
+
+  it("rejects a malformed attendee email without calling api-client", async () => {
+    const result = await ailkCreateBooking({
+      ...VALID_BOOKING,
+      attendee: { name: "Sam Rivera", email: "sam@" },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.kind).toBe("invalid_input");
+    expect(apiClient.schedule.book).not.toHaveBeenCalled();
+  });
+
+  it("forwards the booking and returns the provider's identifier", async () => {
+    apiClient.schedule.book.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        bookingId: "bkg_9",
+        start: "2026-08-27T16:00:00.000Z",
+        end: "2026-08-27T16:15:00.000Z",
+      },
+    });
+
+    const result = await ailkCreateBooking(VALID_BOOKING);
+
+    expect(apiClient.schedule.book).toHaveBeenCalledWith(VALID_BOOKING);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data.bookingId).toBe("bkg_9");
+  });
+
+  it("surfaces a lost race as slot_unavailable so the caller can retry another slot", async () => {
+    apiClient.schedule.book.mockResolvedValueOnce({
+      ok: false,
+      status: 409,
+      body: null,
+    });
+
+    const result = await ailkCreateBooking(VALID_BOOKING);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.kind).toBe("slot_unavailable");
+  });
+});

package/templates/apps/mcp/__tests__/submit_lead.test.ts

@@ -55,7 +55,7 @@ describe("ailkCaptureLead — happy path", () => {
   it("forwards canonical body to api-client and returns ok:true with id and persisted", async () => {
     apiClient.leads.submit.mockResolvedValueOnce({
       ok: true,
-      body: { id: "lead_abc123", persisted: "db" },
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d1", persisted: "db" },
     });
 
     const result = await ailkCaptureLead(VALID_INPUT);
@@ -68,7 +68,7 @@ describe("ailkCaptureLead — happy path", () => {
     });
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.id).toBe("lead_abc123");
+      expect(result.id).toBe("lead_00000000-0000-7000-8000-0000000000d1");
       expect(result.persisted).toBe("db");
     }
   });
@@ -135,7 +135,7 @@ describe("ailkCaptureLead — siteId default", () => {
     delete process.env.AILK_SITE_ID;
     apiClient.leads.submit.mockResolvedValueOnce({
       ok: true,
-      body: { id: "lead_default", persisted: "db" },
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d2", persisted: "db" },
     });
 
     await ailkCaptureLead(VALID_INPUT);
@@ -154,7 +154,7 @@ describe("ailkCaptureLead — siteId override", () => {
     process.env.AILK_SITE_ID = "site-abc";
     apiClient.leads.submit.mockResolvedValueOnce({
       ok: true,
-      body: { id: "lead_override", persisted: "db" },
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d3", persisted: "db" },
     });
 
     await ailkCaptureLead(VALID_INPUT);

package/templates/apps/mcp/__tests__/subscribe_newsletter.test.ts

@@ -52,7 +52,7 @@ describe("ailkSubscribeNewsletter — happy path", () => {
   it("forwards canonical body to api-client and returns ok:true with id and persisted", async () => {
     apiClient.leads.subscribe.mockResolvedValueOnce({
       ok: true,
-      body: { id: "sub_xyz789", persisted: "db" },
+      body: { id: "subscr_00000000-0000-7000-8000-0000000000d1", persisted: "db" },
     });
 
     const result = await ailkSubscribeNewsletter(VALID_INPUT);
@@ -64,7 +64,7 @@ describe("ailkSubscribeNewsletter — happy path", () => {
     });
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.id).toBe("sub_xyz789");
+      expect(result.id).toBe("subscr_00000000-0000-7000-8000-0000000000d1");
       expect(result.persisted).toBe("db");
     }
   });
@@ -131,7 +131,7 @@ describe("ailkSubscribeNewsletter — siteId default", () => {
     delete process.env.AILK_SITE_ID;
     apiClient.leads.subscribe.mockResolvedValueOnce({
       ok: true,
-      body: { id: "sub_default", persisted: "db" },
+      body: { id: "subscr_00000000-0000-7000-8000-0000000000d2", persisted: "db" },
     });
 
     await ailkSubscribeNewsletter(VALID_INPUT);
@@ -150,7 +150,7 @@ describe("ailkSubscribeNewsletter — siteId override", () => {
     process.env.AILK_SITE_ID = "site-abc";
     apiClient.leads.subscribe.mockResolvedValueOnce({
       ok: true,
-      body: { id: "sub_override", persisted: "db" },
+      body: { id: "subscr_00000000-0000-7000-8000-0000000000d3", persisted: "db" },
     });
 
     await ailkSubscribeNewsletter(VALID_INPUT);

package/templates/apps/mcp/__tests__/tools/purchase.test.ts

@@ -54,6 +54,22 @@ describe("PurchaseInputSchema", () => {
     expect(result.success).toBe(true);
   });
 
+  it("accepts an optional allowPromotionCodes boolean", () => {
+    const result = PurchaseInputSchema.safeParse({
+      priceId: "price_test_123",
+      allowPromotionCodes: true,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a non-boolean allowPromotionCodes", () => {
+    const result = PurchaseInputSchema.safeParse({
+      priceId: "price_test_123",
+      allowPromotionCodes: "yes",
+    });
+    expect(result.success).toBe(false);
+  });
+
   it("rejects input missing priceId", () => {
     const result = PurchaseInputSchema.safeParse({ quantity: 1 });
     expect(result.success).toBe(false);
@@ -132,6 +148,37 @@ describe("ailkPurchase — valid input", () => {
     expect(body.quantity).toBe(1);
   });
 
+  it("forwards allowPromotionCodes when supplied, omits it otherwise", async () => {
+    const okResponse = () => ({
+      ok: true,
+      status: 201,
+      json: () =>
+        Promise.resolve({
+          sessionId: "cs_test_promo",
+          url: "https://checkout.stripe.com/pay/cs_test_promo",
+        }),
+    });
+    mockFetch.mockResolvedValueOnce(okResponse());
+
+    await ailkPurchase({
+      priceId: "price_test_123",
+      allowPromotionCodes: true,
+    });
+
+    const withFlag = JSON.parse(
+      (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
+    ) as Record<string, unknown>;
+    expect(withFlag.allowPromotionCodes).toBe(true);
+
+    mockFetch.mockResolvedValueOnce(okResponse());
+    await ailkPurchase({ priceId: "price_test_123" });
+
+    const withoutFlag = JSON.parse(
+      (mockFetch.mock.calls[1] as [string, RequestInit])[1].body as string,
+    ) as Record<string, unknown>;
+    expect(withoutFlag).not.toHaveProperty("allowPromotionCodes");
+  });
+
   it("returns { url } on success", async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,

package/templates/apps/mcp/__tests__/update_page.test.ts

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * Tests for the update_page MCP tool handler.
  *

package/templates/apps/mcp/package.json

@@ -6,6 +6,7 @@
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
+    "lint": "tsx ../../scripts/lint-package.ts",
     "build": "tsc -b",
     "type-check": "tsc --noEmit",
     "dev": "node --experimental-vm-modules dist/index.js",
@@ -14,6 +15,9 @@
     "test:coverage": "jest --coverage"
   },
   "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@working-theory/aeo": "workspace:*",
     "@working-theory/api-client": "workspace:*",
     "@working-theory/content-adapters": "workspace:*",
@@ -21,10 +25,8 @@
     "@working-theory/metadata": "workspace:*",
     "@working-theory/schema": "workspace:*",
     "@working-theory/validation": "workspace:*",
-    "@fastify/cors": "^11.2.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "fastify": "^5.7.2",
+    "fastify": "^5.12.1",
+    "yaml": "^2.9.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {

package/templates/apps/mcp/src/config/modules.ts

@@ -0,0 +1,37 @@
+/**
+ * Paid-module presence — the registration-grain signal used by `server.ts`
+ * to decide whether a paid module's tools are wired into this build
+ * (S1, #5088). Mirrors `apps/api/src/config/modules.ts` — apps/* may not
+ * import apps/*, so this tiny reader is duplicated rather than shared.
+ *
+ * `AILK_ENABLED_MODULES` is a comma-separated allowlist (e.g.
+ * `"multi-tenant,scheduling"`). Unset means "every module on" — today's
+ * behavior, unchanged for every existing deployment; an explicit empty
+ * string (`""`) means "no paid modules" (the OSS-strip build target).
+ *
+ * Recognized module keys: `docs`, `multi-tenant`, `scheduling` (the
+ * `ModuleName` vocabulary `packages/create-ailk/src/module-architecture.ts`
+ * already models via `MODULE_SLICES`) plus `content-write` — the Pro
+ * content-write surface (`create_page`/`update_page`/`delete_page`).
+ * `content-write` is intentionally NOT a `MODULE_SLICES` entry: it is not
+ * (yet) a create-ailk `--modules` selector, so it stays a local flag here
+ * rather than widening the create-ailk module vocabulary.
+ */
+
+function enabledModules(): Set<string> | undefined {
+  const raw = process.env.AILK_ENABLED_MODULES;
+  if (raw === undefined) return undefined; // undefined sentinel = "all enabled"
+  return new Set(
+    raw
+      .split(",")
+      .map((m) => m.trim())
+      .filter(Boolean),
+  );
+}
+
+/** Whether the named paid module's tools should register on this build/boot. */
+export function isModuleEnabled(moduleName: string): boolean {
+  const enabled = enabledModules();
+  if (enabled === undefined) return true;
+  return enabled.has(moduleName);
+}

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

@@ -12,15 +12,15 @@
  * each catalog entry to its handler.
  */
 
-import { getMcpToolRegistrations, OSS_DISABLED_TOOLS } from "@working-theory/metadata";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getMcpToolRegistrations, OSS_DISABLED_TOOLS } from "@working-theory/metadata";
 
+import { isModuleEnabled } from "./config/modules.js";
 import { ailkAudit } from "./tools/audit.js";
 import { ailkCaptureLead } from "./tools/capture_lead.js";
-import { ailkCreatePage } from "./tools/create_page.js";
-import { ailkDeletePage } from "./tools/delete_page.js";
 import { ailkGetBusinessHours } from "./tools/get_business_hours.js";
 import { ailkGetFaq } from "./tools/get_faq.js";
+import { ailkGetFlow } from "./tools/get_flow.js";
 import { ailkGetLocations } from "./tools/get_locations.js";
 import { ailkGetOfferings } from "./tools/get_offerings.js";
 import { ailkGetPricing } from "./tools/get_pricing.js";
@@ -31,8 +31,8 @@ import { ailkReadContent } from "./tools/read_content.js";
 import { ailkRequestCallback } from "./tools/request_callback.js";
 import { ailkScaffold } from "./tools/scaffold.js";
 import { ailkSearchContent } from "./tools/search_content.js";
+import { ailkSubmitFlowStep } from "./tools/submit_flow_step.js";
 import { ailkSubscribeNewsletter } from "./tools/subscribe_newsletter.js";
-import { ailkUpdatePage } from "./tools/update_page.js";
 
 /**
  * Tool-name → handler map. Each handler accepts the parsed input the SDK
@@ -65,16 +65,87 @@ const HANDLERS: Record<string, (input: unknown) => Promise<unknown>> = {
   subscribe_newsletter: (input) => ailkSubscribeNewsletter(input as never),
   request_callback: (input) => ailkRequestCallback(input as never),
   scaffold: (input) => ailkScaffold(input as never),
+  get_flow: (input) => ailkGetFlow(input as never),
+  submit_flow_step: (input) => ailkSubmitFlowStep(input as never),
+};
+
+type ToolHandler = (input: unknown) => Promise<unknown>;
+
+/**
+ * Module-conditional tool handlers — the FILE-grain half of S1's registration
+ * gate (#5182).
+ *
+ * `shouldRegister` already keeps a paid module's tools out of the registered
+ * catalog when the module is absent, but that is a RUNTIME filter: a static
+ * `import` of the handler still pins the file into the TYPE graph, so an OSS
+ * strip that deletes it reds `tsc`. A literal `await import()` does not help —
+ * `import()` defers evaluation, not resolution, so `tsc` resolves the specifier
+ * either way and reports TS2307 once the file is gone.
+ *
+ * The specifier therefore comes from this table rather than being written
+ * inline, which is what makes it non-literal at the call site and so
+ * unresolvable by `tsc`. The cast in {@link resolveHandler} is the load-bearing
+ * line: `import(nonLiteral)` yields `any`, and the cast is the only thing
+ * restoring a type at the module boundary.
+ *
+ * Every entry here is a slice file the strip deletes; every entry's catalog
+ * row carries the matching `module` tag, so `shouldRegister` and this table
+ * appear or vanish together.
+ */
+const MODULE_TOOL_ENTRIES: Record<
+  string,
+  { readonly specifier: string; readonly exportName: string }
+> = {
+  // #4416 — the scheduling twins of GET /v1/schedule/availability and
+  // POST /v1/schedule/book. Anonymous, identity-blind, credential-free: the
+  // scheduling credential lives in apps/api, which these reach via api-client.
+  list_availability: {
+    specifier: "./tools/list_availability.js",
+    exportName: "ailkListAvailability",
+  },
+  get_event_meta: {
+    specifier: "./tools/get_event_meta.js",
+    exportName: "ailkGetEventMeta",
+  },
+  create_booking: {
+    specifier: "./tools/create_booking.js",
+    exportName: "ailkCreateBooking",
+  },
   // D14a Stage 1 Unit C (#55): Paid-tier content write surface. Handlers
   // self-gate via requirePaidTier and return canonical error bodies (no throw)
   // for license / validation / conflict / not-found cases — see
   // apps/mcp/src/lib/errors.ts. Catalog entries carry tier: "pro" so agents
   // see the gating before invoking via list_tools.
-  create_page: (input) => ailkCreatePage(input as never),
-  update_page: (input) => ailkUpdatePage(input as never),
-  delete_page: (input) => ailkDeletePage(input as never),
+  create_page: { specifier: "./tools/create_page.js", exportName: "ailkCreatePage" },
+  update_page: { specifier: "./tools/update_page.js", exportName: "ailkUpdatePage" },
+  delete_page: { specifier: "./tools/delete_page.js", exportName: "ailkDeletePage" },
 };
 
+/**
+ * Resolves a tool name to its handler: the statically-imported map first, then
+ * the module-conditional table. Called from inside the already-`async`
+ * `server.tool` callback so {@link createMcpServer} stays synchronous — seven
+ * files call it that way, one of them production (`src/index.ts`), and making
+ * it async would rewrite all seven for no gain.
+ */
+async function resolveHandler(name: string): Promise<ToolHandler> {
+  const direct = HANDLERS[name];
+  if (direct) return direct;
+
+  const entry = MODULE_TOOL_ENTRIES[name];
+  if (!entry) {
+    throw new Error(`MCP catalog drift: no handler for tool '${name}'`);
+  }
+  const mod = (await import(entry.specifier)) as Record<string, ToolHandler | undefined>;
+  const fn = mod[entry.exportName];
+  if (!fn) {
+    throw new Error(
+      `MCP slice drift: '${entry.specifier}' does not export '${entry.exportName}'`,
+    );
+  }
+  return fn;
+}
+
 /**
  * Tool descriptor returned by {@link listRegisteredTools}. A minimal shape
  * sufficient for callers that need to assert which tools are registered
@@ -86,10 +157,25 @@ export interface RegisteredToolDescriptor {
   description: string;
 }
 
+/**
+ * Whether a catalog registration entry should register on this build/boot —
+ * the OSS-disabled filter (static per-name set) AND the module-presence
+ * filter (S1, #5088): a tool tagged with `module` (e.g. `create_booking`
+ * carrying `module: "scheduling"`) registers only when
+ * {@link isModuleEnabled} says its module is present, the same way its
+ * `apps/api` HTTP route is module-conditional in `server.ts` there — so a
+ * tool and its route appear or vanish together, holding API↔MCP parity.
+ */
+function shouldRegister(reg: { name: string; module?: string }): boolean {
+  if (OSS_DISABLED_TOOLS.has(reg.name)) return false;
+  if (reg.module && !isModuleEnabled(reg.module)) return false;
+  return true;
+}
+
 /**
  * Returns the list of tools that {@link createMcpServer} will register, after
- * the OSS catalog filter ({@link OSS_DISABLED_TOOLS}) is applied. Pure — no
- * server instance is constructed.
+ * the OSS catalog filter ({@link OSS_DISABLED_TOOLS}) and the module-presence
+ * filter are applied. Pure — no server instance is constructed.
  *
  * Consumed by `apps/mcp/__tests__/purchase-disabled.test.ts` to assert that
  * disabled tools are absent from the registered catalog. If a future change
@@ -98,20 +184,22 @@ export interface RegisteredToolDescriptor {
  */
 export function listRegisteredTools(): RegisteredToolDescriptor[] {
   return getMcpToolRegistrations()
-    .filter((reg) => !OSS_DISABLED_TOOLS.has(reg.name))
+    .filter(shouldRegister)
     .map((reg) => ({ name: reg.name, description: reg.description }));
 }
 
 /**
  * Creates a configured McpServer with all AILK tools registered, less any
- * tool name in {@link OSS_DISABLED_TOOLS}. The disabled filter is applied
- * defensively here even though the upstream `getMcpToolRegistrations()`
- * already excludes them — a belt-and-braces guard so a future regression in
- * the metadata package can't accidentally re-register a disabled tool.
+ * tool name in {@link OSS_DISABLED_TOOLS} and less any tool whose `module`
+ * is not enabled on this build (S1, #5088; see {@link shouldRegister}). The
+ * disabled filter is applied defensively here even though the upstream
+ * `getMcpToolRegistrations()` already excludes them — a belt-and-braces
+ * guard so a future regression in the metadata package can't accidentally
+ * re-register a disabled tool.
  *
  * Re-enable criteria for each disabled tool live at
  * `docs/internal/roadmaps/phase-3-readiness.md`. S15a (issue #610) is the
- * source of this filter.
+ * source of the disabled-tool filter.
  */
 export function createMcpServer(): McpServer {
   const server = new McpServer({
@@ -120,14 +208,17 @@ export function createMcpServer(): McpServer {
   });
 
   for (const reg of getMcpToolRegistrations()) {
-    if (OSS_DISABLED_TOOLS.has(reg.name)) {
+    if (!shouldRegister(reg)) {
       continue;
     }
-    const handler = HANDLERS[reg.name];
-    if (!handler) {
+    // Boot-time drift detection is preserved: a registered name must be
+    // resolvable from ONE of the two tables, checked here rather than at first
+    // invocation, so a catalog/handler mismatch still fails at startup.
+    if (!HANDLERS[reg.name] && !MODULE_TOOL_ENTRIES[reg.name]) {
       throw new Error(`MCP catalog drift: no handler for tool '${reg.name}'`);
     }
     server.tool(reg.name, reg.description, reg.inputShape, async (input) => {
+      const handler = await resolveHandler(reg.name);
       const result = await handler(input);
       return {
         content: [{ type: "text", text: JSON.stringify(result) }],

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

@@ -1,7 +1,7 @@
 /**
  * capture_lead — capture a contact-form lead.
  *
- * Validates input via Zod, forwards to POST /api/leads/submit via
+ * Validates input via Zod, forwards to POST /v1/leads/submit via
  * @working-theory/api-client, and shapes the response into the MCP output schema.
  * No business logic — orchestration lives in apps/api B6.
  *