mcp-server-framework 1.0.0

package/build/mcp/capabilities/registry/scope-enforcement.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Scope Enforcement for SDK Bindings
+ *
+ * Centralizes RBAC scope checking used by tool, resource, and prompt registries.
+ * This is the internal enforcement layer — for consumer-facing guards,
+ * see `server/auth/guards.ts` (requireAuth, requireScope, hasScope).
+ *
+ * @module mcp/capabilities/registry/scope-enforcement
+ * @internal
+ */
+import type { Logger } from "../../../logger/index.js";
+/**
+ * Minimal auth info shape from SDK's `extra.authInfo`.
+ * Kept intentionally loose to match all SDK callback signatures.
+ * @internal
+ */
+export interface SdkAuthInfo {
+    readonly scopes?: readonly string[];
+}
+/**
+ * Checks that all `requiredScopes` are present in the token's scopes.
+ * Throws {@link AuthorizationError} and logs a warning if scopes are insufficient.
+ *
+ * No-op when:
+ * - `requiredScopes` is undefined or empty
+ * - `authInfo` is undefined (no auth middleware active)
+ *
+ * @param requiredScopes - Scopes required by the definition (AND logic)
+ * @param authInfo - Auth info from SDK `extra.authInfo`
+ * @param capabilityType - Label for log messages (e.g. 'Tool', 'Resource', 'Prompt')
+ * @param capabilityName - Name/URI of the capability for log context
+ * @param logger - Logger instance for warning output
+ *
+ * @throws {@link AuthorizationError} when required scopes are not satisfied
+ * @internal
+ */
+export declare function enforceScopeOrThrow(requiredScopes: readonly string[] | undefined, authInfo: SdkAuthInfo | undefined, capabilityType: string, capabilityName: string, logger: Logger): void;
+/**
+ * Checks if all required scopes are present in the token's scopes.
+ * Used by scope-filtered list handlers to decide visibility.
+ *
+ * @param required - Scopes required by the definition (AND logic)
+ * @param tokenScopes - Scopes present on the token
+ * @returns `true` if all required scopes are present
+ * @internal
+ */
+export declare function hasAllRequiredScopes(required: readonly string[], tokenScopes: readonly string[]): boolean;
+//# sourceMappingURL=scope-enforcement.d.ts.map

package/build/mcp/capabilities/registry/scope-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-enforcement.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/scope-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAMvD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC7C,QAAQ,EAAE,WAAW,GAAG,SAAS,EACjC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,IAAI,CAYN;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAEzG"}

package/build/mcp/capabilities/registry/scope-enforcement.js

@@ -0,0 +1,62 @@
+/**
+ * Scope Enforcement for SDK Bindings
+ *
+ * Centralizes RBAC scope checking used by tool, resource, and prompt registries.
+ * This is the internal enforcement layer — for consumer-facing guards,
+ * see `server/auth/guards.ts` (requireAuth, requireScope, hasScope).
+ *
+ * @module mcp/capabilities/registry/scope-enforcement
+ * @internal
+ */
+import { AuthorizationError } from "../../../errors/index.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const AUTH_SCOPE_DENIED = "%s [%s] requires scopes [%s] but token has [%s]";
+// ============================================================================
+// Enforcement
+// ============================================================================
+/**
+ * Checks that all `requiredScopes` are present in the token's scopes.
+ * Throws {@link AuthorizationError} and logs a warning if scopes are insufficient.
+ *
+ * No-op when:
+ * - `requiredScopes` is undefined or empty
+ * - `authInfo` is undefined (no auth middleware active)
+ *
+ * @param requiredScopes - Scopes required by the definition (AND logic)
+ * @param authInfo - Auth info from SDK `extra.authInfo`
+ * @param capabilityType - Label for log messages (e.g. 'Tool', 'Resource', 'Prompt')
+ * @param capabilityName - Name/URI of the capability for log context
+ * @param logger - Logger instance for warning output
+ *
+ * @throws {@link AuthorizationError} when required scopes are not satisfied
+ * @internal
+ */
+export function enforceScopeOrThrow(requiredScopes, authInfo, capabilityType, capabilityName, logger) {
+    if (!requiredScopes || requiredScopes.length === 0 || !authInfo) {
+        return;
+    }
+    const tokenScopes = authInfo.scopes ?? [];
+    const missing = requiredScopes.filter((s) => !tokenScopes.includes(s));
+    if (missing.length > 0) {
+        logger.warn(AUTH_SCOPE_DENIED, capabilityType, capabilityName, requiredScopes.join(","), tokenScopes.join(","));
+        throw AuthorizationError.insufficientScope(requiredScopes, tokenScopes);
+    }
+}
+// ============================================================================
+// List Filtering
+// ============================================================================
+/**
+ * Checks if all required scopes are present in the token's scopes.
+ * Used by scope-filtered list handlers to decide visibility.
+ *
+ * @param required - Scopes required by the definition (AND logic)
+ * @param tokenScopes - Scopes present on the token
+ * @returns `true` if all required scopes are present
+ * @internal
+ */
+export function hasAllRequiredScopes(required, tokenScopes) {
+    return required.every((s) => tokenScopes.includes(s));
+}
+//# sourceMappingURL=scope-enforcement.js.map

