mcp-use 1.9.0 → 1.9.1-canary.0

package/dist/src/server/types/tool-context.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Tool Context Types
+ *
+ * Defines the context object and related types passed to tool callbacks.
+ * Provides access to sampling, elicitation, and progress reporting capabilities.
+ */
+import type { CreateMessageRequest, CreateMessageResult, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+/**
+ * Options for the sample() function in tool context.
+ */
+export interface SampleOptions {
+    /**
+     * Timeout in milliseconds for the sampling request.
+     * Default: no timeout (Infinity) - waits indefinitely for the LLM response.
+     * Set this if you want to limit how long to wait for sampling.
+     */
+    timeout?: number;
+    /**
+     * Interval in milliseconds between progress notifications.
+     * Default: 5000 (5 seconds).
+     * Progress notifications are sent to the client to prevent timeout
+     * when the client has resetTimeoutOnProgress enabled.
+     */
+    progressIntervalMs?: number;
+    /**
+     * Optional callback called each time a progress notification is sent.
+     * Useful for logging or custom progress handling.
+     */
+    onProgress?: (progress: {
+        progress: number;
+        total?: number;
+        message: string;
+    }) => void;
+    /**
+     * Maximum number of tokens to generate.
+     * Default: 1000 (when using string prompt shorthand).
+     * Only used when calling sample() with a string prompt.
+     */
+    maxTokens?: number;
+    /**
+     * Model preferences for sampling.
+     * Allows specifying which models to use via hints.
+     */
+    modelPreferences?: {
+        hints?: Array<{
+            name?: string;
+        }>;
+        costPriority?: number;
+        speedPriority?: number;
+        intelligencePriority?: number;
+    };
+    /**
+     * System prompt to prepend to the conversation.
+     */
+    systemPrompt?: string;
+    /**
+     * Temperature for sampling (0.0 to 1.0).
+     * Controls randomness in the response.
+     */
+    temperature?: number;
+    /**
+     * Stop sequences to end generation.
+     */
+    stopSequences?: string[];
+    /**
+     * Additional metadata to pass with the request.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for the elicit() function in tool context.
+ */
+export interface ElicitOptions {
+    /**
+     * Timeout in milliseconds for the elicitation request.
+     * Default: no timeout (Infinity) - waits indefinitely for user response.
+     * Set this if you want to limit how long to wait for user input.
+     *
+     * @example
+     * ```typescript
+     * // Wait indefinitely (default)
+     * await ctx.elicit(message, schema);
+     *
+     * // With 2 minute timeout
+     * await ctx.elicit(message, schema, { timeout: 120000 });
+     * ```
+     */
+    timeout?: number;
+}
+/**
+ * Parameters for form mode elicitation.
+ * Used to request structured data from users with optional JSON schema validation.
+ */
+export interface ElicitFormParams {
+    /** Human-readable message explaining why the information is needed */
+    message: string;
+    /** JSON Schema defining the structure of the expected response */
+    requestedSchema: Record<string, any>;
+    /** Mode specifier (optional for backwards compatibility, defaults to "form") */
+    mode?: "form";
+}
+/**
+ * Parameters for URL mode elicitation.
+ * Used to direct users to external URLs for sensitive interactions.
+ * MUST be used for interactions involving sensitive information like credentials.
+ */
+export interface ElicitUrlParams {
+    /** Human-readable message explaining why the interaction is needed */
+    message: string;
+    /** URL for the user to navigate to */
+    url: string;
+    /** Mode specifier (required for URL mode) */
+    mode: "url";
+}
+/**
+ * Context object passed to tool callbacks.
+ * Provides access to sampling, elicitation, and progress reporting capabilities.
+ */
+export interface ToolContext {
+    /**
+     * Request sampling from the client's LLM with automatic progress notifications.
+     *
+     * Supports two calling patterns:
+     * 1. **Simplified string API**: Pass a prompt string with optional options
+     * 2. **Full control API**: Pass complete CreateMessageRequest params
+     *
+     * Progress notifications are sent every 5 seconds (configurable) while waiting
+     * for the sampling response. This prevents client-side timeouts when the client
+     * has `resetTimeoutOnProgress: true` enabled.
+     *
+     * By default, there is no timeout - the function waits indefinitely for the
+     * LLM response. Set `options.timeout` to limit the wait time.
+     *
+     * @param promptOrParams - Either a string prompt or complete sampling parameters
+     * @param options - Optional configuration for timeout, progress, maxTokens, etc.
+     * @returns The sampling result from the client's LLM
+     *
+     * @example
+     * ```typescript
+     * // Simplified API - just pass a string prompt
+     * const result = await ctx.sample("What is the capital of France?");
+     *
+     * // With options (maxTokens, temperature, etc.)
+     * const result = await ctx.sample(
+     *   "Analyze this code...",
+     *   { maxTokens: 2000, temperature: 0.7 }
+     * );
+     *
+     * // Full control API - complete params object
+     * const result = await ctx.sample({
+     *   messages: [
+     *     { role: 'system', content: { type: 'text', text: 'You are helpful' } },
+     *     { role: 'user', content: { type: 'text', text: 'Hello' } }
+     *   ],
+     *   maxTokens: 1500,
+     *   modelPreferences: { hints: [{ name: 'claude-3-5-sonnet' }] }
+     * });
+     *
+     * // With timeout and custom progress handling
+     * const result = await ctx.sample(
+     *   "Complex task...",
+     *   {
+     *     timeout: 120000, // 2 minute timeout
+     *     progressIntervalMs: 3000, // Report progress every 3 seconds
+     *     onProgress: ({ progress, message }) => console.log(message),
+     *   }
+     * );
+     * ```
+     */
+    sample: {
+        (prompt: string, options?: SampleOptions): Promise<CreateMessageResult>;
+        (params: CreateMessageRequest["params"], options?: SampleOptions): Promise<CreateMessageResult>;
+    };
+    /**
+     * Request user input via the client through elicitation.
+     *
+     * Supports two modes with automatic mode detection:
+     * - **Form mode**: Pass a Zod schema as second parameter - collects structured data
+     * - **URL mode**: Pass a URL string as second parameter - directs to external URL
+     * - **Verbose mode**: Pass an object with explicit mode for backwards compatibility
+     *
+     * By default, there is no timeout - waits indefinitely for user response.
+     * Set `options.timeout` to limit the wait time.
+     *
+     * @example
+     * ```typescript
+     * // Form mode (simplified) - automatically inferred from Zod schema
+     * const result = await ctx.elicit(
+     *   "Please provide your information",
+     *   z.object({
+     *     name: z.string().default("Anonymous"),
+     *     age: z.number().default(0)
+     *   })
+     * );
+     * // result.data is typed as { name: string, age: number }
+     *
+     * // With timeout
+     * const result = await ctx.elicit(
+     *   "Enter info",
+     *   z.object({ name: z.string() }),
+     *   { timeout: 60000 } // 1 minute timeout
+     * );
+     *
+     * // URL mode (simplified) - automatically inferred from URL string
+     * const authResult = await ctx.elicit(
+     *   "Please authorize access",
+     *   "https://example.com/oauth/authorize"
+     * );
+     *
+     * // Verbose API (backwards compatible)
+     * const verboseResult = await ctx.elicit({
+     *   message: "Please provide your information",
+     *   requestedSchema: { type: "object", properties: {...} },
+     *   mode: "form"
+     * });
+     * ```
+     */
+    elicit: {
+        <T extends z.ZodObject<any>>(message: string, schema: T, options?: ElicitOptions): Promise<ElicitResult & {
+            data: z.infer<T>;
+        }>;
+        (message: string, url: string, options?: ElicitOptions): Promise<ElicitResult>;
+        (params: ElicitFormParams | ElicitUrlParams, options?: ElicitOptions): Promise<ElicitResult>;
+    };
+    /**
+     * Send a progress notification to the client.
+     * Only available if the client requested progress updates for this tool call.
+     *
+     * @param progress - Current progress value (should increase with each call)
+     * @param total - Total progress value if known
+     * @param message - Optional message describing current progress
+     */
+    reportProgress?: (progress: number, total?: number, message?: string) => Promise<void>;
+}
+//# sourceMappingURL=tool-context.d.ts.map

package/dist/src/server/types/tool-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../../../src/server/types/tool-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACb,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,KAAK,IAAI,CAAC;IAEX;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE;QACjB,KAAK,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;IAEF;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,IAAI,EAAE,KAAK,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,MAAM,EAAE;QAEN,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAGxE,CACE,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACtC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAAC;KACjC,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,EAAE;QAEN,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,GAAG;YAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;SAAE,CAAC,CAAC;QAGhD,CACE,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;QAGzB,CACE,MAAM,EAAE,gBAAgB,GAAG,eAAe,EAC1C,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;KAC1B,CAAC;IAEF;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB"}

package/dist/src/server/types/tool.d.ts

@@ -1,6 +1,6 @@
 import type { InputDefinition } from "./common.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { ToolContext } from "../mcp-server.js";
+import type { ToolContext } from "./tool-context.js";
 import type { McpContext } from "./context.js";
 import type { z } from "zod";
 import type { TypedCallToolResult } from "../utils/response-helpers.js";
@@ -18,9 +18,12 @@ import type { TypedCallToolResult } from "../utils/response-helpers.js";
  */
 export type EnhancedToolContext<HasOAuth extends boolean = false> = ToolContext & McpContext<HasOAuth>;
 /**
- * Callback function for tool execution.
+ * Callback function interface for tool execution.
  *
- * Accepts input parameters and an enhanced context object that provides:
+ * Uses method signature syntax to enable bivariant parameter checking,
+ * which allows more flexible destructuring patterns for optional fields.
+ *
+ * Accepts input parameters and an optional enhanced context object that provides:
  * - LLM sampling via `ctx.sample()`
  * - Progress reporting via `ctx.reportProgress()`
  * - Authentication info via `ctx.auth` (when OAuth is configured)
@@ -52,14 +55,67 @@ export type EnhancedToolContext<HasOAuth extends boolean = false> = ToolContext
  * }
  * ```
  */
-export type ToolCallback<TInput = Record<string, any>, TOutput extends Record<string, unknown> = Record<string, unknown>, HasOAuth extends boolean = false> = ((params: TInput) => Promise<TypedCallToolResult<TOutput>>) | ((params: TInput, ctx: EnhancedToolContext<HasOAuth>) => Promise<TypedCallToolResult<TOutput>>);
+/**
+ * Helper interface that uses method signature syntax to enable bivariant parameter checking.
+ * This allows more flexible callback assignments where users can destructure optional fields
+ * without explicitly marking them as optional in their function signature.
+ *
+ * @internal
+ */
+interface ToolCallbackBivariant<TInput, TOutput extends Record<string, unknown>, HasOAuth extends boolean> {
+    bivarianceHack(params: TInput, ctx: EnhancedToolContext<HasOAuth>): Promise<TypedCallToolResult<TOutput>>;
+}
+/**
+ * Callback function type for tool execution.
+ *
+ * Uses bivariant parameter checking via method signature extraction,
+ * which allows more flexible destructuring patterns for optional fields.
+ *
+ * Accepts input parameters and an enhanced context object that provides:
+ * - LLM sampling via `ctx.sample()`
+ * - Progress reporting via `ctx.reportProgress()`
+ * - Elicitation via `ctx.elicit()`
+ * - Authentication info via `ctx.auth` (when OAuth is configured)
+ * - HTTP request via `ctx.req`
+ * - All Hono Context properties and methods
+ *
+ * @template TInput - Input parameters type
+ * @template TOutput - Output type (constrains the structuredContent property when outputSchema is defined)
+ * @template HasOAuth - Whether OAuth is configured (affects ctx.auth availability)
+ *
+ * @example
+ * ```typescript
+ * // Simple tool without context
+ * async ({ name }) => ({
+ *   content: [{ type: 'text', text: `Hello, ${name}!` }]
+ * })
+ *
+ * // Tool with sampling and context
+ * async ({ text }, ctx) => {
+ *   const result = await ctx.sample({
+ *     messages: [{ role: 'user', content: { type: 'text', text } }]
+ *   });
+ *   return { content: result.content };
+ * }
+ *
+ * // Tool with authentication
+ * async ({ userId }, ctx) => {
+ *   return { content: [{ type: 'text', text: `User: ${ctx.auth.user.email}` }] };
+ * }
+ * ```
+ */
+export type ToolCallback<TInput = Record<string, any>, TOutput extends Record<string, unknown> = Record<string, unknown>, HasOAuth extends boolean = false> = ToolCallbackBivariant<TInput, TOutput, HasOAuth>["bivarianceHack"];
 /**
  * Generic callback with full context support for better type inference.
  * This variant always requires the context parameter.
  */
 export type ToolCallbackWithContext<TInput = Record<string, any>, TOutput extends Record<string, unknown> = Record<string, unknown>, HasOAuth extends boolean = false> = (params: TInput, ctx: EnhancedToolContext<HasOAuth>) => Promise<TypedCallToolResult<TOutput>>;
 /**
- * Extract input type from a tool definition's schema
+ * Extract input type from a tool definition's schema.
+ * Uses z.infer which preserves Zod's optional/default handling.
+ *
+ * For .optional() fields, the type will be T | undefined
+ * For .default() fields, the type will be T (since Zod guarantees a value)
  */
 export type InferToolInput<T> = T extends {
     schema: infer S;
@@ -115,4 +171,5 @@ export interface ToolDefinition<TInput = Record<string, any>, TOutput extends Re
     /** Metadata for the tool */
     _meta?: Record<string, unknown>;
 }
+export {};
 //# sourceMappingURL=tool.d.ts.map

package/dist/src/server/types/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../src/server/types/tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../src/server/types/tool.ts"],"names":[],"mappings":"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"}

package/dist/src/server/utils/hono-proxy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hono Proxy Utilities
+ *
+ * Utilities for creating proxied instances that allow direct access to Hono methods
+ * while preserving server functionality.
+ */
+import type { Hono as HonoType } from "hono";
+/**
+ * Create a proxy that allows direct access to Hono methods
+ *
+ * Creates a Proxy wrapper that:
+ * - Auto-detects and adapts Express middleware to Hono
+ * - Proxies all Hono methods to the underlying app
+ * - Preserves the target instance's own methods and properties
+ *
+ * @param target - The target instance to proxy
+ * @param app - The Hono app instance
+ * @returns Proxied instance with both target and Hono methods
+ */
+export declare function createHonoProxy<T extends object>(target: T, app: HonoType): T & HonoType;
+//# sourceMappingURL=hono-proxy.d.ts.map

package/dist/src/server/utils/hono-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono-proxy.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/hono-proxy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,MAAM,CAAC;AAM7C;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,QAAQ,GACZ,CAAC,GAAG,QAAQ,CAqEd"}

package/dist/src/server/utils/index.d.ts

@@ -3,4 +3,7 @@
  */
 export * from "./response-helpers.js";
 export * from "./runtime.js";
+export * from "./server-helpers.js";
+export * from "./server-lifecycle.js";
+export * from "./hono-proxy.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/server/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC"}

package/dist/src/server/utils/jsonrpc-helpers.d.ts

@@ -0,0 +1,94 @@
+/**
+ * JSON-RPC Helper Utilities
+ *
+ * Common utilities for creating JSON-RPC notifications, requests, and error responses.
+ */
+/**
+ * JSON-RPC notification object structure
+ */
+export interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * JSON-RPC request object structure
+ */
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * JSON-RPC error response object structure
+ */
+export interface JsonRpcError {
+    jsonrpc: "2.0";
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id: string | number | null;
+}
+/**
+ * Create a JSON-RPC notification object
+ *
+ * Notifications are one-way messages that don't expect a response.
+ *
+ * @param method - The notification method name
+ * @param params - Optional parameters to include in the notification
+ * @returns JSON-RPC notification object
+ *
+ * @example
+ * ```typescript
+ * const notification = createNotification("notifications/resources/list_changed");
+ * const notificationWithParams = createNotification("custom/alert", { message: "Hello" });
+ * ```
+ */
+export declare function createNotification(method: string, params?: Record<string, unknown>): JsonRpcNotification;
+/**
+ * Create a JSON-RPC request object
+ *
+ * Requests are two-way messages that expect a response.
+ *
+ * @param id - Unique request identifier
+ * @param method - The request method name
+ * @param params - Optional parameters to include in the request
+ * @returns JSON-RPC request object
+ *
+ * @example
+ * ```typescript
+ * const request = createRequest("123", "roots/list", {});
+ * ```
+ */
+export declare function createRequest(id: string | number, method: string, params?: Record<string, unknown>): JsonRpcRequest;
+/**
+ * Create a JSON-RPC error response object
+ *
+ * @param code - Error code (e.g., -32000 for application errors)
+ * @param message - Human-readable error message
+ * @param id - Request ID (null if error occurred before ID could be determined)
+ * @param data - Optional additional error data
+ * @returns JSON-RPC error response object
+ *
+ * @example
+ * ```typescript
+ * const error = createJsonRpcError(-32000, "Session not found", "123");
+ * const errorNoId = createJsonRpcError(-32600, "Invalid Request", null);
+ * ```
+ */
+export declare function createJsonRpcError(code: number, message: string, id?: string | number | null, data?: unknown): JsonRpcError;
+/**
+ * Common JSON-RPC error codes
+ */
+export declare const JsonRpcErrorCode: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly APPLICATION_ERROR: -32000;
+};
+//# sourceMappingURL=jsonrpc-helpers.d.ts.map

