akanjs 3.0.0-alpha.68 → 3.0.0-alpha.69

package/common/mcpExposure.ts

@@ -16,9 +16,13 @@ export interface McpExposureEndpoint {
   args: { name: string; refName: string; type: string; arrDepth?: number; nullable?: boolean }[];
   guards?: string[];
   fileUpload?: boolean;
+  mcp?: boolean;
 }
 
 export interface McpExposureOption {
+  /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
+  refName: string;
+  key: string;
   /**
    * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
    * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
@@ -56,10 +60,19 @@ export const mcpHintsOf = (key: string, endpoint: { type: string }) => {
 };
 
 /** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
-export const mcpRefusalOf = (endpoint: McpExposureEndpoint, { readOnly }: McpExposureOption = {}): string | null => {
+export const mcpRefusalOf = (
+  endpoint: McpExposureEndpoint,
+  { refName, key, readOnly }: McpExposureOption,
+): string | null => {
+
+  if (endpoint.mcp === false)
+    return "it declares `mcp: false`, so it is deliberately off the agent shelf. HTTP still serves it.";
 
   if (!endpoint.guards?.length)
     return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
+
+  if (key === `light${capitalize(refName)}`)
+    return `it reads the same document as \`${refName}\` in a smaller shape — call \`${refName}\` instead.`;
   if (endpoint.type === "prompt") return mcpPromptRefusalOf(endpoint);
   if (endpoint.type === "pubsub" || endpoint.type === "message")
     return `\`${endpoint.type}\` rides the websocket, and its internal arguments read a socket an MCP request does not have.`;

package/dictionary/base.dictionary.ts

@@ -27,6 +27,24 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       })),
     pubsubPing: fn(["Pubsub Ping", "Pubsub Ping"]),
   }))
+  .error({
+    serverUnreachable: [
+      "Cannot reach the server. Check your connection and try again.",
+      "서버에 연결할 수 없습니다. 네트워크 상태를 확인한 뒤 다시 시도해주세요.",
+    ],
+    serverUnavailable: [
+      "The server is restarting. Please try again in a moment.",
+      "서버가 재시작 중입니다. 잠시 후 다시 시도해주세요.",
+    ],
+    gatewayTimeout: [
+      "The server took too long to answer. Please try again in a moment.",
+      "서버 응답이 지연되고 있습니다. 잠시 후 다시 시도해주세요.",
+    ],
+    unexpectedResponse: [
+      "The server returned an unexpected response ({status}).",
+      "서버가 예상하지 못한 응답을 보냈습니다. ({status})",
+    ],
+  })
   .translate({
     somethingWrong: ["Something's wrong!", "문제가 생겼어요!"],
     connecting: ["Connecting...", "연결 중..."],

package/fetch/client/fetchClient.ts

@@ -443,6 +443,9 @@ export class FetchClient {
     const createGuards = signal.createGuards ?? signal.cruGuards;
     const updateGuards = signal.updateGuards ?? signal.cruGuards;
     const removeGuards = signal.removeGuards ?? signal.cruGuards;
+
+    const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) =>
+      signal.mcp?.[verb] === false ? { mcp: false as const } : {};
     const endpoint: { [key: string]: SerializedEndpoint } = {};
     if (signal.getGuards) {
       endpoint[names.model] = {
@@ -450,12 +453,14 @@ export class FetchClient {
         args: [{ type: "param", name: names.modelId, refName: "ID" }],
         returns: { refName, modelType: "full" },
         guards: signal.getGuards,
+        ...mcp("get"),
       };
       endpoint[names.lightModel] = {
         type: "query",
         args: [{ type: "param", name: names.modelId, refName: "ID" }],
         returns: { refName, modelType: "light" },
         guards: signal.getGuards,
+        ...mcp("get"),
       };
     }
     if (createGuards) {
@@ -464,6 +469,7 @@ export class FetchClient {
         args: [{ type: "body", name: "data", refName, modelType: "input" }],
         returns: { refName, modelType: "full" },
         guards: createGuards,
+        ...mcp("create"),
       };
     }
     if (updateGuards) {
@@ -475,6 +481,7 @@ export class FetchClient {
         ],
         returns: { refName, modelType: "full" },
         guards: updateGuards,
+        ...mcp("update"),
       };
     }
     if (removeGuards) {
@@ -483,6 +490,7 @@ export class FetchClient {
         args: [{ type: "param", name: names.modelId, refName: "ID" }],
         returns: { refName, modelType: "full" },
         guards: removeGuards,
+        ...mcp("remove"),
       };
     }
     return endpoint;
@@ -602,18 +610,22 @@ export class FetchClient {
       list: `${refName}List${capSuffix}`,
       insight: `${refName}Insight${capSuffix}`,
     };
+
+    const mcp = slice.mcp === false ? { mcp: false as const } : {};
     const endpoint: { [key: string]: SerializedEndpoint } = {
       [names.list]: {
         type: "query",
         args: [...slice.args, ...FetchClient.paginationArgs],
         returns: { refName, modelType: "light", arrDepth: 1 },
         guards: slice.guards,
+        ...mcp,
       },
       [names.insight]: {
         type: "query",
         args: [...slice.args],
         returns: { refName, modelType: "insight" },
         guards: slice.guards,
+        ...mcp,
       },
     };
     return endpoint;

package/fetch/client/httpClient.ts

@@ -27,6 +27,19 @@ interface FetchOptions {
   baseUrl?: string;
 }
 
+const jsonContentType = /^application\/(?:[\w.+-]+\+)?json\b/i;
+
+const transportErrorKeyMap = {
+  408: "base.error.gatewayTimeout",
+  502: "base.error.serverUnavailable",
+  503: "base.error.serverUnavailable",
+  504: "base.error.gatewayTimeout",
+} as const;
+
+const serverUnreachableKey = "base.error.serverUnreachable";
+const unexpectedResponseKey = "base.error.unexpectedResponse";
+const transportDetailLimit = 200;
+
 export class HttpClient {
   readonly baseUrl: string;
   constructor(
@@ -42,11 +55,17 @@ export class HttpClient {
   #resolveBaseUrl(baseUrl?: string) {
     return (baseUrl ?? this.baseUrl).replace(/\/$/, "");
   }
+  #resolveUrl(url: string, options: FetchOptions) {
+    return `${this.#resolveBaseUrl(options.baseUrl)}${url}`;
+  }
+
+  static #makeHeaders(headers: Record<string, string>, options: FetchOptions) {
+    return { Accept: "application/json", ...headers, ...options.headers };
+  }
   async get<Returns = unknown>(url: string, options: FetchOptions = {}): Promise<Returns> {
-    const res = await fetch(`${this.#resolveBaseUrl(options.baseUrl)}${url}`, {
-      headers: { "Content-Type": "application/json", ...options.headers },
+    return await this.#request<Returns>(this.#resolveUrl(url, options), {
+      headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options),
     });
-    return await this.#readJsonResponse<Returns>(res);
   }
   #makeReqContent(data: FormData | Record<string, unknown>): { body: BodyInit; headers: Record<string, string> } {
 
@@ -60,12 +79,11 @@ export class HttpClient {
     options: FetchOptions = {},
   ): Promise<Returns> {
     const { body, headers } = this.#makeReqContent(data);
-    const res = await fetch(`${this.#resolveBaseUrl(options.baseUrl)}${url}`, {
+    return await this.#request<Returns>(this.#resolveUrl(url, options), {
       method,
       body,
-      headers: { ...headers, ...options.headers },
+      headers: HttpClient.#makeHeaders(headers, options),
     });
-    return await this.#readJsonResponse<Returns>(res);
   }
   async put<Returns = unknown>(
     url: string,
@@ -82,19 +100,69 @@ export class HttpClient {
     return await this.send<Returns>("POST", url, data, options);
   }
   async delete<Returns = unknown>(url: string, options: FetchOptions = {}): Promise<Returns> {
-    const res = await fetch(`${this.#resolveBaseUrl(options.baseUrl)}${url}`, {
+    return await this.#request<Returns>(this.#resolveUrl(url, options), {
       method: "DELETE",
-      headers: { "Content-Type": "application/json", ...options.headers },
+      headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options),
     });
+  }
+
+  async #request<Returns>(url: string, init: RequestInit): Promise<Returns> {
+    const res = await this.#fetch(url, init);
     return await this.#readJsonResponse<Returns>(res);
   }
 
+  /**
+   * `fetch` rejects only when no response arrived at all — a refused connection, a DNS failure, a socket
+   * dropped mid-flight. That is the server being unreachable, not an error this API reported, so it is
+   * restored as one rather than surfacing the runtime's own `TypeError: Failed to fetch`.
+   */
+  async #fetch(url: string, init: RequestInit) {
+    try {
+      return await fetch(url, init);
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") throw error;
+      throw this.#restoreError({ error: serverUnreachableKey, details: String(error) }, 503);
+    }
+  }
+
   async #readJsonResponse<Returns>(res: Response): Promise<Returns> {
