mcp-use 0.1.20 → 0.3.0

package/dist/src/server/index.cjs

@@ -0,0 +1,566 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  McpServer: () => McpServer,
+  createMCPServer: () => createMCPServer
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/server/mcp-server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_zod = require("zod");
+var import_express = __toESM(require("express"), 1);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/server/logging.ts
+function requestLogger(req, res, next) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().substring(11, 23);
+  const method = req.method;
+  const url = req.url;
+  const originalEnd = res.end.bind(res);
+  res.end = function(chunk, encoding, cb) {
+    const statusCode = res.statusCode;
+    let statusColor = "";
+    if (statusCode >= 200 && statusCode < 300) {
+      statusColor = "\x1B[32m";
+    } else if (statusCode >= 300 && statusCode < 400) {
+      statusColor = "\x1B[33m";
+    } else if (statusCode >= 400 && statusCode < 500) {
+      statusColor = "\x1B[31m";
+    } else if (statusCode >= 500) {
+      statusColor = "\x1B[35m";
+    }
+    let logMessage = `[${timestamp}] ${method} \x1B[1m${url}\x1B[0m`;
+    if (method === "POST" && url === "/mcp" && req.body?.method) {
+      logMessage += ` \x1B[1m[${req.body.method}]\x1B[0m`;
+    }
+    logMessage += ` ${statusColor}${statusCode}\x1B[0m`;
+    console.log(logMessage);
+    return originalEnd(chunk, encoding, cb);
+  };
+  next();
+}
+__name(requestLogger, "requestLogger");
+
+// src/server/mcp-server.ts
+var McpServer = class {
+  static {
+    __name(this, "McpServer");
+  }
+  server;
+  config;
+  app;
+  mcpMounted = false;
+  inspectorMounted = false;
+  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) {
+    this.config = config;
+    this.server = new import_mcp.McpServer({
+      name: config.name,
+      version: config.version
+    });
+    this.app = (0, import_express.default)();
+    this.app.use((req, res, next) => {
+      res.header("Access-Control-Allow-Origin", "*");
+      res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+      res.header("Access-Control-Allow-Headers", "Content-Type");
+      next();
+    });
+    this.app.use(requestLogger);
+    this.setupWidgetRoutes();
+    return new Proxy(this, {
+      get(target, prop) {
+        if (prop in target) {
+          return target[prop];
+        }
+        const value = target.app[prop];
+        return typeof value === "function" ? value.bind(target.app) : value;
+      }
+    });
+  }
+  /**
+   * 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) {
+    this.server.resource(
+      resourceDefinition.name,
+      resourceDefinition.uri,
+      resourceDefinition.resource,
+      async () => {
+        return await resourceDefinition.fn();
+      }
+    );
+    return this;
+  }
+  /**
+   * Define a dynamic resource template with parameters
+   */
+  // TODO implement, for some freaky reason this give errors
+  // resourceTemplate(resourceTemplateDefinition: ResourceTemplateDefinition): this {
+  //   this.server.resource(
+  //     resourceTemplateDefinition.name,
+  //     resourceTemplateDefinition.resourceTemplate,
+  //     async (uri, params) => {
+  //       return await resourceTemplateDefinition.fn(uri, params)
+  //     },
+  //   )
+  //   return this
+  // }
+  /**
+   * 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) {
+    const inputSchema = this.createToolInputSchema(toolDefinition.inputs || []);
+    this.server.tool(
+      toolDefinition.name,
+      toolDefinition.description ?? "",
+      inputSchema,
+      async (params) => {
+        return await toolDefinition.fn(params);
+      }
+    );
+    return 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) {
+    const argsSchema = this.createPromptArgsSchema(promptDefinition.args || []);
+    this.server.prompt(
+      promptDefinition.name,
+      promptDefinition.description ?? "",
+      argsSchema,
+      async (params) => {
+        return await promptDefinition.fn(params);
+      }
+    );
+    return 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
+   */
+  async mountMcp() {
+    if (this.mcpMounted) return;
+    const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
+    const httpTransport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0
+      // Stateless mode
+    });
+    await this.server.connect(httpTransport);
+    const endpoint = "/mcp";
+    this.app.get(endpoint, async (req, res) => {
+      await httpTransport.handleRequest(req, res);
+    });
+    this.app.post(endpoint, import_express.default.json(), async (req, res) => {
+      await httpTransport.handleRequest(req, res, req.body);
+    });
+    this.app.delete(endpoint, async (req, res) => {
+      await httpTransport.handleRequest(req, res);
+    });
+    this.mcpMounted = true;
+    console.log(`[MCP] Server mounted at ${endpoint}`);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async listen(port) {
+    await this.mountMcp();
+    this.serverPort = port || 3001;
+    this.mountInspector();
+    this.app.listen(this.serverPort, () => {
+      console.log(`[SERVER] Listening on http://localhost:${this.serverPort}`);
+      console.log(`[MCP] Endpoints: http://localhost:${this.serverPort}/mcp`);
+    });
+  }
+  /**
+   * 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
+   */
+  mountInspector() {
+    if (this.inspectorMounted) return;
+    import("@mcp-use/inspector").then(({ mountInspector }) => {
+      const mcpServerUrl = `http://localhost:${this.serverPort}/mcp`;
+      mountInspector(this.app, "/inspector", mcpServerUrl);
+      this.inspectorMounted = true;
+      console.log(`[INSPECTOR] UI available at http://localhost:${this.serverPort}/inspector`);
+    }).catch(() => {
+    });
+  }
+  /**
+   * 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)
+   */
+  setupWidgetRoutes() {
+    this.app.get("/mcp-use/widgets/:widget/assets/*", (req, res, next) => {
+      const widget = req.params.widget;
+      const assetFile = req.params[0];
+      const assetPath = (0, import_node_path.join)(process.cwd(), "dist", "resources", "mcp-use", "widgets", widget, "assets", assetFile);
+      res.sendFile(assetPath, (err) => err ? next() : void 0);
+    });
+    this.app.get("/mcp-use/widgets/assets/*", (req, res, next) => {
+      const assetFile = req.params[0];
+      const widgetsDir = (0, import_node_path.join)(process.cwd(), "dist", "resources", "mcp-use", "widgets");
+      try {
+        const widgets = (0, import_node_fs.readdirSync)(widgetsDir);
+        for (const widget of widgets) {
+          const assetPath = (0, import_node_path.join)(widgetsDir, widget, "assets", assetFile);
+          if ((0, import_node_fs.existsSync)(assetPath)) {
+            return res.sendFile(assetPath);
+          }
+        }
+        next();
+      } catch {
+        next();
+      }
+    });
+    this.app.get("/mcp-use/widgets/:widget", (req, res, next) => {
+      const filePath = (0, import_node_path.join)(process.cwd(), "dist", "resources", "mcp-use", "widgets", req.params.widget, "index.html");
+      res.sendFile(filePath, (err) => err ? next() : void 0);
+    });
+  }
+  /**
+   * 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() }
+   * ```
+   */
+  createInputSchema(uriTemplate) {
+    const params = this.extractTemplateParams(uriTemplate);
+    const schema = {};
+    params.forEach((param) => {
+      schema[param] = import_zod.z.string();
+    });
+    return schema;
+  }
+  /**
+   * 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() }
+   * ```
+   */
+  createToolInputSchema(inputs) {
+    const schema = {};
+    inputs.forEach((input) => {
+      let zodType;
+      switch (input.type) {
+        case "string":
+          zodType = import_zod.z.string();
+          break;
+        case "number":
+          zodType = import_zod.z.number();
+          break;
+        case "boolean":
+          zodType = import_zod.z.boolean();
+          break;
+        case "object":
+          zodType = import_zod.z.object({});
+          break;
+        case "array":
+          zodType = import_zod.z.array(import_zod.z.any());
+          break;
+        default:
+          zodType = import_zod.z.any();
+      }
+      if (!input.required) {
+        zodType = zodType.optional();
+      }
+      schema[input.name] = zodType;
+    });
+    return schema;
+  }
+  /**
+   * 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() }
+   * ```
+   */
+  createPromptArgsSchema(inputs) {
+    const schema = {};
+    inputs.forEach((input) => {
+      let zodType;
+      switch (input.type) {
+        case "string":
+          zodType = import_zod.z.string();
+          break;
+        case "number":
+          zodType = import_zod.z.number();
+          break;
+        case "boolean":
+          zodType = import_zod.z.boolean();
+          break;
+        case "object":
+          zodType = import_zod.z.object({});
+          break;
+        case "array":
+          zodType = import_zod.z.array(import_zod.z.any());
+          break;
+        default:
+          zodType = import_zod.z.any();
+      }
+      if (!input.required) {
+        zodType = zodType.optional();
+      }
+      schema[input.name] = zodType;
+    });
+    return schema;
+  }
+  /**
+   * 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"]
+   * ```
+   */
+  extractTemplateParams(uriTemplate) {
+    const matches = uriTemplate.match(/\{([^}]+)\}/g);
+    return matches ? matches.map((match) => match.slice(1, -1)) : [];
+  }
+};
+function createMCPServer(name, config = {}) {
+  const instance = new McpServer({
+    name,
+    version: config.version || "1.0.0",
+    description: config.description
+  });
+  return instance;
+}
+__name(createMCPServer, "createMCPServer");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  McpServer,
+  createMCPServer
+});

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

@@ -0,0 +1,3 @@
+export { createMCPServer, McpServer } from './mcp-server.js';
+export type { InputDefinition, PromptDefinition, PromptHandler, ResourceDefinition, ResourceHandler, ServerConfig, ToolDefinition, ToolHandler, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC5D,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/dist/src/server/index.js

@@ -0,0 +1,9 @@
+import {
+  McpServer,
+  createMCPServer
+} from "../../chunk-JXLQRAW2.js";
+import "../../chunk-SHUYVCID.js";
+export {
+  McpServer,
+  createMCPServer
+};

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

@@ -0,0 +1,16 @@
+import type { Request, Response, NextFunction } from 'express';
+/**
+ * Request logging middleware with timestamp, colored status codes, and MCP method info
+ *
+ * Logs all HTTP requests with:
+ * - Timestamp in HH:MM:SS.mmm format
+ * - HTTP method and endpoint in bold
+ * - MCP method name in brackets for POST requests to /mcp
+ * - Color-coded status codes (green 2xx, yellow 3xx, red 4xx, magenta 5xx)
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ */
+export declare function requestLogger(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=logging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/server/logging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAkCnF"}