@mastra/mcp 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/client/types.d.ts

@@ -0,0 +1,188 @@
+import type { RequestContext } from '@mastra/core/di';
+import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
+import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { ClientCapabilities, ElicitRequest, ElicitResult, LoggingLevel, ProgressNotification } from '@modelcontextprotocol/sdk/types.js';
+export type { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Log message structure for MCP client logging.
+ */
+export interface LogMessage {
+    /** Logging level (debug, info, warning, error, etc.) */
+    level: LoggingLevel;
+    /** Log message content */
+    message: string;
+    /** Timestamp when the log was created */
+    timestamp: Date;
+    /** Name of the MCP server that generated the log */
+    serverName: string;
+    /** Optional additional details */
+    details?: Record<string, any>;
+    requestContext?: RequestContext | null;
+}
+/**
+ * Handler function for processing log messages from MCP servers.
+ */
+export type LogHandler = (logMessage: LogMessage) => void;
+/**
+ * Handler function for processing elicitation requests from MCP servers.
+ *
+ * @param request - The elicitation request parameters including message and schema
+ * @returns Promise resolving to the user's response (accept/decline/cancel with optional content)
+ */
+export type ElicitationHandler = (request: ElicitRequest['params']) => Promise<ElicitResult>;
+/**
+ * Handler function for processing progress notifications from MCP servers.
+ *
+ * @param params - The progress notification parameters including message and status
+ */
+export type ProgressHandler = (params: ProgressNotification['params']) => void;
+/**
+ * Represents a filesystem root that the client exposes to MCP servers.
+ *
+ * Per MCP spec (https://modelcontextprotocol.io/specification/2025-11-25/client/roots):
+ * Roots define the boundaries of where servers can operate within the filesystem,
+ * allowing them to understand which directories and files they have access to.
+ *
+ * @example
+ * ```typescript
+ * const root: Root = {
+ *   uri: 'file:///home/user/projects/myproject',
+ *   name: 'My Project'
+ * };
+ * ```
+ */
+export interface Root {
+    /** Unique identifier for the root. Must be a file:// URI. */
+    uri: string;
+    /** Optional human-readable name for display purposes. */
+    name?: string;
+}
+/**
+ * Base options common to all MCP server definitions.
+ */
+export type BaseServerOptions = {
+    /** Optional handler for server log messages */
+    logger?: LogHandler;
+    /** Optional timeout in milliseconds for server operations */
+    timeout?: number;
+    /** Optional client capabilities to advertise to the server */
+    capabilities?: ClientCapabilities;
+    /** Whether to enable server log forwarding (default: true) */
+    enableServerLogs?: boolean;
+    /** Whether to enable progress tracking (default: false) */
+    enableProgressTracking?: boolean;
+    /**
+     * List of filesystem roots to expose to the MCP server.
+     *
+     * Per MCP spec (https://modelcontextprotocol.io/specification/2025-11-25/client/roots):
+     * Roots define the boundaries of where servers can operate within the filesystem.
+     *
+     * When configured, the client will:
+     * 1. Automatically advertise the `roots` capability to the server
+     * 2. Respond to `roots/list` requests with these roots
+     * 3. Send `notifications/roots/list_changed` when roots are updated via `setRoots()`
+     *
+     * @example
+     * ```typescript
+     * {
+     *   command: 'npx',
+     *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+     *   roots: [
+     *     { uri: 'file:///tmp', name: 'Temp Directory' }
+     *   ]
+     * }
+     * ```
+     */
+    roots?: Root[];
+};
+/**
+ * Configuration for MCP servers using stdio (subprocess) transport.
+ *
+ * Used when the MCP server is spawned as a subprocess that communicates via stdin/stdout.
+ */
+export type StdioServerDefinition = BaseServerOptions & {
+    /** Command to execute (e.g., 'node', 'python', 'npx') */
+    command: string;
+    /** Optional arguments to pass to the command */
+    args?: string[];
+    /** Optional environment variables for the subprocess */
+    env?: Record<string, string>;
+    url?: never;
+    requestInit?: never;
+    eventSourceInit?: never;
+    authProvider?: never;
+    reconnectionOptions?: never;
+    sessionId?: never;
+    connectTimeout?: never;
+};
+/**
+ * Configuration for MCP servers using HTTP-based transport (Streamable HTTP or SSE fallback).
+ *
+ * Used when connecting to remote MCP servers over HTTP. The client will attempt Streamable HTTP
+ * transport first and fall back to SSE if that fails.
+ */
+export type HttpServerDefinition = BaseServerOptions & {
+    /** URL of the MCP server endpoint */
+    url: URL;
+    command?: never;
+    args?: never;
+    env?: never;
+    /** Optional request configuration for HTTP requests */
+    requestInit?: StreamableHTTPClientTransportOptions['requestInit'];
+    /** Optional configuration for SSE fallback (required when using custom headers with SSE) */
+    eventSourceInit?: SSEClientTransportOptions['eventSourceInit'];
+    /** Optional authentication provider for HTTP requests */
+    authProvider?: StreamableHTTPClientTransportOptions['authProvider'];
+    /** Optional reconnection configuration for Streamable HTTP */
+    reconnectionOptions?: StreamableHTTPClientTransportOptions['reconnectionOptions'];
+    /** Optional session ID for Streamable HTTP */
+    sessionId?: StreamableHTTPClientTransportOptions['sessionId'];
+    /** Optional timeout in milliseconds for the connection phase (default: 3000ms).
+     * This timeout allows the system to switch MCP streaming protocols during the setup phase.
+     * The default is set to 3s because the long default timeout would be extremely slow for SSE backwards compat (60s).
+     */
+    connectTimeout?: number;
+};
+/**
+ * Configuration for connecting to an MCP server.
+ *
+ * Either stdio-based (subprocess) or HTTP-based (remote server). The transport type is
+ * automatically detected based on whether `command` or `url` is provided.
+ *
+ * @example
+ * ```typescript
+ * // Stdio server
+ * const stdioServer: MastraMCPServerDefinition = {
+ *   command: 'npx',
+ *   args: ['tsx', 'server.ts'],
+ *   env: { API_KEY: 'secret' }
+ * };
+ *
+ * // HTTP server
+ * const httpServer: MastraMCPServerDefinition = {
+ *   url: new URL('http://localhost:8080/mcp'),
+ *   requestInit: {
+ *     headers: { Authorization: 'Bearer token' }
+ *   }
+ * };
+ * ```
+ */
+export type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefinition;
+/**
+ * Options for creating an internal MCP client instance.
+ *
+ * @internal
+ */
+export type InternalMastraMCPClientOptions = {
+    /** Name identifier for this client */
+    name: string;
+    /** Server connection configuration */
+    server: MastraMCPServerDefinition;
+    /** Optional client capabilities to advertise to the server */
+    capabilities?: ClientCapabilities;
+    /** Optional client version */
+    version?: string;
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

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