mcp-use 0.2.0 → 1.0.0

package/dist/src/server/mcp-server.d.ts

@@ -0,0 +1,282 @@
+import type { PromptDefinition, ResourceDefinition, ServerConfig, ToolDefinition } from './types.js';
+import { type Express } from 'express';
+export declare class McpServer {
+    private server;
+    private config;
+    private app;
+    private mcpMounted;
+    private inspectorMounted;
+    private serverPort?;
+    /**
+     * Creates a new MCP server instance with Express integration
+     *
+     * Initializes the server with the provided configuration, sets up CORS headers,
+     * configures widget serving routes, and creates a proxy that allows direct
+     * access to Express methods while preserving MCP server functionality.
+     *
+     * @param config - Server configuration including name, version, and description
+     * @returns A proxied McpServer instance that supports both MCP and Express methods
+     */
+    constructor(config: ServerConfig);
+    /**
+     * Define a static resource that can be accessed by clients
+     *
+     * Registers a resource with the MCP server that clients can access via HTTP.
+     * Resources are static content like files, data, or pre-computed results that
+     * can be retrieved by clients without requiring parameters.
+     *
+     * @param resourceDefinition - Configuration object containing resource metadata and handler function
+     * @param resourceDefinition.name - Unique identifier for the resource
+     * @param resourceDefinition.uri - URI pattern for accessing the resource
+     * @param resourceDefinition.resource - Resource metadata (mime type, description, etc.)
+     * @param resourceDefinition.fn - Async function that returns the resource content
+     * @returns The server instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * server.resource({
+     *   name: 'config',
+     *   uri: 'config://app-settings',
+     *   resource: { mimeType: 'application/json' },
+     *   fn: async () => ({ theme: 'dark', language: 'en' })
+     * })
+     * ```
+     */
+    resource(resourceDefinition: ResourceDefinition): this;
+    /**
+     * Define a dynamic resource template with parameters
+     */
+    /**
+     * Define a tool that can be called by clients
+     *
+     * Registers a tool with the MCP server that clients can invoke with parameters.
+     * Tools are functions that perform actions, computations, or operations and
+     * return results. They accept structured input parameters and return structured output.
+     *
+     * @param toolDefinition - Configuration object containing tool metadata and handler function
+     * @param toolDefinition.name - Unique identifier for the tool
+     * @param toolDefinition.description - Human-readable description of what the tool does
+     * @param toolDefinition.inputs - Array of input parameter definitions with types and validation
+     * @param toolDefinition.fn - Async function that executes the tool logic with provided parameters
+     * @returns The server instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * server.tool({
+     *   name: 'calculate',
+     *   description: 'Performs mathematical calculations',
+     *   inputs: [
+     *     { name: 'expression', type: 'string', required: true },
+     *     { name: 'precision', type: 'number', required: false }
+     *   ],
+     *   fn: async ({ expression, precision = 2 }) => {
+     *     const result = eval(expression)
+     *     return { result: Number(result.toFixed(precision)) }
+     *   }
+     * })
+     * ```
+     */
+    tool(toolDefinition: ToolDefinition): this;
+    /**
+     * Define a prompt template
+     *
+     * Registers a prompt template with the MCP server that clients can use to generate
+     * structured prompts for AI models. Prompt templates accept parameters and return
+     * formatted text that can be used as input to language models or other AI systems.
+     *
+     * @param promptDefinition - Configuration object containing prompt metadata and handler function
+     * @param promptDefinition.name - Unique identifier for the prompt template
+     * @param promptDefinition.description - Human-readable description of the prompt's purpose
+     * @param promptDefinition.args - Array of argument definitions with types and validation
+     * @param promptDefinition.fn - Async function that generates the prompt from provided arguments
+     * @returns The server instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * server.prompt({
+     *   name: 'code-review',
+     *   description: 'Generates a code review prompt',
+     *   args: [
+     *     { name: 'language', type: 'string', required: true },
+     *     { name: 'focus', type: 'string', required: false }
+     *   ],
+     *   fn: async ({ language, focus = 'general' }) => {
+     *     return {
+     *       messages: [{
+     *         role: 'user',
+     *         content: `Please review this ${language} code with focus on ${focus}...`
+     *       }]
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    prompt(promptDefinition: PromptDefinition): this;
+    /**
+     * Mount MCP server endpoints at /mcp
+     *
+     * Sets up the HTTP transport layer for the MCP server, creating endpoints for
+     * Server-Sent Events (SSE) streaming, POST message handling, and DELETE session cleanup.
+     * Uses stateless mode for session management, making it suitable for stateless deployments.
+     *
+     * This method is called automatically when the server starts listening and ensures
+     * that MCP clients can communicate with the server over HTTP.
+     *
+     * @private
+     * @returns Promise that resolves when MCP endpoints are successfully mounted
+     *
+     * @example
+     * Endpoints created:
+     * - GET /mcp - SSE streaming endpoint for real-time communication
+     * - POST /mcp - Message handling endpoint for MCP protocol messages
+     * - DELETE /mcp - Session cleanup endpoint
+     */
+    private mountMcp;
+    /**
+     * Start the Express server with MCP endpoints
+     *
+     * Initiates the server startup process by mounting MCP endpoints, configuring
+     * the inspector UI (if available), and starting the Express server to listen
+     * for incoming connections. This is the main entry point for running the server.
+     *
+     * The server will be accessible at the specified port with MCP endpoints at /mcp
+     * and inspector UI at /inspector (if the inspector package is installed).
+     *
+     * @param port - Port number to listen on (defaults to 3001 if not specified)
+     * @returns Promise that resolves when the server is successfully listening
+     *
+     * @example
+     * ```typescript
+     * await server.listen(8080)
+     * // Server now running at http://localhost:8080
+     * // MCP endpoints: http://localhost:8080/mcp
+     * // Inspector UI: http://localhost:8080/inspector
+     * ```
+     */
+    listen(port?: number): Promise<void>;
+    /**
+     * Mount MCP Inspector UI at /inspector
+     *
+     * Dynamically loads and mounts the MCP Inspector UI package if available, providing
+     * a web-based interface for testing and debugging MCP servers. The inspector
+     * automatically connects to the local MCP server endpoints.
+     *
+     * This method gracefully handles cases where the inspector package is not installed,
+     * allowing the server to function without the inspector in production environments.
+     *
+     * @private
+     * @returns void
+     *
+     * @example
+     * If @mcp-use/inspector is installed:
+     * - Inspector UI available at http://localhost:PORT/inspector
+     * - Automatically connects to http://localhost:PORT/mcp
+     *
+     * If not installed:
+     * - Server continues to function normally
+     * - No inspector UI available
+     */
+    private mountInspector;
+    /**
+     * Setup default widget serving routes
+     *
+     * Configures Express routes to serve MCP UI widgets and their static assets.
+     * Widgets are served from the dist/resources/mcp-use/widgets directory and can
+     * be accessed via HTTP endpoints for embedding in web applications.
+     *
+     * Routes created:
+     * - GET /mcp-use/widgets/:widget - Serves widget's index.html
+     * - GET /mcp-use/widgets/:widget/assets/* - Serves widget-specific assets
+     * - GET /mcp-use/widgets/assets/* - Fallback asset serving with auto-discovery
+     *
+     * @private
+     * @returns void
+     *
+     * @example
+     * Widget routes:
+     * - http://localhost:3001/mcp-use/widgets/kanban-board
+     * - http://localhost:3001/mcp-use/widgets/todo-list/assets/style.css
+     * - http://localhost:3001/mcp-use/widgets/assets/script.js (auto-discovered)
+     */
+    private setupWidgetRoutes;
+    /**
+     * Create input schema for resource templates
+     *
+     * Parses a URI template string to extract parameter names and generates a Zod
+     * validation schema for those parameters. Used internally for validating resource
+     * template parameters before processing requests.
+     *
+     * @param uriTemplate - URI template string with parameter placeholders (e.g., "/users/{id}/posts/{postId}")
+     * @returns Object mapping parameter names to Zod string schemas
+     *
+     * @example
+     * ```typescript
+     * const schema = this.createInputSchema("/users/{id}/posts/{postId}")
+     * // Returns: { id: z.string(), postId: z.string() }
+     * ```
+     */
+    private createInputSchema;
+    /**
+     * Create input schema for tools
+     *
+     * Converts tool input definitions into Zod validation schemas for runtime validation.
+     * Supports common data types (string, number, boolean, object, array) and optional
+     * parameters. Used internally when registering tools with the MCP server.
+     *
+     * @param inputs - Array of input parameter definitions with name, type, and optional flag
+     * @returns Object mapping parameter names to Zod validation schemas
+     *
+     * @example
+     * ```typescript
+     * const schema = this.createToolInputSchema([
+     *   { name: 'query', type: 'string', required: true },
+     *   { name: 'limit', type: 'number', required: false }
+     * ])
+     * // Returns: { query: z.string(), limit: z.number().optional() }
+     * ```
+     */
+    private createToolInputSchema;
+    /**
+     * Create arguments schema for prompts
+     *
+     * Converts prompt argument definitions into Zod validation schemas for runtime validation.
+     * Supports common data types (string, number, boolean, object, array) and optional
+     * parameters. Used internally when registering prompt templates with the MCP server.
+     *
+     * @param inputs - Array of argument definitions with name, type, and optional flag
+     * @returns Object mapping argument names to Zod validation schemas
+     *
+     * @example
+     * ```typescript
+     * const schema = this.createPromptArgsSchema([
+     *   { name: 'topic', type: 'string', required: true },
+     *   { name: 'style', type: 'string', required: false }
+     * ])
+     * // Returns: { topic: z.string(), style: z.string().optional() }
+     * ```
+     */
+    private createPromptArgsSchema;
+    /**
+     * Extract parameter names from URI template
+     *
+     * Parses a URI template string to extract parameter names enclosed in curly braces.
+     * Used internally to identify dynamic parameters in resource templates and generate
+     * appropriate validation schemas.
+     *
+     * @param uriTemplate - URI template string with parameter placeholders (e.g., "/users/{id}/posts/{postId}")
+     * @returns Array of parameter names found in the template
+     *
+     * @example
+     * ```typescript
+     * const params = this.extractTemplateParams("/users/{id}/posts/{postId}")
+     * // Returns: ["id", "postId"]
+     * ```
+     */
+    private extractTemplateParams;
+}
+export type McpServerInstance = Omit<McpServer, keyof Express> & Express;
+/**
+ * Create a new MCP server instance
+ */
+export declare function createMCPServer(name: string, config?: Partial<ServerConfig>): McpServerInstance;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/src/server/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../../src/server/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAA;AAGnB,OAAgB,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAK/C,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,UAAU,CAAC,CAAQ;IAE3B;;;;;;;;;OASG;gBACS,MAAM,EAAE,YAAY;IAmChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,GAAG,IAAI;IAYtD;;OAEG;IAaH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,IAAI,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI;IAa1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI;IAahD;;;;;;;;;;;;;;;;;;OAkBG;YACW,QAAQ;IAkCtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,cAAc;IAqBtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,iBAAiB;IAsCzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,qBAAqB;IAmC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,sBAAsB;IAmC9B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,qBAAqB;CAI9B;AAED,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,GAAG,OAAO,CAAA;AAExE;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,iBAAiB,CAOnG"}

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

