@ttoss/http-server-mcp 0.33.1 → 0.34.0

package/dist/index.d.mts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { CallToolResult, InMemoryServerEventBus, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource, ServerEvent, ServerEventBus, ServerEventBus as ServerEventBus$1, ServerNotifier, ServerNotifier as ServerNotifier$1, ToolAnnotations } from "@modelcontextprotocol/server";
+import { CallToolResult, InMemoryServerEventBus, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource, ServerEvent, ServerEventBus, ServerEventBus as ServerEventBus$1, ServerNotifier, ServerNotifier as ServerNotifier$1, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
@@ -688,10 +688,199 @@ declare const getApiHeaders: () => Record<string, string>;
 /**
  * The `Accept-Language` header of the current MCP request, or `undefined`
  * outside a request or when the client sent none. The default locale source
- * for `createGatedToolRegistrar`'s `i18n` option.
+ * for `createToolGate`'s `i18n` option.
  */
 declare const getRequestLocale: () => string | undefined;
 //#endregion
+//#region src/tool.d.ts
+/**
+ * A plain JSON Schema object (draft-07 compatible) describing the shape of a
+ * tool's input or output. Forwarded verbatim over `tools/list`, so features
+ * Zod cannot express (`anyOf`, `$ref`, `pattern`, `allOf`, …) survive intact.
+ */
+interface JsonObjectSchema {
+  type: 'object';
+  properties?: Record<string, unknown>;
+  required?: string[];
+  [key: string]: unknown;
+}
+/**
+ * A schema a tool declares: a plain JSON Schema, or a Standard Schema with
+ * JSON Schema support — Zod 4's `z.object(...)`, ArkType, or Valibot.
+ */
+type ToolSchema = JsonObjectSchema | StandardSchemaWithJSON;
+/**
+ * An MCP tool: what it is and how it answers, independent of how a server
+ * exposes it. {@link registerTools} registers a list of them, either one MCP
+ * tool each or deferred behind `search` / `describe` / `call`.
+ */
+interface Tool {
+  /** Unique tool name. */
+  name: string;
+  /** Display name clients show instead of `name`. */
+  title?: string;
+  /** What the tool does, written for the model. */
+  description: string;
+  /**
+   * The tool's input.
+   *
+   * - A **JSON Schema** is advertised verbatim and enforced only with
+   *   `validateArguments`; the handler receives the raw arguments.
+   * - A **Standard Schema** (`z.object(...)`) is always enforced; the handler
+   *   receives its parsed output, defaults and coercions applied.
+   *
+   * @default { type: 'object', properties: {} }
+   */
+  inputSchema?: ToolSchema;
+  /**
+   * Whether a JSON Schema `inputSchema` is enforced before the handler runs.
+   *
+   * Enable it once the schema describes every value the tool genuinely
+   * accepts. Schemas generated from an OpenAPI document are a common source of
+   * *incomplete* ones — a field a client may send as `null` to clear it, or
+   * one accepting several shapes, is easy to emit as a bare
+   * `{ type: 'string' }` — and validating against them rejects calls the
+   * underlying API would have accepted. A Standard Schema ignores this flag.
+   *
+   * @default false
+   */
+  validateArguments?: boolean;
+  /**
+   * The result's schema, advertised on `tools/list`. A result's
+   * `structuredContent` is validated against it.
+   */
+  outputSchema?: ToolSchema;
+  /**
+   * Behaviour hints forwarded on `tools/list` (`readOnlyHint`,
+   * `destructiveHint`, `idempotentHint`, `openWorldHint`). Clients use them to
+   * decide when to ask the user for confirmation; they never enforce anything.
+   */
+  annotations?: ToolAnnotations;
+  /** Groups the tool for the deferred `search` filter. Not sent on `tools/list`. */
+  tags?: string[];
+  /**
+   * The line the deferred `search` shows for the tool. Defaults to the first
+   * line of `description`. Not sent on `tools/list`.
+   */
+  summary?: string;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list`. The MCP Apps extension
+   * links a tool to its view through it: build the bag with
+   * `registerAppResource(...).toolMeta()`.
+   */
+  _meta?: Record<string, unknown>;
+  /** Answers a call with the (validated, when enforced) arguments. */
+  handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
+}
+/** Parameters for {@link defineTool}. */
+interface DefineToolParams extends Omit<Tool, 'handler'> {
+  /**
+   * Answers a call with plain data, which becomes the tool result: JSON text,
+   * plus `structuredContent` when `outputSchema` is set. Resolving to `null`
+   * or `undefined` answers `notFoundMessage` as an `isError` result.
+   */
+  method: (args: Record<string, unknown>) => unknown;
+  /**
+   * The `isError` message for a `null` or `undefined` result.
+   * @default 'Not found'
+   */
+  notFoundMessage?: string;
+}
+/**
+ * Builds a {@link Tool} from a `method` that returns data instead of a
+ * `CallToolResult`, which is what most hand-written tools want.
+ *
+ * @example
+ * ```typescript
+ * const getCampaign = defineTool({
+ *   name: 'get-campaign',
+ *   description: 'Get a campaign by id.',
+ *   inputSchema: z.object({ campaignId: z.string() }),
+ *   method: ({ campaignId }) => findCampaign(campaignId as string),
+ *   notFoundMessage: 'Campaign not found',
+ * });
+ * ```
+ */
+declare const defineTool: ({
+  method,
+  notFoundMessage,
+  ...tool
+}: DefineToolParams) => Tool;
+//#endregion
+//#region src/toolSearch.d.ts
+/** What the deferred `search` ranks: one call, already narrowed to the visible tools. */
+interface ToolSearchArgs {
+  /** Free-text query. One without words lists the tools in order. */
+  query: string;
+  /** Only tools carrying this tag. */
+  tag?: string;
+  /** Maximum number of tools to return. */
+  limit: number;
+  /** The tools this request may see. */
+  tools: Tool[];
+}
+/**
+ * The deferred tools' default search: scores each tool by the query's terms,
+ * weighted name > summary > tags > description, and breaks ties by the
+ * tools' order. No index — a few hundred tools need none.
+ */
+declare const rankTools: ({
+  query,
+  tag,
+  limit,
+  tools
+}: ToolSearchArgs) => Tool[];
+//#endregion
+//#region src/deferTools.d.ts
+/** How {@link registerTools} defers tools behind `search` / `describe` / `call`. */
+interface DeferToolsOptions {
+  /**
+   * Tools that are not deferred: they are also registered as standalone MCP
+   * tools, and stay reachable through `search` / `describe` / `call` too.
+   *
+   * Defaults to the tools linked to an MCP Apps view: a host finds a tool's
+   * view through that tool's own `tools/list` entry, so a view behind `call`
+   * would never render.
+   */
+  except?: (args: {
+    tool: Tool;
+  }) => boolean;
+  /**
+   * The names of the three tools that reach the deferred ones, to avoid a
+   * collision with a standalone tool or to defer two sets on one server.
+   * @default { search: 'search', describe: 'describe', call: 'call' }
+   */
+  names?: {
+    search?: string;
+    describe?: string;
+    call?: string;
+  };
+  /**
+   * Replaces the default ranking, e.g. with embeddings. Receives only the
+   * tools `visible` lets through; the result is cut to `limit`.
+   * {@link rankTools} is the default, for a fallback.
+   */
+  search?: (args: ToolSearchArgs) => Tool[] | Promise<Tool[]>;
+  /**
+   * How many tools `search` returns when the model does not say.
+   * @default 10
+   */
+  searchLimit?: number;
+  /**
+   * Runs on every `search`, `describe` and `call`. A tool it rejects is
+   * absent from all three; `call` answers it as an unknown name. Tools
+   * `except` keeps standalone are listed on `tools/list` regardless.
+   *
+   * @example
+   * ```typescript
+   * visible: ({ tool }) => canUse({ identity: getIdentity(), tool: tool.name }),
+   * ```
+   */
+  visible?: (args: {
+    tool: Tool;
+  }) => boolean;
+}
+//#endregion
 //#region src/registerAppResource.d.ts
 /**
  * Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
@@ -800,9 +989,8 @@ interface RegisteredAppResource {
   /** The SDK's registration handle, for `update`/`disable`/`remove`. */
   resource: RegisteredResource;
   /**
-   * Builds the `_meta` bag that links a tool to this view. Pass it to
-   * `registerTool`, {@link registerToolFromSchema}, or a `GatedToolDef` —
-   * whichever registration path the tool uses.
+   * Builds the `_meta` bag that links a tool to this view. Pass it as a
+   * `Tool`'s `_meta`, or to the SDK's `registerTool`.
    */
   toolMeta: (params?: ToolMetaParams) => Record<string, unknown>;
 }
@@ -883,113 +1071,59 @@ declare const registerAppResource: ({
   ui
 }: RegisterAppResourceParams) => RegisteredAppResource;
 //#endregion
-//#region src/registerToolFromSchema.d.ts
-/**
- * A plain JSON Schema object (draft-07 compatible) describing the shape of a
- * tool's input. Used with {@link registerToolFromSchema} as an alternative to
- * providing a Zod shape, enabling lossless round-trips for schemas that contain
- * features not expressible in Zod v3 (`anyOf`, `$ref`, `pattern`, `allOf`, …).
- */
-interface JsonObjectSchema {
-  type: 'object';
-  properties?: Record<string, unknown>;
-  required?: string[];
-  [key: string]: unknown;
-}
-/**
- * Parameters accepted by {@link registerToolFromSchema}.
- */
-interface RegisterToolFromSchemaParams {
-  /** Unique tool name. */
-  name: string;
-  /** Human-readable description shown to the AI client. */
-  description?: string;
-  /**
-   * Plain JSON Schema that describes the tool's input object.
-   * This schema is forwarded verbatim over the MCP wire protocol, so any
-   * JSON Schema feature (`anyOf`, `$ref`, `pattern`, …) is preserved without
-   * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
-   */
-  inputSchema?: JsonObjectSchema;
+//#region src/registerTools.d.ts
+/** Parameters for {@link registerTools}. */
+interface RegisterToolsParams {
+  /** The MCP server the tools are registered on. */
+  server: McpServer$1;
+  /** The tools to expose. */
+  tools: Tool[];
   /**
-   * Whether `tools/call` arguments are validated against `inputSchema` before
-   * the handler runs, rejecting a mismatch with an MCP error.
-   *
-   * Defaults to `false`, which forwards arguments to the handler unchecked —
-   * the behavior this helper has always had. `inputSchema` is still advertised
-   * verbatim over `tools/list` either way; this only controls enforcement.
+   * Defers `tools` behind three tools — `search`, `describe`, `call` —
+   * instead of registering one MCP tool each. `true` takes every
+   * {@link DeferToolsOptions} default.
    *
-   * Enable it once you know `inputSchema` describes every value the tool
-   * genuinely accepts. Schemas generated from an OpenAPI document are a common
-   * source of *incomplete* ones — a field a client may send as `null` to clear
-   * it, or one accepting several shapes, is easy to emit as a bare
-   * `{ type: 'string' }`. Validating against a schema like that rejects calls
-   * the underlying API would have accepted.
+   * A large tool set overflows a client's context: every definition ships to
+   * the model on every turn, some providers cap the number of tools per
+   * request, and clients that don't defer tool loading choke on the list.
+   * Deferred, the model sees three small definitions, and a schema
+   * enters its context only for the tools it is about to use.
    *
    * @default false
    */
-  validateArguments?: boolean;
-  /**
-   * Tool metadata forwarded verbatim on `tools/list`.
-   *
-   * The MCP Apps extension links a tool to the view its result is rendered
-   * with through this field; build the bag with `toolMeta()` from
-   * `registerAppResource` rather than writing the keys by hand.
-   *
-   * @example
-   * ```typescript
-   * _meta: dashboard.toolMeta({ visibility: ['app'] }),
-   * ```
-   */
-  _meta?: Record<string, unknown>;
-  /**
-   * Tool handler invoked when the AI client calls the tool.
-   * Receives the request arguments, validated against `inputSchema` only when
-   * `validateArguments` is enabled.
-   */
-  handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
+  defer?: boolean | DeferToolsOptions;
 }
 /**
- * Registers a tool on an MCP server using a **plain JSON Schema** object for
- * `inputSchema` instead of a Zod shape.
- *
- * This is useful when tool definitions are shared between the MCP server and
- * an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume
- * a plain JSON Schema at runtime. Using this helper eliminates the lossy
- * JSON-Schema→Zod conversion that would otherwise be required.
- *
- * Thin wrapper over `@modelcontextprotocol/server`'s `fromJsonSchema`, which
- * converts a JSON Schema into a Standard Schema that `registerTool` accepts
- * directly, so the schema round-trips verbatim over `tools/list`. Arguments
- * reach the handler unchecked unless `validateArguments` is enabled.
- *
- * @param server - The `McpServer` instance to register the tool on.
- * @param params - Tool configuration including name, description, inputSchema,
- *   validateArguments, `_meta`, and handler.
+ * Registers tools on an MCP server, either one MCP tool each (the default)
+ * or deferred behind `search` / `describe` / `call`. The same `tools` can feed
+ * both, so two endpoints over one API cannot drift apart.
  *
  * @example
  * ```typescript
- * import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
+ * import { McpServer, registerTools, z } from '@ttoss/http-server-mcp';
  *
- * const server = new McpServer({ name: 'my-server', version: '1.0.0' });
- *
- * registerToolFromSchema(server, {
- *   name: 'get-project',
- *   description: 'Get a project by ID',
- *   inputSchema: {
- *     type: 'object',
- *     properties: { id: { type: 'string', description: 'Project public ID' } },
- *     required: ['id'],
+ * const tools = [
+ *   {
+ *     name: 'get-project',
+ *     description: 'Get a project by ID',
+ *     inputSchema: z.object({ id: z.string() }),
+ *     handler: async ({ id }) => ({
+ *       content: [{ type: 'text', text: `Project: ${id}` }],
+ *     }),
  *   },
- *   handler: async ({ id }) => ({
- *     content: [{ type: 'text', text: `Project: ${id}` }],
- *   }),
- * });
+ * ];
+ *
+ * registerTools({ server: fullServer, tools });
+ * registerTools({ server: deferredServer, tools, defer: true });
  * ```
  */
-declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
+declare const registerTools: ({
+  server,
+  tools,
+  defer
+}: RegisterToolsParams) => void;
 //#endregion
-//#region src/createGatedToolRegistrar.d.ts
+//#region src/toolGate.d.ts
 /** Resolved identity for a gated tool call. */
 type ToolIdentity = {
   userId: string;
@@ -1003,50 +1137,16 @@ type ToolIdentity = {
 type ToolCallContext = {
   /** The resolved caller identity. */identity: ToolIdentity;
   /**
-   * The validated tool input (post SDK parse). Present for gates and
-   * `buildContext`. Arg-conditional gates read this to vary their predicate
-   * per call.
+   * The validated tool input. Arg-conditional gates read this to vary their
+   * predicate per call.
    */
   args: Record<string, unknown>; /** Tool name, for error attribution and gate labelling. */
   handler: string;
 };
-/** Definition for a single gated tool. */
-type GatedToolDef = {
-  /** Tool name as registered with the MCP server. */name: string; /** Human-readable tool description. */
-  description: string; /** Display name shown by clients instead of `name`. */
-  title?: string;
-  /**
-   * Behaviour hints forwarded on `tools/list` (`readOnlyHint`,
-   * `destructiveHint`, `idempotentHint`, `openWorldHint`). Clients use them to
-   * decide when to ask the user for confirmation; they are hints, never
-   * enforcement — scope and gates still decide what may run.
-   */
-  annotations?: ToolAnnotations;
-  /**
-   * Zod field map or ZodObject describing the result. When set, a successful
-   * result is also returned as `structuredContent`, and the SDK validates it
-   * against this schema.
-   */
-  outputSchema?: unknown; /** The single scope that must be present on the caller's token. */
-  requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
-  inputSchema: unknown;
-  /**
-   * Per-tool gates merged after the global `gates`. Useful for arg-conditional
-   * authorization (e.g. different subscription tiers based on call args).
-   * Each gate receives the full {@link ToolCallContext} (identity + args).
-   * Throw to reject the call; return (or resolve) to continue.
-   */
-  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
-  /**
-   * Tool metadata forwarded verbatim on `tools/list` — how a gated tool links
-   * to an MCP Apps view (`registerAppResource(...).toolMeta()`).
-   */
-  _meta?: Record<string, unknown>; /** The tool handler. Receives merged call args + `buildContext` output. */
-  method: (args: Record<string, unknown>) => Promise<unknown>;
-};
-/** Options for {@link createGatedToolRegistrar}. */
-type CreateGatedToolRegistrarOptions = {
-  /** The MCP server instance to register tools on. */server: McpServer$1;
+/** An authorization check. Throw to reject the call; return to continue. */
+type ToolCallGate = (ctx: ToolCallContext) => void | Promise<void>;
+/** Options for {@link createToolGate}. */
+type CreateToolGateOptions = {
   /**
    * Called once per tool invocation to resolve the caller's identity.
    * Defaults to `getIdentity()` from the request context.
@@ -1057,12 +1157,11 @@ type CreateGatedToolRegistrarOptions = {
    * per-tool gates. Each receives the full {@link ToolCallContext} — both
    * identity and the validated call args — so gate predicates may be
    * conditional on either.
-   * Throw to reject the call; return (or resolve) to continue.
    * Gates own their own error handling — `onError` covers the tool handler only.
    */
-  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  gates?: ToolCallGate[];
   /**
-   * When `true` (default), checks `def.requiredScope` against `identity.scopes`
+   * When `true` (default), checks `requiredScope` against `identity.scopes`
    * and returns an `isError` result when the scope is absent. Set to `false`
    * to skip the scope check (e.g. when all scopes are enforced by `gates`).
    */
@@ -1079,11 +1178,6 @@ type CreateGatedToolRegistrarOptions = {
    * so context can vary by identity or by call args.
    */
   buildContext?: (ctx: ToolCallContext) => Record<string, unknown>;
-  /**
-   * Message returned as an `isError` result when the handler resolves to
-   * `null` or `undefined`. Defaults to `"Not found"`.
-   */
-  notFoundMessage?: string;
   /**
    * Renders a `LocalizedError` — thrown by a gate or by the handler — as an
    * `isError` result `{ error: <message>, code }` in the caller's locale,
@@ -1101,18 +1195,79 @@ type CreateGatedToolRegistrarOptions = {
     getLocale?: (ctx: ToolCallContext) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>;
   };
 };
-declare const createGatedToolRegistrar: ({
-  server,
+/** Parameters for the gate {@link createToolGate} returns. */
+interface GateToolParams {
+  /** The tool to protect. */
+  tool: Tool;
+  /** The single scope that must be present on the caller's token. */
+  requiredScope: string;
+  /**
+   * Per-tool gates run after the global `gates`. Useful for arg-conditional
+   * authorization (e.g. different subscription tiers based on call args).
+   */
+  gates?: ToolCallGate[];
+}
+/** Wraps a {@link Tool}'s handler in the authorization pipeline. */
+type ToolGate = (params: GateToolParams) => Tool;
+/**
+ * Factory for a gate: a function that wraps a {@link Tool} so every call
+ * passes the same authentication and authorization pipeline before its
+ * handler runs. The gated tool is an ordinary `Tool`, so it registers
+ * directly or joins a catalog like any other.
+ *
+ * Every gated call:
+ * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
+ *    `isError` result when the identity is absent (unauthenticated request).
+ * 2. When `enforceScope` is `true` (default), checks `requiredScope` — returns
+ *    an `isError` result when the scope is absent, consistent with how MCP
+ *    surfaces authorization errors.
+ * 3. Runs global `gates` then the tool's `gates` in order; a throwing gate
+ *    rejects the call. Every gate receives the full {@link ToolCallContext}.
+ * 4. Merges `buildContext` output into the handler args.
+ * 5. Calls `onError` on handler throw before rethrowing.
+ * 6. With `i18n`, renders a `LocalizedError` from a gate or the handler as an
+ *    `isError` result in the caller's locale instead of rethrowing it.
+ *
+ * @example
+ * ```typescript
+ * const gate = createToolGate({
+ *   resolveIdentity: () => {
+ *     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
+ *     return { userId: jwt!.sub, scopes: jwt!.scopes };
+ *   },
+ * });
+ *
+ * registerTools({
+ *   server,
+ *   tools: [
+ *     gate({
+ *       requiredScope: 'campaigns:write',
+ *       // arg-conditional gate: active vs. inactive have different restrictions
+ *       gates: [
+ *         ({ args }) =>
+ *           args.isActive
+ *             ? subscriptionGate(['mustNotExceedMaxActive', 'mustHaveBudget'])
+ *             : subscriptionGate(['mustIncludeService']),
+ *       ],
+ *       tool: defineTool({
+ *         name: 'activate-campaign',
+ *         description: 'Activate or deactivate a campaign.',
+ *         inputSchema: z.object({ isActive: z.boolean() }),
+ *         method: ({ userId, isActive }) => toggleCampaign(userId, isActive),
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const createToolGate: ({
   resolveIdentity,
   gates,
   enforceScope,
   onError,
   buildContext,
-  notFoundMessage,
   i18n
-}: CreateGatedToolRegistrarOptions) => {
-  register: (def: GatedToolDef) => void;
-};
+}?: CreateToolGateOptions) => ToolGate;
 //#endregion
 //#region src/index.d.ts
 type Context$1 = Application.Context;
@@ -1551,4 +1706,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => McpRouter;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, InMemoryServerEventBus, type JsonObjectSchema, McpAuthOptions, McpRouter, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ServerEvent, type ServerEventBus, type ServerNotifier, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, registerAppResource, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateToolGateOptions, type DeferToolsOptions, type DefineToolParams, type GateToolParams, InMemoryServerEventBus, type JsonObjectSchema, McpAuthOptions, McpRouter, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolsParams, type RegisteredAppResource, type ServerEvent, type ServerEventBus, type ServerNotifier, type Tool, type ToolCallContext, type ToolCallGate, type ToolGate, type ToolIdentity, type ToolMetaParams, type ToolSchema, type ToolSearchArgs, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, rankTools, registerAppResource, registerTools, z };