-    const body = await res.json();
+    const body = await this.#readBody(res);
     if (res.ok) return body as Returns;
     throw this.#restoreError(body, res.status);
   }
 
+  /**
+   * A proxy answers a restarting upstream with a page of its own — nginx's `504 Gateway Time-out` HTML,
+   * the federation gateway's plain-text 503. That body is not this API's, so parsing it would surface the
+   * parser's complaint (`Unexpected token '<'`) instead of the fact that the server is down.
+   */
+  async #readBody(res: Response) {
+    if (jsonContentType.test(res.headers.get("content-type") ?? "")) {
+      try {
+        return (await res.json()) as unknown;
+      } catch (error) {
+        throw this.#transportError(res.status, String(error));
+      }
+    }
+    const raw = await res.text();
+    const parsed = HttpClient.#parseJson(raw);
+    if (parsed === undefined) throw this.#transportError(res.status, raw);
+    return parsed;
+  }
+
+  static #parseJson(raw: string): unknown {
+    try {
+      return JSON.parse(raw) as unknown;
+    } catch {
+      return undefined;
+    }
+  }
+
+  #transportError(status: number, detail: string): RestoredError {
+    const error = transportErrorKeyMap[status as keyof typeof transportErrorKeyMap] ?? unexpectedResponseKey;
+    return this.#restoreError({ error, data: { status }, details: detail.slice(0, transportDetailLimit) }, status);
+  }
+
   #restoreError(body: unknown, fallbackStatusCode: number): RestoredError {
     const payload =
       body && typeof body === "object" && "error" in body

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.68",
+  "version": "3.0.0-alpha.69",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -367,4 +367,4 @@
     "bun": ">=1.4.0"
   },
   "main": "./index.ts"
