mcp-server-framework 1.0.0

package/build/mcp/capabilities/registry/base-registry.js

@@ -0,0 +1,149 @@
+/**
+ * Base Registry
+ *
+ * Generic abstract base class for MCP registries (Tools, Resources, Prompts).
+ * Extracts common functionality to reduce code duplication.
+ *
+ * @module mcp/capabilities/registry/base-registry
+ */
+import { logger as baseLogger } from "../../../logger/index.js";
+import { RegistryError } from "../../../errors/index.js";
+// ============================================================================
+// Logger
+// ============================================================================
+const LOG_COMPONENT = "registry";
+const LogMessages = {
+    REGISTERED: "%s registered: %s",
+    REPLACED: "%s replaced: %s",
+    CLEARED: "%s registry cleared (%d item(s) removed)",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Base Registry Class
+// ============================================================================
+/**
+ * Abstract base class for MCP registries.
+ *
+ * Provides common functionality:
+ * - Registration (with duplicate checking)
+ * - Lookup by name
+ * - Iteration and size
+ * - Clear/unregister operations
+ *
+ * @typeParam T - The item type (must have a `name` property)
+ *
+ * @example
+ * ```typescript
+ * class ToolRegistry extends BaseRegistry<Tool> {
+ *   // Add tool-specific methods here
+ * }
+ * ```
+ */
+export class BaseRegistry {
+    /** Internal storage */
+    items = new Map();
+    // ──────────────────────────────────────────────────────────────────────────
+    // Registration
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Register a new item. Throws if name already exists.
+     *
+     * @param item - Item to register
+     * @throws If an item with the same name is already registered
+     */
+    register(item) {
+        if (this.items.has(item.name)) {
+            throw RegistryError.duplicate(this.itemTypeName, item.name);
+        }
+        this.items.set(item.name, item);
+        logger.trace(LogMessages.REGISTERED, this.itemTypeName, item.name);
+    }
+    /**
+     * Register or replace an existing item.
+     *
+     * @param item - Item to register/replace
+     * @returns true if replaced, false if new
+     */
+    registerOrReplace(item) {
+        const existed = this.items.has(item.name);
+        this.items.set(item.name, item);
+        if (existed) {
+            logger.trace(LogMessages.REPLACED, this.itemTypeName, item.name);
+        }
+        else {
+            logger.trace(LogMessages.REGISTERED, this.itemTypeName, item.name);
+        }
+        return existed;
+    }
+    /**
+     * Unregister an item by name.
+     *
+     * @param name - Name of the item to remove
+     * @returns true if removed, false if not found
+     */
+    unregister(name) {
+        return this.items.delete(name);
+    }
+    /**
+     * Clear all items from the registry.
+     */
+    clear() {
+        const count = this.items.size;
+        this.items.clear();
+        if (count > 0) {
+            logger.trace(LogMessages.CLEARED, this.itemTypeName, count);
+        }
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Lookup
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Get an item by name.
+     *
+     * @param name - Name of the item
+     * @returns The item or undefined
+     */
+    get(name) {
+        return this.items.get(name);
+    }
+    /**
+     * Check if an item exists.
+     *
+     * @param name - Name to check
+     * @returns true if exists
+     */
+    has(name) {
+        return this.items.has(name);
+    }
+    /**
+     * Get all registered items.
+     *
+     * @returns Readonly array of all items
+     */
+    getAll() {
+        return Array.from(this.items.values());
+    }
+    /**
+     * Number of registered items.
+     */
+    get size() {
+        return this.items.size;
+    }
+    /**
+     * Iterate over all items.
+     */
+    [Symbol.iterator]() {
+        return this.items.values();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Abstract / Override
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Human-readable name for error messages (e.g., "Tool", "Resource").
+     * Override in subclasses.
+     */
+    get itemTypeName() {
+        return "Item";
+    }
+}
+//# sourceMappingURL=base-registry.js.map

package/build/mcp/capabilities/registry/base-registry.js.map

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

package/build/mcp/capabilities/registry/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Registry Module
+ *
+ * Provides registry classes that implement Provider interfaces for direct use
+ * with McpServerBuilder. Each registry also provides `static bindToSdk()` for
+ * registering definitions with MCP SDK server instances.
+ *
+ * @module mcp/capabilities/registry
+ */
+export { BaseRegistry, type RegistryItem } from "./base-registry.js";
+export { ToolRegistry, globalToolRegistry, type ToolBindOptions } from "./tool-registry.js";
+export { ResourceRegistry, globalResourceRegistry, type ResourceBindOptions } from "./resource-registry.js";
+export { PromptRegistry, globalPromptRegistry, type PromptBindOptions } from "./prompt-registry.js";
+export { TaskToolRegistry, globalTaskToolRegistry, type TaskToolBindOptions } from "./task-tool-registry.js";
+export { resetAllRegistries } from "./reset.js";
+//# sourceMappingURL=index.d.ts.map

package/build/mcp/capabilities/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMrE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAM5F,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAM5G,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAMpG,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAM7G,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/build/mcp/capabilities/registry/index.js

@@ -0,0 +1,34 @@
+/**
+ * Registry Module
+ *
+ * Provides registry classes that implement Provider interfaces for direct use
+ * with McpServerBuilder. Each registry also provides `static bindToSdk()` for
+ * registering definitions with MCP SDK server instances.
+ *
+ * @module mcp/capabilities/registry
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Base Registry
+// ─────────────────────────────────────────────────────────────────────────────
+export { BaseRegistry } from "./base-registry.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Registry
+// ─────────────────────────────────────────────────────────────────────────────
+export { ToolRegistry, globalToolRegistry } from "./tool-registry.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Resource Registry
+// ─────────────────────────────────────────────────────────────────────────────
+export { ResourceRegistry, globalResourceRegistry } from "./resource-registry.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Prompt Registry
+// ─────────────────────────────────────────────────────────────────────────────
+export { PromptRegistry, globalPromptRegistry } from "./prompt-registry.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Task Tool Registry
+// ─────────────────────────────────────────────────────────────────────────────
+export { TaskToolRegistry, globalTaskToolRegistry } from "./task-tool-registry.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Lifecycle Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+export { resetAllRegistries } from "./reset.js";
+//# sourceMappingURL=index.js.map

package/build/mcp/capabilities/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,OAAO,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAErE,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAwB,MAAM,oBAAoB,CAAC;AAE5F,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAA4B,MAAM,wBAAwB,CAAC;AAE5G,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAA0B,MAAM,sBAAsB,CAAC;AAEpG,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAA4B,MAAM,yBAAyB,CAAC;AAE7G,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,116 @@
+/**
+ * Prompt Registry
+ *
+ * Global registry for MCP prompts that implements PromptProvider.
+ * Extends BaseRegistry for common CRUD operations.
+ *
+ * The registry is the single authority for prompt definitions:
+ * - Storage: CRUD operations via BaseRegistry
+ * - SDK Binding: `bindToSdk()` registers prompts with MCP SDK server instances
+ *
+ * @module mcp/capabilities/registry/prompt-registry
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+import type { PromptDefinition, PromptProvider } from "../../types/index.js";
+import type { Logger } from "../../../logger/index.js";
+import { BaseRegistry } from "./base-registry.js";
+/**
+ * Options for binding prompts to an MCP SDK server.
+ * @internal
+ */
+export interface PromptBindOptions {
+    readonly logger: Logger;
+}
+/**
+ * Registry for MCP prompts that implements PromptProvider.
+ *
+ * Extends BaseRegistry for standard CRUD operations (register, get, has, etc.)
+ * and provides `bindToSdk()` for registering prompts with MCP SDK server instances.
+ *
+ * @example
+ * ```typescript
+ * import { promptRegistry, definePrompt } from 'mcp-server-framework';
+ *
+ * // Prompts are auto-registered via definePrompt()
+ * definePrompt({ name: 'explain', ... });
+ *
+ * // Registry can be used directly as a provider
+ * builder.withPromptProvider(promptRegistry);
+ * ```
+ */
+export declare class PromptRegistry extends BaseRegistry<PromptDefinition> implements PromptProvider {
+    /**
+     * Creates an isolated PromptRegistry (no shared global state).
+     *
+     * Use for testing or when multiple independent registries are needed.
+     */
+    static createIsolated(): PromptRegistry;
+    protected get itemTypeName(): string;
+    /**
+     * Register a prompt from a generic factory function.
+     *
+     * Centralizes TypeScript generic variance handling. `PromptDefinition<TInput>`
+     * is invariant — `TInput` appears in both covariant (input property) and
+     * contravariant (generate parameter) positions via Zod's type mapping.
+     * TypeScript requires `as unknown as` because neither type sufficiently
+     * overlaps with the other (invariance).
+     *
+     * @internal Used by definePrompt() — prefer registerOrReplace() for non-generic usage.
+     */
+    registerFromFactory<TInput extends z.AnyZodObject>(prompt: PromptDefinition<TInput>): boolean;
+    /**
+     * Get all registered prompts.
+     */
+    getPrompts(): ReadonlyArray<PromptDefinition>;
+    /**
+     * Check if provider has any prompts.
+     */
+    hasPrompts(): boolean;
+    /**
+     * Registers prompt definitions with an MCP SDK server instance.
+     *
+     * Each prompt is registered with:
+     * - Schema extraction for SDK's raw shape format
+     * - Completable wrapping for prompt autocompletion
+     * - OpenTelemetry tracing spans
+     * - Structured error handling and logging
+     *
+     * @param sdk - The MCP SDK server instance
+     * @param prompts - Prompt definitions to register
+     * @param options - Registration context (logger)
+     * @internal
+     */
+    static bindToSdk(sdk: McpServer, prompts: readonly PromptDefinition[], options: PromptBindOptions): void;
+    /**
+     * Extracts the raw shape from a ZodObject for SDK prompt registration.
+     *
+     * @sdk-constraint — The SDK's `registerPrompt()` passes `argsSchema` directly to
+     * `objectFromShape()`, which expects a `Record<string, ZodType>` (raw shape),
+     * NOT a ZodObject instance. In contrast, `registerTool()` uses `getZodSchemaObject()`
+     * which handles both ZodObject and raw shapes. This asymmetry requires explicit
+     * shape extraction for prompts.
+     *
+     * @param schema - A ZodObject schema (e.g. `z.object({ name: z.string() })`)
+     * @returns The raw shape object (e.g. `{ name: z.string() }`) or undefined
+     */
+    private static extractPromptArgsShape;
+    /**
+     * Wraps Zod schema shape fields with SDK's `completable()` for prompt autocompletion.
+     *
+     * When a prompt defines a `complete` callback, each field in the args schema is wrapped
+     * so the SDK's built-in completion handler can invoke the callback per-field.
+     *
+     * @sdk-constraint — The SDK checks `isCompletable(field)` on each Zod schema field
+     * and uses `getCompleter(field)` to get the completion callback.
+     */
+    private static wrapShapeWithCompletable;
+}
+/**
+ * Global prompt registry singleton.
+ *
+ * This instance is used by definePrompt() for auto-registration
+ * and by createServer() to discover all prompts.
+ */
+export declare const globalPromptRegistry: PromptRegistry;
+//# sourceMappingURL=prompt-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-registry.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/prompt-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,gBAAgB,EAAiB,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAChH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAmBlD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAe,SAAQ,YAAY,CAAC,gBAAgB,CAAE,YAAW,cAAc;IAK1F;;;;OAIG;IACH,MAAM,CAAC,cAAc,IAAI,cAAc;IAOvC,cAAuB,YAAY,IAAI,MAAM,CAE5C;IAMD;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,OAAO;IAS7F;;OAEG;IACH,UAAU,IAAI,aAAa,CAAC,gBAAgB,CAAC;IAI7C;;OAEG;IACH,UAAU,IAAI,OAAO;IAQrB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,gBAAgB,EAAE,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IA6ExG;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAarC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;CA6BxC;AAMD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,gBAAuB,CAAC"}

package/build/mcp/capabilities/registry/prompt-registry.js

@@ -0,0 +1,232 @@
+/**
+ * Prompt Registry
+ *
+ * Global registry for MCP prompts that implements PromptProvider.
+ * Extends BaseRegistry for common CRUD operations.
+ *
+ * The registry is the single authority for prompt definitions:
+ * - Storage: CRUD operations via BaseRegistry
+ * - SDK Binding: `bindToSdk()` registers prompts with MCP SDK server instances
+ *
+ * @module mcp/capabilities/registry/prompt-registry
+ */
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { withSpan, MCP_ATTRIBUTES, SpanKind } from "../../../telemetry/index.js";
+import { BaseRegistry } from "./base-registry.js";
+import { enforceScopeOrThrow } from "./scope-enforcement.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const SdkBindingMessages = {
+    PROMPTS_REGISTERED: "Registered %d prompts with SDK",
+    PROMPT_REGISTERED: "Registered prompt: %s",
+    NO_PROMPTS: "No prompts to register",
+    PROMPT_GETTING: "Getting prompt: %s with args %j",
+    PROMPT_ERROR: "Error generating prompt %s: %s",
+};
+// ============================================================================
+// Prompt Registry Class
+// ============================================================================
+/**
+ * Registry for MCP prompts that implements PromptProvider.
+ *
+ * Extends BaseRegistry for standard CRUD operations (register, get, has, etc.)
+ * and provides `bindToSdk()` for registering prompts with MCP SDK server instances.
+ *
+ * @example
+ * ```typescript
+ * import { promptRegistry, definePrompt } from 'mcp-server-framework';
+ *
+ * // Prompts are auto-registered via definePrompt()
+ * definePrompt({ name: 'explain', ... });
+ *
+ * // Registry can be used directly as a provider
+ * builder.withPromptProvider(promptRegistry);
+ * ```
+ */
+export class PromptRegistry extends BaseRegistry {
+    // ──────────────────────────────────────────────────────────────────────────
+    // Factory
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Creates an isolated PromptRegistry (no shared global state).
+     *
+     * Use for testing or when multiple independent registries are needed.
+     */
+    static createIsolated() {
+        return new PromptRegistry();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // BaseRegistry Override
+    // ──────────────────────────────────────────────────────────────────────────
+    get itemTypeName() {
+        return "Prompt";
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Generic Registration (Variance-Safe)
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Register a prompt from a generic factory function.
+     *
+     * Centralizes TypeScript generic variance handling. `PromptDefinition<TInput>`
+     * is invariant — `TInput` appears in both covariant (input property) and
+     * contravariant (generate parameter) positions via Zod's type mapping.
+     * TypeScript requires `as unknown as` because neither type sufficiently
+     * overlaps with the other (invariance).
+     *
+     * @internal Used by definePrompt() — prefer registerOrReplace() for non-generic usage.
+     */
+    registerFromFactory(prompt) {
+        // @type-variance — Generic input erased for homogeneous storage; SDK validates at runtime
+        return this.registerOrReplace(prompt);
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // PromptProvider Implementation
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Get all registered prompts.
+     */
+    getPrompts() {
+        return this.getAll();
+    }
+    /**
+     * Check if provider has any prompts.
+     */
+    hasPrompts() {
+        return this.size > 0;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // SDK Binding
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Registers prompt definitions with an MCP SDK server instance.
+     *
+     * Each prompt is registered with:
+     * - Schema extraction for SDK's raw shape format
+     * - Completable wrapping for prompt autocompletion
+     * - OpenTelemetry tracing spans
+     * - Structured error handling and logging
+     *
+     * @param sdk - The MCP SDK server instance
+     * @param prompts - Prompt definitions to register
+     * @param options - Registration context (logger)
+     * @internal
+     */
+    static bindToSdk(sdk, prompts, options) {
+        const { logger } = options;
+        if (prompts.length === 0) {
+            logger.trace(SdkBindingMessages.NO_PROMPTS);
+            return;
+        }
+        logger.trace(SdkBindingMessages.PROMPTS_REGISTERED, prompts.length);
+        for (const prompt of prompts) {
+            // @sdk-constraint — SDK registerPrompt expects PromptArgsRawShape (Record<string, ZodType>),
+            // NOT a ZodObject.
+            const argsShape = PromptRegistry.extractPromptArgsShape(prompt.input);
+            // Wrap schema fields with SDK's completable() when a complete callback is provided
+            const completableShape = argsShape && prompt.complete
+                ? PromptRegistry.wrapShapeWithCompletable(argsShape, prompt.complete, logger)
+                : argsShape;
+            const config = {
+                description: prompt.description,
+                ...(completableShape && { argsSchema: completableShape }),
+            };
+            // @sdk-constraint — registerPrompt generic requires PromptArgsRawShape; config carries extracted shape
+            sdk.registerPrompt(prompt.name, config, async (args, extra) => {
+                // Scope enforcement (RBAC)
+                enforceScopeOrThrow(prompt.requiredScopes, extra.authInfo, "Prompt", prompt.name, logger);
+                return withSpan(`mcp.prompt.${prompt.name}`, async (span) => {
+                    span.setAttributes({
+                        [MCP_ATTRIBUTES.PROMPT_NAME]: prompt.name,
+                        [MCP_ATTRIBUTES.OPERATION]: "prompt_generate",
+                    });
+                    logger.trace(SdkBindingMessages.PROMPT_GETTING, prompt.name, args);
+                    try {
+                        // @sdk-constraint — SDK prompt callback types args as unknown
+                        const messages = await prompt.generate(args);
+                        span.setAttribute(MCP_ATTRIBUTES.RESULT_CONTENT_COUNT, messages.length);
+                        return {
+                            messages: messages.map((m) => ({
+                                role: m.role,
+                                content: { type: "text", text: m.content },
+                            })),
+                        };
+                    }
+                    catch (error) {
+                        const msg = error instanceof Error ? error.message : String(error);
+                        logger.error(SdkBindingMessages.PROMPT_ERROR, prompt.name, msg);
+                        throw new McpError(ErrorCode.InternalError, `Prompt '${prompt.name}' failed: ${msg}`);
+                    }
+                }, { kind: SpanKind.SERVER });
+            });
+            logger.trace(SdkBindingMessages.PROMPT_REGISTERED, prompt.name);
+        }
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Private SDK Binding Helpers
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Extracts the raw shape from a ZodObject for SDK prompt registration.
+     *
+     * @sdk-constraint — The SDK's `registerPrompt()` passes `argsSchema` directly to
+     * `objectFromShape()`, which expects a `Record<string, ZodType>` (raw shape),
+     * NOT a ZodObject instance. In contrast, `registerTool()` uses `getZodSchemaObject()`
+     * which handles both ZodObject and raw shapes. This asymmetry requires explicit
+     * shape extraction for prompts.
+     *
+     * @param schema - A ZodObject schema (e.g. `z.object({ name: z.string() })`)
+     * @returns The raw shape object (e.g. `{ name: z.string() }`) or undefined
+     */
+    static extractPromptArgsShape(schema) {
+        if (!schema)
+            return undefined;
+        // @type-narrowing — ZodObject.shape is typed as ZodRawShape (Record<string, ZodTypeAny>)
+        const shape = schema.shape;
+        // Empty shapes are valid — SDK handles them (creates z4mini.object({}))
+        // but skipping registration entirely for empty schemas is cleaner
+        if (Object.keys(shape).length === 0)
+            return undefined;
+        return shape;
+    }
+    /**
+     * Wraps Zod schema shape fields with SDK's `completable()` for prompt autocompletion.
+     *
+     * When a prompt defines a `complete` callback, each field in the args schema is wrapped
+     * so the SDK's built-in completion handler can invoke the callback per-field.
+     *
+     * @sdk-constraint — The SDK checks `isCompletable(field)` on each Zod schema field
+     * and uses `getCompleter(field)` to get the completion callback.
+     */
+    static wrapShapeWithCompletable(shape, complete, logger) {
+        const wrapped = {};
+        for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+            // Clone the schema before wrapping — completable() mutates the Zod object via
+            // Object.defineProperty with configurable:false. Since definitions are global
+            // singletons (DD-002), a second session would fail with "Cannot redefine property".
+            const cloned = fieldSchema.describe(fieldSchema.description ?? "");
+            wrapped[fieldName] = completable(cloned, async (value) => {
+                try {
+                    const result = await complete(fieldName, value);
+                    return result.values;
+                }
+                catch (error) {
+                    logger.warn("Completion callback failed for field '%s': %s", fieldName, error instanceof Error ? error.message : String(error));
+                    return [];
+                }
+            });
+        }
+        return wrapped;
+    }
+}
+// ============================================================================
+// Global Singleton Instance
+// ============================================================================
+/**
+ * Global prompt registry singleton.
+ *
+ * This instance is used by definePrompt() for auto-registration
+ * and by createServer() to discover all prompts.
+ */
+export const globalPromptRegistry = new PromptRegistry();
+//# sourceMappingURL=prompt-registry.js.map

package/build/mcp/capabilities/registry/prompt-registry.js.map

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

package/build/mcp/capabilities/registry/reset.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Registry Reset Utility
+ *
+ * Provides a lifecycle function to reset all global registries.
+ * Keeps the barrel file (index.ts) free of implementation logic.
+ *
+ * @module mcp/capabilities/registry/reset
+ */
+/**
+ * Reset all global registries.
+ *
+ * Clears all registered tools, resources, resource templates, and prompts
+ * from the global singleton registries. After calling this, all `define*()`
+ * calls must be re-executed to repopulate the registries.
+ *
+ * **Use cases:**
+ * - Hot-reload during development
+ * - Server restart / lifecycle management
+ * - Isolated testing scenarios
+ *
+ * @example
+ * ```typescript
+ * import { resetAllRegistries } from 'mcp-server-framework';
+ *
+ * // Before re-registering tools in a hot-reload scenario
+ * resetAllRegistries();
+ * ```
+ */
+export declare function resetAllRegistries(): void;
+//# sourceMappingURL=reset.d.ts.map

package/build/mcp/capabilities/registry/reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/registry/reset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC"}