@dereekb/firebase-server 13.11.18 → 13.12.1

package/mcp/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dereekb/firebase-server/mcp",
+  "version": "13.12.1",
+  "peerDependencies": {
+    "@dereekb/analytics": "13.12.1",
+    "@dereekb/date": "13.12.1",
+    "@dereekb/firebase": "13.12.1",
+    "@dereekb/firebase-server": "13.12.1",
+    "@dereekb/firebase-server/oidc": "13.12.1",
+    "@dereekb/model": "13.12.1",
+    "@dereekb/nestjs": "13.12.1",
+    "@dereekb/rxjs": "13.12.1",
+    "@dereekb/util": "13.12.1",
+    "@dereekb/zoho": "13.12.1",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "express": "^5.2.1",
+    "firebase-admin": "^13.8.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/mcp/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/mcp/src/lib/controller/index.d.ts

@@ -0,0 +1,2 @@
+export * from './mcp.controller';
+export * from './mcp.wellknown.controller';

package/mcp/src/lib/controller/mcp.controller.d.ts

@@ -0,0 +1,19 @@
+import { type Request, type Response } from 'express';
+import { McpServerFactoryService } from '../service/mcp.server.factory';
+/**
+ * NestJS controller mounting the MCP Streamable HTTP transport at `POST /mcp`.
+ *
+ * Auth is enforced by the global OIDC bearer middleware (`OidcAuthBearerTokenMiddleware`)
+ * which must include `'/mcp'` in its `protectedPaths`. By the time the request reaches
+ * this controller, `req.auth` is populated with the authenticated user's data.
+ *
+ * Each request gets a fresh transport + MCP server pair (stateless mode), which is
+ * adequate for Claude custom-connector style usage. A session-tracked variant can
+ * be layered on later if streaming tool output becomes a requirement.
+ */
+export declare class McpController {
+    private readonly factory;
+    private readonly _logger;
+    constructor(factory: McpServerFactoryService);
+    handleMcpRequest(req: Request, res: Response): Promise<void>;
+}

package/mcp/src/lib/controller/mcp.wellknown.controller.d.ts

@@ -0,0 +1,25 @@
+import { McpModuleConfig } from '../mcp.config';
+/**
+ * Discovery document body for the OAuth protected-resource indicator.
+ *
+ * Format defined by RFC 9728 (OAuth 2.0 Protected Resource Metadata).
+ */
+export interface OAuthProtectedResourceMetadata {
+    readonly resource: string;
+    readonly authorization_servers: ReadonlyArray<string>;
+}
+/**
+ * Serves the `GET /.well-known/oauth-protected-resource` metadata document so
+ * Claude (and other MCP clients) can discover which OIDC issuer guards this
+ * MCP endpoint.
+ *
+ * The route is registered without a controller-level prefix because well-known
+ * URIs must live at the host root. Apps need to exclude `.well-known/{*path}`
+ * from any global API route prefix (see `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`
+ * in `firebase-server/oidc` for the corresponding OIDC excludes).
+ */
+export declare class McpWellKnownController {
+    private readonly mcpConfig;
+    constructor(mcpConfig: McpModuleConfig);
+    getProtectedResourceMetadata(): OAuthProtectedResourceMetadata;
+}

package/mcp/src/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from './mcp.config';
+export * from './mcp.module';
+export * from './controller';
+export * from './service';
+export * from './transport';

package/mcp/src/lib/mcp.config.d.ts

@@ -0,0 +1,100 @@
+import { type AuthClaims, type AuthRoleSet } from '@dereekb/util';
+/**
+ * Default path the MCP Streamable HTTP transport is mounted at.
+ *
+ * Combined with the app origin to form the canonical MCP resource URL
+ * (e.g., `https://api.example.com/mcp`) advertised in the protected-resource
+ * discovery document at `/.well-known/oauth-protected-resource`.
+ */
+export declare const DEFAULT_MCP_PATH = "/mcp";
+/**
+ * Default name advertised by the MCP server on the JSON-RPC `initialize` handshake.
+ *
+ * Apps may override this via {@link McpModuleConfig.serverName} to identify their
+ * deployment (e.g., `demo-api-mcp`, `hellosubs-api-mcp`).
+ */
+export declare const DEFAULT_MCP_SERVER_NAME = "dbx-firebase-server-mcp";
+/**
+ * Configuration for the firebase-server/mcp module.
+ *
+ * Apps construct this in their `*McpModule` provider and pass it through
+ * {@link mcpModuleMetadata}. It carries:
+ *
+ * - The canonical issuer URL for the OIDC provider that gates this MCP endpoint
+ *   (used in the protected-resource discovery document).
+ * - The canonical resource URL where the MCP transport is mounted (also part of
+ *   the discovery document; doubles as the `resource` claim consumers should
+ *   verify their access tokens against).
+ * - Optional server identity (name, version) advertised on the MCP `initialize` handshake.
+ *
+ * The OAuth bearer middleware that authenticates `/mcp` is configured on
+ * {@link OidcModuleConfig.protectedPaths} — that's outside this config's scope.
+ */
+export declare abstract class McpModuleConfig {
+    /**
+     * The canonical issuer URL of the OIDC provider that gates this MCP endpoint.
+     *
+     * Surfaced in the `authorization_servers` field of the protected-resource
+     * discovery document. Claude custom-connector reads this to discover the OIDC issuer.
+     *
+     * @example 'https://api.example.com/oidc'
+     */
+    readonly oidcIssuer: string;
+    /**
+     * The canonical resource URL of the MCP endpoint.
+     *
+     * Surfaced as the `resource` field of the protected-resource discovery document,
+     * and used as the audience the access token's `aud` claim should match.
+     *
+     * @example 'https://api.example.com/mcp'
+     */
+    readonly mcpUrl: string;
+    /**
+     * Optional name advertised on the MCP `initialize` handshake. Defaults to
+     * {@link DEFAULT_MCP_SERVER_NAME}.
+     */
+    readonly serverName?: string;
+    /**
+     * Optional version advertised on the MCP `initialize` handshake.
+     */
+    readonly serverVersion?: string;
+    /**
+     * Absolute path to a pre-rendered MCP manifest JSON file produced by
+     * `dbx-cli-generate-mcp-manifest`. When set, the runtime reads it once at
+     * boot and uses each tool's `description`, `inputSchema`, and `outputSchema`
+     * during tool generation — no per-request file I/O.
+     *
+     * Optional. When unset or the file is missing, the runtime falls back to
+     * today's behavior (auto-generated descriptions, ArkType-derived input
+     * schemas, no output schemas) and emits a single boot warning.
+     */
+    readonly mcpManifestPath?: string;
+    /**
+     * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
+     *
+     * Write tools (`create`/`update`/`delete`) and tools with unknown classification (e.g., `invoke`
+     * with no explicit `mcp.readOnly` override) are dropped from `tools/list` — fail-safe under the
+     * principle that anything not provably read-only is treated as a write.
+     *
+     * The advertised `serverName` on the JSON-RPC `initialize` handshake is suffixed with
+     * ` (read-only)` so the client surface reflects the mode.
+     */
+    readonly readOnly?: boolean;
+}
+/**
+ * Signature for the optional role reader the MCP module uses when evaluating
+ * declarative {@link McpVisibilityRule.requiredRoles} on `tools/list`.
+ *
+ * The MCP factory does not have access to the constructed `FirebaseServerAuthContext`
+ * (that's built later by the dispatch chain), so apps wire a thin function that
+ * maps the caller's Firebase custom claims to the corresponding role set —
+ * typically `authRoleClaimsService(...).toRoles` from `@dereekb/util`.
+ *
+ * When no reader is provided, declarative role checks fail closed (treated as
+ * "missing role"), and the factory emits a single boot-time warning.
+ */
+export type McpAuthRoleReader = (claims: AuthClaims) => AuthRoleSet;
+/**
+ * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
+ */
+export declare const MCP_AUTH_ROLE_READER = "MCP_AUTH_ROLE_READER";

package/mcp/src/lib/mcp.module.d.ts

@@ -0,0 +1,49 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type ClassType } from '@dereekb/util';
+/**
+ * Routes the firebase-server/mcp module owns. Apps should exclude these from
+ * any global API route prefix (`globalApiRoutePrefix.exclude`) so the canonical
+ * URLs land at `/.well-known/...` and `/mcp` rather than `/api/.well-known/...`.
+ */
+export declare const FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE: string[];
+/**
+ * Configuration for {@link mcpModuleMetadata}.
+ */
+export interface McpModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the required dependencies.
+     *
+     * Must provide:
+     * - {@link ModelApiDispatchConfig} — so the MCP server can reuse the call model dispatch chain.
+     * - {@link McpModuleConfig} — issuer + resource URLs for protected-resource discovery.
+     *
+     * In practice, downstream apps typically import their own `*ModelApiModule` first (which provides
+     * `ModelApiCallModelDispatchService` + `MODEL_API_NEST_APPLICATION_CONTEXT`) and add the
+     * `McpModuleConfig` provider in the dependency module passed here.
+     */
+    readonly dependencyModule: ClassType;
+}
+/**
+ * Generates NestJS module metadata for the firebase-server/mcp module.
+ *
+ * Mirrors the convention used by {@link modelApiModuleMetadata}: the consumer provides
+ * a dependency module that exposes the required tokens, and this factory wires up the
+ * controllers + factory service.
+ *
+ * @param metadataConfig - Configuration including the dependency module.
+ * @returns NestJS module metadata exposing the MCP transport + well-known controller.
+ *
+ * @Module ({
+ *   imports: [DemoModelApiModule],
+ *   providers: [{ provide: McpModuleConfig, useValue: { oidcIssuer, mcpUrl } }],
+ *   exports: [McpModuleConfig, ModelApiCallModelDispatchService, MODEL_API_NEST_APPLICATION_CONTEXT]
+ * })
+ * export class DemoMcpDependencyModule {}
+ * @Module (mcpModuleMetadata({ dependencyModule: DemoMcpDependencyModule }))
+ * export class DemoMcpModule {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ */
+export declare function mcpModuleMetadata(metadataConfig: McpModuleMetadataConfig): ModuleMetadata;

