chore: docstrings

Author: pietrozullo

packages/mcp-use/src/server/mcp-server.ts

@@ -18,6 +18,16 @@ export class McpServer {
   private inspectorMounted = false
   private serverPort?: number
 
+  /**
+   * 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) {
     this.config = config
     this.server = new OfficialMcpServer({
@@ -52,6 +62,27 @@ export class McpServer {
 
   /**
    * 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 {
     this.server.resource(
@@ -82,6 +113,33 @@ export class McpServer {
 
   /**
    * 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 {
     const inputSchema = this.createToolInputSchema(toolDefinition.inputs || [])
@@ -98,6 +156,37 @@ export class McpServer {
 
   /**
    * 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 {
     const argsSchema = this.createPromptArgsSchema(promptDefinition.args || [])
@@ -114,6 +203,22 @@ export class McpServer {
 
   /**
    * 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 async mountMcp(): Promise<void> {
     if (this.mcpMounted) return
@@ -154,7 +259,24 @@ export class McpServer {
 
   /**
    * Start the Express server with MCP endpoints
-   * @param port - Port to listen on (defaults to 3001)
+   * 
+   * 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?: number): Promise<void> {
     await this.mountMcp()
@@ -171,6 +293,25 @@ export class McpServer {
 
   /**
    * 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(): void {
     if (this.inspectorMounted) return
@@ -193,6 +334,24 @@ export class McpServer {
 
   /**
    * 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(): void {
     // Serve static assets (JS, CSS) from the assets directory
@@ -234,6 +393,19 @@ export class McpServer {
 
   /**
    * 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(uriTemplate: string): Record<string, z.ZodSchema> {
     const params = this.extractTemplateParams(uriTemplate)
@@ -248,6 +420,22 @@ export class McpServer {
 
   /**
    * 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(inputs: Array<{ name: string, type: string, required?: boolean }>): Record<string, z.ZodSchema> {
     const schema: Record<string, z.ZodSchema> = {}
@@ -286,6 +474,22 @@ export class McpServer {
 
   /**
    * 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(inputs: Array<{ name: string, type: string, required?: boolean }>): Record<string, z.ZodSchema> {
     const schema: Record<string, z.ZodSchema> = {}
@@ -324,6 +528,19 @@ export class McpServer {
 
   /**
    * 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(uriTemplate: string): string[] {
     const matches = uriTemplate.match(/\{([^}]+)\}/g)
@@ -332,15 +549,3 @@ export class McpServer {
 }
 
 export type McpServerInstance = Omit<McpServer, keyof Express> & Express
-
-/**
- * Create a new MCP server instance
- */
-export function createMCPServer(name: string, config: Partial<ServerConfig> = {}): McpServerInstance {
-  const instance = new McpServer({
-    name,
-    version: config.version || '1.0.0',
-    description: config.description,
-  })
-  return instance as unknown as McpServerInstance
-}