@mastra/mcp-docs-server 0.0.7 → 0.0.8

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

@@ -1,341 +0,0 @@
-### 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": "ISC",
-  "description": "",
-  "dependencies": {
-    "@ai-sdk/openai": "latest",
-    "@mastra/core": "workspace:*",
-    "@mastra/mcp": "workspace:*",
-    "@mastra/memory": "workspace:*",
-    "chalk": "^5.4.1",
-    "fastmcp": "^1.20.4",
-    "zod": "^3.24.2"
-  },
-  "devDependencies": {
-    "@jest/globals": "^29.7.0",
-    "jest": "^29.7.0",
-    "mastra": "workspace:*",
-    "ts-jest": "^29.2.6",
-    "tsx": "^4.19.3"
-  },
-  "version": "0.0.1"
-}
-
-```
-
-### index.ts
-```typescript
-import { openai } from '@ai-sdk/openai';
-import { Agent } from '@mastra/core/agent';
-import { MCPConfiguration } 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 MCPConfiguration`));
-const mcp = new MCPConfiguration({
-  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 { MCPConfiguration } 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 MCPConfiguration({
-  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 { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-
-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 FastMCP({
-  name: 'Stock Price Server',
-  version: '1.0.0',
-});
-
-server.addTool({
-  name: 'getStockPrice',
-  description: "Fetches the last day's closing stock price for a given symbol",
-  parameters: z.object({
-    symbol: z.string(),
-  }),
-  execute: async args => {
-    console.log('Using tool to fetch stock price for', args.symbol);
-    const price = await getStockPrice(args.symbol);
-    return JSON.stringify({
-      symbol: args.symbol,
-      currentPrice: price,
-    });
-  },
-});
-
-// Start the server with stdio transport
-server.start({
-  transportType: 'stdio',
-});
-
-export { server };
-
-```
-
-### mastra/tools/weather.ts
-```typescript
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-
-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 FastMCP({
-  name: 'Weather Server',
-  version: '1.0.0',
-});
-
-server.addTool({
-  name: 'getWeather',
-  description: 'Get current weather for a location',
-  parameters: z.object({
-    location: z.string().describe('City name'),
-  }),
-  execute: async args => {
-    try {
-      const weatherData = await getWeather(args.location);
-      return JSON.stringify(weatherData);
-    } catch (error) {
-      if (error instanceof Error) {
-        throw new Error(`Weather fetch failed: ${error.message}`);
-      }
-      throw error;
-    }
-  },
-});
-
-// Start the server with SSE support
-server.start({
-  transportType: 'sse',
-  sse: {
-    endpoint: '/sse',
-    port: 8080,
-  },
-});
-
-export { server };
-
-```

package/.docs/raw/guides/ai-recruiter.mdx

