create-ailk 0.10.0 → 0.11.0

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

@@ -11,6 +11,10 @@
  * (#5971, superseding S15a / issue #610). The describe block at the end of
  * this file pins the registration half from the bootstrap's own side.
  *
+ * #7136: the five licence-feature-tagged tools — registration in both gate
+ * modes, the once-per-boot warning (`reportUnlicensedProTools`), and its
+ * place in `index.ts`'s boot order.
+ *
  * Strategy: createMcpServer() returns the McpServer instance before connecting
  * to a transport. Tests inspect server._registeredTools (plain object in SDK
  * v1.x — no public API exists for listing tools without a live transport).
@@ -18,11 +22,20 @@
  * casts below. Pinned to @modelcontextprotocol/sdk ^1.29.0.
  */
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
 import {
   __setMcpCommerceClaimForTest,
+  __setMcpFeatureGateForTest,
+  __setMcpHeldFeaturesForTest,
   resetMcpCommerceClaim,
 } from "../src/lib/commerce-claim.js";
-import { createMcpServer, listRegisteredTools } from "../src/server.js";
+import {
+  createMcpServer,
+  listRegisteredTools,
+  reportUnlicensedProTools,
+} from "../src/server.js";
 
 describe("createMcpServer", () => {
   it("creates an McpServer without throwing", () => {
@@ -166,3 +179,151 @@ describe("start_purchase registration — gated on the commerce claim (#5971)",
     expect(keyed).toEqual([...keyless, "start_purchase"].sort());
   });
 });
+
+describe("the five licence-feature tools — one-release warning cycle (#7136)", () => {
+  const FLOW_PAIR = ["get_flow", "submit_flow_step"];
+  const BOOKING_TRIO = [
+    "list_availability",
+    "get_event_meta",
+    "create_booking",
+  ];
+  const FIVE = [...FLOW_PAIR, ...BOOKING_TRIO];
+  const FEATURE_OF: Record<string, string> = {
+    get_flow: "flows-deliverables",
+    submit_flow_step: "flows-deliverables",
+    list_availability: "scheduling",
+    get_event_meta: "scheduling",
+    create_booking: "scheduling",
+  };
+
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+
+  beforeEach(() => {
+    process.env.AILK_ENABLED_MODULES = "scheduling,signal-collectors";
+  });
+
+  afterEach(() => {
+    resetMcpCommerceClaim();
+    jest.restoreAllMocks();
+  });
+
+  afterAll(() => {
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
+  function registeredKeys(): string[] {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: mirrors the registration assertions above
+    return Object.keys((createMcpServer() as any)._registeredTools);
+  }
+
+  it("warn mode, no feature held: all five still register and serve", () => {
+    __setMcpHeldFeaturesForTest([]);
+
+    const listed = listRegisteredTools().map((t) => t.name);
+    const registered = registeredKeys();
+    for (const name of FIVE) {
+      expect(listed).toContain(name);
+      expect(registered).toContain(name);
+    }
+  });
+
+  it("warn mode, no feature held: one warning per tool, naming the tool, its feature and the next release", () => {
+    __setMcpHeldFeaturesForTest([]);
+    const warn = jest.fn();
+
+    const names = reportUnlicensedProTools(warn);
+
+    expect(names.slice().sort()).toEqual(FIVE.slice().sort());
+    expect(warn).toHaveBeenCalledTimes(5);
+    for (const name of FIVE) {
+      const message = warn.mock.calls
+        .map(([m]) => m as string)
+        .find((m) => m.includes(`"${name}"`));
+      expect(message).toBeDefined();
+      expect(message).toContain(`"${FEATURE_OF[name]}"`);
+      expect(message).toContain("next release stops serving it");
+    }
+  });
+
+  it("warns only for tools whose feature is unheld", () => {
+    const warn = jest.fn();
+
+    __setMcpHeldFeaturesForTest(["scheduling"]);
+    expect(reportUnlicensedProTools(warn).sort()).toEqual(
+      FLOW_PAIR.slice().sort(),
+    );
+    expect(warn).toHaveBeenCalledTimes(2);
+
+    warn.mockClear();
+    __setMcpHeldFeaturesForTest(["scheduling", "flows-deliverables"]);
+    expect(reportUnlicensedProTools(warn)).toEqual([]);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("never warns about a tool whose module is off", () => {
+    process.env.AILK_ENABLED_MODULES = "signal-collectors";
+    __setMcpHeldFeaturesForTest([]);
+    const warn = jest.fn();
+
+    expect(reportUnlicensedProTools(warn).sort()).toEqual(
+      FLOW_PAIR.slice().sort(),
+    );
+    expect(warn).toHaveBeenCalledTimes(2);
+  });
+
+  it("refuse mode, no feature held: none of the five registers, and nothing is warned", () => {
+    __setMcpFeatureGateForTest("refuse");
+    __setMcpHeldFeaturesForTest([]);
+    const warn = jest.fn();
+
+    expect(reportUnlicensedProTools(warn)).toEqual([]);
+    expect(warn).not.toHaveBeenCalled();
+    const listed = listRegisteredTools().map((t) => t.name);
+    const registered = registeredKeys();
+    for (const name of FIVE) {
+      expect(listed).not.toContain(name);
+      expect(registered).not.toContain(name);
+    }
+  });
+
+  it("refuse mode registers exactly the tools whose feature is held", () => {
+    __setMcpFeatureGateForTest("refuse");
+    __setMcpHeldFeaturesForTest(["scheduling"]);
+
+    const registered = registeredKeys();
+    for (const name of BOOKING_TRIO) expect(registered).toContain(name);
+    for (const name of FLOW_PAIR) expect(registered).not.toContain(name);
+  });
+
+  it("building a server never warns — the warning is once per boot, not per HTTP session", () => {
+    __setMcpHeldFeaturesForTest([]);
+    const consoleWarn = jest
+      .spyOn(console, "warn")
+      .mockImplementation(() => undefined);
+
+    createMcpServer();
+    createMcpServer();
+
+    expect(consoleWarn).not.toHaveBeenCalled();
+  });
+
+  it("index.ts reports after the claim resolves and before either transport starts", () => {
+    const index = readFileSync(join(__dirname, "../src/index.ts"), "utf8");
+    const init = index.indexOf("await initMcpCommerceClaim()");
+    const report = index.indexOf("reportUnlicensedProTools(");
+    const transport = index.indexOf('if (transport === "http")');
+
+    expect(init).toBeGreaterThan(-1);
+    expect(report).toBeGreaterThan(init);
+    expect(transport).toBeGreaterThan(report);
+  });
+
+  it("server.ts never writes to stdout — the stdio transport's JSON-RPC channel", () => {
+    const server = readFileSync(join(__dirname, "../src/server.ts"), "utf8");
+    expect(server).not.toContain("console.log");
+  });
+});

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

@@ -21,7 +21,10 @@
  *   DATABASE_URL=  (required only when CONTENT_ADAPTER=database)
  */
 
-import { initMcpCommerceClaim } from "./lib/commerce-claim.js";
+import {
+  initMcpCommerceClaim,
+  startMcpClaimRefresh,
+} from "./lib/commerce-claim.js";
 import { registerLicenseKeyStore } from "./lib/license-key-store.js";
 import { initMcpPublicWorkspace } from "./lib/public-workspace.js";
 
@@ -55,10 +58,17 @@ try {
 // it. Never throws; without DATABASE_URL the file store stays in place.
 await registerLicenseKeyStore();
 
-// Resolves the deployment's `commerce` add-on claim ONCE, before either
+// 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.
+// 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
@@ -74,6 +84,28 @@ try {
   );
 }
 
+// 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,
+  );
+}
+
 const transport = process.env["MCP_TRANSPORT"] ?? "stdio";
 
 if (transport === "http") {

package/templates/apps/mcp/src/lib/commerce-claim.ts

@@ -1,6 +1,11 @@
 /**
- * The deployment's `commerce` add-on claim, resolved ONCE at boot and read
- * synchronously thereafter (#5971 spec D2).
+ * The deployment's licence claims, resolved at boot and re-read every
+ * `MCP_CLAIM_REFRESH_MS` (#7156 spec D1), read synchronously thereafter: the
+ * `commerce` add-on claim (#5971 spec D2) and,
+ * from the same single `checkLicense()` read, the set of licence features the
+ * deployment holds (#7136 spec D3) — which gates the five `feature`-tagged
+ * catalog tools under `MCP_FEATURE_GATE_MODE`. The claim is the deployment's
+ * own: no tool argument, request header or session feeds it.
  *
  * Why memoised: `createMcpServer()` and `listRegisteredTools()`
  * (`apps/mcp/src/server.ts`) are synchronous and must stay that way —
@@ -20,17 +25,18 @@
  * `unclaimed` at the boundary, and this gate needs neither the stored-JWT read
  * nor the env-presence read the API twin carries.
  *
- * Fail closed (NFR-3): the initial state is `"unclaimed"`, and every path that
- * cannot POSITIVELY establish the claim — an unresolved boot, a thrown
- * `checkLicense()`, a revoked licence, an expired or unreadable one — leaves
- * it that way.
+ * Fail closed (NFR-3): the initial state is `"unclaimed"` with no feature
+ * held, and every path that cannot POSITIVELY establish the claim — an
+ * unresolved boot, a thrown `checkLicense()`, a revoked licence, an expired
+ * or unreadable one — leaves it that way.
  *
  * `apps/*` may not import `apps/*`, so the small duplication of the API-side
  * gate is the same shape `apps/mcp/src/config/modules.ts` already documents
  * for `isModuleEnabled`.
  */
 
-import { checkLicense } from "@working-theory/license";
+import { checkLicense, type ProFeature } from "@working-theory/license";
+import type { McpCatalogOptions } from "@working-theory/metadata";
 
 /** The licence `features[]` claim that turns the commerce add-on on — the
  * same literal `apps/api/src/lib/require-commerce-claim.ts` reads. */
@@ -41,17 +47,50 @@ export type McpCommerceClaim = "claimed" | "unclaimed";
 
 let claim: McpCommerceClaim = "unclaimed";
 
+const NO_FEATURES: ReadonlySet<ProFeature> = new Set();
+
+let heldFeatures: ReadonlySet<ProFeature> = NO_FEATURES;
+
+let featureGateOverride: McpCatalogOptions["featureGate"];
+
 export interface InitMcpCommerceClaimOptions {
   /** Injection seam for tests — when supplied, used in place of the real
    * `checkLicense()` so no suite reaches a licence server (NFR-6). */
   checkLicense?: typeof checkLicense;
 }
 
+/** One resolved read: the commerce claim and the held feature set it
+ * implies, from a single `checkLicense()` call. Never throws — the mapping
+ * both {@link initMcpCommerceClaim} and {@link startMcpClaimRefresh}'s loop
+ * share (#7156 spec D1): a revoked or unreadable licence resolves to the
+ * fail-closed `"unclaimed"` with no feature, rather than propagating. */
+async function readMcpClaims(
+  options: InitMcpCommerceClaimOptions,
+): Promise<{ claim: McpCommerceClaim; features: ReadonlySet<ProFeature> }> {
+  const read = options.checkLicense ?? checkLicense;
+  try {
+    const result = await read();
+    // Revoked paid licences keep verifying until JWT exp (up to 24h after the
+    // server reports `revoked`), so a revoked licence holds no feature. See
+    // packages/license/src/types.ts § LicenseResult, ADR 0014.
+    const features =
+      result.revoked !== true ? new Set(result.features) : NO_FEATURES;
+    const resolvedClaim: McpCommerceClaim = features.has(COMMERCE_FEATURE)
+      ? "claimed"
+      : "unclaimed";
+    return { claim: resolvedClaim, features };
+  } catch {
+    return { claim: "unclaimed", features: NO_FEATURES };
+  }
+}
+
 /**
- * Resolves the deployment's commerce claim, once, and memoises it for
- * {@link mcpCommerceClaim}'s synchronous read. Safe to call more than once
- * (each call re-resolves and re-memoises); production calls it exactly once,
- * at bootstrap (`index.ts`).
+ * Resolves the deployment's commerce claim and held licence features from
+ * ONE `checkLicense()` call, and memoises both for {@link mcpCommerceClaim}'s
+ * and {@link mcpHeldFeatures}'s synchronous reads. Safe to call more than
+ * once (each call re-resolves and re-memoises); production calls it once at
+ * bootstrap, and {@link startMcpClaimRefresh} re-reads through the same
+ * mapping thereafter.
  *
  * Never throws: a licence read that fails resolves to the fail-closed
  * `"unclaimed"` rather than propagating.
@@ -59,20 +98,112 @@ export interface InitMcpCommerceClaimOptions {
 export async function initMcpCommerceClaim(
   options: InitMcpCommerceClaimOptions = {},
 ): Promise<McpCommerceClaim> {
-  const read = options.checkLicense ?? checkLicense;
-  try {
-    const result = await read();
-    // Revoked paid licences keep verifying until JWT exp (up to 24h after the
-    // server reports `revoked`) — the same window `lib/require-paid-tier.ts`
-    // closes. See packages/license/src/types.ts § LicenseResult, ADR 0014.
-    claim =
-      result.revoked !== true && result.features.includes(COMMERCE_FEATURE)
-        ? "claimed"
-        : "unclaimed";
-  } catch {
+  const result = await readMcpClaims(options);
+  claim = result.claim;
+  heldFeatures = result.features;
+  return claim;
+}
+
+/** How often the running server re-reads the deployment's licence claim
+ * (#7156). The server re-reads on this bound, so it agrees with the manifest
+ * route's origin response within it; the route answers
+ * `cache-control: public, max-age=86400`, so a downstream cache may serve an
+ * older manifest for up to 24 hours. A code constant, not an env var.
+ *
+ * The call-time half of the refuse-flip gate is `isServedNow()` in
+ * `server.ts` (#7315): it re-applies this memo at every claim-tagged call, so
+ * a session opened before a re-read still refuses within this bound. */
+export const MCP_CLAIM_REFRESH_MS = 5 * 60 * 1000;
+
+/** How many consecutive re-read intervals may find the previous read still
+ * unfinished before the memo falls back to no claim (#7315 L1). With
+ * `MCP_CLAIM_REFRESH_MS` at 5 minutes, a claim is served at most 20 minutes
+ * after the last read that finished. A code constant, not an env var. */
+export const MCP_CLAIM_MAX_MISSED_REREADS = 3;
+
+/** The running re-read loop's timer, if one is active — module-global so
+ * {@link resetMcpCommerceClaim} can stop it. */
+let refreshTimer: ReturnType<typeof setInterval> | undefined;
+
+/** Bumped by every {@link startMcpClaimRefresh} and {@link
+ * resetMcpCommerceClaim} call. Each loop's closure captures its own
+ * generation at start; a tick whose generation has gone stale (a later
+ * start, or a reset) discards its result instead of writing it. */
+let refreshGeneration = 0;
+
+/** Stops the running re-read loop, if any, and bumps the generation so any
+ * read already in flight from it is discarded on settling. */
+function stopMcpClaimRefresh(): void {
+  if (refreshTimer !== undefined) {
+    clearInterval(refreshTimer);
+    refreshTimer = undefined;
+  }
+  refreshGeneration++;
+}
+
+/**
+ * Starts the bounded re-read: every `MCP_CLAIM_REFRESH_MS`, one licence read,
+ * skipped while the previous one is still pending. At most one loop per
+ * process — a second call replaces the first. The timer is unref'd, so it
+ * never holds a process open. Never throws.
+ *
+ * A tick that finds the previous read still unfinished increments a `missed`
+ * count and returns, as before, UNLESS that count has reached
+ * {@link MCP_CLAIM_MAX_MISSED_REREADS}: at the ceiling the memo falls back to
+ * no claim and a fresh read starts on the same tick (#7315 L1). Each read
+ * captures its own sequence number; a read writes the memo, and clears the
+ * in-flight flag, only while it is still the most recently started read — so
+ * a read the ceiling abandons can never write a stale result once a fresh
+ * read has replaced it.
+ */
+export function startMcpClaimRefresh(
+  options: InitMcpCommerceClaimOptions = {},
+): void {
+  stopMcpClaimRefresh();
+  const generation = refreshGeneration;
+  let inFlight = false;
+  let missed = 0;
+  let readSeq = 0;
+
+  function startRead(): void {
+    inFlight = true;
+    missed = 0;
+    const seq = ++readSeq;
+    void readMcpClaims(options)
+      .then((result) => {
+        if (generation === refreshGeneration && seq === readSeq) {
+          claim = result.claim;
+          heldFeatures = result.features;
+        }
+      })
+      .finally(() => {
+        if (seq === readSeq) {
+          inFlight = false;
+        }
+      });
+  }
+
+  const timer = setInterval(() => {
+    if (generation !== refreshGeneration) return;
+    if (!inFlight) {
+      startRead();
+      return;
+    }
+    if (++missed < MCP_CLAIM_MAX_MISSED_REREADS) return;
     claim = "unclaimed";
+    heldFeatures = NO_FEATURES;
+    startRead();
+  }, MCP_CLAIM_REFRESH_MS);
+  timer.unref();
+  refreshTimer = timer;
+}
+
+/** Test-only writers are inert outside a test run (#7156 L2): each throws,
+ * before touching any state, unless NODE_ENV is "test" — which Jest sets. */
+function assertTestOnly(name: string): void {
+  if (process.env["NODE_ENV"] !== "test") {
+    throw new Error(`${name} is test-only and cannot run outside a test`);
   }
-  return claim;
 }
 
 /** The memoised claim, read synchronously by both gates in `server.ts` and
@@ -85,10 +216,48 @@ export function mcpCommerceClaim(): McpCommerceClaim {
  * licence read entirely. The seam every claim-state matrix in
  * `apps/mcp/__tests__` drives both halves through. */
 export function __setMcpCommerceClaimForTest(next: McpCommerceClaim): void {
+  assertTestOnly("__setMcpCommerceClaimForTest");
   claim = next;
 }
 
-/** Test-only reset — returns to the module's initial, fail-closed state. */
+/** The memoised licence features this deployment holds (#7136), read
+ * synchronously by `server.ts`'s catalog options and boot warning. */
+export function mcpHeldFeatures(): ReadonlySet<ProFeature> {
+  return heldFeatures;
+}
+
+/** Test-only injector — sets the memoised feature set directly, bypassing
+ * the licence read entirely. */
+export function __setMcpHeldFeaturesForTest(
+  features: readonly ProFeature[],
+): void {
+  assertTestOnly("__setMcpHeldFeaturesForTest");
+  heldFeatures = new Set(features);
+}
+
+/** The test-set gate mode, or `undefined` — meaning `MCP_FEATURE_GATE_MODE`
+ * decides. Production never sets it. */
+export function mcpFeatureGateOverride(): McpCatalogOptions["featureGate"] {
+  return featureGateOverride;
+}
+
+/** Test-only injector — overrides `MCP_FEATURE_GATE_MODE` for this module's
+ * readers, so a suite can drive refuse mode without flipping the constant. */
+export function __setMcpFeatureGateForTest(
+  mode: McpCatalogOptions["featureGate"],
+): void {
+  assertTestOnly("__setMcpFeatureGateForTest");
+  featureGateOverride = mode;
+}
+
+/** Test-only reset — returns to the module's initial, fail-closed state: no
+ * commerce claim, no feature held, no gate-mode override — and stops the
+ * re-read loop (#7156 D1), so a suite's `afterEach(resetMcpCommerceClaim)`
+ * cannot leak one. */
 export function resetMcpCommerceClaim(): void {
+  assertTestOnly("resetMcpCommerceClaim");
+  stopMcpClaimRefresh();
   claim = "unclaimed";
+  heldFeatures = NO_FEATURES;
+  featureGateOverride = undefined;
 }

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

@@ -16,10 +16,17 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
   getMcpToolRegistrations,
   OSS_DISABLED_TOOLS,
+  type McpCatalogOptions,
+  type McpToolRegistration,
 } from "@working-theory/metadata";
 
 import { isModuleEnabled } from "./config/modules.js";
-import { mcpCommerceClaim } from "./lib/commerce-claim.js";
+import {
+  mcpCommerceClaim,
+  mcpFeatureGateOverride,
+  mcpHeldFeatures,
+} from "./lib/commerce-claim.js";
+import { notFoundError } from "./lib/errors.js";
 import { ailkAudit } from "./tools/audit.js";
 import { ailkCaptureLead } from "./tools/capture_lead.js";
 import { ailkCreateProject } from "./tools/create_project.js";
@@ -179,8 +186,14 @@ export interface RegisteredToolDescriptor {
  *     repo, and "keyless site" / "keyed site" name the LICENCE, not an env
  *     allowlist.
  *
- * The claim is the boot-memoised `mcpCommerceClaim()`, so this stays
- * synchronous — see `lib/commerce-claim.ts`.
+ * The claim is the memoised claim, re-read every `MCP_CLAIM_REFRESH_MS`; this
+ * stays synchronous — see `lib/commerce-claim.ts`. {@link isServedNow}
+ * re-applies this filter at call time.
+ *
+ * The LICENCE-FEATURE gate (#7136) is not repeated here: it applies upstream,
+ * in `getMcpToolRegistrations()`, through {@link catalogOptionsForThisBoot} —
+ * only the catalog knows `MCP_FEATURE_GATE_MODE`. `catalog-drift.test.ts`
+ * pins that upstream filter from this side in every claim state.
  */
 function shouldRegister(reg: {
   name: string;
@@ -194,13 +207,62 @@ function shouldRegister(reg: {
   return true;
 }
 
+/**
+ * Call-time gate (#7315). True when a server built NOW would register this
+ * tool — the exact same predicate {@link listRegisteredTools} computes, so
+ * the call-time answer and a fresh session's `tools/list` cannot disagree by
+ * construction. A session keeps the tool list it registered at `initialize`;
+ * this makes each listed entry refuse within `MCP_CLAIM_REFRESH_MS` of a
+ * re-read that drops its claim.
+ */
+function isServedNow(reg: McpToolRegistration): boolean {
+  return listRegisteredTools().some((current) => current.name === reg.name);
+}
+
 /**
  * The {@link McpCatalogOptions} this boot's claims imply — passed to
  * `getMcpToolRegistrations()` so the upstream catalog filter and
  * {@link shouldRegister} agree by construction rather than by coincidence.
+ * Carries the held licence features (#7136); the gate mode is the catalog's
+ * `MCP_FEATURE_GATE_MODE` unless a test has overridden it.
+ */
+function catalogOptionsForThisBoot(): McpCatalogOptions {
+  const featureGate = mcpFeatureGateOverride();
+  return {
+    addons: { commerce: mcpCommerceClaim() === "claimed" },
+    features: [...mcpHeldFeatures()],
+    ...(featureGate ? { featureGate } : {}),
+  };
+}
+
+/**
+ * The one-release warning cycle's boot report (#7136): for every tool this
+ * 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
+ * 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
+ * `console.warn` — stderr, never stdout, which is the stdio transport's
+ * JSON-RPC channel. The message carries two catalog literals and nothing
+ * read from the licence.
  */
-function catalogOptionsForThisBoot(): { addons: { commerce: boolean } } {
-  return { addons: { commerce: mcpCommerceClaim() === "claimed" } };
+export function reportUnlicensedProTools(
+  warn: (message: string) => void = console.warn,
+): string[] {
+  const held = mcpHeldFeatures();
+  const unlicensed = getMcpToolRegistrations(catalogOptionsForThisBoot())
+    .filter(shouldRegister)
+    .filter((reg) => reg.feature !== undefined && !held.has(reg.feature));
+  for (const reg of unlicensed) {
+    warn(
+      `[mcp] licence feature "${reg.feature}" is not held by this deployment — ` +
+        `tool "${reg.name}" is served in this release only; the next release ` +
+        `stops serving it unless the licence includes "${reg.feature}".`,
+    );
+  }
+  return unlicensed.map((reg) => reg.name);
 }
 
 /**
@@ -246,6 +308,16 @@ export function createMcpServer(): McpServer {
       throw new Error(`MCP catalog drift: no handler for tool '${reg.name}'`);
     }
     server.tool(reg.name, reg.description, reg.inputShape, async (input) => {
+      if (
+        (reg.feature !== undefined || reg.addon !== undefined) &&
+        !isServedNow(reg)
+      ) {
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(notFoundError("Not found")) },
+          ],
+        };
+      }
       const handler = await resolveHandler(reg.name);
       const result = await handler(input);
       return {

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

@@ -92,7 +92,7 @@ function commerceDisabledBody(): ErrorBody {
  *
  * Returns a typed error BODY rather than throwing on every failure an agent
  * can act on (FR-2) — MCP tools surface errors as their result body, the
- * pattern `lib/require-paid-tier.ts` already establishes.
+ * pattern `lib/errors.ts`'s error bodies establish.
  */
 export async function ailkPurchase(
   input: PurchaseMcpInput,

package/templates/apps/web/app/.well-known/mcp.json/build-manifest.ts

@@ -14,10 +14,13 @@
  * endpoint when MCP_PUBLIC_HTTP_URL is configured.
  * Issue #4157 — `name` resolves from SITE_NAME (env → _site.mdx → neutral
  * default) instead of a hardcoded vendor-brand literal.
+ * Issue #7136 — the five `feature`-tagged tools are gated on the licence
+ * features the route passes in (`heldFeatures`), as registration is.
  */
 
 import {
   getMcpToolCatalog,
+  type McpCatalogOptions,
   type McpToolCatalogEntry,
 } from "@working-theory/metadata";
 
@@ -88,6 +91,16 @@ export interface BuildMcpManifestOptions {
    * claim and passes it in. Omitted ⇒ false, the fail-closed default.
    */
   commerceClaimed?: boolean;
+  /**
+   * The licence features this deployment holds (#7136). In refuse mode a
+   * `feature`-tagged tool is advertised only when its feature is held — the
+   * same gate the MCP server's registration applies. Injected, like
+   * `commerceClaimed`. Omitted ⇒ none, the fail-closed default.
+   */
+  heldFeatures?: readonly string[];
+  /** Overrides `MCP_FEATURE_GATE_MODE` — a test seam; `route.ts` never
+   * passes it. */
+  featureGate?: McpCatalogOptions["featureGate"];
 }
 
 /** Path the MCP server is mounted at, relative to baseUrl. */
@@ -121,6 +134,8 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
     mcpEndpoint: `${opts.baseUrl}${MCP_ENDPOINT_PATH}`,
     tools: getMcpToolCatalog({
       addons: { commerce: opts.commerceClaimed === true },
+      features: opts.heldFeatures ?? [],
+      ...(opts.featureGate ? { featureGate: opts.featureGate } : {}),
     }),
     transport: {
       type: "http",