package/dist/src/server/utils/jsonrpc-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc-helpers.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/jsonrpc-helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,mBAAmB,CAMrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,cAAc,CAOhB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,MAAM,GAAG,MAAM,GAAG,IAAW,EACjC,IAAI,CAAC,EAAE,OAAO,GACb,YAAY,CAUd;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;CAQnB,CAAC"}

package/dist/src/server/utils/response-helpers.d.ts

@@ -8,23 +8,30 @@ export interface TypedCallToolResult<T extends Record<string, unknown> = Record<
     structuredContent?: T;
 }
 /**
- * Create a text content response for MCP tools
+ * Create a text content response for MCP tools and resources
  *
  * @param content - The text content to return
  * @returns CallToolResult with text content
  *
  * @example
  * ```typescript
+ * // For tools
  * server.tool({
  *   name: 'greet',
  *   schema: z.object({ name: z.string() }),
  *   cb: async ({ name }) => text(`Hello, ${name}!`)
  * })
+ *
+ * // For resources
+ * server.resource(
+ *   { name: 'greeting', uri: 'app://greeting' },
+ *   async () => text('Hello World!')
+ * )
  * ```
  */
 export declare function text(content: string): CallToolResult;
 /**
- * Create an image content response for MCP tools
+ * Create an image content response for MCP tools and resources
  *
  * @param data - The image data (data URL or base64)
  * @param mimeType - MIME type (e.g., 'image/png', defaults to 'image/png')
@@ -32,10 +39,17 @@ export declare function text(content: string): CallToolResult;
  *
  * @example
  * ```typescript
+ * // For tools
  * server.tool({
  *   name: 'generate-image',
  *   cb: async () => image('data:image/png;base64,...', 'image/png')
  * })
+ *
+ * // For resources
+ * server.resource(
+ *   { name: 'logo', uri: 'asset://logo' },
+ *   async () => image(base64Data, 'image/png')
+ * )
  * ```
  */
 export declare function image(data: string, mimeType?: string): CallToolResult;
