@mastra/mcp-docs-server 0.0.13 → 0.0.14-alpha.1

package/.docs/organized/code-examples/mcp-configuration.md

@@ -0,0 +1,579 @@
+### package.json
+```json
+{
+  "name": "examples-mcp-configuration",
+  "type": "module",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "start": "npx bun src/index.ts",
+    "dev": "mastra dev",
+    "test": "cross-env NODE_OPTIONS='--experimental-vm-modules --max-old-space-size=8192' jest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/mcp": "latest",
+    "@mastra/memory": "latest",
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "chalk": "^5.4.1",
+    "zod": "^3.24.3",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "jest": "^29.7.0",
+    "mastra": "latest",
+    "ts-jest": "^29.2.6",
+    "tsx": "^4.19.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "@mastra/core": "link:../../packages/core",
+      "@mastra/mcp": "link:../../packages/mcp",
+      "@mastra/memory": "link:../../packages/memory",
+      "mastra": "link:../../packages/cli"
+    }
+  },
+  "version": "0.0.1",
+  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
+}
+
+```
+
+### index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { MCPClient } from '@mastra/mcp';
+import chalk from 'chalk';
+
+// start sse server - in real life this would already be running but want to show using sse and stdio in this example
+import './mastra/tools/sse';
+
+console.log(chalk.blue(`Creating agent`));
+export const stockWeatherAgent = new Agent({
+  name: 'Stock + Weather Agent',
+  instructions:
+    'You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price. You also love to check the weather when your stock market buddies ask you what the weather is.',
+  model: openai('gpt-4o'),
+});
+
+console.log(chalk.blue(`Creating MCPClient`));
+const mcp = new MCPClient({
+  servers: {
+    stockPrice: {
+      command: 'npx',
+      args: ['-y', 'tsx', './src/mastra/tools/stock-price.ts'],
+      env: {
+        FAKE_CREDS: 'let me in!',
+      },
+    },
+    weather: {
+      url: new URL('http://localhost:8080/sse'),
+    },
+  },
+});
+
+const toolsets = await mcp.getToolsets();
+
+console.log({ toolsets });
+
+const prompt = `Whats the weather in Seattle and what is the current stock price of Apple (AAPL)?`;
+console.log(chalk.yellow(`Sending prompt:\n"${prompt}"\n\n`));
+const response = await stockWeatherAgent.stream(prompt, {
+  toolsets,
+});
+
+for await (const part of response.fullStream) {
+  switch (part.type) {
+    case 'error':
+      console.error(part.error);
+      break;
+    case 'text-delta':
+      process.stdout.write(chalk.green(part.textDelta));
+      break;
+    case 'tool-call':
+      console.log(`calling tool ${part.toolName} with args ${chalk.red(JSON.stringify(part.args, null, 2))}`);
+      break;
+    case 'tool-result':
+      console.log(`tool result ${chalk.cyan(JSON.stringify(part.result, null, 2))}`);
+      break;
+  }
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { MCPClient } from '@mastra/mcp';
+
+// start sse server - in real life this would already be running but want to show using sse and stdio in this example
+import '../tools/sse';
+
+const mcp = new MCPClient({
+  servers: {
+    stockPrice: {
+      command: 'npx',
+      args: ['-y', 'tsx', '../../src/mastra/tools/stock-price.ts'],
+      env: {
+        FAKE_CREDS: 'let me in!',
+      },
+    },
+    weather: {
+      url: new URL('http://localhost:8080/sse'),
+    },
+  },
+});
+
+export const stockWeatherAgent = new Agent({
+  name: 'Stock + Weather Agent',
+  instructions:
+    'You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price. You also love to check the weather when your stock market buddies ask you what the weather is.',
+  model: openai('gpt-4o'),
+  tools: await mcp.getTools(),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { stockWeatherAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { stockWeatherAgent },
+});
+
+```
+
+### mastra/tools/sse.ts
+```typescript
+import chalk from 'chalk';
+import { spawn } from 'child_process';
+import path from 'path';
+
+function relativeFromRoot(pathString: string) {
+  if (import.meta.url.includes(`.mastra`)) {
+    return path.join(`../../`, pathString);
+  }
+
+  return path.join(`./`, pathString);
+}
+
+const sseFile = relativeFromRoot(`./src/mastra/tools/weather.ts`);
+
+console.log(chalk.blue(`Starting mock sse server`));
+// simulating an sse server that's already running
+const sseProcess = spawn(`npx`, [`-y`, `tsx`, sseFile]);
+
+sseProcess.stderr.on(`data`, chunk => {
+  const message = chunk.toString();
+  console.error(message);
+});
+await new Promise(res => {
+  sseProcess.stdout.on(`data`, chunk => {
+    const message = chunk.toString();
+    if (message.includes('server is running on SSE')) {
+      res(null);
+    } else {
+      console.log(message);
+    }
+  });
+});
+
+process.on(`exit`, () => {
+  sseProcess.kill(`SIGINT`);
+});
+
+```
+
+### mastra/tools/stock-price.ts
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+const getStockPrice = async (symbol: string) => {
+  const data = await fetch(`https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`).then(r => r.json());
+  return data.prices['4. close'];
+};
+
+const server = new Server(
+  {
+    name: 'Stock Price Server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+const stockInputSchema = z.object({
+  symbol: z.string().describe('Stock symbol'),
+});
+
+const stockTool = {
+  name: 'getStockPrice',
+  description: "Fetches the last day's closing stock price for a given symbol",
+  execute: async (args: z.infer<typeof stockInputSchema>) => {
+    try {
+      console.log('Using tool to fetch stock price for', args.symbol);
+      const price = await getStockPrice(args.symbol);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              symbol: args.symbol,
+              currentPrice: price,
+            }),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Stock price fetch failed: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'An unknown error occurred.',
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+};
+
+// Set up request handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: stockTool.name,
+      description: stockTool.description,
+      inputSchema: zodToJsonSchema(stockInputSchema),
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async request => {
+  try {
+    switch (request.params.name) {
+      case 'getStockPrice': {
+        const args = stockInputSchema.parse(request.params.arguments);
+        return await stockTool.execute(args);
+      }
+      default:
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Unknown tool: ${request.params.name}`,
+            },
+          ],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid arguments: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+export { server };
+
+```
+
+### mastra/tools/weather.ts
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { createServer, IncomingMessage, ServerResponse } from 'http';
+
+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;
+  };
+}
+
+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();
+
+  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: WeatherResponse = await response.json();
+
+  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';
+}
+
+const server = new Server(
+  {
+    name: 'Weather Server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+const weatherInputSchema = z.object({
+  location: z.string().describe('City name'),
+});
+
+const weatherTool = {
+  name: 'getWeather',
+  description: 'Get current weather for a location',
+  execute: async (args: z.infer<typeof weatherInputSchema>) => {
+    try {
+      const weatherData = await getWeather(args.location);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(weatherData),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Weather fetch failed: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'An unknown error occurred.',
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+};
+
+// Set up request handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: weatherTool.name,
+      description: weatherTool.description,
+      inputSchema: zodToJsonSchema(weatherInputSchema),
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async request => {
+  try {
+    switch (request.params.name) {
+      case 'getWeather': {
+        const args = weatherInputSchema.parse(request.params.arguments);
+        return await weatherTool.execute(args);
+      }
+      default:
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Unknown tool: ${request.params.name}`,
+            },
+          ],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid arguments: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server with SSE support
+let transport: SSEServerTransport | undefined;
+
+const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+  const url = new URL(req.url || '', `http://${req.headers.host}`);
+
+  if (url.pathname === '/sse') {
+    console.log('Received SSE connection');
+    transport = new SSEServerTransport('/message', res);
+    await server.connect(transport);
+
+    server.onclose = async () => {
+      await server.close();
+      transport = undefined;
+    };
+
+    // Handle client disconnection
+    res.on('close', () => {
+      transport = undefined;
+    });
+  } else if (url.pathname === '/message') {
+    console.log('Received message');
+    if (!transport) {
+      res.writeHead(503);
+      res.end('SSE connection not established');
+      return;
+    }
+    await transport.handlePostMessage(req, res);
+  } else {
+    console.log('Unknown path:', url.pathname);
+    res.writeHead(404);
+    res.end();
+  }
+});
+
+const PORT = process.env.PORT || 8080;
+httpServer.listen(PORT, () => {
+  console.log(`Weather server is running on SSE at http://localhost:${PORT}`);
+});
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Shutting down weather server...');
+  if (transport) {
+    await server.close();
+    transport = undefined;
+  }
+  // Close the HTTP server
+  httpServer.close(() => {
+    console.log('Weather server shut down complete');
+    process.exit(0);
+  });
+});
+
+export { server };
+
+```

package/.docs/organized/code-examples/mcp-registry-registry.md

@@ -15,7 +15,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.20",
+    "@ai-sdk/openai": "^1.3.22",
     "@mastra/core": "latest",
     "@mastra/mcp": "latest",
     "@mastra/mcp-registry-registry": "latest",

package/.docs/organized/code-examples/memory-with-context.md

@@ -13,7 +13,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@ai-sdk/openai": "^1.2.1",
+    "@ai-sdk/openai": "^1.3.22",
     "@mastra/core": "latest",
     "@mastra/memory": "latest",
     "chalk": "^5.4.1",