package/mcp/src/lib/service/index.d.ts

@@ -0,0 +1,8 @@
+export * from './mcp.manifest';
+export * from './mcp.response-formatter';
+export * from './mcp.server.factory';
+export * from './mcp.tool-generator';
+export * from './mcp.visibility';
+export * from './tools/mcp.tool.model-get';
+export * from './tools/mcp.tool.model-info';
+export * from './tools/mcp.tool.model-decode';

package/mcp/src/lib/service/mcp.manifest.d.ts

@@ -0,0 +1,150 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * Version stamp embedded in the build-time MCP manifest JSON. Runtime loaders
+ * refuse manifests whose `version` does not match this constant.
+ *
+ * Mirrors {@link MCP_MANIFEST_VERSION} in `@dereekb/dbx-cli` — both packages
+ * version-bump together when the manifest shape changes.
+ */
+export declare const MCP_MANIFEST_VERSION: 1;
+/**
+ * One tool entry inside the pre-rendered MCP manifest JSON.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `McpManifestToolEntry` so the
+ * firebase-server/mcp runtime can consume the build output without taking a
+ * runtime dependency on the build-time CLI package.
+ */
+export interface McpManifestToolEntry {
+    readonly description?: string;
+    readonly inputSchema?: object;
+    readonly outputSchema?: object;
+}
+/**
+ * One persisted field on a {@link McpManifestModelEntry}.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `CliModelField` minus the
+ * converter-text fields (CLI-only). The runtime keeps the payload narrow so the
+ * built-in `model-info` / `model-decode` tools can answer catalog queries without
+ * round-tripping back through the source packages.
+ */
+export interface McpManifestModelField {
+    readonly name: string;
+    readonly longName: string;
+    readonly tsType?: string;
+    readonly optional: boolean;
+    readonly description?: string;
+    readonly enumRef?: string;
+    readonly syncFlag?: string;
+    readonly nestedFields?: readonly McpManifestModelField[];
+    readonly nestedIsArray?: boolean;
+}
+/**
+ * One Firestore model entry in the pre-rendered MCP manifest JSON.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `CliModelManifestEntry`. Drives the
+ * built-in `model-info` and `model-decode` MCP tools.
+ */
+export interface McpManifestModelEntry {
+    readonly modelType: string;
+    readonly modelName: string;
+    readonly modelGroup?: string;
+    readonly identityConst: string;
+    readonly collectionPrefix: string;
+    readonly parentIdentityConst?: string;
+    readonly description?: string;
+    readonly sourcePackage: string;
+    readonly sourceFile: string;
+    readonly fields: readonly McpManifestModelField[];
+    /**
+     * Read posture declared by `@dbxModelRead <level>` on the model interface (`system` /
+     * `owner` / `admin-only` / `permissions`). Absent when the source model omits the tag.
+     */
+    readonly read?: 'system' | 'owner' | 'admin-only' | 'permissions';
+    /**
+     * Resolved `@dbxModelServiceFactory`-tagged export that implements this model, joined onto
+     * the model entry by `modelType`. Absent when no factory was found in the same scan.
+     */
+    readonly serviceFactory?: {
+        readonly exportName: string;
+        readonly sourceFile: string;
+    };
+}
+/**
+ * One auth claim entry in the pre-rendered MCP manifest JSON.
+ *
+ * Source paths and line numbers are deliberately stripped — the `whoami`
+ * runtime tool only needs the claim key, the interface it belongs to, the
+ * roles it grants, and the human-readable description.
+ */
+export interface McpManifestAuthClaim {
+    readonly key: string;
+    readonly description: string;
+    readonly type: string;
+    readonly app?: string;
+    readonly interfaceName?: string;
+    readonly source: 'system' | 'app';
+    readonly mapping: {
+        readonly roles: readonly string[];
+        readonly inverse: boolean;
+        readonly inverseMode?: 'any' | 'all';
+        readonly claimValue?: string | number | boolean;
+        readonly customEncodeDecode: boolean;
+    };
+    readonly tags: readonly string[];
+}
+/**
+ * One auth app entry in the pre-rendered MCP manifest JSON.
+ *
+ * `auth.app` denotes the manifest's primary app (the host that emitted the
+ * manifest). `auth.apps` carries the full list, which may include the primary
+ * plus inherited apps (e.g. `storageFile-upload-user`).
+ */
+export interface McpManifestAuthApp {
+    readonly app: string;
+    readonly claimsInterfaceName: string;
+    readonly serviceConstName: string;
+    readonly claimKeys: readonly string[];
+    readonly scopes: readonly string[];
+    readonly description?: string;
+}
+/**
+ * Auth section of the pre-rendered MCP manifest JSON. Drives the built-in
+ * `whoami` static tool. Optional — runtimes that pre-date this section skip
+ * registering whoami.
+ */
+export interface McpManifestAuth {
+    readonly app?: McpManifestAuthApp;
+    readonly apps: readonly McpManifestAuthApp[];
+    readonly claims: readonly McpManifestAuthClaim[];
+}
+/**
+ * Full MCP manifest JSON shape consumed at boot.
+ *
+ * The optional `models` array carries the Firestore model catalog used by the
+ * built-in `model-info` / `model-decode` static tools. When absent (e.g., legacy
+ * manifests rendered before model catalog support landed), the runtime skips
+ * registering those tools instead of failing the boot.
+ *
+ * The optional `auth` section drives the built-in `whoami` static tool.
+ */
+export interface McpManifest {
+    readonly version: typeof MCP_MANIFEST_VERSION;
+    readonly generatedAt: string;
+    readonly tools: {
+        readonly [key: string]: McpManifestToolEntry | undefined;
+    };
+    readonly models?: readonly McpManifestModelEntry[];
+    readonly auth?: McpManifestAuth;
+}
+/**
+ * Builds the canonical MCP manifest key for a (modelType, callType, specifier) triple.
+ *
+ * Default-specifier entries collapse to `_`. Must stay in sync with the build-time
+ * helper of the same name in `@dereekb/dbx-cli`.
+ *
+ * @param modelType - The Firestore model type segment of the key.
+ * @param call - The call type segment of the key.
+ * @param specifier - The specifier segment, or `_` / undefined for the default entry.
+ * @returns The canonical `modelType.call.specifier` manifest key.
+ */
+export declare function mcpManifestKey(modelType: string, call: string, specifier?: Maybe<string>): string;