@@ -77,13 +91,14 @@ export declare function resource(uri: string, mimeType?: string, text?: string):
  */
 export declare function error(message: string): CallToolResult;
 /**
- * Create a JSON object response for MCP tools
+ * Create a JSON object response for MCP tools and resources
  *
  * @param data - The object to return as JSON
  * @returns TypedCallToolResult with JSON text content and typed structuredContent
  *
  * @example
  * ```typescript
+ * // For tools
  * server.tool({
  *   name: 'get-user-info',
  *   cb: async (_args, _ctx, { auth }) => object({
@@ -91,12 +106,109 @@ export declare function error(message: string): CallToolResult;
  *     email: auth.user.email
  *   })
  * })
+ *
+ * // For resources
+ * server.resource(
+ *   { name: 'config', uri: 'config://settings' },
+ *   async () => object({ theme: 'dark', version: '1.0' })
+ * )
  * ```
  */
 export declare function object<T extends Record<string, any>>(data: T): TypedCallToolResult<T>;
 export declare function array<T extends any[]>(data: T): TypedCallToolResult<{
     data: T;
 }>;
+/**
+ * Create an HTML content response for MCP tools and resources
+ *
+ * @param content - The HTML content to return
+ * @returns CallToolResult with HTML text content and MIME type metadata
+ *
+ * @example
+ * ```typescript
+ * server.resource(
+ *   { name: 'page', uri: 'ui://dashboard' },
+ *   async () => html('<h1>Dashboard</h1><p>Welcome</p>')
+ * )
+ * ```
+ */
+export declare function html(content: string): CallToolResult;
+/**
+ * Create a Markdown content response for MCP tools and resources
+ *
+ * @param content - The Markdown content to return
+ * @returns CallToolResult with Markdown text content and MIME type metadata
+ *
+ * @example
+ * ```typescript
+ * server.resource(
+ *   { name: 'readme', uri: 'doc://readme' },
+ *   async () => markdown('# Welcome\n\nGetting started...')
+ * )
+ * ```
+ */
+export declare function markdown(content: string): CallToolResult;
+/**
+ * Create an XML content response for MCP tools and resources
+ *
+ * @param content - The XML content to return
+ * @returns CallToolResult with XML text content and MIME type metadata
+ *
+ * @example
+ * ```typescript
+ * server.resource(
+ *   { name: 'sitemap', uri: 'data://sitemap' },
+ *   async () => xml('<?xml version="1.0"?><root>...</root>')
+ * )
+ * ```
+ */
+export declare function xml(content: string): CallToolResult;
+/**
+ * Create a CSS content response for MCP tools and resources
+ *
+ * @param content - The CSS content to return
+ * @returns CallToolResult with CSS text content and MIME type metadata
+ *
+ * @example
+ * ```typescript
+ * server.resource(
+ *   { name: 'styles', uri: 'asset://theme.css' },
+ *   async () => css('body { margin: 0; }')
+ * )
+ * ```
+ */
+export declare function css(content: string): CallToolResult;
+/**
+ * Create a JavaScript content response for MCP tools and resources
+ *
+ * @param content - The JavaScript content to return
+ * @returns CallToolResult with JavaScript text content and MIME type metadata
+ *
+ * @example
+ * ```typescript
+ * server.resource(
+ *   { name: 'script', uri: 'asset://main.js' },
+ *   async () => javascript('console.log("Hello");')
+ * )
+ * ```
+ */
+export declare function javascript(content: string): CallToolResult;
+/**
+ * Create a binary content response for MCP tools and resources
+ *
+ * @param base64Data - The base64-encoded binary data
+ * @param mimeType - The MIME type of the binary content
+ * @returns CallToolResult with binary content and MIME type metadata
+ *
+ * @example
+ * ```typescript
+ * server.resource(
+ *   { name: 'document', uri: 'file://document.pdf' },
+ *   async () => binary(base64PdfData, 'application/pdf')
+ * )
+ * ```
+ */
+export declare function binary(base64Data: string, mimeType: string): CallToolResult;
 /**
  * Configuration for widget response utility
  */