@mastra/core
Version:
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
1 lines • 16 kB
Source Map (JSON)
{"version":3,"sources":["../../src/mcp/index.ts"],"names":["MastraBase","MastraError","RegisteredLogger","slugify","randomUUID"],"mappings":"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","file":"index.cjs","sourcesContent":["import { randomUUID } from 'node:crypto';\nimport slugify from '@sindresorhus/slugify';\nimport type { ToolsInput } from '../agent';\nimport { MastraBase } from '../base';\nimport { MastraError } from '../error';\nimport { RegisteredLogger } from '../logger';\nimport type { Mastra } from '../mastra';\nimport type { RequestContext } from '../request-context';\nimport type { InternalCoreTool, MCPToolType } from '../tools';\nimport type {\n MCPServerConfig,\n MCPServerHonoSSEOptions,\n MCPServerHTTPOptions,\n MCPServerSSEOptions,\n PackageInfo,\n RemoteInfo,\n Repository,\n ServerDetailInfo,\n ServerInfo,\n} from './types';\nexport * from './types';\nexport type { MCPToolType } from '../tools';\n\n/**\n * Abstract base class for MCP server implementations.\n * This provides a common interface and shared functionality for all MCP servers\n * that can be registered with Mastra, including handling of server metadata.\n */\nexport abstract class MCPServerBase<TId extends string = string> extends MastraBase {\n /** Tracks if the server ID has been definitively set. */\n private idWasSet = false;\n /** The display name of the MCP server. */\n public readonly name: string;\n /** The semantic version of the MCP server. */\n public readonly version: string;\n /** Internal storage for the server's unique ID. */\n private _id: TId;\n /** A description of what the MCP server does. */\n public readonly description?: string;\n /** Optional instructions describing how to use the server and its features. */\n public readonly instructions?: string;\n /** Repository information for the server's source code. */\n public readonly repository?: Repository;\n /** The release date of this server version (ISO 8601 string). */\n public readonly releaseDate: string;\n /** Indicates if this version is the latest available. */\n public readonly isLatest: boolean;\n /** The canonical packaging format (e.g., \"npm\", \"docker\"), if applicable. */\n public readonly packageCanonical?: MCPServerConfig['packageCanonical'];\n /** Information about installable packages for this server. */\n public readonly packages?: PackageInfo[];\n /** Information about remote access points for this server. */\n public readonly remotes?: RemoteInfo[];\n /** The tools registered with and converted by this MCP server. */\n public convertedTools: Record<string, InternalCoreTool>;\n /** Reference to the Mastra instance if this server is registered with one. */\n public mastra: Mastra | undefined;\n /** Agents to be exposed as tools. */\n protected readonly agents?: MCPServerConfig['agents'];\n /** Workflows to be exposed as tools. */\n protected readonly workflows?: MCPServerConfig['workflows'];\n /** Original tools configuration for re-conversion when Mastra instance is registered. */\n protected readonly originalTools: ToolsInput;\n\n /**\n * Public getter for the server's unique ID.\n * The ID is set at construction or by Mastra and is read-only afterwards.\n */\n public get id(): TId {\n return this._id;\n }\n\n /**\n * Gets a read-only view of the registered tools.\n * @returns A readonly record of converted tools.\n */\n tools(): Readonly<Record<string, InternalCoreTool>> {\n return this.convertedTools;\n }\n\n /**\n * Sets the server's unique ID. This method is typically called by Mastra when\n * registering the server, using the key provided in the Mastra configuration.\n * It ensures the ID is set only once.\n * If an ID was already provided in the MCPServerConfig, this method will be a no-op.\n * @param id The unique ID to assign to the server.\n */\n setId(id: TId) {\n if (this.idWasSet) {\n return;\n }\n this._id = id;\n this.idWasSet = true;\n }\n\n /**\n * Abstract method to convert and validate tool definitions provided to the server.\n * This method will also handle agents passed in the config.\n * @param tools Tool definitions to convert.\n * @param agents Agent definitions to convert to tools.\n * @param workflows Workflow definitions to convert to tools.\n * @returns A record of converted and validated tools.\n */\n public abstract convertTools(\n tools: ToolsInput,\n agents?: MCPServerConfig['agents'],\n workflows?: MCPServerConfig['workflows'],\n ): Record<string, InternalCoreTool>;\n\n /**\n * Internal method used by Mastra to register itself with the server.\n * @param mastra The Mastra instance.\n * @internal\n */\n __registerMastra(mastra: Mastra): void {\n this.mastra = mastra;\n // Re-convert tools now that we have the Mastra instance to populate MCP tools execute with mastra instance\n this.convertedTools = this.convertTools(this.originalTools, this.agents, this.workflows);\n\n // Auto-register tools with the Mastra instance\n if (this.originalTools && typeof this.originalTools === 'object') {\n Object.entries(this.originalTools).forEach(([key, tool]) => {\n try {\n // Only add tools that have an id property (ToolAction type)\n if (tool && typeof tool === 'object' && 'id' in tool) {\n // Use tool's intrinsic ID to avoid collisions across MCP servers\n const toolKey = typeof (tool as any).id === 'string' ? (tool as any).id : key;\n mastra.addTool(tool as any, toolKey);\n }\n } catch (error) {\n // Tool might already be registered, that's okay\n if (!(error instanceof MastraError) || error.id !== 'MASTRA_ADD_TOOL_DUPLICATE_KEY') {\n throw error;\n }\n }\n });\n }\n\n // Auto-register agents with the Mastra instance\n if (this.agents && typeof this.agents === 'object') {\n Object.entries(this.agents).forEach(([key, agent]) => {\n try {\n mastra.addAgent(agent, key);\n } catch (error) {\n // Agent might already be registered, that's okay\n if (!(error instanceof MastraError) || error.id !== 'MASTRA_ADD_AGENT_DUPLICATE_KEY') {\n throw error;\n }\n }\n });\n }\n\n // Auto-register workflows with the Mastra instance\n if (this.workflows && typeof this.workflows === 'object') {\n Object.entries(this.workflows).forEach(([key, workflow]) => {\n try {\n mastra.addWorkflow(workflow, key);\n } catch (error) {\n // Workflow might already be registered, that's okay\n if (!(error instanceof MastraError) || error.id !== 'MASTRA_ADD_WORKFLOW_DUPLICATE_KEY') {\n throw error;\n }\n }\n });\n }\n }\n\n /**\n * Constructor for the MCPServerBase.\n * @param config Configuration options for the MCP server, including metadata.\n */\n constructor(config: MCPServerConfig<TId>) {\n super({ component: RegisteredLogger.MCP_SERVER, name: config.name });\n this.name = config.name;\n this.version = config.version;\n\n // If user does not provide an ID, we will use the key from the Mastra config, but if user does not pass MCPServer\n // to Mastra, we will generate a random UUID as a backup.\n if (config.id) {\n this._id = slugify(config.id) as TId;\n this.idWasSet = true;\n } else {\n this._id = (this.mastra?.generateId() || randomUUID()) as TId;\n }\n\n this.description = config.description;\n this.instructions = config.instructions;\n this.repository = config.repository;\n this.releaseDate = config.releaseDate || new Date().toISOString();\n this.isLatest = config.isLatest === undefined ? true : config.isLatest;\n this.packageCanonical = config.packageCanonical;\n this.packages = config.packages;\n this.remotes = config.remotes;\n this.agents = config.agents;\n this.workflows = config.workflows;\n this.originalTools = config.tools;\n this.convertedTools = this.convertTools(config.tools, config.agents, config.workflows);\n }\n\n /**\n * Start the MCP server using stdio transport\n * This is typically used for Windsurf integration\n */\n public abstract startStdio(): Promise<void>;\n\n /**\n * Start the MCP server using SSE transport\n * This is typically used for web integration\n * @param options Options for the SSE transport\n */\n public abstract startSSE(options: MCPServerSSEOptions): Promise<void>;\n\n /**\n * Start the MCP server using Hono SSE transport\n * Used for Hono servers\n * @param options Options for the SSE transport\n */\n public abstract startHonoSSE(options: MCPServerHonoSSEOptions): Promise<Response | undefined>;\n\n /**\n * Start the MCP server using HTTP transport\n * @param options Options for the HTTP transport\n */\n public abstract startHTTP(options: MCPServerHTTPOptions): Promise<void>;\n\n /**\n * Close the MCP server and all its connections\n */\n public abstract close(): Promise<void>;\n\n /**\n * Gets the basic information about the server, conforming to the MCP Registry 'Server' schema.\n * This information is suitable for listing multiple servers.\n * @returns ServerInfo object containing basic server metadata.\n */\n public abstract getServerInfo(): ServerInfo;\n\n /**\n * Gets detailed information about the server, conforming to the MCP Registry 'ServerDetail' schema.\n * This includes all information from `getServerInfo` plus package and remote details.\n * @returns ServerDetailInfo object containing comprehensive server metadata.\n */\n public abstract getServerDetail(): ServerDetailInfo;\n\n /**\n * Gets a list of tools provided by this MCP server, including their schemas.\n * @returns An object containing an array of tool information.\n */\n public abstract getToolListInfo(requestContext?: RequestContext):\n | {\n tools: Array<{\n name: string;\n description?: string;\n inputSchema: any;\n outputSchema?: any;\n toolType?: MCPToolType;\n _meta?: Record<string, unknown>;\n }>;\n }\n | Promise<{\n tools: Array<{\n name: string;\n description?: string;\n inputSchema: any;\n outputSchema?: any;\n toolType?: MCPToolType;\n _meta?: Record<string, unknown>;\n }>;\n }>;\n\n /**\n * Gets information for a specific tool provided by this MCP server.\n * @param toolId The ID/name of the tool to retrieve.\n * @returns Tool information (name, description, inputSchema) or undefined if not found.\n */\n public abstract getToolInfo(toolId: string):\n | {\n name: string;\n description?: string;\n inputSchema: any;\n outputSchema?: any;\n toolType?: MCPToolType;\n _meta?: Record<string, unknown>;\n }\n | undefined\n | Promise<\n | {\n name: string;\n description?: string;\n inputSchema: any;\n outputSchema?: any;\n toolType?: MCPToolType;\n _meta?: Record<string, unknown>;\n }\n | undefined\n >;\n\n /**\n * Executes a specific tool provided by this MCP server.\n * @param toolId The ID/name of the tool to execute.\n * @param args The arguments to pass to the tool's execute function.\n * @param executionContext Optional context for the tool execution (e.g., messages, toolCallId).\n * @returns A promise that resolves to the result of the tool execution.\n * @throws Error if the tool is not found, or if execution fails.\n */\n public abstract executeTool(\n toolId: string,\n args: any,\n executionContext?: { messages?: any[]; toolCallId?: string; requestContext?: RequestContext },\n ): Promise<any>;\n\n /**\n * Reads the content of a resource by URI.\n * @param uri The resource URI to read (e.g. `ui://weather/dashboard`).\n * @returns A promise resolving to the resource content.\n */\n public abstract readResource(\n uri: string,\n ): Promise<{ contents: Array<{ uri: string; text?: string; blob?: string }> }>;\n\n /**\n * Lists all resources available on this MCP server.\n * @returns A promise resolving to the list of resources.\n */\n public abstract listResources(): Promise<{\n resources: Array<{\n uri: string;\n name: string;\n description?: string;\n mimeType?: string;\n _meta?: Record<string, unknown>;\n }>;\n }>;\n}\n"]}