@@ -0,0 +1,47 @@
+import type { CallToolResult, GetPromptResult, ReadResourceResult, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
+export interface ServerConfig {
+    name: string;
+    version: string;
+    description?: string;
+}
+export interface InputDefinition {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description?: string;
+    required?: boolean;
+    default?: any;
+}
+export interface ResourceTemplateDefinition {
+    name: string;
+    resourceTemplate: ResourceTemplate;
+    title?: string;
+    description?: string;
+    fn: ResourceTemplateHandler;
+}
+export interface ResourceDefinition {
+    name: string;
+    uri: string;
+    resource: {
+        title?: string;
+        description?: string;
+        mimeType: string;
+    };
+    fn: ResourceHandler;
+}
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    inputs?: InputDefinition[];
+    fn: ToolHandler;
+}
+export interface PromptDefinition {
+    name: string;
+    description?: string;
+    args?: InputDefinition[];
+    fn: PromptHandler;
+}
+export type ResourceHandler = () => Promise<ReadResourceResult>;
+export type ResourceTemplateHandler = (uri: URL, params: Record<string, any>) => Promise<ReadResourceResult>;
+export type ToolHandler = (params: Record<string, any>) => Promise<CallToolResult>;
+export type PromptHandler = (params: Record<string, any>) => Promise<GetPromptResult>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAC,MAAM,oCAAoC,CAAA;AAC9H,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,GAAG,CAAA;CACd;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,EAAE,EAAE,uBAAuB,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,EAAE,EAAE,eAAe,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;IAC1B,EAAE,EAAE,WAAW,CAAA;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;IACxB,EAAE,EAAE,aAAa,CAAA;CAClB;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAA;AAC/D,MAAM,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;AAC5G,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;AAClF,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA"}

package/dist/src/utils/assert.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Asserts that a condition is true, throwing an error if not.
+ * Useful for type narrowing.
+ * @param condition The condition to check.
+ * @param message The error message to throw if the condition is false.
+ */
+export declare function assert(condition: unknown, message: string): asserts condition;
+//# sourceMappingURL=assert.d.ts.map

package/dist/src/utils/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../../src/utils/assert.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAI7E"}