@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.1

package/.docs/raw/guides/guide/chef-michel.mdx

@@ -0,0 +1,271 @@
+---
+title: "Guide: Building an AI Chef Assistant | Mastra Agent Guides"
+description: Guide on creating a Chef Assistant agent in Mastra to help users cook meals with available ingredients.
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import YouTube from "@site/src/components/YouTube-player";
+
+# Building an AI Chef Assistant
+
+In this guide, you'll create a "Chef Assistant" agent that helps users cook meals with available ingredients.
+
+You'll learn how to create the agent and register it with Mastra. Next, you'll interact with the agent through your terminal and get to know different response formats. Lastly, you'll access the agent through Mastra's local API endpoints.
+
+<YouTube id="_tZhOqHCrF0" />
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](/models/v1)
+- An existing Mastra project (Follow the [installation guide](/docs/v1/getting-started/installation) to set up a new project)
+
+## Creating the Agent
+
+To create an agent in Mastra use the `Agent` class to define it and then register it with Mastra.
+
+<Steps>
+
+<StepItem>
+
+Create a new file `src/mastra/agents/chefAgent.ts` and define your agent:
+
+```ts copy title="src/mastra/agents/chefAgent.ts"
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+export const chefAgent = new Agent({
+  id: "chef-agent",
+  name: "chef-agent",
+  instructions:
+    "You are Michel, a practical and experienced home chef" +
+    "You help people cook with whatever ingredients they have available.",
+  model: openai("gpt-4o-mini"),
+});
+```
+
+</StepItem>
+
+<StepItem>
+
+In your `src/mastra/index.ts` file, register the agent:
+
+```ts copy title="src/mastra/index.ts" {2, 5}
+import { Mastra } from "@mastra/core";
+import { chefAgent } from "./agents/chefAgent";
+
+export const mastra = new Mastra({
+  agents: { chefAgent },
+});
+```
+
+</StepItem>
+
+</Steps >
+
+## Interacting with the Agent
+
+Depending on your requirements you can interact and get responses from the agent in different formats. In the following steps you'll learn how to generate, stream, and get structured output.
+
+<Steps>
+
+<StepItem>
+
+Create a new file `src/index.ts` and add a `main()` function to it. Inside, craft a query to ask the agent and log its response.
+
+```ts copy title="src/index.ts"
+import { chefAgent } from "./mastra/agents/chefAgent";
+
+async function main() {
+  const query =
+    "In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make?";
+  console.log(`Query: ${query}`);
+
+  const response = await chefAgent.generate([{ role: "user", content: query }]);
+  console.log("\n👨‍🍳 Chef Michel:", response.text);
+}
+
+main();
+```
+
+Afterwards, run the script:
+
+```bash copy
+npx bun src/index.ts
+```
+
+You should get an output similar to this:
+
+```
+Query: In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make?
+
+👨‍🍳 Chef Michel: You can make a delicious pasta al pomodoro! Here's how...
+```
+
+</StepItem>
+
+<StepItem>
+
+In the previous example you might have waited a bit for the response without any sign of progress. To show the agent's output as it creates it you should instead stream its response to the terminal.
+
+```ts copy title="src/index.ts"
+import { chefAgent } from "./mastra/agents/chefAgent";
+
+async function main() {
+  const query =
+    "Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.";
+  console.log(`Query: ${query}`);
+
+  const stream = await chefAgent.stream([{ role: "user", content: query }]);
+
+  console.log("\n Chef Michel: ");
+
+  for await (const chunk of stream.textStream) {
+    process.stdout.write(chunk);
+  }
+
+  console.log("\n\n✅ Recipe complete!");
+}
+
+main();
+```
+
+Afterwards, run the script again:
+
+```bash copy
+npx bun src/index.ts
+```
+
+You should get an output similar to the one below. This time though you can read it line by line instead of one large block.
+
+```
+Query: Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.
+
+👨‍🍳 Chef Michel:
+Great! You can make a comforting chicken curry...
+
+✅ Recipe complete!
+```
+
+</StepItem>
+
+<StepItem>
+
+Instead of showing the agent's response to a human you might want to pass it along to another part of your code. For these instances your agent should return [structured output](/docs/v1/agents/overview#structured-output).
+
+Change your `src/index.ts` to the following:
+
+```ts copy title="src/index.ts"
+import { chefAgent } from "./mastra/agents/chefAgent";
+import { z } from "zod";
+
+async function main() {
+  const query =
+    "I want to make lasagna, can you generate a lasagna recipe for me?";
+  console.log(`Query: ${query}`);
+
+  // Define the Zod schema
+  const schema = z.object({
+    ingredients: z.array(
+      z.object({
+        name: z.string(),
+        amount: z.string(),
+      }),
+    ),
+    steps: z.array(z.string()),
+  });
+
+  const response = await chefAgent.generate(
+    [{ role: "user", content: query }],
+    {
+      structuredOutput: {
+        schema,
+      },
+    },
+  );
+  console.log("\n👨‍🍳 Chef Michel:", response.object);
+}
+
+main();
+```
+
+After running the script again you should get an output similar to this:
+
+```
+Query: I want to make lasagna, can you generate a lasagna recipe for me?
+
+👨‍🍳 Chef Michel: {
+  ingredients: [
+    { name: "Lasagna noodles", amount: "12 sheets" },
+    { name: "Ground beef", amount: "1 pound" },
+    // ...
+  ],
+  steps: [
+    "Preheat oven to 375°F (190°C).",
+    "Cook the lasagna noodles according to package instructions.",
+    // ...
+  ]
+}
+```
+
+</StepItem>
+
+</Steps >
+
+## Running the Agent Server
+
+Learn how to interact with your agent through Mastra's API.
+
+<Steps>
+
+<StepItem>
+
+You can run your agent as a service using the `mastra dev` command:
+
+```bash copy
+mastra dev
+```
+
+This will start a server exposing endpoints to interact with your registered agents. Within [Studio](/docs/v1/getting-started/studio) you can test your agent through a UI.
+
+</StepItem>
+
+<StepItem>
+
+By default, `mastra dev` runs on `http://localhost:4111`. Your Chef Assistant agent will be available at:
+
+```
+POST http://localhost:4111/api/agents/chefAgent/generate
+```
+
+</StepItem>
+
+<StepItem>
+
+You can interact with the agent using `curl` from the command line:
+
+```bash copy
+curl -X POST http://localhost:4111/api/agents/chefAgent/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {
+        "role": "user",
+        "content": "I have eggs, flour, and milk. What can I make?"
+      }
+    ]
+  }'
+```
+
+**Sample Response:**
+
+```json
+{
+  "text": "You can make delicious pancakes! Here's a simple recipe..."
+}
+```
+
+</StepItem>
+
+</Steps>