package/mcp/src/lib/service/mcp.response-formatter.d.ts

@@ -0,0 +1,36 @@
+import { type OnCallTypedModelParams } from '@dereekb/firebase';
+import { type McpToolResponseContent, type OnCallModelFunctionApiDetails } from '@dereekb/firebase-server';
+/**
+ * Default structured value emitted by MCP when a handler returns `undefined`.
+ *
+ * Keeps the response usable by clients that key off either the text content or the
+ * structured/object body. Tests and any future overrides should compare against this
+ * constant rather than re-literalling `{ ok: true }`.
+ */
+export declare const DEFAULT_VOID_MCP_SUCCESS_VALUE: {
+    readonly ok: true;
+};
+/**
+ * Resolves a dispatch result + handler API details into the MCP `CallToolResult` shape.
+ *
+ * Three-tier resolution as documented on {@link OnCallModelFunctionApiDetails.mcp}:
+ *
+ * - **Tier 3** — when `mcp.formatResponse` is set, its return value is used verbatim.
+ * - **Tier 2** — when `mcp.summarizeResponse` is set, the summary string is wrapped into a
+ *   single text content block with the raw `result` exposed as `structuredContent`.
+ * - **Tier 1** — default: JSON-stringify `result` as a single text content block, also
+ *   exposing the raw value as `structuredContent`.
+ *
+ * @param result - The handler's return value.
+ * @param params - The {@link OnCallTypedModelParams} that were dispatched.
+ * @param details - The handler-level API details (carries Tier 2/3 formatters).
+ * @returns The MCP tool response content.
+ */
+export declare function formatMcpToolResponse(result: unknown, params: OnCallTypedModelParams, details: OnCallModelFunctionApiDetails | undefined): McpToolResponseContent;
+/**
+ * Converts an error thrown from the dispatch chain into the MCP error response shape.
+ *
+ * @param error - The thrown error.
+ * @returns An MCP tool response with `isError: true` and the error message as a text block.
+ */
+export declare function formatMcpToolErrorResponse(error: unknown): McpToolResponseContent;

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -0,0 +1,124 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Request } from 'express';
+import { ModelApiCallModelDispatchService, ModelApiGetService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { McpModuleConfig, type McpAuthRoleReader } from '../mcp.config';
+/**
+ * Optional per-request context passed when invoking the MCP server through a
+ * Streamable HTTP transport. Carries the authenticated user (already extracted
+ * by the OIDC bearer middleware) and the raw Express request so the dispatch
+ * chain can satisfy `nestApplication`, `auth`, and `rawRequest` consumers.
+ */
+export interface McpRequestContext {
+    readonly auth?: FirebaseServerAuthData;
+    readonly rawRequest: Request;
+}
+/**
+ * Injectable factory that builds {@link McpServer} instances pre-wired to the
+ * call model dispatch chain.
+ *
+ * The factory is invoked per Streamable HTTP request — `@modelcontextprotocol/sdk`
+ * recommends a fresh `McpServer` + transport pair per stateless JSON-RPC request,
+ * which sidesteps session bookkeeping for the common Claude-connector case.
+ */
+export declare class McpServerFactoryService {
+    private readonly mcpConfig;
+    private readonly dispatchService;
+    private readonly modelApiGetService?;
+    private readonly roleReader?;
+    private readonly _logger;
+    private _cachedTools;
+    private _cachedStaticTools;
+    private _cachedManifest;
+    private _cachedManifestModels;
+    private _cachedManifestAuth;
+    private _manifestLoaded;
+    private _loggedSkips;
+    private _warnedMissingRoleReader;
+    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined);
+    /**
+     * Builds a configured MCP server with tool listing + dispatch handlers wired up.
+     *
+     * @param ctx - The per-request context (auth, raw request) used when forwarding tool calls.
+     * @returns A configured MCP server ready to be `connect()`-ed to a transport.
+     */
+    createServer(ctx: McpRequestContext): McpServer;
+    /**
+     * Reads cached tool definitions, regenerating + logging skips on first call.
+     *
+     * The underlying call model `_apiDetails` is built at boot and doesn't change at runtime,
+     * so the generation result is safe to cache for the lifetime of the process.
+     *
+     * @returns The cached or freshly-generated tool generation result.
+     */
+    private _resolveToolDefinitions;
+    /**
+     * Builds the list of statically-registered (non-callModel) MCP tools.
+     *
+     * Includes `model-get` whenever {@link ModelApiGetService} is available, plus
+     * `model-info` and `model-decode` whenever the boot-time MCP manifest provided
+     * a non-empty `models` catalog. The list is cached for the lifetime of the
+     * process since static tools share the same boot-time inputs as the
+     * auto-generated ones.
+     *
+     * @returns The cached array of static tool definitions, filtered for collisions with generated tools.
+     */
+    private _resolveStaticTools;
+    /**
+     * Reads the pre-rendered MCP manifest JSON once, validates its version, and caches the
+     * resulting `key → entry` map plus the optional `models` catalog for the process lifetime.
+     *
+     * Missing file or wrong version fall back to "no manifest" with a single boot warning;
+     * the runtime still produces tools using the auto-generated descriptions and
+     * ArkType-derived schemas.
+     *
+     * @returns The cached tool-entry map, or `undefined` when no manifest was loaded.
+     */
+    private _resolveManifest;
+    private _resetManifestCache;
+    private _parseManifestFile;
+    private _applyParsedManifest;
+    /**
+     * Reads the caller's OIDC scopes from the raw Express request via the auth context.
+     *
+     * Synthesizes the same `{ auth: { token } }` shape that `getOidcScopesFromRequest`
+     * expects post-dispatch, so the upstream helper stays the single source of scope parsing.
+     * Returns `undefined` for non-OIDC callers (no `oidcValidatedToken.scope`) — the filter
+     * loop treats that as "skip scope enforcement", matching `oidcCallModelScopePreAssert`.
+     *
+     * @param ctx - The per-request context carrying the validated auth payload.
+     * @returns The set of granted OIDC scopes, or `undefined` when scope enforcement should be skipped.
+     */
+    private _resolveScopes;
+    /**
+     * Maps the caller's Firebase custom claims through the optional role reader.
+     * Emits one boot-time warning when a declarative `requiredRoles` rule will be checked
+     * but no reader is wired — that path will fail closed.
+     *
+     * @param ctx - The per-request context carrying the authenticated user's token.
+     * @returns The resolved auth role set, or `undefined` when no auth or reader is available.
+     */
+    private _resolveAuthRoles;
+    private _filterToolsForRequest;
+    private _passesVisibility;
+    private _checkDeclarativeVisibility;
+    /**
+     * Resolves the wire-shape `tools/list` entry for a single tool.
+     *
+     * Hot-path short-circuit: tools without a `toolDetailsBuilder` reuse the precomputed,
+     * frozen {@link McpToolDefinition.staticWireEntry} verbatim — zero allocations per
+     * request for the common case.
+     *
+     * Tools that opted in to {@link McpToolDetailsBuilder} get a fresh wire entry built
+     * from the builder's overrides. If the builder throws, the framework falls back to
+     * the static defaults and logs a warning (fail-soft, matching `_passesVisibility`).
+     *
+     * @param tool - The tool definition whose wire entry is being resolved.
+     * @param ctx - The per-request context forwarded to any dynamic details builder.
+     * @param scopes - The caller's granted OIDC scopes forwarded to any dynamic details builder.
+     * @returns The wire-shape entry to emit for this tool on `tools/list`.
+     */
+    private _buildToolListEntry;
+    private _handleToolCall;
+    private _handleStaticToolCall;
+    private _handleCallModelToolCall;
+}