-}
+}

package/server/akanApp.ts

@@ -780,7 +780,7 @@ export class AkanApp {
           `Child ${child.idx}/${child.role} upstream is unreachable (${child.upstream.socketPath}); restarting`,
         );
         this.#scheduleChildRestart(child, child.proc, "upstream-open-failed");
-        return new Response("Federation child upstream is unreachable; restarting", { status: 503 });
+        return AkanApp.#unavailableResponse(req, "Federation child upstream is unreachable; restarting");
       }
       throw error;
     } finally {
@@ -802,13 +802,13 @@ export class AkanApp {
    */
   async #pickReadyFederationChild(req: Request): Promise<ChildState | null> {
     const ready = this.#pickFederationChild();
-    if (ready) return ready;
+    if (ready?.upstream) return ready;
     const deadline = performance.now() + this.#upstreamWaitMs;
     while (performance.now() < deadline) {
       if (this.#stopping || req.signal.aborted || this.#getCrashLoopDetail()) return null;
       await Bun.sleep(50);
       const child = this.#pickFederationChild();
-      if (child) return child;
+      if (child?.upstream) return child;
     }
     return null;
   }
@@ -844,13 +844,26 @@ export class AkanApp {
           text: "No healthy federation child is ready",
           note: "A replica is booting or restarting — this page reloads itself as soon as it answers.",
         };
-    if (!req.headers.get("accept")?.includes("text/html")) {
-      return new Response(page.text, { status: 503, headers: { "cache-control": "no-store" } });
+    if (req.headers.get("accept")?.includes("text/html")) {
+      return new Response(AkanApp.#statusPageHtml(page), {
+        status: 503,
+        headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+      });
     }
-    return new Response(AkanApp.#statusPageHtml(page), {
-      status: 503,
-      headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
-    });
+    return AkanApp.#unavailableResponse(req, page.text);
+  }
+
+  /**
+   * An API caller asks for JSON, so it is answered with the payload `HttpClient` restores into an `Err` —
+   * a bare-text 503 reaches the browser as a JSON parse error naming the page body instead of the outage.
+   */
+  static #unavailableResponse(req: Request, detail: string): Response {
+    const headers = { "cache-control": "no-store" };
+    if (!req.headers.get("accept")?.includes("application/json")) return new Response(detail, { status: 503, headers });
+    return Response.json(
+      { error: "base.error.serverUnavailable", statusCode: 503, data: { status: 503 }, details: detail },
+      { status: 503, headers },
+    );
   }
 
   static #statusPageHtml({ heading, detail, note }: { heading: string; detail: string; note: string }) {

package/server/mcp/McpRouter.ts

@@ -14,6 +14,7 @@ import {
   type McpExposedEndpoint,
   type McpJsonRpcRequest,
   McpProgress,
+  type McpSignalCost,
   type McpToolResult,
 } from "../../signal/mcp";
 import type { MiddlewareCls } from "../../signal/middleware";
