mcp-server-framework 1.0.0

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

@@ -0,0 +1,242 @@
+/**
+ * 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 { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { createProgressReporter } from "../../handlers/index.js";
+import { JsonRpcErrorCode } from "../../../errors/index.js";
+import { withSpan, getServerMetrics, MCP_ATTRIBUTES, SpanKind } from "../../../telemetry/index.js";
+import { BaseRegistry } from "./base-registry.js";
+import { enforceScopeOrThrow } from "./scope-enforcement.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const SdkBindingMessages = {
+    TOOLS_REGISTERED: "Registered %d tools with SDK",
+    TOOL_REGISTERED: "Registered tool: %s",
+    NO_TOOLS: "No tools to register",
+    TOOL_EXECUTING: "Tool [%s] executing",
+    TOOL_COMPLETED: "Tool [%s] completed in %dms",
+    TOOL_CANCELLED: "Tool [%s] cancelled",
+    TOOL_ERROR: "Error executing %s:",
+    REQUEST_CANCELLED_BEFORE: "Request was cancelled before execution",
+    REQUEST_CANCELLED: "Request was cancelled",
+};
+// ============================================================================
+// Tool Registry Class
+// ============================================================================
+/**
+ * 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 class ToolRegistry extends BaseRegistry {
+    // ──────────────────────────────────────────────────────────────────────────
+    // Factory
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Creates an isolated ToolRegistry (no shared global state).
+     *
+     * Used for testing.
+     */
+    static createIsolated() {
+        return new ToolRegistry();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // BaseRegistry Override
+    // ──────────────────────────────────────────────────────────────────────────
+    get itemTypeName() {
+        return "Tool";
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Generic Registration (Variance-Safe)
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * 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(tool) {
+        // @type-variance — Generic input erased for homogeneous storage; SDK validates at runtime
+        return this.registerOrReplace(tool);
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // ToolProvider Implementation
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Get all registered tools.
+     *
+     * @returns Readonly array of all tools
+     */
+    getTools() {
+        return this.getAll();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // SDK Binding
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * 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, tools, options) {
+        const { logger, stateless } = options;
+        if (tools.length === 0) {
+            logger.trace(SdkBindingMessages.NO_TOOLS);
+            return;
+        }
+        logger.trace(SdkBindingMessages.TOOLS_REGISTERED, tools.length);
+        for (const tool of tools) {
+            sdk.registerTool(tool.name, {
+                description: tool.description,
+                inputSchema: tool.input,
+                ...(tool.annotations && { annotations: tool.annotations }),
+                ...(tool._meta && { _meta: tool._meta }),
+            }, async (args, extra) => {
+                const { signal: abortSignal, requestId, sessionId } = extra;
+                const progressToken = extra._meta?.progressToken;
+                const reportProgress = createProgressReporter(extra.sendNotification.bind(extra), progressToken);
+                // ── Auth Context from SDK ────────────────────────────────────────
+                // SDK flows req.auth → extra.authInfo when bearer auth middleware is active
+                const authInfo = extra.authInfo;
+                // Tool-level scope enforcement (RBAC)
+                enforceScopeOrThrow(tool.requiredScopes, authInfo, "Tool", tool.name, logger);
+                // Build auth context for tool handler
+                const auth = authInfo
+                    ? {
+                        authInfo,
+                        extra: undefined,
+                    }
+                    : undefined;
+                // Cross-request features: only available in stateful mode + client capability
+                const isStateful = !stateless;
+                const clientCaps = sdk.server.getClientCapabilities();
+                const createMessage = isStateful && clientCaps?.sampling ? sdk.server.createMessage.bind(sdk.server) : undefined;
+                const listRoots = isStateful && clientCaps?.roots ? sdk.server.listRoots.bind(sdk.server) : undefined;
+                const elicitInput = isStateful && clientCaps?.elicitation ? sdk.server.elicitInput.bind(sdk.server) : undefined;
+                return ToolRegistry.executeToolCall(tool, args, {
+                    reportProgress,
+                    abortSignal,
+                    requestId,
+                    sessionId,
+                    stateless,
+                    ...(auth && { auth }),
+                    ...(createMessage && { createMessage }),
+                    ...(listRoots && { listRoots }),
+                    ...(elicitInput && { elicitInput }),
+                }, logger);
+            });
+            logger.trace(SdkBindingMessages.TOOL_REGISTERED, tool.name);
+        }
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Private SDK Binding Helpers
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Executes a tool handler with cancellation, progress, tracing, and error handling.
+     */
+    static executeToolCall(tool, args, context, logger) {
+        const startTime = Date.now();
+        let success = true;
+        return withSpan(`mcp.tool.${tool.name}`, async (span) => {
+            span.setAttributes({
+                [MCP_ATTRIBUTES.TOOL_NAME]: tool.name,
+                [MCP_ATTRIBUTES.OPERATION]: "tool_call",
+                [MCP_ATTRIBUTES.REQUEST_ID]: String(context.requestId),
+                ...(context.sessionId && {
+                    [MCP_ATTRIBUTES.SESSION_ID]: context.sessionId,
+                }),
+            });
+            try {
+                // Check for pre-cancellation
+                if (context.abortSignal.aborted) {
+                    // @sdk-constraint — SDK ErrorCode has no cancellation code; use framework's REQUEST_CANCELLED (-32002)
+                    throw new McpError(JsonRpcErrorCode.REQUEST_CANCELLED, SdkBindingMessages.REQUEST_CANCELLED_BEFORE);
+                }
+                logger.info(SdkBindingMessages.TOOL_EXECUTING, tool.name);
+                // @sdk-constraint — SDK registerTool erases input schema type; args validated at runtime by SDK
+                const result = await tool.handler(args, context);
+                // Record result metadata on span
+                span.setAttributes({
+                    [MCP_ATTRIBUTES.SUCCESS]: true,
+                    [MCP_ATTRIBUTES.RESULT_IS_ERROR]: result.isError === true,
+                    [MCP_ATTRIBUTES.RESULT_CONTENT_COUNT]: result.content?.length ?? 0,
+                });
+                return result;
+            }
+            catch (error) {
+                success = false;
+                // Handle cancellation
+                if (context.abortSignal.aborted || (error instanceof Error && error.name === "AbortError")) {
+                    logger.info(SdkBindingMessages.TOOL_CANCELLED, tool.name);
+                    span.setAttribute(MCP_ATTRIBUTES.SUCCESS, false);
+                    // @sdk-constraint — SDK ErrorCode has no cancellation code; use framework's REQUEST_CANCELLED (-32002)
+                    throw new McpError(JsonRpcErrorCode.REQUEST_CANCELLED, SdkBindingMessages.REQUEST_CANCELLED);
+                }
+                logger.error(SdkBindingMessages.TOOL_ERROR, tool.name, error);
+                span.setAttribute(MCP_ATTRIBUTES.SUCCESS, false);
+                if (error instanceof McpError) {
+                    throw error;
+                }
+                throw new McpError(ErrorCode.InternalError, `Error executing ${tool.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            finally {
+                const durationMs = Date.now() - startTime;
+                getServerMetrics().recordRequest(tool.name, durationMs, success);
+                if (success) {
+                    logger.debug(SdkBindingMessages.TOOL_COMPLETED, tool.name, durationMs);
+                }
+            }
+        }, { kind: SpanKind.SERVER });
+    }
+}
+// ============================================================================
+// Global Singleton Instance
+// ============================================================================
+/**
+ * Global tool registry singleton.
+ *
+ * This instance is used by defineTool() for auto-registration
+ * and by createServer() to discover all tools.
+ */
+export const globalToolRegistry = new ToolRegistry();
+//# sourceMappingURL=tool-registry.js.map

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

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

package/build/mcp/capabilities/resources/define-resource.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Resource Definition Factory
+ *
+ * Provides the defineResource() and defineResourceTemplate() factory functions
+ * for zero-boilerplate resource registration. Resources defined with these
+ * functions are automatically registered in global registries.
+ *
+ * @module mcp/capabilities/resources/define-resource
+ */
+import type { z } from "zod";
+import type { ResourceStaticDefinition, ResourceTemplateDefinition } from "../../types/index.js";
+/**
+ * Define a resource with automatic registration.
+ *
+ * This is the recommended way to define static resources in the framework.
+ * The resource is automatically registered in the global registry when defined.
+ *
+ * @param definition - Resource definition with name, description, uri, and read handler
+ * @returns The registered resource (for re-export and type inference)
+ *
+ * @example
+ * ```typescript
+ * // resources/config.ts
+ * import { defineResource } from 'mcp-server-framework';
+ *
+ * export const configResource = defineResource({
+ *   name: 'app-config',
+ *   description: 'Application configuration',
+ *   uri: 'myapp://config/main',
+ *   mimeType: 'application/json',
+ *   read: async () => JSON.stringify({
+ *     version: '1.0.0',
+ *     environment: process.env.NODE_ENV,
+ *   }),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // resources/readme.ts - Text resource
+ * import { defineResource } from 'mcp-server-framework';
+ * import { readFile } from 'fs/promises';
+ *
+ * export const readmeResource = defineResource({
+ *   name: 'readme',
+ *   description: 'Project README file',
+ *   uri: 'myapp://docs/readme',
+ *   mimeType: 'text/markdown',
+ *   read: async () => readFile('./README.md', 'utf-8'),
+ * });
+ * ```
+ */
+export declare function defineResource(definition: ResourceStaticDefinition): ResourceStaticDefinition;
+/**
+ * Define a resource template with automatic registration.
+ *
+ * Resource templates support dynamic URIs using RFC 6570 URI Templates.
+ * The template is automatically registered in the global registry when defined.
+ *
+ * @typeParam TInput - Zod object schema for parameter validation
+ * @param definition - Template definition with name, description, uriTemplate, and read handler
+ * @returns The registered template (for re-export and type inference)
+ *
+ * @example
+ * ```typescript
+ * // resources/logs.ts - With typed parameters
+ * import { defineResourceTemplate } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ *
+ * export const logResource = defineResourceTemplate({
+ *   name: 'log-viewer',
+ *   description: 'View application logs by ID',
+ *   uriTemplate: 'myapp://logs/{logId}',
+ *   mimeType: 'text/plain',
+ *   input: z.object({
+ *     logId: z.string().describe('Log identifier'),
+ *   }),
+ *   read: async ({ logId }) => {
+ *     const log = await fetchLogById(logId);
+ *     return log.content;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // resources/users.ts - User profile template
+ * import { defineResourceTemplate } from 'mcp-server-framework';
+ *
+ * export const userProfileResource = defineResourceTemplate({
+ *   name: 'user-profile',
+ *   description: 'Get user profile by ID',
+ *   uriTemplate: 'myapp://users/{userId}/profile',
+ *   mimeType: 'application/json',
+ *   read: async ({ userId }) => {
+ *     const user = await getUserById(userId);
+ *     return JSON.stringify(user);
+ *   },
+ * });
+ * ```
+ */
+export declare function defineResourceTemplate<TInput extends z.AnyZodObject = z.AnyZodObject>(definition: ResourceTemplateDefinition<TInput>): ResourceTemplateDefinition<TInput>;
+//# sourceMappingURL=define-resource.d.ts.map

package/build/mcp/capabilities/resources/define-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/resources/define-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAajG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,wBAAwB,GAAG,wBAAwB,CAU7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,SAAS,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,EACnF,UAAU,EAAE,0BAA0B,CAAC,MAAM,CAAC,GAC7C,0BAA0B,CAAC,MAAM,CAAC,CAiCpC"}

package/build/mcp/capabilities/resources/define-resource.js

@@ -0,0 +1,137 @@
+/**
+ * Resource Definition Factory
+ *
+ * Provides the defineResource() and defineResourceTemplate() factory functions
+ * for zero-boilerplate resource registration. Resources defined with these
+ * functions are automatically registered in global registries.
+ *
+ * @module mcp/capabilities/resources/define-resource
+ */
+import { globalResourceRegistry } from "../registry/index.js";
+import { validateDefinitionBase, validateNonEmptyString, validateFunction, validateZodSchema, } from "../../../utils/index.js";
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Define a resource with automatic registration.
+ *
+ * This is the recommended way to define static resources in the framework.
+ * The resource is automatically registered in the global registry when defined.
+ *
+ * @param definition - Resource definition with name, description, uri, and read handler
+ * @returns The registered resource (for re-export and type inference)
+ *
+ * @example
+ * ```typescript
+ * // resources/config.ts
+ * import { defineResource } from 'mcp-server-framework';
+ *
+ * export const configResource = defineResource({
+ *   name: 'app-config',
+ *   description: 'Application configuration',
+ *   uri: 'myapp://config/main',
+ *   mimeType: 'application/json',
+ *   read: async () => JSON.stringify({
+ *     version: '1.0.0',
+ *     environment: process.env.NODE_ENV,
+ *   }),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // resources/readme.ts - Text resource
+ * import { defineResource } from 'mcp-server-framework';
+ * import { readFile } from 'fs/promises';
+ *
+ * export const readmeResource = defineResource({
+ *   name: 'readme',
+ *   description: 'Project README file',
+ *   uri: 'myapp://docs/readme',
+ *   mimeType: 'text/markdown',
+ *   read: async () => readFile('./README.md', 'utf-8'),
+ * });
+ * ```
+ */
+export function defineResource(definition) {
+    // Validate required fields (safety net for JS consumers and empty strings)
+    validateDefinitionBase(definition, "Resource");
+    validateNonEmptyString(definition.uri, "Resource", "uri");
+    validateFunction(definition.read, "Resource", "read");
+    // Auto-register in global registry (replace if exists for hot-reload support)
+    globalResourceRegistry.registerOrReplaceResource(definition);
+    return definition;
+}
+/**
+ * Define a resource template with automatic registration.
+ *
+ * Resource templates support dynamic URIs using RFC 6570 URI Templates.
+ * The template is automatically registered in the global registry when defined.
+ *
+ * @typeParam TInput - Zod object schema for parameter validation
+ * @param definition - Template definition with name, description, uriTemplate, and read handler
+ * @returns The registered template (for re-export and type inference)
+ *
+ * @example
+ * ```typescript
+ * // resources/logs.ts - With typed parameters
+ * import { defineResourceTemplate } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ *
+ * export const logResource = defineResourceTemplate({
+ *   name: 'log-viewer',
+ *   description: 'View application logs by ID',
+ *   uriTemplate: 'myapp://logs/{logId}',
+ *   mimeType: 'text/plain',
+ *   input: z.object({
+ *     logId: z.string().describe('Log identifier'),
+ *   }),
+ *   read: async ({ logId }) => {
+ *     const log = await fetchLogById(logId);
+ *     return log.content;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // resources/users.ts - User profile template
+ * import { defineResourceTemplate } from 'mcp-server-framework';
+ *
+ * export const userProfileResource = defineResourceTemplate({
+ *   name: 'user-profile',
+ *   description: 'Get user profile by ID',
+ *   uriTemplate: 'myapp://users/{userId}/profile',
+ *   mimeType: 'application/json',
+ *   read: async ({ userId }) => {
+ *     const user = await getUserById(userId);
+ *     return JSON.stringify(user);
+ *   },
+ * });
+ * ```
+ */
+export function defineResourceTemplate(definition) {
+    // Validate required fields (safety net for JS consumers and empty strings)
+    validateDefinitionBase(definition, "ResourceTemplate");
+    validateNonEmptyString(definition.uriTemplate, "ResourceTemplate", "uriTemplate");
+    validateFunction(definition.read, "ResourceTemplate", "read");
+    // Basic RFC 6570 check: uriTemplate must contain at least one {varName} placeholder
+    if (!/{[a-zA-Z_]\w*}/.test(definition.uriTemplate)) {
+        throw new TypeError(`ResourceTemplate '${definition.name}': uriTemplate must contain at least one {variable} placeholder (RFC 6570), got '${definition.uriTemplate}'`);
+    }
+    // Validate optional Zod schema if provided (consistent with defineTool)
+    if (definition.input) {
+        validateZodSchema(definition.input, "ResourceTemplate", "input");
+        // Validate URI template variables match schema fields
+        const uriVars = [...definition.uriTemplate.matchAll(/\{(\w+)\}/g)].map((m) => m[1] ?? "");
+        const schemaKeys = Object.keys(definition.input.shape);
+        const missingInSchema = uriVars.filter((v) => !schemaKeys.includes(v));
+        if (missingInSchema.length > 0) {
+            throw new TypeError(`ResourceTemplate '${definition.name}': URI template variables {${missingInSchema.join(", ")}} have no corresponding fields in the input schema`);
+        }
+    }
+    // Auto-register in global registry (variance handled by registry)
+    globalResourceRegistry.registerTemplateFromFactory(definition);
+    return definition;
+}
+//# sourceMappingURL=define-resource.js.map

package/build/mcp/capabilities/resources/define-resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-resource.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/resources/define-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AAEjC,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,cAAc,CAAC,UAAoC;IACjE,2EAA2E;IAC3E,sBAAsB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAC/C,sBAAsB,CAAC,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC1D,gBAAgB,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAEtD,8EAA8E;IAC9E,sBAAsB,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC;IAE7D,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAA8C;IAE9C,2EAA2E;IAC3E,sBAAsB,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;IACvD,sBAAsB,CAAC,UAAU,CAAC,WAAW,EAAE,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAClF,gBAAgB,CAAC,UAAU,CAAC,IAAI,EAAE,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAE9D,oFAAoF;IACpF,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CACjB,qBAAqB,UAAU,CAAC,IAAI,oFAAoF,UAAU,CAAC,WAAW,GAAG,CAClJ,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,iBAAiB,CAAC,UAAU,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAEjE,sDAAsD;QACtD,MAAM,OAAO,GAAG,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1F,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAgC,CAAC,CAAC;QAElF,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,qBAAqB,UAAU,CAAC,IAAI,8BAA8B,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,oDAAoD,CACjJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,sBAAsB,CAAC,2BAA2B,CAAC,UAAU,CAAC,CAAC;IAE/D,OAAO,UAAU,CAAC;AACpB,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Resources Module
+ *
+ * Exports resource definition factories for zero-boilerplate registration.
+ * Types should be imported directly from `mcp/types/`.
+ *
+ * @module mcp/capabilities/resources
+ */
+export { defineResource, defineResourceTemplate } from "./define-resource.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/resources/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Resources Module
+ *
+ * Exports resource definition factories for zero-boilerplate registration.
+ * Types should be imported directly from `mcp/types/`.
+ *
+ * @module mcp/capabilities/resources
+ */
+export { defineResource, defineResourceTemplate } from "./define-resource.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/resources/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC"}

package/build/mcp/capabilities/server-capabilities.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP Server Capabilities
+ *
+ * Defines which MCP protocol capabilities a server advertises to clients.
+ * Lives in the MCP layer because capabilities are an MCP protocol concept.
+ *
+ * @module mcp/capabilities/server-capabilities
+ */
+/**
+ * MCP server capabilities to advertise to clients.
+ */
+export interface ServerCapabilities {
+    /** Enable tools capability with optional list-changed notifications */
+    tools?: boolean | {
+        listChanged?: boolean;
+    };
+    /** Enable resources capability with optional list-changed and subscribe notifications */
+    resources?: boolean | {
+        listChanged?: boolean;
+        subscribe?: boolean;
+    };
+    /** Enable prompts capability with optional list-changed notifications */
+    prompts?: boolean | {
+        listChanged?: boolean;
+    };
+    /** Enable logging capability */
+    logging?: boolean;
+}
+/**
+ * Default server capabilities.
+ */
+export declare const DEFAULT_CAPABILITIES: ServerCapabilities;
+//# sourceMappingURL=server-capabilities.d.ts.map

package/build/mcp/capabilities/server-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-capabilities.d.ts","sourceRoot":"","sources":["../../../src/mcp/capabilities/server-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,GAAG;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAE5C,yFAAyF;IACzF,SAAS,CAAC,EAAE,OAAO,GAAG;QAAE,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAErE,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAE9C,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBAGzB,CAAC"}

package/build/mcp/capabilities/server-capabilities.js

@@ -0,0 +1,16 @@
+/**
+ * MCP Server Capabilities
+ *
+ * Defines which MCP protocol capabilities a server advertises to clients.
+ * Lives in the MCP layer because capabilities are an MCP protocol concept.
+ *
+ * @module mcp/capabilities/server-capabilities
+ */
+/**
+ * Default server capabilities.
+ */
+export const DEFAULT_CAPABILITIES = {
+    tools: { listChanged: true },
+    logging: true,
+};
+//# sourceMappingURL=server-capabilities.js.map

package/build/mcp/capabilities/server-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-capabilities.js","sourceRoot":"","sources":["../../../src/mcp/capabilities/server-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;IAC5B,OAAO,EAAE,IAAI;CACL,CAAC"}