@mastra/mcp 0.13.3 → 0.13.4

package/dist/server/promptActions.d.ts

@@ -5,14 +5,33 @@ interface ServerPromptActionsDependencies {
     getSdkServer: () => Server;
     clearDefinedPrompts: () => void;
 }
+/**
+ * Server-side prompt actions for notifying clients about prompt changes.
+ *
+ * This class provides methods for MCP servers to notify connected clients when
+ * the list of available prompts changes.
+ */
 export declare class ServerPromptActions {
     private readonly getLogger;
     private readonly getSdkServer;
     private readonly clearDefinedPrompts;
+    /**
+     * @internal
+     */
     constructor(dependencies: ServerPromptActionsDependencies);
     /**
-     * Notifies the server that the overall list of available prompts has changed.
-     * This will clear the internal cache of defined prompts and send a list_changed notification to clients.
+     * Notifies clients that the overall list of available prompts has changed.
+     *
+     * This clears the internal prompt cache and sends a `notifications/prompts/list_changed`
+     * message to all clients, prompting them to re-fetch the prompt list.
+     *
+     * @throws {MastraError} If sending the notification fails
+     *
+     * @example
+     * ```typescript
+     * // After adding or modifying prompts
+     * await server.prompts.notifyListChanged();
+     * ```
      */
     notifyListChanged(): Promise<void>;
 }