@@ -94,6 +95,8 @@ const discoverCache: McpCacheHint = { ttlMs: 3_600_000, cacheScope: "public" };
  */
 export class McpRouter {
   static readonly logger = new Logger("McpRouter");
+  /** Past this a listing is a meaningful slice of a model's window, which is where it becomes worth saying so. */
+  static readonly listingWarnBytes = 100 * 1024;
 
   readonly #props: McpRouterProps;
   readonly #dispatcher: McpDispatcher;
@@ -138,9 +141,18 @@ export class McpRouter {
    */
   report() {
     try {
-      const { tools, prompts, resourceTemplates, refusals, undescribed } = this.#getDocument();
+      const document = this.#getDocument();
+      const { tools, prompts, resourceTemplates, refusals, undescribed } = document;
+      const cost = document.listingCost;
       const counts = `tools=${tools.length} prompts=${prompts.length} resourceTemplates=${resourceTemplates.length}`;
-      McpRouter.logger.debug(`MCP catalogue: ${counts}${this.#props.readOnly ? " (read-only deployment)" : ""}`);
+      const readOnly = this.#props.readOnly ? " (read-only deployment)" : "";
+      McpRouter.logger.debug(`MCP catalogue: ${counts}${readOnly} · listing ${McpRouter.#kb(cost.bytes)}`);
+      if (cost.bySignal.length) McpRouter.logger.debug(`MCP catalogue cost: ${McpRouter.#costLine(cost.bySignal)}`);
+
+      if (cost.bytes > McpRouter.listingWarnBytes)
+        McpRouter.logger.warn(
+          `MCP listing is ${McpRouter.#kb(cost.bytes)}, which every agent that connects pays before its first turn. Narrow it with \`mcp: false\` on an endpoint or the \`mcp\` map on \`slice()\`.`,
+        );
 
       if (!tools.length && !prompts.length)
         McpRouter.logger.warn(
@@ -157,6 +169,20 @@ export class McpRouter {
     }
   }
 
+  static #kb(bytes: number) {
+    return bytes < 1024 ? `${bytes}B` : `${Math.round(bytes / 1024)}KB`;
+  }
+
+  /** The heaviest signals first, capped: a fleet of forty models would otherwise wrap the line off the screen. */
+  static #costLine(bySignal: McpSignalCost[]) {
+    const shown = bySignal.slice(0, 8);
+    const rest = bySignal.length - shown.length;
+    const line = shown
+      .map(({ refName, entries, bytes }) => `${refName} ${entries}/${McpRouter.#kb(bytes)}`)
+      .join(" · ");
+    return rest > 0 ? `${line} · +${rest} more` : line;
+  }
+
   /** Rebuilding per request would re-derive every tool schema on a list agents poll; the set is fixed at boot. */
   #getDocument() {
     if (this.#document) return this.#document;

package/signal/mcp/McpDocument.ts

@@ -1,4 +1,4 @@
-import { capitalize, isMcpDescribableArg, mcpHintsOf, mcpRefusalOf } from "akanjs/common";
+import { isMcpDescribableArg, mcpHintsOf, mcpRefusalOf } from "akanjs/common";
 import { FetchClient } from "akanjs/fetch";
 import { type AgentCandidate, AgentCatalogue, type AgentRefusal, type AgentUndescribed } from "../agent";
 import { type JsonSchema, JsonSchemaBuilder } from "../schema";
@@ -30,6 +30,18 @@ export interface McpExposedEndpoint {
 export type McpRefusal = AgentRefusal;
 export type McpUndescribed = AgentUndescribed;
 
+/** What one signal contributes to a listing, so a catalogue that grew can say where it grew. */
+export interface McpSignalCost {
+  refName: string;
+  entries: number;
+  bytes: number;
+}
+
+export interface McpListingCost {
+  bytes: number;
+  bySignal: McpSignalCost[];
+}
+
 /**
  * Turns the serialized signal registry into the three MCP catalogues and answers the lookups `tools/call` and
  * `resources/read` need. Pure: no IO and no DI — the sibling of `createOpenApiDocument`.
@@ -62,6 +74,7 @@ export class McpDocument {
   readonly #byPromptName = new Map<string, { exposed: McpExposedEndpoint; prompt: McpPrompt }>();
   /** Keyed by endpoint key: what is addressable, and by exactly which uri. */
   readonly #templates = new Map<string, string>();
+  #cost: McpListingCost | null = null;
 
   constructor(serializedSignal: Record<string, SerializedSignal>, options: McpDocumentOptions = {}) {
     this.#options = options;
@@ -82,6 +95,30 @@ export class McpDocument {
     this.undescribed = this.#catalogue.undescribed;
   }
 
+  /**
+   * Roughly what a `tools/list` plus `prompts/list` costs the caller, and which signals it went to.
+   *
+   * Worth reporting because the number is nobody's intuition: MCP has no shared component section and forbids a
+   * `$ref` across entries, so every entry inlines the full schema of every model it mentions — a plain 21-field
+   * model with one named slice ships 12KB across its eight entries, three quarters of it the same four schemas
+   * repeated. A catalogue is re-sent whole to every agent that connects, before its first turn.
+   */
+  get listingCost(): McpListingCost {
+    if (this.#cost) return this.#cost;
+    const bySignal = new Map<string, McpSignalCost>();
+    const add = (refName: string, entry: unknown) => {
+      const cost = bySignal.get(refName) ?? { refName, entries: 0, bytes: 0 };
+      cost.entries += 1;
+      cost.bytes += JSON.stringify(entry).length;
+      bySignal.set(refName, cost);
+    };
+    for (const tool of this.tools) add(this.#byToolName.get(tool.name)?.refName ?? tool.name, tool);
+    for (const prompt of this.prompts) add(this.#byPromptName.get(prompt.name)?.exposed.refName ?? prompt.name, prompt);
+    const costs = [...bySignal.values()].sort((a, b) => b.bytes - a.bytes);
+    this.#cost = { bytes: costs.reduce((sum, cost) => sum + cost.bytes, 0), bySignal: costs };
+    return this.#cost;
+  }
+
   findTool(name: string): McpExposedEndpoint | undefined {
     return this.#byToolName.get(name);
   }
@@ -132,7 +169,11 @@ export class McpDocument {
         endpoint: candidate.endpoint,
       };
       
-      const reason = mcpRefusalOf(item.endpoint, { readOnly: this.#options.readOnly });
+      const reason = mcpRefusalOf(item.endpoint, {
+        refName: item.refName,
+        key: item.key,
+        readOnly: this.#options.readOnly,
+      });
       if (reason) {
         this.#catalogue.refuse(item.key, reason);
         continue;
@@ -273,7 +314,6 @@ export class McpDocument {
 
   static #uriTemplate(refName: string, key: string, endpoint: SerializedEndpoint) {
     if (key === refName) return McpUriTemplate.model(refName);
-    if (key === `light${capitalize(refName)}`) return McpUriTemplate.light(refName);
     const listPrefix = `${refName}List`;
     if (!key.startsWith(listPrefix)) return undefined;
     const suffix = key.slice(listPrefix.length);

package/signal/mcp/McpUriTemplate.ts

@@ -15,14 +15,11 @@ export interface McpResourceTarget {
 export class McpUriTemplate {
   static readonly scheme = "akan";
   /** Reserved second segment: a model id may never take one of these values, and none is a valid ObjectId. */
-  static readonly #reserved = new Set(["light", "list"]);
+  static readonly #reserved = new Set(["list"]);
 
   static model(refName: string) {
     return `${McpUriTemplate.scheme}://${refName}/{${refName}Id}`;
   }
-  static light(refName: string) {
-    return `${McpUriTemplate.scheme}://${refName}/light/{${refName}Id}`;
-  }
   /**
    * The model's own unfiltered list is the bare `…/list`, never `…/list/<token>`. A named slice occupies the
    * third segment, and a slice key is an author-chosen identifier — so any token put there for the root list
@@ -51,8 +48,6 @@ export class McpUriTemplate {
       return { endpointKey: refName, args: { [`${refName}Id`]: second } };
     if (segments.length === 2 && second === "list")
       return { endpointKey: `${refName}List`, args: McpUriTemplate.#searchArgs(search) };
-    if (segments.length === 3 && second === "light" && third)
-      return { endpointKey: `light${capitalize(refName)}`, args: { [`${refName}Id`]: third } };
     if (segments.length === 3 && second === "list" && third)
       return { endpointKey: `${refName}List${capitalize(third)}`, args: McpUriTemplate.#searchArgs(search) };
     return null;

package/signal/serializer/fetch.serializer.ts

@@ -13,6 +13,7 @@ import type {
   SerializedFilter,
   SerializedReturns,
   SerializedSignal,
+  SerializedSignalMcp,
   SerializedSlice,
   SliceCls,
   SliceInfo,
@@ -69,6 +70,7 @@ export class FetchSerializer {
       ...(endpointInfo.signalOption.method ? { method: endpointInfo.signalOption.method } : {}),
       ...(endpointInfo.signalOption.fileUpload ? { fileUpload: true } : {}),
       ...(guards?.length ? { guards } : {}),
+      ...(endpointInfo.signalOption.mcp === false ? { mcp: false as const } : {}),
     };
   }
 
@@ -107,6 +109,7 @@ export class FetchSerializer {
       args: sliceInfo.args.map(FetchSerializer.#serializeArg),
       ...(sliceInfo.signalOption.path ? { path: sliceInfo.signalOption.path } : {}),
       ...(guards?.length ? { guards } : {}),
+      ...(sliceInfo.signalOption.mcp === false ? { mcp: false as const } : {}),
     };
   }
 
@@ -146,10 +149,21 @@ export class FetchSerializer {
       ...(sliceCls.removeGuards !== sliceCls.cruGuards && sliceCls.removeGuards.filter((g) => g.name !== "None").length
         ? { removeGuards: sliceCls.removeGuards.map((g) => g.name) }
         : {}),
+      ...FetchSerializer.#serializeSliceMcp(sliceCls),
       endpoint,
     };
   }
 
+  /** Only the verbs kept off the shelf travel: `true` is the default, so emitting it would grow every payload. */
+  static #serializeSliceMcp(sliceCls: SliceCls): { mcp?: SerializedSignalMcp } {
+    const mcp = Object.fromEntries(
+      Object.entries(sliceCls.mcp ?? {})
+        .filter(([, published]) => !published)
+        .map(([verb]) => [verb, false]),
+    ) as SerializedSignalMcp;
+    return Object.keys(mcp).length ? { mcp } : {};
+  }
+
   static serializeServiceSignal(endpointCls: EndpointCls): SerializedSignal {
     const endpointMeta = endpointCls[ENDPOINT_META] as { [key: string]: EndpointInfo };
     const endpoint: { [key: string]: SerializedEndpoint } = {};

package/signal/slice.ts

@@ -38,8 +38,17 @@ export type SliceCls<
   createGuards: GuardCls[];
   updateGuards: GuardCls[];
   removeGuards: GuardCls[];
+  mcp: ResolvedSliceMcp;
 };
 
+/** The generated verbs, resolved to a plain answer each. `root` is not here: it rides on the root slice itself. */
+export interface ResolvedSliceMcp {
+  get: boolean;
+  create: boolean;
+  update: boolean;
+  remove: boolean;
+}
+
 interface RootSliceOption {
   guards?: {
     root?: GuardCls | GuardCls[];
@@ -49,6 +58,18 @@ interface RootSliceOption {
     update?: GuardCls | GuardCls[];
     remove?: GuardCls | GuardCls[];
   };
+  /**
+   * Which of the entries this call generates belong on an agent's shelf. Keyed exactly like `guards` above and
+   * scoped to exactly what `guards` governs — the root slice and the generated CRUD — so `false` here narrows the
+   * catalogue and nothing else. `create`/`update`/`remove` fall back to `cru` the same way their guards do, and
+   * the bare `false` is every key at once.
+   *
+   * A named slice and a custom endpoint declare their own `mcp` in their own signal option, exactly as they
+   * declare their own guards. This is curation, not authorization: HTTP is unchanged.
+   */
+  mcp?:
+    | boolean
+    | { root?: boolean; get?: boolean; cru?: boolean; create?: boolean; update?: boolean; remove?: boolean };
   prefix?: string;
 }
 
@@ -131,6 +152,15 @@ export function slice<
   const createGuards = option.guards?.create ? toGuards(option.guards.create) : cruGuards;
   const updateGuards = option.guards?.update ? toGuards(option.guards.update) : cruGuards;
   const removeGuards = option.guards?.remove ? toGuards(option.guards.remove) : cruGuards;
+  const mcpOption =
+    typeof option.mcp === "boolean" ? { root: option.mcp, get: option.mcp, cru: option.mcp } : option.mcp;
+  const cruMcp = mcpOption?.cru !== false;
+  const mcp: ResolvedSliceMcp = {
+    get: mcpOption?.get !== false,
+    create: mcpOption?.create ?? cruMcp,
+    update: mcpOption?.update ?? cruMcp,
+    remove: mcpOption?.remove ?? cruMcp,
+  };
   const srvKeys = [
     ...new Set([...Object.keys(srv.srvMap), ...libSlices.flatMap((libSlice) => Object.keys(libSlice.srv.srvMap))]),
   ];
@@ -144,10 +174,11 @@ export function slice<
     static createGuards = createGuards;
     static updateGuards = updateGuards;
     static removeGuards = removeGuards;
+    static mcp = mcp;
     static [SLICE_META] = Object.assign(
       {
 
-        [""]: init({ guards: rootGuards })
+        [""]: init({ guards: rootGuards, ...(mcpOption?.root === false ? { mcp: false } : {}) })
           .search<"queryKey", string>("queryKey", String)
           .search<"args", unknown[]>("args", Any)
           .exec((queryKey, args) => {

package/signal/types.ts

@@ -85,6 +85,17 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
   method?: HttpMutationMethod;
   /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
   fileUpload?: boolean;
+  /**
+   * Whether this endpoint belongs on an agent's shelf. `true` — the default — publishes it to MCP subject to the
+   * guard and shape rules; `false` keeps it out of the catalogue entirely.
+   *
+   * This is curation, not authorization: HTTP serves the endpoint exactly as before, and the guards are still the
+   * only thing deciding who may call it. Write it where an endpoint is perfectly guarded and still has no business
+   * on a shelf — a step of a UI-driven state machine (`requestPhoneCodeForSignin`), or a read a model would only
+   * ever call by mistake. Every catalogue entry carries the model schemas it mentions, so one endpoint dropped
+   * here is kilobytes off every `tools/list`.
+   */
+  mcp?: boolean;
   /**
    * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
    * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
@@ -108,6 +119,13 @@ interface SerializedSignalOption {
   guards?: string[];
   method?: HttpMutationMethod;
   fileUpload?: boolean;
+  /**
+   * Only ever `false`, and only when something declared it: `true` is the default, so serializing it would ship a
+   * field per endpoint that says nothing. Resolved here rather than left to the reader because the browser API
+   * explorer has guard *names* and no classes, and a second implementation of the rule would eventually disagree
+   * with the catalogue.
+   */
+  mcp?: false;
 }
 export interface SerializedSlice extends SerializedSignalOption {}
 
@@ -152,6 +170,19 @@ export interface SerializedSignal {
   createGuards?: string[];
   updateGuards?: string[];
   removeGuards?: string[];
+  /**
+   * Which generated CRUD verbs this model keeps off the agent shelf. Carried on the signal because the endpoints
+   * it names do not exist until `FetchClient.getBaseEndpoint` synthesizes them. Only the `false` keys travel.
+   */
+  mcp?: SerializedSignalMcp;
+}
+
+/** Keyed by generated verb, mirroring the `guards` map `slice()` takes. The root slice's own flag rides on `slice[""]`. */
+export interface SerializedSignalMcp {
+  get?: false;
+  create?: false;
+  update?: false;
+  remove?: false;
 }
 
 export type SignalType = "restapi" | "websocket";

package/types/common/mcpExposure.d.ts

@@ -22,8 +22,12 @@ export interface McpExposureEndpoint {
     }[];
     guards?: string[];
     fileUpload?: boolean;
+    mcp?: boolean;
 }
 export interface McpExposureOption {
+    /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
+    refName: string;
+    key: string;
     /**
      * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
      * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
@@ -50,7 +54,7 @@ export declare const mcpHintsOf: (key: string, endpoint: {
     openWorldHint: boolean;
 };
 /** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
-export declare const mcpRefusalOf: (endpoint: McpExposureEndpoint, { readOnly }?: McpExposureOption) => string | null;
+export declare const mcpRefusalOf: (endpoint: McpExposureEndpoint, { refName, key, readOnly }: McpExposureOption) => string | null;
 /**
  * A prompt is a read exposed on the same terms as a query, so every rejection here is one thing: an argument
  * `prompts/get` cannot carry. Its `arguments` is a flat string map — one string per name, and no schema beside it

package/types/dictionary/base.dictionary.d.ts

@@ -1 +1 @@
-export declare const baseDictionary: import("./dictInfo.d.ts").ServiceDictInfo<[string, string], "ping" | "pingBody" | "pingParam" | "pingQuery" | "wsPing" | "pubsubPing", never, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">;
+export declare const baseDictionary: import("./dictInfo.d.ts").ServiceDictInfo<[string, string], "ping" | "pingBody" | "pingParam" | "pingQuery" | "wsPing" | "pubsubPing", "serverUnreachable" | "serverUnavailable" | "gatewayTimeout" | "unexpectedResponse", "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">;

package/types/dictionary/dictionary.d.ts

@@ -1,13 +1,13 @@
 import type { AgentEndpoint, AgentTurn, BaseEndpoint } from "akanjs/signal";
 export declare const dictionary: {
-    base: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">, never>;
+    base: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view">, "base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse">;
     agentTurn: import("./locale.d.ts").DictModule<import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc`, never>;
     agent: import("./locale.d.ts").DictModule<import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">;
 };
-export declare const Err: import("./trans.d.ts").ErrConstructor<"agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">, translate: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja", key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, data?: import("./trans.d.ts").TranslationData) => string, msg: {
+export declare const Err: import("./trans.d.ts").ErrConstructor<"base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse" | "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed">, translate: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja", key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, data?: import("./trans.d.ts").TranslationData) => string, msg: {
     info: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     success: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     error: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     warning: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
     loading: (key: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, option?: import("./trans.d.ts").TransMessageOption) => void;
-}, getDictionary: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja") => object, getAllDictionary: () => import("./trans.d.ts").RootDictionary, __Dict_Key__: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, __Error_Key__: "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed";
+}, getDictionary: (lang: "en" | "ko" | "zhChs" | "zhCht" | "ja") => object, getAllDictionary: () => import("./trans.d.ts").RootDictionary, __Dict_Key__: import("./locale.d.ts").ServiceTranslatorKey<"base", BaseEndpoint, "error" | "remove" | "save" | "refresh" | "password" | "stop" | "send" | "skip" | "agent" | "ok" | "connecting" | "new" | "somethingWrong" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "success" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "unauthorized" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "approve" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "edit" | "view"> | import("./locale.d.ts").ScalarTranslatorKey<"agentTurn", AgentTurn, never> | `agentStop.${string}` | `agentStop.${string}.desc` | import("./locale.d.ts").ServiceTranslatorKey<"agent", AgentEndpoint, never>, __Error_Key__: "base.error.gatewayTimeout" | "base.error.serverUnavailable" | "base.error.serverUnreachable" | "base.error.unexpectedResponse" | "agent.error.llmUnavailable" | "agent.error.deepseekRequestFailed";

package/types/server/mcp/McpRouter.d.ts

@@ -41,6 +41,8 @@ export interface McpRouterProps {
 export declare class McpRouter {
     #private;
     static readonly logger: Logger;
+    /** Past this a listing is a meaningful slice of a model's window, which is where it becomes worth saying so. */
+    static readonly listingWarnBytes: number;
     constructor(props: McpRouterProps);
     createRoutes(): HttpRoutes;
     /**

package/types/signal/mcp/McpDocument.d.ts

@@ -22,6 +22,16 @@ export interface McpExposedEndpoint {
  */
 export type McpRefusal = AgentRefusal;
 export type McpUndescribed = AgentUndescribed;
+/** What one signal contributes to a listing, so a catalogue that grew can say where it grew. */
+export interface McpSignalCost {
+    refName: string;
+    entries: number;
+    bytes: number;
+}
+export interface McpListingCost {
+    bytes: number;
+    bySignal: McpSignalCost[];
+}
 /**
  * Turns the serialized signal registry into the three MCP catalogues and answers the lookups `tools/call` and
  * `resources/read` need. Pure: no IO and no DI — the sibling of `createOpenApiDocument`.
@@ -46,6 +56,15 @@ export declare class McpDocument {
     /** What is published with no description of its own, which is the field a model picks a tool by. */
     readonly undescribed: McpUndescribed[];
     constructor(serializedSignal: Record<string, SerializedSignal>, options?: McpDocumentOptions);
+    /**
+     * Roughly what a `tools/list` plus `prompts/list` costs the caller, and which signals it went to.
+     *
+     * Worth reporting because the number is nobody's intuition: MCP has no shared component section and forbids a
+     * `$ref` across entries, so every entry inlines the full schema of every model it mentions — a plain 21-field
+     * model with one named slice ships 12KB across its eight entries, three quarters of it the same four schemas
+     * repeated. A catalogue is re-sent whole to every agent that connects, before its first turn.
+     */
+    get listingCost(): McpListingCost;
     findTool(name: string): McpExposedEndpoint | undefined;
     /** Returns the catalogue entry alongside the endpoint: `prompts/get` validates against the published one. */
     findPrompt(name: string): {

package/types/signal/mcp/McpUriTemplate.d.ts

@@ -13,7 +13,6 @@ export declare class McpUriTemplate {
     #private;
     static readonly scheme = "akan";
     static model(refName: string): string;
-    static light(refName: string): string;
     /**
      * The model's own unfiltered list is the bare `…/list`, never `…/list/<token>`. A named slice occupies the
      * third segment, and a slice key is an author-chosen identifier — so any token put there for the root list

package/types/signal/slice.d.ts

@@ -29,7 +29,15 @@ export type SliceCls<SrvModule extends ServiceModel = ServiceModel, SliceInfoObj
     createGuards: GuardCls[];
     updateGuards: GuardCls[];
     removeGuards: GuardCls[];
+    mcp: ResolvedSliceMcp;
 };
+/** The generated verbs, resolved to a plain answer each. `root` is not here: it rides on the root slice itself. */
+export interface ResolvedSliceMcp {
+    get: boolean;
+    create: boolean;
+    update: boolean;
+    remove: boolean;
+}
 interface RootSliceOption {
     guards?: {
         root?: GuardCls | GuardCls[];
@@ -39,6 +47,23 @@ interface RootSliceOption {
         update?: GuardCls | GuardCls[];
         remove?: GuardCls | GuardCls[];
     };
+    /**
+     * Which of the entries this call generates belong on an agent's shelf. Keyed exactly like `guards` above and
+     * scoped to exactly what `guards` governs — the root slice and the generated CRUD — so `false` here narrows the
+     * catalogue and nothing else. `create`/`update`/`remove` fall back to `cru` the same way their guards do, and
+     * the bare `false` is every key at once.
+     *
+     * A named slice and a custom endpoint declare their own `mcp` in their own signal option, exactly as they
+     * declare their own guards. This is curation, not authorization: HTTP is unchanged.
+     */
+    mcp?: boolean | {
+        root?: boolean;
+        get?: boolean;
+        cru?: boolean;
+        create?: boolean;
+        update?: boolean;
+        remove?: boolean;
+    };
     prefix?: string;
 }
 type RootSliceQueryKey<Filter extends FilterInstance> = Extract<keyof Filter["query"], string>;

package/types/signal/types.d.ts

@@ -74,6 +74,17 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
     method?: HttpMutationMethod;
     /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
     fileUpload?: boolean;
+    /**
+     * Whether this endpoint belongs on an agent's shelf. `true` — the default — publishes it to MCP subject to the
+     * guard and shape rules; `false` keeps it out of the catalogue entirely.
+     *
+     * This is curation, not authorization: HTTP serves the endpoint exactly as before, and the guards are still the
+     * only thing deciding who may call it. Write it where an endpoint is perfectly guarded and still has no business
+     * on a shelf — a step of a UI-driven state machine (`requestPhoneCodeForSignin`), or a read a model would only
+     * ever call by mistake. Every catalogue entry carries the model schemas it mentions, so one endpoint dropped
+     * here is kilobytes off every `tools/list`.
+     */
+    mcp?: boolean;
     /**
      * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
      * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
@@ -95,6 +106,13 @@ interface SerializedSignalOption {
     guards?: string[];
     method?: HttpMutationMethod;
     fileUpload?: boolean;
+    /**
+     * Only ever `false`, and only when something declared it: `true` is the default, so serializing it would ship a
+     * field per endpoint that says nothing. Resolved here rather than left to the reader because the browser API
+     * explorer has guard *names* and no classes, and a second implementation of the rule would eventually disagree
+     * with the catalogue.
+     */
+    mcp?: false;
 }
 export interface SerializedSlice extends SerializedSignalOption {
 }
@@ -144,6 +162,18 @@ export interface SerializedSignal {
     createGuards?: string[];
     updateGuards?: string[];
     removeGuards?: string[];
+    /**
+     * Which generated CRUD verbs this model keeps off the agent shelf. Carried on the signal because the endpoints
+     * it names do not exist until `FetchClient.getBaseEndpoint` synthesizes them. Only the `false` keys travel.
+     */
+    mcp?: SerializedSignalMcp;
+}
+/** Keyed by generated verb, mirroring the `guards` map `slice()` takes. The root slice's own flag rides on `slice[""]`. */
+export interface SerializedSignalMcp {
+    get?: false;
+    create?: false;
+    update?: false;
+    remove?: false;
 }
 export type SignalType = "restapi" | "websocket";
 export type WebsocketReqData = {

package/types/ui/System/Common.d.ts

@@ -40,7 +40,7 @@ export interface ProviderProps {
     /** Root route component used by CSR page loading. */
     of: (props: unknown) => ReactNode | null;
 }
-export declare const Common: () => import("react/jsx-runtime").JSX.Element;
+export declare const Common: () => null;
 export declare function ManifestLink({ manifest }: {
     manifest?: WebAppManifest;
 }): import("react/jsx-runtime").JSX.Element | null;

package/ui/Signal/Doc.tsx

@@ -247,7 +247,7 @@ const Zone = ({ refName, fetch, openAll }: ZoneProps) => {
   const desc = dictText(l, `${refName}.modelDesc`);
   const entries = endpointEntriesOf(refName, fetch);
   const wsEntries = entries.filter(({ endpoint }) => isWsEndpoint(endpoint));
-  const mcpEntries = entries.filter(({ endpoint }) => !mcpRefusalOf(endpoint));
+  const mcpEntries = entries.filter(({ key, endpoint }) => !mcpRefusalOf(endpoint, { refName, key }));
   return (
     <div className="flex break-after-page flex-col gap-6">
       <div className="flex flex-col gap-1">

package/ui/Signal/RestApi.tsx

@@ -110,7 +110,7 @@ const RestApiEndpoint = ({
   const [viewStatus, setViewStatus] = useState<"doc" | "test">("doc");
   const path = FetchClient.makeHttpUrl(endpointKey, endpoint, signalPrefix, new Map());
 
-  const mcpRefusal = mcpRefusalOf(endpoint);
+  const mcpRefusal = mcpRefusalOf(endpoint, { refName, key: endpointKey });
   const guards = guardsOf(endpoint);
   const label = dictText(l, `${refName}.signal.${endpointKey}`);
   const desc = dictText(l, `${refName}.signal.${endpointKey}.desc`);

package/ui/System/Common.tsx

@@ -44,7 +44,7 @@ export interface ProviderProps {
 }
 
 export const Common = () => {
-  return <></>;
+  return null;
 };
 
 export function ManifestLink({ manifest }: { manifest?: WebAppManifest }) {