mcp-server-framework 1.0.0

package/build/mcp/handlers/progress.js

@@ -0,0 +1,79 @@
+/**
+ * Progress Reporting Utility
+ *
+ * Creates rate-limited progress reporters using the SDK's native
+ * `sendNotification` from `RequestHandlerExtra`. This replaces
+ * the redundant RequestManager progress functionality.
+ *
+ * Rate-limiting prevents flooding the client with too many
+ * `notifications/progress` messages during tight loops.
+ *
+ * @see https://spec.modelcontextprotocol.io/specification/2025-11-25/server/utilities/progress/
+ * @module mcp/handlers/progress
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Minimum interval between progress notifications in milliseconds.
+ * Prevents flooding the client with updates during tight loops.
+ */
+export const PROGRESS_MIN_INTERVAL_MS = 100;
+/**
+ * MCP notification method for progress updates.
+ */
+const PROGRESS_METHOD = "notifications/progress";
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates a rate-limited progress reporter for a tool invocation.
+ *
+ * Uses the SDK's native `sendNotification` to send `notifications/progress`
+ * messages. Applies rate-limiting (100ms minimum interval) to prevent
+ * flooding the client during tight loops.
+ *
+ * @param sendNotification - The SDK extra's `sendNotification` function
+ * @param progressToken - The progress token from `_meta.progressToken` (undefined = no progress requested)
+ * @returns A ProgressReporter function, or undefined if no progressToken was provided
+ *
+ * @example
+ * ```typescript
+ * // Inside SDK tool callback:
+ * const reporter = createProgressReporter(extra.sendNotification, extra._meta?.progressToken);
+ *
+ * // Use in tool handler:
+ * await reporter?.({ progress: 1, total: 10, message: 'Processing...' });
+ * ```
+ */
+export function createProgressReporter(sendNotification, progressToken) {
+    if (progressToken === undefined) {
+        return undefined;
+    }
+    let lastNotificationTime = 0;
+    return async (data) => {
+        const now = Date.now();
+        // Rate-limit: skip if too soon after last notification
+        if (now - lastNotificationTime < PROGRESS_MIN_INTERVAL_MS) {
+            return false;
+        }
+        lastNotificationTime = now;
+        try {
+            await sendNotification({
+                method: PROGRESS_METHOD,
+                params: {
+                    progressToken,
+                    progress: data.progress,
+                    ...(data.total !== undefined && { total: data.total }),
+                    ...(data.message !== undefined && { message: data.message }),
+                },
+            });
+            return true;
+        }
+        catch {
+            // Progress notifications are best-effort per MCP specification
+            return false;
+        }
+    };
+}
+//# sourceMappingURL=progress.js.map

