@mastra/mcp 0.4.0-alpha.8 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp",
-  "version": "0.4.0-alpha.8",
+  "version": "0.4.0",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "date-fns": "^4.1.0",
     "exit-hook": "^4.0.0",
     "uuid": "^11.1.0",
-    "@mastra/core": "^0.9.0-alpha.7"
+    "@mastra/core": "^0.9.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^1.1.15",
@@ -38,6 +38,7 @@
     "vitest": "^3.0.9",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.22.4",
+    "json-schema-to-zod": "^2.6.0",
     "@internal/lint": "0.0.2"
   },
   "scripts": {

package/src/__fixtures__/server-weather.ts

@@ -0,0 +1,16 @@
+import { MCPServer } from '../server';
+import { weatherTool } from './tools';
+
+const server = new MCPServer({
+  name: 'My MCP Server',
+  version: '1.0.0',
+  tools: {
+    weatherTool,
+  },
+});
+
+server.startStdio().catch(error => {
+  const errorMessage = 'Fatal error running server';
+  console.error(errorMessage, error);
+  process.exit(1);
+});

package/src/__fixtures__/tools.ts

@@ -0,0 +1,103 @@
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+interface GeocodingResponse {
+  results: {
+    latitude: number;
+    longitude: number;
+    name: string;
+  }[];
+}
+interface WeatherResponse {
+  current: {
+    time: string;
+    temperature_2m: number;
+    apparent_temperature: number;
+    relative_humidity_2m: number;
+    wind_speed_10m: number;
+    wind_gusts_10m: number;
+    weather_code: number;
+  };
+}
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('City name'),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    feelsLike: z.number(),
+    humidity: z.number(),
+    windSpeed: z.number(),
+    windGust: z.number(),
+    conditions: z.string(),
+    location: z.string(),
+  }),
+  execute: async ({ context }) => {
+    console.log('weather tool', context);
+    return await getWeather(context.location);
+  },
+});
+
+const getWeather = async (location: string) => {
+  const geocodingUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(location)}&count=1`;
+  const geocodingResponse = await fetch(geocodingUrl);
+  const geocodingData = (await geocodingResponse.json()) as GeocodingResponse;
+
+  if (!geocodingData.results?.[0]) {
+    throw new Error(`Location '${location}' not found`);
+  }
+
+  const { latitude, longitude, name } = geocodingData.results[0];
+
+  const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,wind_gusts_10m,weather_code`;
+
+  const response = await fetch(weatherUrl);
+  const data = (await response.json()) as WeatherResponse;
+
+  return {
+    temperature: data.current.temperature_2m,
+    feelsLike: data.current.apparent_temperature,
+    humidity: data.current.relative_humidity_2m,
+    windSpeed: data.current.wind_speed_10m,
+    windGust: data.current.wind_gusts_10m,
+    conditions: getWeatherCondition(data.current.weather_code),
+    location: name,
+  };
+};
+
+function getWeatherCondition(code: number): string {
+  const conditions: Record<number, string> = {
+    0: 'Clear sky',
+    1: 'Mainly clear',
+    2: 'Partly cloudy',
+    3: 'Overcast',
+    45: 'Foggy',
+    48: 'Depositing rime fog',
+    51: 'Light drizzle',
+    53: 'Moderate drizzle',
+    55: 'Dense drizzle',
+    56: 'Light freezing drizzle',
+    57: 'Dense freezing drizzle',
+    61: 'Slight rain',
+    63: 'Moderate rain',
+    65: 'Heavy rain',
+    66: 'Light freezing rain',
+    67: 'Heavy freezing rain',
+    71: 'Slight snow fall',
+    73: 'Moderate snow fall',
+    75: 'Heavy snow fall',
+    77: 'Snow grains',
+    80: 'Slight rain showers',
+    81: 'Moderate rain showers',
+    82: 'Violent rain showers',
+    85: 'Slight snow showers',
+    86: 'Heavy snow showers',
+    95: 'Thunderstorm',
+    96: 'Thunderstorm with slight hail',
+    99: 'Thunderstorm with heavy hail',
+  };
+  return conditions[code] || 'Unknown';
+}

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './client';
 export * from './configuration';
+export * from './server';

package/src/logger.ts