package/dist/server/promptActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promptActions.d.ts","sourceRoot":"","sources":["../../src/server/promptActions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAExE,UAAU,+BAA+B;IACvC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAa;gBAErC,YAAY,EAAE,+BAA+B;IAMzD;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBhD"}
+{"version":3,"file":"promptActions.d.ts","sourceRoot":"","sources":["../../src/server/promptActions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAExE,UAAU,+BAA+B;IACvC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAa;IAEjD;;OAEG;gBACS,YAAY,EAAE,+BAA+B;IAMzD;;;;;;;;;;;;;OAaG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBhD"}

package/dist/server/resourceActions.d.ts

@@ -7,23 +7,54 @@ interface ServerResourceActionsDependencies {
     clearDefinedResources: () => void;
     clearDefinedResourceTemplates: () => void;
 }
+/**
+ * Server-side resource actions for notifying clients about resource changes.
+ *
+ * This class provides methods for MCP servers to notify connected clients when
+ * resources are updated or when the resource list changes.
+ */
 export declare class ServerResourceActions {
     private readonly getSubscriptions;
     private readonly getLogger;
     private readonly getSdkServer;
     private readonly clearDefinedResources;
     private readonly clearDefinedResourceTemplates;
+    /**
+     * @internal
+     */
     constructor(dependencies: ServerResourceActionsDependencies);
     /**
-     * Checks if any resources have been updated.
-     * If the resource is subscribed to by clients, an update notification will be sent.
+     * Notifies subscribed clients that a specific resource has been updated.
+     *
+     * If clients are subscribed to the resource URI, they will receive a
+     * `notifications/resources/updated` message to re-fetch the resource content.
+     *
+     * @param params - Notification parameters
+     * @param params.uri - URI of the resource that was updated
+     * @throws {MastraError} If sending the notification fails
+     *
+     * @example
+     * ```typescript
+     * // After updating a file resource
+     * await server.resources.notifyUpdated({ uri: 'file://data.txt' });
+     * ```
      */
     notifyUpdated({ uri }: {
         uri: string;
     }): Promise<void>;
     /**
-     * Notifies the server that the overall list of available resources has changed.
-     * This will clear the internal cache of defined resources and send a list_changed notification to clients.
+     * Notifies clients that the overall list of available resources has changed.
+     *
+     * This clears the internal resource cache and sends a `notifications/resources/list_changed`
+     * message to all clients, prompting them to re-fetch the resource list.
+     *
+     * @throws {MastraError} If sending the notification fails
+     *
+     * @example
+     * ```typescript
+     * // After adding a new resource to your resource handler
+     * await server.resources.notifyListChanged();
+     * ```
      */
     notifyListChanged(): Promise<void>;
 }

package/dist/server/resourceActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resourceActions.d.ts","sourceRoot":"","sources":["../../src/server/resourceActions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAExE,UAAU,iCAAiC;IACzC,gBAAgB,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,IAAI,CAAC;IAClC,6BAA6B,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAa;gBAE/C,YAAY,EAAE,iCAAiC;IAQ3D;;;OAGG;IACU,aAAa,CAAC,EAAE,GAAG,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BnE;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBhD"}
+{"version":3,"file":"resourceActions.d.ts","sourceRoot":"","sources":["../../src/server/resourceActions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAExE,UAAU,iCAAiC;IACzC,gBAAgB,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,IAAI,CAAC;IAClC,6BAA6B,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAa;IAE3D;;OAEG;gBACS,YAAY,EAAE,iCAAiC;IAQ3D;;;;;;;;;;;;;;;OAeG;IACU,aAAa,CAAC,EAAE,GAAG,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BnE;;;;;;;;;;;;;OAaG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBhD"}

package/dist/server/server.d.ts

@@ -12,6 +12,34 @@ import { SSETransport } from 'hono-mcp-server-sse-transport';
 import { ServerPromptActions } from './promptActions.js';
 import { ServerResourceActions } from './resourceActions.js';
 import type { MCPServerPrompts, MCPServerResources, ElicitationActions } from './types.js';
+/**
+ * MCPServer exposes Mastra tools, agents, and workflows as a Model Context Protocol (MCP) server.
+ *
+ * This class allows any MCP client (like Cursor, Windsurf, or Claude Desktop) to connect and use your
+ * Mastra capabilities. It supports both stdio (subprocess) and SSE (HTTP) MCP transports.
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer } from '@mastra/mcp';
+ * import { createTool } from '@mastra/core/tools';
+ * import { z } from 'zod';
+ *
+ * const weatherTool = createTool({
+ *   id: 'getWeather',
+ *   description: 'Gets the current weather for a location.',
+ *   inputSchema: z.object({ location: z.string() }),
+ *   execute: async ({ context }) => `Weather in ${context.location} is sunny.`,
+ * });
+ *
+ * const server = new MCPServer({
+ *   name: 'My Weather Server',
+ *   version: '1.0.0',
+ *   tools: { weatherTool },
+ * });
+ *
+ * await server.startStdio();
+ * ```
+ */
 export declare class MCPServer extends MCPServerBase {
     private server;
     private stdioTransport?;
@@ -26,28 +54,126 @@ export declare class MCPServer extends MCPServerBase {
     private promptOptions?;
     private subscriptions;
     private currentLoggingLevel;
+    /**
+     * Provides methods to notify clients about resource changes.
+     *
+     * @example
+     * ```typescript
+     * // Notify that a specific resource was updated
+     * await server.resources.notifyUpdated({ uri: 'file://data.txt' });
+     *
+     * // Notify that the resource list changed
+     * await server.resources.notifyListChanged();
+     * ```
+     */
     readonly resources: ServerResourceActions;
+    /**
+     * Provides methods to notify clients about prompt changes.
+     *
+     * @example
+     * ```typescript
+     * // Notify that the prompt list changed
+     * await server.prompts.notifyListChanged();
+     * ```
+     */
     readonly prompts: ServerPromptActions;
+    /**
+     * Provides methods for interactive user input collection during tool execution.
+     *
+     * @example
+     * ```typescript
+     * // Within a tool's execute function
+     * const result = await options.elicitation.sendRequest({
+     *   message: 'Please provide your email address',
+     *   requestedSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       email: { type: 'string', format: 'email' }
+     *     },
+     *     required: ['email']
+     *   }
+     * });
+     * ```
+     */
     readonly elicitation: ElicitationActions;
     /**
-     * Get the current stdio transport.
+     * Gets the stdio transport instance if the server was started using stdio.
+     *
+     * This is primarily for internal checks or testing purposes.
+     *
+     * @returns The stdio transport instance, or undefined if not using stdio transport
      */
     getStdioTransport(): StdioServerTransport | undefined;
     /**
-     * Get the current SSE transport.
+     * Gets the SSE transport instance if the server was started using SSE.
+     *
+     * This is primarily for internal checks or testing purposes.
+     *
+     * @returns The SSE transport instance, or undefined if not using SSE transport
      */
     getSseTransport(): SSEServerTransport | undefined;
     /**
-     * Get the current SSE Hono transport.
+     * Gets the Hono SSE transport instance for a specific session.
+     *
+     * This is primarily for internal checks or testing purposes.
+     *
+     * @param sessionId - The session identifier
+     * @returns The Hono SSE transport instance, or undefined if session not found
      */
     getSseHonoTransport(sessionId: string): SSETransport | undefined;
     /**
-     * Get the current server instance.
+     * Gets the underlying MCP SDK Server instance.
+     *
+     * This provides access to the low-level server instance for advanced use cases.
+     *
+     * @returns The Server instance from @modelcontextprotocol/sdk
      */
     getServer(): Server;
     /**
-     * Construct a new MCPServer instance.
-     * @param opts - Configuration options for the server, including registry metadata.
+     * Creates a new MCPServer instance.
+     *
+     * The server exposes tools, agents, and workflows to MCP clients. Agents are automatically
+     * converted to tools named `ask_<agentKey>`, and workflows become tools named `run_<workflowKey>`.
+     *
+     * @param opts - Configuration options for the server
+     * @param opts.name - Descriptive name for the server (e.g., 'My Weather Server')
+     * @param opts.version - Semantic version of the server (e.g., '1.0.0')
+     * @param opts.tools - Object mapping tool names to tool definitions
+     * @param opts.agents - Optional object mapping agent identifiers to Agent instances
+     * @param opts.workflows - Optional object mapping workflow identifiers to Workflow instances
+     * @param opts.resources - Optional resource configuration for exposing data and content
+     * @param opts.prompts - Optional prompt configuration for exposing reusable templates
+     * @param opts.id - Optional unique identifier (generated if not provided)
+     * @param opts.description - Optional description of what the server does
+     *
+     * @example
+     * ```typescript
+     * import { MCPServer } from '@mastra/mcp';
+     * import { Agent } from '@mastra/core/agent';
+     * import { createTool } from '@mastra/core/tools';
+     * import { z } from 'zod';
+     *
+     * const myAgent = new Agent({
+     *   name: 'Helper',
+     *   description: 'A helpful assistant',
+     *   instructions: 'You are helpful.',
+     *   model: openai('gpt-4o-mini'),
+     * });
+     *
+     * const server = new MCPServer({
+     *   name: 'My Server',
+     *   version: '1.0.0',
+     *   tools: {
+     *     weatherTool: createTool({
+     *       id: 'getWeather',
+     *       description: 'Gets weather',
+     *       inputSchema: z.object({ location: z.string() }),
+     *       execute: async ({ context }) => `Sunny in ${context.location}`,
+     *     })
+     *   },
+     *   agents: { myAgent },
+     * });
+     * ```
      */
     constructor(opts: MCPServerConfig & {
         resources?: MCPServerResources;
@@ -92,39 +218,135 @@ export declare class MCPServer extends MCPServerBase {
      */
     convertTools(tools: ToolsInput, agentsConfig?: Record<string, Agent>, workflowsConfig?: Record<string, Workflow>): Record<string, ConvertedTool>;
     /**
-     * Start the MCP server using stdio transport (for Windsurf integration).
+     * Starts the MCP server using standard input/output (stdio) transport.
+     *
+     * This is typically used when running the server as a command-line program that MCP clients
+     * spawn as a subprocess (e.g., integration with Windsurf, Cursor, or Claude Desktop).
+     *
+     * @throws {MastraError} If the stdio connection fails
+     *
+     * @example
+     * ```typescript
+     * const server = new MCPServer({
+     *   name: 'My Server',
+     *   version: '1.0.0',
+     *   tools: { weatherTool },
+     * });
+     *
+     * await server.startStdio();
+     * ```
      */
     startStdio(): Promise<void>;
     /**
-     * Handles MCP-over-SSE protocol for user-provided HTTP servers.
-     * Call this from your HTTP server for both the SSE and message endpoints.
+     * Integrates the MCP server with an existing HTTP server using Server-Sent Events (SSE).
      *
-     * @param url Parsed URL of the incoming request
-     * @param ssePath Path for establishing the SSE connection (e.g. '/sse')
-     * @param messagePath Path for POSTing client messages (e.g. '/message')
-     * @param req Incoming HTTP request
-     * @param res HTTP response (must support .write/.end)
+     * Call this method from your web server's request handler for both the SSE and message paths.
+     * This enables web-based MCP clients to connect to your server.
+     *
+     * @param options - Configuration for SSE integration
+     * @param options.url - Parsed URL of the incoming request
+     * @param options.ssePath - Path for establishing SSE connection (e.g., '/sse')
+     * @param options.messagePath - Path for POSTing client messages (e.g., '/message')
+     * @param options.req - Incoming HTTP request object
+     * @param options.res - HTTP response object (must support .write/.end)
+     *
+     * @throws {MastraError} If SSE connection setup fails
+     *
+     * @example
+     * ```typescript
+     * import http from 'http';
+     *
+     * const httpServer = http.createServer(async (req, res) => {
+     *   await server.startSSE({
+     *     url: new URL(req.url || '', `http://localhost:1234`),
+     *     ssePath: '/sse',
+     *     messagePath: '/message',
+     *     req,
+     *     res,
+     *   });
+     * });
+     *
+     * httpServer.listen(1234, () => {
+     *   console.log('MCP server listening on http://localhost:1234/sse');
+     * });
+     * ```
      */
     startSSE({ url, ssePath, messagePath, req, res }: MCPServerSSEOptions): Promise<void>;
     /**
-     * Handles MCP-over-SSE protocol for user-provided HTTP servers.
-     * Call this from your HTTP server for both the SSE and message endpoints.
+     * Integrates the MCP server with a Hono web framework using Server-Sent Events (SSE).
+     *
+     * Call this method from your Hono server's request handler for both the SSE and message paths.
+     * This enables Hono-based web applications to expose MCP servers.
+     *
+     * @param options - Configuration for Hono SSE integration
+     * @param options.url - Parsed URL of the incoming request
+     * @param options.ssePath - Path for establishing SSE connection (e.g., '/hono-sse')
+     * @param options.messagePath - Path for POSTing client messages (e.g., '/message')
+     * @param options.context - Hono context object
+     *
+     * @throws {MastraError} If Hono SSE connection setup fails
+     *
+     * @example
+     * ```typescript
+     * import { Hono } from 'hono';
      *
-     * @param url Parsed URL of the incoming request
-     * @param ssePath Path for establishing the SSE connection (e.g. '/sse')
-     * @param messagePath Path for POSTing client messages (e.g. '/message')
-     * @param context Incoming Hono context
+     * const app = new Hono();
+     *
+     * app.all('*', async (c) => {
+     *   const url = new URL(c.req.url);
+     *   return await server.startHonoSSE({
+     *     url,
+     *     ssePath: '/hono-sse',
+     *     messagePath: '/message',
+     *     context: c,
+     *   });
+     * });
+     *
+     * export default app;
+     * ```
      */
     startHonoSSE({ url, ssePath, messagePath, context }: MCPServerHonoSSEOptions): Promise<Response>;
     /**
-     * Handles MCP-over-StreamableHTTP protocol for user-provided HTTP servers.
-     * Call this from your HTTP server for the streamable HTTP endpoint.
+     * Integrates the MCP server with an existing HTTP server using streamable HTTP transport.
+     *
+     * This is the recommended modern transport method, providing better session management and
+     * reliability compared to SSE. Call this from your HTTP server's request handler.
+     *
+     * @param options - Configuration for HTTP integration
+     * @param options.url - Parsed URL of the incoming request
+     * @param options.httpPath - Path for the MCP endpoint (e.g., '/mcp')
+     * @param options.req - Incoming HTTP request (http.IncomingMessage)
+     * @param options.res - HTTP response object (http.ServerResponse)
+     * @param options.options - Optional transport options
+     * @param options.options.sessionIdGenerator - Function to generate unique session IDs (defaults to randomUUID)
+     * @param options.options.onsessioninitialized - Callback when a new session is initialized
+     * @param options.options.enableJsonResponse - If true, return JSON instead of SSE streaming
+     * @param options.options.eventStore - Event store for message resumability
+     *
+     * @throws {MastraError} If HTTP connection setup fails
      *
-     * @param url Parsed URL of the incoming request
-     * @param httpPath Path for establishing the streamable HTTP connection (e.g. '/mcp')
-     * @param req Incoming HTTP request
-     * @param res HTTP response (must support .write/.end)
-     * @param options Optional options to pass to the transport (e.g. sessionIdGenerator)
+     * @example
+     * ```typescript
+     * import http from 'http';
+     * import { randomUUID } from 'crypto';
+     *
+     * const httpServer = http.createServer(async (req, res) => {
+     *   await server.startHTTP({
+     *     url: new URL(req.url || '', 'http://localhost:1234'),
+     *     httpPath: '/mcp',
+     *     req,
+     *     res,
+     *     options: {
+     *       sessionIdGenerator: () => randomUUID(),
+     *       onsessioninitialized: (sessionId) => {
+     *         console.log(`New MCP session: ${sessionId}`);
+     *       },
+     *     },
+     *   });
+     * });
+     *
+     * httpServer.listen(1234);
+     * ```
      */
     startHTTP({ url, httpPath, req, res, options, }: {
         url: URL;
@@ -133,32 +355,122 @@ export declare class MCPServer extends MCPServerBase {
         res: http.ServerResponse<http.IncomingMessage>;
         options?: StreamableHTTPServerTransportOptions;
     }): Promise<void>;
+    /**
+     * Establishes the SSE connection for the MCP server.
+     *
+     * This is a lower-level method called internally by `startSSE()`. In most cases,
+     * you should use `startSSE()` instead which handles both connection establishment
+     * and message routing.
+     *
+     * @param params - Connection parameters
+     * @param params.messagePath - Path for POST requests from the client
+     * @param params.res - HTTP response object for the SSE stream
+     * @throws {MastraError} If SSE connection establishment fails
+     *
+     * @example
+     * ```typescript
+     * // Usually called internally by startSSE()
+     * await server.connectSSE({
+     *   messagePath: '/message',
+     *   res: response
+     * });
+     * ```
+     */
     connectSSE({ messagePath, res, }: {
         messagePath: string;
         res: http.ServerResponse<http.IncomingMessage>;
     }): Promise<void>;
+    /**
+     * Establishes the Hono SSE connection for the MCP server.
+     *
+     * This is a lower-level method called internally by `startHonoSSE()`. In most cases,
+     * you should use `startHonoSSE()` instead which handles both connection establishment
+     * and message routing.
+     *
+     * @param params - Connection parameters
+     * @param params.messagePath - Path for POST requests from the client
+     * @param params.stream - Hono SSE streaming API object
+     * @throws {MastraError} If Hono SSE connection establishment fails
+     *
+     * @example
+     * ```typescript
+     * // Usually called internally by startHonoSSE()
+     * await server.connectHonoSSE({
+     *   messagePath: '/message',
+     *   stream: sseStream
+     * });
+     * ```
+     */
     connectHonoSSE({ messagePath, stream }: {
         messagePath: string;
         stream: SSEStreamingApi;
     }): Promise<void>;
     /**
-     * Close the MCP server and all its connections
+     * Closes the MCP server and releases all resources.
+     *
+     * This method cleanly shuts down all active transports (stdio, SSE, HTTP) and their
+     * associated connections. Call this when your application is shutting down.
+     *
+     * @throws {MastraError} If closing the server fails
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * process.on('SIGTERM', async () => {
+     *   await server.close();
+     *   process.exit(0);
+     * });
+     * ```
      */
     close(): Promise<void>;
     /**
-     * Gets the basic information about the server, conforming to the Server schema.
-     * @returns ServerInfo object.
+     * Gets basic information about the server.
+     *
+     * Returns metadata including server ID, name, description, repository, and version details.
+     * This information conforms to the MCP Server schema.
+     *
+     * @returns Server information object
+     *
+     * @example
+     * ```typescript
+     * const info = server.getServerInfo();
+     * console.log(`${info.name} v${info.version_detail.version}`);
+     * // Output: My Weather Server v1.0.0
+     * ```
      */
     getServerInfo(): ServerInfo;
     /**
-     * Gets detailed information about the server, conforming to the ServerDetail schema.
-     * @returns ServerDetailInfo object.
+     * Gets detailed information about the server including packaging and deployment metadata.
+     *
+     * Returns extended server information with package details, remotes, and deployment configurations.
+     * This information conforms to the MCP ServerDetail schema.
+     *
+     * @returns Detailed server information object
+     *
+     * @example
+     * ```typescript
+     * const detail = server.getServerDetail();
+     * console.log(detail.package_canonical); // 'npm'
+     * console.log(detail.packages); // Package installation info
+     * ```
      */
     getServerDetail(): ServerDetailInfo;
     /**
-     * Gets a list of tools provided by this MCP server, including their schemas.
-     * This leverages the same tool information used by the internal ListTools MCP request.
-     * @returns An object containing an array of tool information.
+     * Gets a list of all tools provided by this MCP server with their schemas.
+     *
+     * Returns information about all registered tools including explicit tools, agent-derived tools,
+     * and workflow-derived tools. Includes input/output schemas and tool types.
+     *
+     * @returns Object containing array of tool information
+     *
+     * @example
+     * ```typescript
+     * const toolList = server.getToolListInfo();
+     * toolList.tools.forEach(tool => {
+     *   console.log(`${tool.name}: ${tool.description}`);
+     *   console.log(`Type: ${tool.toolType || 'tool'}`);
+     * });
+     * ```
      */
     getToolListInfo(): {
         tools: Array<{
@@ -171,8 +483,21 @@ export declare class MCPServer extends MCPServerBase {
     };
     /**
      * Gets information for a specific tool provided by this MCP server.
-     * @param toolId The ID/name of the tool to retrieve.
-     * @returns Tool information (name, description, inputSchema) or undefined if not found.
+     *
+     * Returns detailed information about a single tool including its name, description, schemas, and type.
+     * Returns undefined if the tool is not found.
+     *
+     * @param toolId - The ID/name of the tool to retrieve
+     * @returns Tool information object or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const toolInfo = server.getToolInfo('getWeather');
+     * if (toolInfo) {
+     *   console.log(toolInfo.description);
+     *   console.log(toolInfo.inputSchema);
+     * }
+     * ```
      */
     getToolInfo(toolId: string): {
         name: string;
@@ -183,11 +508,25 @@ export declare class MCPServer extends MCPServerBase {
     } | undefined;
     /**
      * Executes a specific tool provided by this MCP server.
-     * @param toolId The ID/name of the tool to execute.
-     * @param args The arguments to pass to the tool's execute function.
-     * @param executionContext Optional context for the tool execution.
-     * @returns A promise that resolves to the result of the tool execution.
-     * @throws Error if the tool is not found, validation fails, or execution fails.
+     *
+     * This method validates the tool arguments against the input schema and executes the tool.
+     * If validation fails, returns an error object instead of throwing.
+     *
+     * @param toolId - The ID/name of the tool to execute
+     * @param args - The arguments to pass to the tool's execute function
+     * @param executionContext - Optional context including messages and toolCallId
+     * @returns Promise resolving to the tool execution result
+     * @throws {MastraError} If the tool is not found or execution fails
+     *
+     * @example
+     * ```typescript
+     * const result = await server.executeTool(
+     *   'getWeather',
+     *   { location: 'London' },
+     *   { toolCallId: 'call_123' }
+     * );
+     * console.log(result);
+     * ```
      */
     executeTool(toolId: string, args: any, executionContext?: {
         messages?: any[];

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

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