package/build/mcp/handlers/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../src/mcp/handlers/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAE5C;;GAEG;AACH,MAAM,eAAe,GAAG,wBAAiC,CAAC;AAE1D,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CACpC,gBAAoC,EACpC,aAAwC;IAExC,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAE7B,OAAO,KAAK,EAAE,IAAkB,EAAoB,EAAE;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,uDAAuD;QACvD,IAAI,GAAG,GAAG,oBAAoB,GAAG,wBAAwB,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAC;QACf,CAAC;QAED,oBAAoB,GAAG,GAAG,CAAC;QAE3B,IAAI,CAAC;YACH,MAAM,gBAAgB,CAAC;gBACrB,MAAM,EAAE,eAAe;gBACvB,MAAM,EAAE;oBACN,aAAa;oBACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;oBACtD,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;iBAC7D;aACF,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;YAC/D,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/build/mcp/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP Module
+ *
+ * Central export point for all MCP protocol-related functionality.
+ * This module provides the building blocks for defining and managing
+ * MCP tools, resources, prompts, and protocol handlers.
+ *
+ * ## Module Structure
+ *
+ * - **types/** — Consolidated type definitions
+ * - **capabilities/** — Tool, resource, prompt definition factories
+ * - **capabilities/registry/** — Global registries for auto-registration
+ * - **responses/** — Response helper functions
+ * - **handlers/** — MCP protocol handler setup (ping, progress)
+ *
+ * @module mcp
+ */
+export type { ContentAudience, ContentAnnotations, ResponseOptions, TextResponseOptions, JsonResponseOptions, ErrorResponseOptions, ImageMimeType, ImageResponseOptions, AudioMimeType, AudioResponseOptions, ToolResponse, } from "./types/index.js";
+export { defineTool } from "./capabilities/tools/index.js";
+export { defineResource, defineResourceTemplate } from "./capabilities/resources/index.js";
+export { definePrompt } from "./capabilities/prompts/index.js";
+export { defineApp } from "./capabilities/apps/index.js";
+export { defineTask } from "./capabilities/tasks/index.js";
+export { text, json, error, image, audio, multi } from "./responses/index.js";
+export { BaseRegistry, ToolRegistry, globalToolRegistry, ResourceRegistry, globalResourceRegistry, PromptRegistry, globalPromptRegistry, TaskToolRegistry, globalTaskToolRegistry, resetAllRegistries, } from "./capabilities/registry/index.js";
+export type { RegistryItem, TaskToolBindOptions } from "./capabilities/registry/index.js";
+export type { ToolProvider, ResourceProvider, PromptProvider, TaskToolProvider } from "./types/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,YAAY,EAEV,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAM3D,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAM9E,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAG1F,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/build/mcp/index.js

@@ -0,0 +1,34 @@
+/**
+ * MCP Module
+ *
+ * Central export point for all MCP protocol-related functionality.
+ * This module provides the building blocks for defining and managing
+ * MCP tools, resources, prompts, and protocol handlers.
+ *
+ * ## Module Structure
+ *
+ * - **types/** — Consolidated type definitions
+ * - **capabilities/** — Tool, resource, prompt definition factories
+ * - **capabilities/registry/** — Global registries for auto-registration
+ * - **responses/** — Response helper functions
+ * - **handlers/** — MCP protocol handler setup (ping, progress)
+ *
+ * @module mcp
+ */
+// ============================================================================
+// Define Functions (Zero-Boilerplate Registration)
+// ============================================================================
+export { defineTool } from "./capabilities/tools/index.js";
+export { defineResource, defineResourceTemplate } from "./capabilities/resources/index.js";
+export { definePrompt } from "./capabilities/prompts/index.js";
+export { defineApp } from "./capabilities/apps/index.js";
+export { defineTask } from "./capabilities/tasks/index.js";
+// ============================================================================
+// Response Helpers
+// ============================================================================
+export { text, json, error, image, audio, multi } from "./responses/index.js";
+// ============================================================================
+// Registries
+// ============================================================================
+export { BaseRegistry, ToolRegistry, globalToolRegistry, ResourceRegistry, globalResourceRegistry, PromptRegistry, globalPromptRegistry, TaskToolRegistry, globalTaskToolRegistry, resetAllRegistries, } from "./capabilities/registry/index.js";
+//# sourceMappingURL=index.js.map

package/build/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAqBH,+EAA+E;AAC/E,mDAAmD;AACnD,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE9E,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC"}