@@ -0,0 +1,104 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+// Logger interface for type safety
+export interface Logger {
+  info: (message: string, data?: any) => Promise<void>;
+  warning: (message: string, data?: any) => Promise<void>;
+  error: (message: string, error?: any) => Promise<void>;
+  debug: (message: string, data?: any) => Promise<void>;
+}
+
+export const writeErrorLog = (message: string, data?: any) => {
+  const now = new Date();
+  const timestamp = now.toISOString();
+  const hourTimestamp = timestamp.slice(0, 13); // YYYY-MM-DDTHH
+
+  // Create log message
+  const logMessage = {
+    timestamp,
+    message,
+    ...(data ? (typeof data === 'object' ? data : { data }) : {}),
+  };
+
+  // Write to file
+  try {
+    // Ensure cache directory exists
+    const cacheDir = path.join(os.homedir(), '.cache', 'mastra', 'mcp-docs-server-logs');
+    fs.mkdirSync(cacheDir, { recursive: true });
+
+    // Create log file path with timestamp
+    const logFile = path.join(cacheDir, `${hourTimestamp}.log`);
+
+    // Append log entry to file
+    fs.appendFileSync(logFile, JSON.stringify(logMessage) + '\n', 'utf8');
+  } catch (err) {
+    // If file writing fails, at least we still have stderr
+    console.error('Failed to write to log file:', err);
+  }
+};
+
+// Create logger factory to inject server instance
+export function createLogger(server?: Server): Logger {
+  const sendLog = async (level: 'error' | 'debug' | 'info' | 'warning', message: string, data?: any) => {
+    if (!server) return;
+
+    try {
+      await server.sendLoggingMessage({
+        level,
+        data: {
+          message,
+          ...(data ? (typeof data === 'object' ? data : { data }) : {}),
+        },
+      });
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        (error.message === 'Not connected' ||
+          error.message.includes('does not support logging') ||
+          error.message.includes('Connection closed'))
+      ) {
+        return;
+      }
+      console.error(`Failed to send ${level} log:`, error instanceof Error ? error.message : error);
+    }
+  };
+
+  return {
+    info: async (message: string, data?: any) => {
+      // Log to stderr to avoid MCP protocol conflicts on stdout
+      console.error(message, data ? data : '');
+      await sendLog('info', message, data);
+    },
+    warning: async (message: string, data?: any) => {
+      // Log to stderr to avoid MCP protocol conflicts on stdout
+      console.error(message, data ? data : '');
+      await sendLog('warning', message, data);
+    },
+    error: async (message: string, error?: any) => {
+      const errorData =
+        error instanceof Error
+          ? {
+              message: error.message,
+              stack: error.stack,
+              name: error.name,
+            }
+          : error;
+      writeErrorLog(message, errorData);
+      console.error(message, errorData ? errorData : '');
+      await sendLog('error', message, errorData);
+    },
+    debug: async (message: string, data?: any) => {
+      if (process.env.DEBUG || process.env.NODE_ENV === 'development') {
+        // Log to stderr to avoid MCP protocol conflicts on stdout
+        console.error(message, data ? data : '');
+        await sendLog('debug', message, data);
+      }
+    },
+  };
+}
+
+// Create a default logger instance
+export const logger = createLogger();

package/src/server.test.ts

@@ -0,0 +1,115 @@
+import http from 'http';
+import path from 'path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { describe, it, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+import { weatherTool } from './__fixtures__/tools';
+import { MCPConfiguration } from './configuration';
+import { MCPServer } from './server';
+
+const PORT = 9100 + Math.floor(Math.random() * 1000);
+let server: MCPServer;
+let httpServer: http.Server;
+
+vi.setConfig({ testTimeout: 20000, hookTimeout: 20000 });
+
+describe('MCPServer', () => {
+  beforeAll(async () => {
+    server = new MCPServer({
+      name: 'Test MCP Server',
+      version: '0.1.0',
+      tools: { weatherTool },
+    });
+
+    httpServer = http.createServer(async (req, res) => {
+      const url = new URL(req.url || '', `http://localhost:${PORT}`);
+      await server.startSSE({
+        url,
+        ssePath: '/sse',
+        messagePath: '/message',
+        req,
+        res,
+      });
+    });
+
+    await new Promise(resolve => httpServer.listen(PORT, resolve));
+  });
+
+  afterAll(async () => {
+    await new Promise(resolve => httpServer.close(resolve));
+  });
+
+  describe('MCPServer SSE transport', () => {
+    let sseRes: Response | undefined;
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+
+    afterEach(async () => {
+      if (reader) {
+        try {
+          await reader.cancel();
+        } catch {}
+        reader = undefined;
+      }
+      if (sseRes && 'body' in sseRes && sseRes.body) {
+        try {
+          await sseRes.body.cancel();
+        } catch {}
+        sseRes = undefined;
+      }
+    });
+
+    it('should parse SSE stream and contain tool output', async () => {
+      sseRes = await fetch(`http://localhost:${PORT}/sse`, {
+        headers: { Accept: 'text/event-stream' },
+      });
+      expect(sseRes.status).toBe(200);
+      reader = sseRes.body?.getReader();
+      expect(reader).toBeDefined();
+      await fetch(`http://localhost:${PORT}/message`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ tool: 'weatherTool', input: { location: 'Austin' } }),
+      });
+      if (reader) {
+        const { value } = await reader.read();
+        const text = value ? new TextDecoder().decode(value) : '';
+        expect(text).toMatch(/data:/);
+      }
+    });
+
+    it('should return 503 if message sent before SSE connection', async () => {
+      // Manually clear the SSE transport
+      (server as any).sseTransport = undefined;
+      const res = await fetch(`http://localhost:${PORT}/message`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ tool: 'weatherTool', input: { location: 'Austin' } }),
+      });
+      expect(res.status).toBe(503);
+    });
+  });
+
+  describe('MCPServer stdio transport', () => {
+    it('should connect and expose stdio transport', async () => {
+      await server.startStdio();
+      expect(server.getStdioTransport()).toBeInstanceOf(StdioServerTransport);
+    });
+    it('should use stdio transport to get tools', async () => {
+      const existingConfig = new MCPConfiguration({
+        servers: {
+          weather: {
+            command: 'npx',
+            args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/server-weather.ts')],
+            env: {
+              FAKE_CREDS: 'test',
+            },
+          },
+        },
+      });
+
+      const tools = await existingConfig.getTools();
+      expect(Object.keys(tools).length).toBeGreaterThan(0);
+      expect(Object.keys(tools)[0]).toBe('weather_weatherTool');
+      await existingConfig.disconnect();
+    });
+  });
+});