@@ -1,187 +0,0 @@
----
-title: "Building an AI Recruiter | Mastra Workflows | Guides"
-description: Guide on building a recruiter workflow in Mastra to gather and process candidate information using LLMs.
----
-
-# Introduction
-
-In this guide, you'll learn how Mastra helps you build workflows with LLMs.
-
-We'll walk through creating a workflow that gathers information from a candidate's resume, then branches to either a technical or behavioral question based on the candidate's profile. Along the way, you'll see how to structure workflow steps, handle branching, and integrate LLM calls.
-
-Below is a concise version of the workflow. It starts by importing the necessary modules, sets up Mastra, defines steps to extract and classify candidate data, and then asks suitable follow-up questions. Each code block is followed by a short explanation of what it does and why it's useful.
-
-## 1. Imports and Setup
-
-You need to import Mastra tools and Zod to handle workflow definitions and data validation.
-
-```typescript filename="src/mastra/index.ts" copy
-
-import { Mastra } from "@mastra/core";
-import { Step, Workflow } from "@mastra/core/workflows";
-import { z } from "zod";
-```
-
-Add your `OPENAI_API_KEY` to the `.env` file.
-
-```bash filename=".env" copy
-OPENAI_API_KEY=<your-openai-key>
-```
-
-## 2. Step One: Gather Candidate Info
-
-You want to extract candidate details from the resume text and classify them as technical or non-technical. This step calls an LLM to parse the resume and return structured JSON, including the name, technical status, specialty, and the original resume text. The code reads resumeText from trigger data, prompts the LLM, and returns organized fields for use in subsequent steps.
-
-```typescript filename="src/mastra/index.ts" copy
-import { Agent } from '@mastra/core/agent';
-import { openai } from "@ai-sdk/openai";
-
-const recruiter = new Agent({
-  name: "Recruiter Agent",
-  instructions: `You are a recruiter.`,
-  model: openai("gpt-4o-mini"),
-})
-
-const gatherCandidateInfo = new Step({
-  id: "gatherCandidateInfo",
-  inputSchema: z.object({
-    resumeText: z.string(),
-  }),
-  outputSchema: z.object({
-    candidateName: z.string(),
-    isTechnical: z.boolean(),
-    specialty: z.string(),
-    resumeText: z.string(),
-  }),
-  execute: async ({ context }) => {
-    const resumeText = context?.getStepResult<{
-      resumeText: string;
-    }>("trigger")?.resumeText;
-
-    const prompt = `
-          Extract details from the resume text:
-          "${resumeText}"
-        `;
-
-    const res = await recruiter.generate(prompt, {
-      output: z.object({
-        candidateName: z.string(),
-        isTechnical: z.boolean(),
-        specialty: z.string(),
-        resumeText: z.string(),
-      }),
-    });
-
-    return res.object;
-  },
-});
-```
-
-## 3. Technical Question Step
-
-This step prompts a candidate who is identified as technical for more information about how they got into their specialty. It uses the entire resume text so the LLM can craft a relevant follow-up question. The code generates a question about the candidate's specialty.
-
-```typescript filename="src/mastra/index.ts" copy
-interface CandidateInfo {
-  candidateName: string;
-  isTechnical: boolean;
-  specialty: string;
-  resumeText: string;
-}
-
-const askAboutSpecialty = new Step({
-  id: "askAboutSpecialty",
-  outputSchema: z.object({
-    question: z.string(),
-  }),
-  execute: async ({ context }) => {
-    const candidateInfo = context?.getStepResult<CandidateInfo>(
-      "gatherCandidateInfo",
-    );
-
-    const prompt = `
-          You are a recruiter. Given the resume below, craft a short question
-          for ${candidateInfo?.candidateName} about how they got into "${candidateInfo?.specialty}".
-          Resume: ${candidateInfo?.resumeText}
-        `;
-    const res = await recruiter.generate(prompt);
-
-    return { question: res?.text?.trim() || "" };
-  },
-});
-```
-
-## 4. Behavioral Question Step
-
-If the candidate is non-technical, you want a different follow-up question. This step asks what interests them most about the role, again referencing their complete resume text. The code solicits a role-focused query from the LLM.
-
-```typescript filename="src/mastra/index.ts" copy
-const askAboutRole = new Step({
-  id: "askAboutRole",
-  outputSchema: z.object({
-    question: z.string(),
-  }),
-  execute: async ({ context }) => {
-    const candidateInfo = context?.getStepResult<CandidateInfo>(
-      "gatherCandidateInfo",
-    );
-
-    const prompt = `
-          You are a recruiter. Given the resume below, craft a short question
-          for ${candidateInfo?.candidateName} asking what interests them most about this role.
-          Resume: ${candidateInfo?.resumeText}
-        `;
-    const res = await recruiter.generate(prompt);
-    return { question: res?.text?.trim() || "" };
-  },
-});
-```
-
-## 5. Define the Workflow
-
-You now combine the steps to implement branching logic based on the candidate's technical status. The workflow first gathers candidate data, then either asks about their specialty or about their role, depending on isTechnical. The code chains gatherCandidateInfo with askAboutSpecialty and askAboutRole, and commits the workflow.
-
-```typescript filename="src/mastra/index.ts" copy
-const candidateWorkflow = new Workflow({
-  name: "candidate-workflow",
-  triggerSchema: z.object({
-    resumeText: z.string(),
-  }),
-});
-
-candidateWorkflow
-  .step(gatherCandidateInfo)
-  .then(askAboutSpecialty, {
-    when: { "gatherCandidateInfo.isTechnical": true },
-  })
-  .after(gatherCandidateInfo)
-  .step(askAboutRole, {
-    when: { "gatherCandidateInfo.isTechnical": false },
-  });
-
-candidateWorkflow.commit();
-```
-
-## 6. Execute the Workflow
-
-```typescript filename="src/mastra/index.ts" copy
-const mastra = new Mastra({
-  workflows: {
-    candidateWorkflow,
-  },
-});
-
-(async () => {
-  const { runId, start } = mastra.getWorkflow("candidateWorkflow").createRun();
-
-  console.log("Run", runId);
-
-  const runResult = await start({
-    triggerData: { resumeText: "Simulated resume content..." },
-  });
-
-  console.log("Final output:", runResult.results);
-})();
-```
-
-You've just built a workflow to parse a resume and decide which question to ask based on the candidate's technical abilities. Congrats and happy hacking!