package/build/mcp/responses/helpers.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Response Helpers
+ *
+ * Factory functions for creating MCP tool responses with zero boilerplate.
+ * These helpers produce properly formatted CallToolResult objects.
+ *
+ * @module mcp/responses/helpers
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { TextResponseOptions, JsonResponseOptions, ErrorResponseOptions, ImageResponseOptions, AudioResponseOptions, ContentAnnotations } from "../types/index.js";
+/**
+ * Create a text response.
+ *
+ * This is the most common response type for tool results.
+ *
+ * @param content - The text content to return
+ * @param options - Optional annotations and metadata
+ * @returns A CallToolResult with text content
+ *
+ * @example
+ * ```typescript
+ * // Simple text response
+ * return text('Hello, World!');
+ *
+ * // With annotations
+ * return text('Secret message', {
+ *   annotations: { audience: ['user'] },
+ * });
+ * ```
+ */
+export declare function text(content: string, options?: TextResponseOptions): CallToolResult;
+/**
+ * Create a JSON response.
+ *
+ * Automatically serializes the data with pretty-printing.
+ * Useful for returning structured data from tools.
+ *
+ * @param data - The data to serialize as JSON
+ * @param options - Optional formatting, annotations, and metadata
+ * @returns A CallToolResult with JSON text content
+ *
+ * @example
+ * ```typescript
+ * // Simple JSON response
+ * return json({ status: 'ok', count: 42 });
+ *
+ * // Compact JSON (no indentation)
+ * return json(data, { indent: 0 });
+ * ```
+ */
+export declare function json(data: unknown, options?: JsonResponseOptions): CallToolResult;
+/**
+ * Create an error response.
+ *
+ * Sets the isError flag to indicate the tool execution failed.
+ * Use this for user-friendly error messages.
+ *
+ * @param message - The error message to return
+ * @param options - Optional annotations and metadata
+ * @returns A CallToolResult with isError=true
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * return error('Container not found');
+ *
+ * // With annotations
+ * return error('Permission denied', {
+ *   annotations: { audience: ['user'] },
+ * });
+ * ```
+ */
+export declare function error(message: string, options?: ErrorResponseOptions): CallToolResult;
+/**
+ * Create an image response.
+ *
+ * The data must be base64-encoded image data.
+ *
+ * @param data - Base64-encoded image data
+ * @param options - MIME type and optional annotations
+ * @returns A CallToolResult with image content
+ *
+ * @example
+ * ```typescript
+ * // PNG image (default)
+ * return image(base64Data);
+ *
+ * // JPEG image
+ * return image(base64Data, { mimeType: 'image/jpeg' });
+ * ```
+ */
+export declare function image(data: string, options?: ImageResponseOptions): CallToolResult;
+/**
+ * Create an audio response.
+ *
+ * The data must be base64-encoded audio data.
+ *
+ * @param data - Base64-encoded audio data
+ * @param options - MIME type and optional annotations
+ * @returns A CallToolResult with audio content
+ *
+ * @example
+ * ```typescript
+ * // WAV audio (default)
+ * return audio(base64Data);
+ *
+ * // MP3 audio
+ * return audio(base64Data, { mimeType: 'audio/mp3' });
+ * ```
+ */
+export declare function audio(data: string, options?: AudioResponseOptions): CallToolResult;
+/**
+ * Create a response with multiple content items.
+ *
+ * Useful for returning text alongside images or multiple text blocks.
+ *
+ * @param items - Array of text, image, and/or audio content
+ * @param options - Optional metadata
+ * @returns A CallToolResult with multiple content items
+ *
+ * @example
+ * ```typescript
+ * return multi([
+ *   { type: 'text', text: 'Here is the chart:' },
+ *   { type: 'image', data: chartBase64, mimeType: 'image/png' },
+ * ]);
+ * ```
+ */
+export declare function multi(items: Array<{
+    type: "text";
+    text: string;
+    annotations?: ContentAnnotations;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+    annotations?: ContentAnnotations;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+    annotations?: ContentAnnotations;
+}>, options?: {
+    _meta?: Record<string, unknown>;
+}): CallToolResult;
+//# sourceMappingURL=helpers.d.ts.map

package/build/mcp/responses/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/responses/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,mBAAmB,CAAC;AAiC3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAEnF;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAYjF;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAKrF;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAIlF;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAIlF;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CACnB,KAAK,EAAE,KAAK,CACR;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;CAAE,GAChE;IACE,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,CACJ,EACD,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC5C,cAAc,CAQhB"}

package/build/mcp/responses/helpers.js