package/src/server.ts

@@ -0,0 +1,253 @@
+import { isVercelTool, isZodType, resolveSerializedZodOutput } from '@mastra/core';
+import type { ToolsInput } from '@mastra/core/agent';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import jsonSchemaToZod from 'json-schema-to-zod';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { createLogger } from './logger';
+
+const logger = createLogger();
+
+type ConvertedTool = {
+  name: string;
+  description?: string;
+  inputSchema: any;
+  zodSchema: z.ZodTypeAny;
+  execute: any;
+};
+
+export class MCPServer {
+  private server: Server;
+  private convertedTools: Record<string, ConvertedTool>;
+  private stdioTransport?: StdioServerTransport;
+  private sseTransport?: SSEServerTransport;
+
+  /**
+   * Get the current stdio transport.
+   */
+  public getStdioTransport(): StdioServerTransport | undefined {
+    return this.stdioTransport;
+  }
+
+  /**
+   * Get the current SSE transport.
+   */
+  public getSseTransport(): SSEServerTransport | undefined {
+    return this.sseTransport;
+  }
+
+  /**
+   * Get a read-only view of the registered tools (for testing/introspection).
+   */
+  tools(): Readonly<Record<string, ConvertedTool>> {
+    return this.convertedTools;
+  }
+
+  /**
+   * Construct a new MCPServer instance.
+   * @param opts.name - Server name
+   * @param opts.version - Server version
+   * @param opts.tools - Tool definitions to register
+   */
+  constructor({ name, version, tools }: { name: string; version: string; tools: ToolsInput }) {
+    this.server = new Server({ name, version }, { capabilities: { tools: {}, logging: { enabled: true } } });
+    this.convertedTools = this.convertTools(tools);
+    void logger.info(
+      `Initialized MCPServer '${name}' v${version} with tools: ${Object.keys(this.convertedTools).join(', ')}`,
+    );
+
+    this.registerListToolsHandler();
+    this.registerCallToolHandler();
+  }
+
+  /**
+   * Convert and validate all provided tools, logging registration status.
+   * @param tools Tool definitions
+   * @returns Converted tools registry
+   */
+  private convertTools(tools: ToolsInput): Record<string, ConvertedTool> {
+    const convertedTools: Record<string, ConvertedTool> = {};
+    for (const toolName of Object.keys(tools)) {
+      let inputSchema: any;
+      let zodSchema: z.ZodTypeAny;
+      const toolInstance = tools[toolName];
+      if (!toolInstance) {
+        void logger.warning(`Tool instance for '${toolName}' is undefined. Skipping.`);
+        continue;
+      }
+      if (typeof toolInstance.execute !== 'function') {
+        void logger.warning(`Tool '${toolName}' does not have a valid execute function. Skipping.`);
+        continue;
+      }
+      // Vercel tools: .parameters is either Zod or JSON schema
+      if (isVercelTool(toolInstance)) {
+        if (isZodType(toolInstance.parameters)) {
+          zodSchema = toolInstance.parameters;
+          inputSchema = zodToJsonSchema(zodSchema);
+        } else if (typeof toolInstance.parameters === 'object') {
+          zodSchema = resolveSerializedZodOutput(jsonSchemaToZod(toolInstance.parameters));
+          inputSchema = toolInstance.parameters;
+        } else {
+          zodSchema = z.object({});
+          inputSchema = zodToJsonSchema(zodSchema);
+        }
+      } else {
+        // Mastra tools: .inputSchema is always Zod
+        zodSchema = toolInstance?.inputSchema ?? z.object({});
+        inputSchema = zodToJsonSchema(zodSchema);
+      }
+
+      // Wrap execute to support both signatures (typed, returns Promise<any>)
+      const execute: (args: any, execOptions?: any) => Promise<any> = async (args, execOptions) => {
+        if (isVercelTool(toolInstance)) {
+          return (await toolInstance.execute?.(args, execOptions)) ?? undefined;
+        }
+        return (await toolInstance.execute?.({ context: args }, execOptions)) ?? undefined;
+      };
+      convertedTools[toolName] = {
+        name: toolName,
+        description: toolInstance?.description,
+        inputSchema,
+        zodSchema,
+        execute,
+      };
+      void logger.info(`Registered tool: '${toolName}' [${toolInstance?.description || 'No description'}]`);
+    }
+    void logger.info(`Total tools registered: ${Object.keys(convertedTools).length}`);
+    return convertedTools;
+  }
+
+  /**
+   * Register the ListTools handler for listing all available tools.
+   */
+  private registerListToolsHandler() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      await logger.debug('Handling ListTools request');
+      return {
+        tools: Object.values(this.convertedTools).map(tool => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      };
+    });
+  }
+
+  /**
+   * Register the CallTool handler for executing a tool by name.
+   */
+  private registerCallToolHandler() {
+    this.server.setRequestHandler(CallToolRequestSchema, async request => {
+      const startTime = Date.now();
+      try {
+        const tool = this.convertedTools[request.params.name];
+        if (!tool) {
+          await logger.warning(`CallTool: Unknown tool '${request.params.name}' requested.`);
+          return {
+            content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
+            isError: true,
+          };
+        }
+        await logger.debug(`CallTool: Invoking '${request.params.name}' with arguments:`, request.params.arguments);
+        const args = tool.zodSchema.parse(request.params.arguments ?? {});
+        const result = await tool.execute(args, request.params);
+        const duration = Date.now() - startTime;
+        await logger.info(`Tool '${request.params.name}' executed successfully in ${duration}ms.`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result),
+            },
+          ],
+          isError: false,
+        };
+      } catch (error) {
+        const duration = Date.now() - startTime;
+        if (error instanceof z.ZodError) {
+          await logger.warning('Invalid tool arguments', {
+            tool: request.params.name,
+            errors: error.errors,
+            duration: `${duration}ms`,
+          });
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Invalid arguments: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+        await logger.error(`Tool execution failed: ${request.params.name}`, error);
+        return {
+          content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  /**
+   * Start the MCP server using stdio transport (for Windsurf integration).
+   */
+  async startStdio() {
+    this.stdioTransport = new StdioServerTransport();
+    await this.server.connect(this.stdioTransport);
+    await logger.info('Started MCP Server (stdio)');
+  }
+
+  /**
+   * Handles MCP-over-SSE protocol for user-provided HTTP servers.
+   * Call this from your HTTP server for both the SSE and message endpoints.
+   *
+   * @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)
+   */
+  async startSSE({
+    url,
+    ssePath,
+    messagePath,
+    req,
+    res,
+  }: {
+    url: URL;
+    ssePath: string;
+    messagePath: string;
+    req: any;
+    res: any;
+  }) {
+    if (url.pathname === ssePath) {
+      await logger.debug('Received SSE connection');
+      this.sseTransport = new SSEServerTransport(messagePath, res);
+      await this.server.connect(this.sseTransport);
+
+      this.server.onclose = async () => {
+        await this.server.close();
+        this.sseTransport = undefined;
+      };
+      res.on('close', () => {
+        this.sseTransport = undefined;
+      });
+    } else if (url.pathname === messagePath) {
+      await logger.debug('Received message');
+      if (!this.sseTransport) {
+        res.writeHead(503);
+        res.end('SSE connection not established');
+        return;
+      }
+      await this.sseTransport.handlePostMessage(req, res);
+    } else {
+      await logger.debug('Unknown path:', url.pathname);
+      res.writeHead(404);
+      res.end();
+    }
+  }
+}