@mastra/core

import type { ToolsInput } from '../agent/index.js'; import { MastraBase } from '../base.js'; import type { Mastra } from '../mastra/index.js'; import type { RequestContext } from '../request-context/index.js'; import type { InternalCoreTool, MCPToolType } from '../tools/index.js'; import type { MCPServerConfig, MCPServerHonoSSEOptions, MCPServerHTTPOptions, MCPServerSSEOptions, PackageInfo, RemoteInfo, Repository, ServerDetailInfo, ServerInfo } from './types.js'; export * from './types.js'; export type { MCPToolType } from '../tools/index.js'; /** * Abstract base class for MCP server implementations. * This provides a common interface and shared functionality for all MCP servers * that can be registered with Mastra, including handling of server metadata. */ export declare abstract class MCPServerBase<TId extends string = string> extends MastraBase { /** Tracks if the server ID has been definitively set. */ private idWasSet; /** The display name of the MCP server. */ readonly name: string; /** The semantic version of the MCP server. */ readonly version: string; /** Internal storage for the server's unique ID. */ private _id; /** A description of what the MCP server does. */ readonly description?: string; /** Optional instructions describing how to use the server and its features. */ readonly instructions?: string; /** Repository information for the server's source code. */ readonly repository?: Repository; /** The release date of this server version (ISO 8601 string). */ readonly releaseDate: string; /** Indicates if this version is the latest available. */ readonly isLatest: boolean; /** The canonical packaging format (e.g., "npm", "docker"), if applicable. */ readonly packageCanonical?: MCPServerConfig['packageCanonical']; /** Information about installable packages for this server. */ readonly packages?: PackageInfo[]; /** Information about remote access points for this server. */ readonly remotes?: RemoteInfo[]; /** The tools registered with and converted by this MCP server. */ convertedTools: Record<string, InternalCoreTool>; /** Reference to the Mastra instance if this server is registered with one. */ mastra: Mastra | undefined; /** Agents to be exposed as tools. */ protected readonly agents?: MCPServerConfig['agents']; /** Workflows to be exposed as tools. */ protected readonly workflows?: MCPServerConfig['workflows']; /** Original tools configuration for re-conversion when Mastra instance is registered. */ protected readonly originalTools: ToolsInput; /** * Public getter for the server's unique ID. * The ID is set at construction or by Mastra and is read-only afterwards. */ get id(): TId; /** * Gets a read-only view of the registered tools. * @returns A readonly record of converted tools. */ tools(): Readonly<Record<string, InternalCoreTool>>; /** * Sets the server's unique ID. This method is typically called by Mastra when * registering the server, using the key provided in the Mastra configuration. * It ensures the ID is set only once. * If an ID was already provided in the MCPServerConfig, this method will be a no-op. * @param id The unique ID to assign to the server. */ setId(id: TId): void; /** * Abstract method to convert and validate tool definitions provided to the server. * This method will also handle agents passed in the config. * @param tools Tool definitions to convert. * @param agents Agent definitions to convert to tools. * @param workflows Workflow definitions to convert to tools. * @returns A record of converted and validated tools. */ abstract convertTools(tools: ToolsInput, agents?: MCPServerConfig['agents'], workflows?: MCPServerConfig['workflows']): Record<string, InternalCoreTool>; /** * Internal method used by Mastra to register itself with the server. * @param mastra The Mastra instance. * @internal */ __registerMastra(mastra: Mastra): void; /** * Constructor for the MCPServerBase. * @param config Configuration options for the MCP server, including metadata. */ constructor(config: MCPServerConfig<TId>); /** * Start the MCP server using stdio transport * This is typically used for Windsurf integration */ abstract startStdio(): Promise<void>; /** * Start the MCP server using SSE transport * This is typically used for web integration * @param options Options for the SSE transport */ abstract startSSE(options: MCPServerSSEOptions): Promise<void>; /** * Start the MCP server using Hono SSE transport * Used for Hono servers * @param options Options for the SSE transport */ abstract startHonoSSE(options: MCPServerHonoSSEOptions): Promise<Response | undefined>; /** * Start the MCP server using HTTP transport * @param options Options for the HTTP transport */ abstract startHTTP(options: MCPServerHTTPOptions): Promise<void>; /** * Close the MCP server and all its connections */ abstract close(): Promise<void>; /** * Gets the basic information about the server, conforming to the MCP Registry 'Server' schema. * This information is suitable for listing multiple servers. * @returns ServerInfo object containing basic server metadata. */ abstract getServerInfo(): ServerInfo; /** * Gets detailed information about the server, conforming to the MCP Registry 'ServerDetail' schema. * This includes all information from `getServerInfo` plus package and remote details. * @returns ServerDetailInfo object containing comprehensive server metadata. */ abstract getServerDetail(): ServerDetailInfo; /** * Gets a list of tools provided by this MCP server, including their schemas. * @returns An object containing an array of tool information. */ abstract getToolListInfo(requestContext?: RequestContext): { tools: Array<{ name: string; description?: string; inputSchema: any; outputSchema?: any; toolType?: MCPToolType; _meta?: Record<string, unknown>; }>; } | Promise<{ tools: Array<{ name: string; description?: string; inputSchema: any; outputSchema?: any; toolType?: MCPToolType; _meta?: Record<string, unknown>; }>; }>; /** * 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. */ abstract getToolInfo(toolId: string): { name: string; description?: string; inputSchema: any; outputSchema?: any; toolType?: MCPToolType; _meta?: Record<string, unknown>; } | undefined | Promise<{ name: string; description?: string; inputSchema: any; outputSchema?: any; toolType?: MCPToolType; _meta?: Record<string, unknown>; } | 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 (e.g., messages, toolCallId). * @returns A promise that resolves to the result of the tool execution. * @throws Error if the tool is not found, or if execution fails. */ abstract executeTool(toolId: string, args: any, executionContext?: { messages?: any[]; toolCallId?: string; requestContext?: RequestContext; }): Promise<any>; /** * Reads the content of a resource by URI. * @param uri The resource URI to read (e.g. `ui://weather/dashboard`). * @returns A promise resolving to the resource content. */ abstract readResource(uri: string): Promise<{ contents: Array<{ uri: string; text?: string; blob?: string; }>; }>; /** * Lists all resources available on this MCP server. * @returns A promise resolving to the list of resources. */ abstract listResources(): Promise<{ resources: Array<{ uri: string; name: string; description?: string; mimeType?: string; _meta?: Record<string, unknown>; }>; }>; } //# sourceMappingURL=index.d.ts.map