package/build/mcp/capabilities/registry/scope-enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-enforcement.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/scope-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAgB9D,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,MAAM,iBAAiB,GAAG,iDAAiD,CAAC;AAE5E,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CACjC,cAA6C,EAC7C,QAAiC,EACjC,cAAsB,EACtB,cAAsB,EACtB,MAAc;IAEd,IAAI,CAAC,cAAc,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChE,OAAO;IACT,CAAC;IAED,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAChH,MAAM,kBAAkB,CAAC,iBAAiB,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA2B,EAAE,WAA8B;IAC9F,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/build/mcp/capabilities/registry/task-tool-registry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Task Tool Registry
+ *
+ * Global registry for MCP task tools that implements TaskToolProvider interface.
+ * Extends BaseRegistry for common CRUD operations.
+ *
+ * The registry is the single authority for task tool definitions:
+ * - Storage: CRUD operations via BaseRegistry
+ * - SDK Binding: `bindToSdk()` registers task tools with MCP SDK server instances
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ * @module mcp/capabilities/registry/task-tool-registry
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+import type { TaskToolDefinition, TaskToolProvider } from "../../types/index.js";
+import type { Logger } from "../../../logger/index.js";
+import { BaseRegistry } from "./base-registry.js";
+/**
+ * Options for binding task tools to an MCP SDK server.
+ * @internal
+ */
+export interface TaskToolBindOptions {
+    readonly logger: Logger;
+    readonly stateless: boolean;
+}
+/**
+ * Registry for MCP task tools that implements TaskToolProvider.
+ *
+ * Extends BaseRegistry for standard CRUD operations (register, get, has, etc.)
+ * and provides `bindToSdk()` for registering task tools with MCP SDK server instances.
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ *
+ * @example
+ * ```typescript
+ * import { globalTaskToolRegistry, defineTask } from 'mcp-server-framework';
+ *
+ * // Task tools are auto-registered via defineTask()
+ * defineTask({ name: 'long_job', ... });
+ *
+ * // Registry can be used directly as a provider
+ * builder.withTaskToolProvider(globalTaskToolRegistry);
+ * ```
+ */
+export declare class TaskToolRegistry extends BaseRegistry<TaskToolDefinition> implements TaskToolProvider {
+    /**
+     * Creates an isolated TaskToolRegistry (no shared global state).
+     *
+     * Used for testing.
+     */
+    static createIsolated(): TaskToolRegistry;
+    protected get itemTypeName(): string;
+    /**
+     * Register a task tool from a generic factory function.
+     *
+     * Centralizes TypeScript generic variance handling. See ToolRegistry for
+     * detailed explanation of the variance pattern.
+     *
+     * @internal Used by defineTask() — prefer registerOrReplace() for non-generic usage.
+     */
+    registerFromFactory<TInput extends z.ZodTypeAny>(taskTool: TaskToolDefinition<TInput>): boolean;
+    /**
+     * Get all registered task tools.
+     *
+     * @returns Readonly array of all task tools
+     */
+    getTaskTools(): ReadonlyArray<TaskToolDefinition>;
+    /**
+     * Registers task tools with the MCP SDK's experimental tasks API.
+     *
+     * Each task tool is registered via `sdk.experimental.tasks.registerToolTask()`.
+     * The SDK handles the task lifecycle protocol (`tasks/list`, `tasks/get`,
+     * `tasks/result`, `tasks/cancel`) automatically when a `taskStore` is provided.
+     *
+     * @param sdk - The MCP SDK server instance
+     * @param taskTools - Task tool definitions to register
+     * @param options - Registration context (logger, stateless mode)
+     * @internal
+     * @experimental
+     */
+    static bindToSdk(sdk: McpServer, taskTools: readonly TaskToolDefinition[], options: TaskToolBindOptions): void;
+    /**
+     * Builds the shared base context from SDK extra parameters.
+     * Common to all three task handler methods.
+     */
+    private static buildBaseContext;
+}
+/**
+ * Global task tool registry singleton.
+ *
+ * This instance is used by defineTask() for auto-registration
+ * and by createServer() to discover all task tools.
+ */
+export declare const globalTaskToolRegistry: TaskToolRegistry;
+//# sourceMappingURL=task-tool-registry.d.ts.map