package/.docs/raw/guides/guide/notes-mcp-server.mdx

@@ -0,0 +1,450 @@
+---
+title: "Guide: Building a Notes MCP Server | Mastra Guide"
+description: "A step-by-step guide to creating a fully-featured MCP (Model Context Protocol) server for managing notes using the Mastra framework."
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+
+# Building a Notes MCP Server
+
+In this guide, you'll learn how to build a complete MCP (Model Context Protocol) server from scratch. This server will manage a collection of markdown notes and has these features:
+
+1. **List and Read Notes**: Allow clients to browse and view markdown files stored on the server
+2. **Write Notes**: Provide a tool for creating or updating notes
+3. **Offer Smart Prompts**: Generate contextual prompts, like creating a daily note template or summarizing existing content
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](/models/v1)
+- An existing Mastra project (Follow the [installation guide](/docs/v1/getting-started/installation) to set up a new project)
+
+## Adding necessary dependencies & files
+
+Before you can create an MCP server you first need to install additional dependencies and set up a boilerplate folder structure.
+
+<Steps>
+
+<StepItem>
+
+Add `@mastra/mcp` to your project:
+
+```bash copy
+npm install @mastra/mcp@beta
+```
+
+</StepItem>
+
+<StepItem>
+
+After following the default [installation guide](/docs/v1/getting-started/installation) your project will include files that are not relevant for this guide. You can safely remove them:
+
+```bash copy
+rm -rf src/mastra/agents src/mastra/workflows src/mastra/tools/weather-tool.ts
+```
+
+You should also change the `src/mastra/index.ts` file like so:
+
+```ts copy title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { PinoLogger } from "@mastra/loggers";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
+    url: ":memory:",
+  }),
+  logger: new PinoLogger({
+    name: "Mastra",
+    level: "info",
+  }),
+});
+```
+
+</StepItem>
+
+<StepItem>
+
+Create a dedicated directory for your MCP server's logic and a `notes` directory for your notes:
+
+```bash copy
+mkdir notes src/mastra/mcp
+```
+
+Create the following files:
+
+```bash copy
+touch src/mastra/mcp/{server,resources,prompts}.ts
+```
+
+- `server.ts`: Will contain the main MCP server configuration
+- `resources.ts`: Will handle listing and reading note files
+- `prompts.ts`: Will contain the logic for the smart prompts
+
+The resulting directory structure should look like this:
+
+```
+<your-project-name>/
+├── notes/
+└── src/
+    └── mastra/
+        ├── index.ts
+        ├── mcp/
+        │   ├── server.ts
+        │   ├── resources.ts
+        │   └── prompts.ts
+        └── tools/
+```
+
+</StepItem>
+
+</Steps>
+
+## Creating the MCP Server
+
+Let's add the MCP server!
+
+<Steps>
+
+<StepItem>
+
+In `src/mastra/mcp/server.ts`, define the MCP server instance:
+
+```typescript copy title="src/mastra/mcp/server.ts"
+import { MCPServer } from "@mastra/mcp";
+
+export const notes = new MCPServer({
+  id: "notes",
+  name: "Notes Server",
+  version: "0.1.0",
+  tools: {},
+});
+```
+
+Register this MCP server in your Mastra instance at `src/mastra/index.ts`. The key `notes` is the public identifier for your MCP server:
+
+```typescript copy title="src/mastra/index.ts" {4, 15-17}
+import { Mastra } from "@mastra/core";
+import { PinoLogger } from "@mastra/loggers";
+import { LibSQLStore } from "@mastra/libsql";
+import { notes } from "./mcp/server";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
+    url: ":memory:",
+  }),
+  logger: new PinoLogger({
+    name: "Mastra",
+    level: "info",
+  }),
+  mcpServers: {
+    notes,
+  },
+});
+```
+
+</StepItem>
+
+<StepItem>
+
+Resource handlers allow clients to discover and read the content your server manages. Implement handlers to work with markdown files in the `notes` directory. Add to the `src/mastra/mcp/resources.ts` file:
+
+```typescript copy title="src/mastra/mcp/resources.ts"
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import type { MCPServerResources, Resource } from "@mastra/mcp";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const NOTES_DIR = path.resolve(__dirname, "../../notes"); // relative to the default output directory
+
+const listNoteFiles = async (): Promise<Resource[]> => {
+  try {
+    await fs.mkdir(NOTES_DIR, { recursive: true });
+    const files = await fs.readdir(NOTES_DIR);
+    return files
+      .filter((file) => file.endsWith(".md"))
+      .map((file) => {
+        const title = file.replace(".md", "");
+        return {
+          uri: `notes://${title}`,
+          name: title,
+          description: `A note about ${title}`,
+          mime_type: "text/markdown",
+        };
+      });
+  } catch (error) {
+    console.error("Error listing note resources:", error);
+    return [];
+  }
+};
+
+const readNoteFile = async (uri: string): Promise<string | null> => {
+  const title = uri.replace("notes://", "");
+  const notePath = path.join(NOTES_DIR, `${title}.md`);
+  try {
+    return await fs.readFile(notePath, "utf-8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      console.error(`Error reading resource ${uri}:`, error);
+    }
+    return null;
+  }
+};
+
+export const resourceHandlers: MCPServerResources = {
+  listResources: listNoteFiles,
+  getResourceContent: async ({ uri }: { uri: string }) => {
+    const content = await readNoteFile(uri);
+    if (content === null) return { text: "" };
+    return { text: content };
+  },
+};
+```
+
+Register these resource handlers in `src/mastra/mcp/server.ts`:
+
+```typescript copy title="src/mastra/mcp/server.ts" {2, 8}
+import { MCPServer } from "@mastra/mcp";
+import { resourceHandlers } from "./resources";
+
+export const notes = new MCPServer({
+  id: "notes",
+  name: "Notes Server",
+  version: "0.1.0",
+  tools: {},
+  resources: resourceHandlers,
+});
+```
+
+</StepItem>
+
+<StepItem title="Implement and Register a Tool">
+
+Tools are the actions your server can perform. Let's create a `write` tool.
+First, define the tool in `src/mastra/tools/write-note.ts`:
+
+```typescript copy title="src/mastra/tools/write-note.ts"
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { fileURLToPath } from "url";
+import path from "node:path";
+import fs from "fs/promises";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const NOTES_DIR = path.resolve(__dirname, "../../../notes");
+
+export const writeNoteTool = createTool({
+  id: "write",
+  description: "Write a new note or overwrite an existing one.",
+  inputSchema: z.object({
+    title: z
+      .string()
+      .nonempty()
+      .describe("The title of the note. This will be the filename."),
+    content: z
+      .string()
+      .nonempty()
+      .describe("The markdown content of the note."),
+  }),
+  outputSchema: z.string().nonempty(),
+  execute: async (inputData) => {
+    try {
+      const { title, content } = inputData;
+      const filePath = path.join(NOTES_DIR, `${title}.md`);
+      await fs.mkdir(NOTES_DIR, { recursive: true });
+      await fs.writeFile(filePath, content, "utf-8");
+      return `Successfully wrote to note \"${title}\".`;
+    } catch (error: any) {
+      return `Error writing note: ${error.message}`;
+    }
+  },
+});
+```
+
+Register this tool in `src/mastra/mcp/server.ts`:
+
+```typescript copy title="src/mastra/mcp/server.ts"
+import { MCPServer } from "@mastra/mcp";
+import { resourceHandlers } from "./resources";
+import { writeNoteTool } from "../tools/write-note";
+
+export const notes = new MCPServer({
+  id: "notes",
+  name: "Notes Server",
+  version: "0.1.0",
+  resources: resourceHandlers,
+  tools: {
+    write: writeNoteTool,
+  },
+});
+```
+
+</StepItem>
+
+<StepItem title="Implement and Register Prompts">
+
+Prompt handlers provide ready-to-use prompts for clients. You'll add these three:
+
+- Daily note
+- Summarize a note
+- Brainstorm ideas
+
+This requires a few markdown-parsing libraries you need to install:
+
+```bash copy
+npm install unified remark-parse gray-matter @types/unist
+```
+
+Implement the prompts in `src/mastra/mcp/prompts.ts`:
+
+```typescript copy title="src/mastra/mcp/prompts.ts"
+import type { MCPServerPrompts } from "@mastra/mcp";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import matter from "gray-matter";
+import type { Node } from "unist";
+
+const prompts = [
+  {
+    name: "new_daily_note",
+    description: "Create a new daily note.",
+    version: "1.0.0",
+  },
+  {
+    name: "summarize_note",
+    description: "Give me a TL;DR of the note.",
+    version: "1.0.0",
+  },
+  {
+    name: "brainstorm_ideas",
+    description: "Brainstorm new ideas based on a note.",
+    version: "1.0.0",
+  },
+];
+
+function stringifyNode(node: Node): string {
+  if ("value" in node && typeof node.value === "string") return node.value;
+  if ("children" in node && Array.isArray(node.children))
+    return node.children.map(stringifyNode).join("");
+  return "";
+}
+
+export async function analyzeMarkdown(md: string) {
+  const { content } = matter(md);
+  const tree = unified().use(remarkParse).parse(content);
+  const headings: string[] = [];
+  const wordCounts: Record<string, number> = {};
+  let currentHeading = "untitled";
+  wordCounts[currentHeading] = 0;
+  tree.children.forEach((node) => {
+    if (node.type === "heading" && node.depth === 2) {
+      currentHeading = stringifyNode(node);
+      headings.push(currentHeading);
+      wordCounts[currentHeading] = 0;
+    } else {
+      const textContent = stringifyNode(node);
+      if (textContent.trim()) {
+        wordCounts[currentHeading] =
+          (wordCounts[currentHeading] || 0) + textContent.split(/\\s+/).length;
+      }
+    }
+  });
+  return { headings, wordCounts };
+}
+
+const getPromptMessages: MCPServerPrompts["getPromptMessages"] = async ({
+  name,
+  args,
+}) => {
+  switch (name) {
+    case "new_daily_note":
+      const today = new Date().toISOString().split("T")[0];
+      return [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Create a new note titled \"${today}\" with sections: \"## Tasks\", \"## Meetings\", \"## Notes\".`,
+          },
+        },
+      ];
+    case "summarize_note":
+      if (!args?.noteContent) throw new Error("No content provided");
+      const metaSum = await analyzeMarkdown(args.noteContent as string);
+      return [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Summarize each section in ≤ 3 bullets.\\n\\n### Outline\\n${metaSum.headings.map((h) => `- ${h} (${metaSum.wordCounts[h] || 0} words)`).join("\\n")}`.trim(),
+          },
+        },
+      ];
+    case "brainstorm_ideas":
+      if (!args?.noteContent) throw new Error("No content provided");
+      const metaBrain = await analyzeMarkdown(args.noteContent as string);
+      return [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Brainstorm 3 ideas for underdeveloped sections below ${args?.topic ? `on ${args.topic}` : "."}\\n\\nUnderdeveloped sections:\\n${metaBrain.headings.length ? metaBrain.headings.map((h) => `- ${h}`).join("\\n") : "- (none, pick any)"}`,
+          },
+        },
+      ];
+    default:
+      throw new Error(`Prompt \"${name}\" not found`);
+  }
+};
+
+export const promptHandlers: MCPServerPrompts = {
+  listPrompts: async () => prompts,
+  getPromptMessages,
+};
+```
+
+Register these prompt handlers in `src/mastra/mcp/server.ts`:
+
+```typescript copy title="src/mastra/mcp/server.ts"
+import { MCPServer } from "@mastra/mcp";
+import { resourceHandlers } from "./resources";
+import { writeNoteTool } from "../tools/write-note";
+import { promptHandlers } from "./prompts";
+
+export const notes = new MCPServer({
+  id: "notes",
+  name: "Notes Server",
+  version: "0.1.0",
+  resources: resourceHandlers,
+  prompts: promptHandlers,
+  tools: {
+    write: writeNoteTool,
+  },
+});
+```
+
+</StepItem>
+
+</Steps>
+
+## Run the Server
+
+Great, you've authored your first MCP server! Now you can try it out by starting the Mastra dev server and opening [Studio](/docs/v1/getting-started/studio):
+
+```bash copy
+npm run dev
+```
+
+Open [`http://localhost:4111`](http://localhost:4111) in your browser. In the left sidebar, select **MCP Servers**. Select the **notes** MCP server.
+
+You'll now be presented with instructions on how to add the MCP server to your IDE. You're able to use this MCP server with any MCP Client. On the right side under **Available Tools** you can also select the **write** tool.
+
+Inside the **write** tool, try it out by providing `test` as a name and `this is a test` for the markdown content. After clicking on **Submit** you'll have a new `test.md` file inside `notes`.