@@ -0,0 +1,197 @@
+/**
+ * Response Helpers
+ *
+ * Factory functions for creating MCP tool responses with zero boilerplate.
+ * These helpers produce properly formatted CallToolResult objects.
+ *
+ * @module mcp/responses/helpers
+ */
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Build a CallToolResult from content items and options.
+ * Centralizes the repeated annotations + _meta wrapping pattern.
+ */
+function buildResponse(content, options) {
+    return {
+        content,
+        ...(options?.isError && { isError: true }),
+        ...(options?._meta && { _meta: options._meta }),
+    };
+}
+/**
+ * Spread annotations onto a content item if provided.
+ */
+function withAnnotations(item, annotations) {
+    if (!annotations)
+        return item;
+    return { ...item, annotations: { ...annotations } };
+}
+// ============================================================================
+// Text Response
+// ============================================================================
+/**
+ * Create a text response.
+ *
+ * This is the most common response type for tool results.
+ *
+ * @param content - The text content to return
+ * @param options - Optional annotations and metadata
+ * @returns A CallToolResult with text content
+ *
+ * @example
+ * ```typescript
+ * // Simple text response
+ * return text('Hello, World!');
+ *
+ * // With annotations
+ * return text('Secret message', {
+ *   annotations: { audience: ['user'] },
+ * });
+ * ```
+ */
+export function text(content, options) {
+    return buildResponse([withAnnotations({ type: "text", text: content }, options?.annotations)], options);
+}
+// ============================================================================
+// JSON Response
+// ============================================================================
+/**
+ * Create a JSON response.
+ *
+ * Automatically serializes the data with pretty-printing.
+ * Useful for returning structured data from tools.
+ *
+ * @param data - The data to serialize as JSON
+ * @param options - Optional formatting, annotations, and metadata
+ * @returns A CallToolResult with JSON text content
+ *
+ * @example
+ * ```typescript
+ * // Simple JSON response
+ * return json({ status: 'ok', count: 42 });
+ *
+ * // Compact JSON (no indentation)
+ * return json(data, { indent: 0 });
+ * ```
+ */
+export function json(data, options) {
+    const indent = options?.indent ?? 2;
+    let serialized;
+    try {
+        serialized = JSON.stringify(data, null, indent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : "JSON serialization failed";
+        return error(`Failed to serialize response as JSON: ${msg}`, options);
+    }
+    return buildResponse([withAnnotations({ type: "text", text: serialized }, options?.annotations)], options);
+}
+// ============================================================================
+// Error Response
+// ============================================================================
+/**
+ * Create an error response.
+ *
+ * Sets the isError flag to indicate the tool execution failed.
+ * Use this for user-friendly error messages.
+ *
+ * @param message - The error message to return
+ * @param options - Optional annotations and metadata
+ * @returns A CallToolResult with isError=true
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * return error('Container not found');
+ *
+ * // With annotations
+ * return error('Permission denied', {
+ *   annotations: { audience: ['user'] },
+ * });
+ * ```
+ */
+export function error(message, options) {
+    return buildResponse([withAnnotations({ type: "text", text: message }, options?.annotations)], {
+        ...options,
+        isError: true,
+    });
+}
+// ============================================================================
+// Image Response
+// ============================================================================
+/**
+ * Create an image response.
+ *
+ * The data must be base64-encoded image data.
+ *
+ * @param data - Base64-encoded image data
+ * @param options - MIME type and optional annotations
+ * @returns A CallToolResult with image content
+ *
+ * @example
+ * ```typescript
+ * // PNG image (default)
+ * return image(base64Data);
+ *
+ * // JPEG image
+ * return image(base64Data, { mimeType: 'image/jpeg' });
+ * ```
+ */
+export function image(data, options) {
+    const mimeType = options?.mimeType ?? "image/png";
+    return buildResponse([withAnnotations({ type: "image", data, mimeType }, options?.annotations)], options);
+}
+// ============================================================================
+// Audio Response
+// ============================================================================
+/**
+ * Create an audio response.
+ *
+ * The data must be base64-encoded audio data.
+ *
+ * @param data - Base64-encoded audio data
+ * @param options - MIME type and optional annotations
+ * @returns A CallToolResult with audio content
+ *
+ * @example
+ * ```typescript
+ * // WAV audio (default)
+ * return audio(base64Data);
+ *
+ * // MP3 audio
+ * return audio(base64Data, { mimeType: 'audio/mp3' });
+ * ```
+ */
+export function audio(data, options) {
+    const mimeType = options?.mimeType ?? "audio/wav";
+    return buildResponse([withAnnotations({ type: "audio", data, mimeType }, options?.annotations)], options);
+}
+// ============================================================================
+// Multi-Content Response
+// ============================================================================
+/**
+ * Create a response with multiple content items.
+ *
+ * Useful for returning text alongside images or multiple text blocks.
+ *
+ * @param items - Array of text, image, and/or audio content
+ * @param options - Optional metadata
+ * @returns A CallToolResult with multiple content items
+ *
+ * @example
+ * ```typescript
+ * return multi([
+ *   { type: 'text', text: 'Here is the chart:' },
+ *   { type: 'image', data: chartBase64, mimeType: 'image/png' },
+ * ]);
+ * ```
+ */
+export function multi(items, options) {
+    if (items.length === 0) {
+        throw new TypeError("multi() requires at least one content item");
+    }
+    return buildResponse(items.map((item) => withAnnotations({ ...item }, item.annotations)), options);
+}
+//# sourceMappingURL=helpers.js.map

package/build/mcp/responses/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/mcp/responses/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;GAGG;AACH,SAAS,aAAa,CACpB,OAAkC,EAClC,OAAiD;IAEjD,OAAO;QACL,OAAO;QACP,GAAG,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC1C,GAAG,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAoC,IAAO,EAAE,WAAgC;IACnG,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,EAAE,GAAG,WAAW,EAAE,EAAE,CAAC;AACtD,CAAC;AAED,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,OAA6B;IACjE,OAAO,aAAa,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACnH,CAAC;AAED,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,OAA6B;IAC/D,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;IAEpC,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,CAAC;QAC7E,OAAO,KAAK,CAAC,yCAAyC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,aAAa,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACtH,CAAC;AAED,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,OAA8B;IACnE,OAAO,aAAa,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE;QACtG,GAAG,OAAO;QACV,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,OAA8B;IAChE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,WAAW,CAAC;IAElD,OAAO,aAAa,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACrH,CAAC;AAED,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,OAA8B;IAChE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,WAAW,CAAC;IAElD,OAAO,aAAa,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACrH,CAAC;AAED,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,KAAK,CACnB,KAcC,EACD,OAA6C;IAE7C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,aAAa,CAClB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,EACnE,OAAO,CACR,CAAC;AACJ,CAAC"}

package/build/mcp/responses/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Responses Module
+ *
+ * Exports response helper functions for creating MCP tool responses.
+ *
+ * @module mcp/responses
+ */
+export { text, json, error, image, audio, multi } from "./helpers.js";
+//# sourceMappingURL=index.d.ts.map

package/build/mcp/responses/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/responses/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC"}

package/build/mcp/responses/index.js

@@ -0,0 +1,12 @@
+/**
+ * Responses Module
+ *
+ * Exports response helper functions for creating MCP tool responses.
+ *
+ * @module mcp/responses
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Response Helpers (main entry points)
+// ─────────────────────────────────────────────────────────────────────────────
+export { text, json, error, image, audio, multi } from "./helpers.js";
+//# sourceMappingURL=index.js.map

package/build/mcp/responses/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/responses/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,gFAAgF;AAChF,uCAAuC;AACvC,gFAAgF;AAEhF,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC"}