package/build/mcp/capabilities/registry/task-tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-tool-registry.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/task-tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAIjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgBlD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAwBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,kBAAkB,CAAE,YAAW,gBAAgB;IAKhG;;;;OAIG;IACH,MAAM,CAAC,cAAc,IAAI,gBAAgB;IAQzC,cAAuB,YAAY,IAAI,MAAM,CAE5C;IAMD;;;;;;;OAOG;IACH,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,OAAO;IAS/F;;;;OAIG;IACH,YAAY,IAAI,aAAa,CAAC,kBAAkB,CAAC;IAQjD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,kBAAkB,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAiF9G;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAqBhC;AAMD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,kBAAyB,CAAC"}

package/build/mcp/capabilities/registry/task-tool-registry.js

@@ -0,0 +1,190 @@
+/**
+ * Task Tool Registry
+ *
+ * Global registry for MCP task tools that implements TaskToolProvider interface.
+ * Extends BaseRegistry for common CRUD operations.
+ *
+ * The registry is the single authority for task tool definitions:
+ * - Storage: CRUD operations via BaseRegistry
+ * - SDK Binding: `bindToSdk()` registers task tools with MCP SDK server instances
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ * @module mcp/capabilities/registry/task-tool-registry
+ */
+import { createProgressReporter } from "../../handlers/index.js";
+import { BaseRegistry } from "./base-registry.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const SdkBindingMessages = {
+    TASK_TOOLS_REGISTERED: "Registered %d task tools with SDK",
+    TASK_TOOL_REGISTERED: "Registered task tool: %s (taskSupport=%s)",
+    NO_TASK_TOOLS: "No task tools to register",
+};
+// ============================================================================
+// Task Tool Registry Class
+// ============================================================================
+/**
+ * Registry for MCP task tools that implements TaskToolProvider.
+ *
+ * Extends BaseRegistry for standard CRUD operations (register, get, has, etc.)
+ * and provides `bindToSdk()` for registering task tools with MCP SDK server instances.
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ *
+ * @example
+ * ```typescript
+ * import { globalTaskToolRegistry, defineTask } from 'mcp-server-framework';
+ *
+ * // Task tools are auto-registered via defineTask()
+ * defineTask({ name: 'long_job', ... });
+ *
+ * // Registry can be used directly as a provider
+ * builder.withTaskToolProvider(globalTaskToolRegistry);
+ * ```
+ */
+export class TaskToolRegistry extends BaseRegistry {
+    // ──────────────────────────────────────────────────────────────────────────
+    // Factory
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Creates an isolated TaskToolRegistry (no shared global state).
+     *
+     * Used for testing.
+     */
+    static createIsolated() {
+        return new TaskToolRegistry();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // BaseRegistry Override
+    // ──────────────────────────────────────────────────────────────────────────
+    get itemTypeName() {
+        return "TaskTool";
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Generic Registration (Variance-Safe)
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Register a task tool from a generic factory function.
+     *
+     * Centralizes TypeScript generic variance handling. See ToolRegistry for
+     * detailed explanation of the variance pattern.
+     *
+     * @internal Used by defineTask() — prefer registerOrReplace() for non-generic usage.
+     */
+    registerFromFactory(taskTool) {
+        // @type-variance — Generic input erased for homogeneous storage; SDK validates at runtime
+        return this.registerOrReplace(taskTool);
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // TaskToolProvider Implementation
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Get all registered task tools.
+     *
+     * @returns Readonly array of all task tools
+     */
+    getTaskTools() {
+        return this.getAll();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // SDK Binding
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Registers task tools with the MCP SDK's experimental tasks API.
+     *
+     * Each task tool is registered via `sdk.experimental.tasks.registerToolTask()`.
+     * The SDK handles the task lifecycle protocol (`tasks/list`, `tasks/get`,
+     * `tasks/result`, `tasks/cancel`) automatically when a `taskStore` is provided.
+     *
+     * @param sdk - The MCP SDK server instance
+     * @param taskTools - Task tool definitions to register
+     * @param options - Registration context (logger, stateless mode)
+     * @internal
+     * @experimental
+     */
+    static bindToSdk(sdk, taskTools, options) {
+        const { logger, stateless } = options;
+        if (taskTools.length === 0) {
+            logger.trace(SdkBindingMessages.NO_TASK_TOOLS);
+            return;
+        }
+        logger.trace(SdkBindingMessages.TASK_TOOLS_REGISTERED, taskTools.length);
+        for (const taskTool of taskTools) {
+            const taskSupport = taskTool.taskSupport ?? "required";
+            // @sdk-constraint — SDK registerToolTask has two overloads:
+            // Overload 1 (no input): config without inputSchema, ToolTaskHandler<undefined>
+            // Overload 2 (with input): config with inputSchema, ToolTaskHandler<InputArgs>
+            // We must cast to AnySchema to select overload 2
+            const sdkHandler = {
+                createTask: async (args, extra) => {
+                    const base = TaskToolRegistry.buildBaseContext(extra, stateless);
+                    const context = {
+                        ...base,
+                        taskStore: extra.taskStore,
+                    };
+                    // @sdk-constraint — SDK registerToolTask erases input schema type; args validated at runtime
+                    return taskTool.taskHandler.createTask(args, context);
+                },
+                getTask: async (args, extra) => {
+                    const base = TaskToolRegistry.buildBaseContext(extra, stateless);
+                    const context = {
+                        ...base,
+                        taskId: extra.taskId,
+                        taskStore: extra.taskStore,
+                    };
+                    // @sdk-constraint — SDK registerToolTask erases input schema type; args validated at runtime
+                    return taskTool.taskHandler.getTask(args, context);
+                },
+                getTaskResult: async (args, extra) => {
+                    const base = TaskToolRegistry.buildBaseContext(extra, stateless);
+                    const context = {
+                        ...base,
+                        taskId: extra.taskId,
+                        taskStore: extra.taskStore,
+                    };
+                    // @sdk-constraint — SDK registerToolTask erases input schema type; args validated at runtime
+                    return taskTool.taskHandler.getTaskResult(args, context);
+                },
+            };
+            sdk.experimental.tasks.registerToolTask(taskTool.name, {
+                description: taskTool.description,
+                // @sdk-constraint — registerToolTask expects AnySchema; Zod input is compatible at runtime
+                inputSchema: taskTool.input,
+                execution: { taskSupport },
+                ...(taskTool.annotations && { annotations: taskTool.annotations }),
+                ...(taskTool._meta && { _meta: taskTool._meta }),
+            }, sdkHandler);
+            logger.trace(SdkBindingMessages.TASK_TOOL_REGISTERED, taskTool.name, taskSupport);
+        }
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Private SDK Binding Helpers
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Builds the shared base context from SDK extra parameters.
+     * Common to all three task handler methods.
+     */
+    static buildBaseContext(extra, stateless) {
+        const progressToken = extra._meta?.progressToken;
+        const reportProgress = createProgressReporter(extra.sendNotification.bind(extra), progressToken);
+        return {
+            reportProgress,
+            abortSignal: extra.signal,
+            requestId: extra.requestId,
+            sessionId: extra.sessionId,
+            stateless,
+        };
+    }
+}
+// ============================================================================
+// Global Singleton Instance
+// ============================================================================
+/**
+ * Global task tool registry singleton.
+ *
+ * This instance is used by defineTask() for auto-registration
+ * and by createServer() to discover all task tools.
+ */
+export const globalTaskToolRegistry = new TaskToolRegistry();
+//# sourceMappingURL=task-tool-registry.js.map

package/build/mcp/capabilities/registry/task-tool-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-tool-registry.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/task-tool-registry.ts"],"names":[],"mappings":"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"}

package/build/mcp/capabilities/registry/tool-registry.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Tool Registry
+ *
+ * Global registry for MCP tools that implements ToolProvider interface.
+ * Extends BaseRegistry for common CRUD operations and provides SDK binding.
+ *
+ * The registry is the single authority for tool definitions:
+ * - Storage: CRUD operations via BaseRegistry
+ * - SDK Binding: `bindToSdk()` registers tools with MCP SDK server instances
+ *
+ * @module mcp/capabilities/registry/tool-registry
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+import type { ToolDefinition, ToolProvider } from "../../types/index.js";
+import type { Logger } from "../../../logger/index.js";
+import { BaseRegistry } from "./base-registry.js";
+/**
+ * Options for binding tools to an MCP SDK server.
+ * @internal
+ */
+export interface ToolBindOptions {
+    readonly logger: Logger;
+    readonly stateless: boolean;
+}
+/**
+ * Registry for MCP tools that implements ToolProvider.
+ *
+ * Extends BaseRegistry for standard CRUD operations (register, get, has, etc.)
+ * and provides `bindToSdk()` for registering tools with MCP SDK server instances.
+ *
+ * @example
+ * ```typescript
+ * import { toolRegistry, defineTool } from 'mcp-server-framework';
+ *
+ * // Tools are auto-registered via defineTool()
+ * defineTool({ name: 'greet', ... });
+ *
+ * // Registry can be used directly as a provider
+ * builder.withToolProvider(toolRegistry);
+ * ```
+ */
+export declare class ToolRegistry extends BaseRegistry<ToolDefinition> implements ToolProvider {
+    /**
+     * Creates an isolated ToolRegistry (no shared global state).
+     *
+     * Used for testing.
+     */
+    static createIsolated(): ToolRegistry;
+    protected get itemTypeName(): string;
+    /**
+     * Register a tool from a generic factory function.
+     *
+     * Centralizes TypeScript generic variance handling. `ToolDefinition<TInput>`
+     * is invariant — `TInput` appears in both covariant (input property) and
+     * contravariant (handler parameter) positions via Zod's type mapping.
+     * TypeScript requires `as unknown as` because neither `ToolDefinition<TInput>`
+     * nor `ToolDefinition<ZodTypeAny>` sufficiently overlaps with the other.
+     *
+     * This is safe because the MCP SDK validates input via the Zod schema
+     * at runtime before the handler is invoked.
+     *
+     * @internal Used by defineTool() — prefer registerOrReplace() for non-generic usage.
+     */
+    registerFromFactory<TInput extends z.ZodTypeAny>(tool: ToolDefinition<TInput>): boolean;
+    /**
+     * Get all registered tools.
+     *
+     * @returns Readonly array of all tools
+     */
+    getTools(): ReadonlyArray<ToolDefinition>;
+    /**
+     * Registers tool definitions with an MCP SDK server instance.
+     *
+     * Each tool is registered with:
+     * - SDK-native cancellation via `extra.signal` (AbortSignal per request)
+     * - Rate-limited progress reporting via `extra.sendNotification`
+     * - Structured error handling with MCP error codes
+     * - OpenTelemetry tracing spans and metrics recording
+     * - Tool annotations passed through to the SDK
+     *
+     * @param sdk - The MCP SDK server instance
+     * @param tools - Tool definitions to register
+     * @param options - Registration context (logger, stateless mode)
+     * @internal
+     */
+    static bindToSdk(sdk: McpServer, tools: readonly ToolDefinition[], options: ToolBindOptions): void;
+    /**
+     * Executes a tool handler with cancellation, progress, tracing, and error handling.
+     */
+    private static executeToolCall;
+}
+/**
+ * Global tool registry singleton.
+ *
+ * This instance is used by defineTool() for auto-registration
+ * and by createServer() to discover all tools.
+ */
+export declare const globalToolRegistry: ToolRegistry;
+//# sourceMappingURL=tool-registry.d.ts.map

package/build/mcp/capabilities/registry/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAe,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAuBlD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAa,SAAQ,YAAY,CAAC,cAAc,CAAE,YAAW,YAAY;IAKpF;;;;OAIG;IACH,MAAM,CAAC,cAAc,IAAI,YAAY;IAOrC,cAAuB,YAAY,IAAI,MAAM,CAE5C;IAKD;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO;IASvF;;;;OAIG;IACH,QAAQ,IAAI,aAAa,CAAC,cAAc,CAAC;IAQzC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IA8ElG;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAyE/B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,cAAqB,CAAC"}