@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

package/.docs/guides/guide/chef-michel.md

@@ -1,215 +0,0 @@
-# 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 video player](https://www.youtube-nocookie.com/embed/_tZhOqHCrF0)
-
-## Prerequisites
-
-- Node.js `v22.13.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) 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.
-
-1. Create a new file `src/mastra/agents/chefAgent.ts` and define your agent:
-
-   ```ts
-   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-5.1",
-   });
-   ```
-
-2. In your `src/mastra/index.ts` file, register the agent:
-
-   ```ts
-   import { Mastra } from "@mastra/core";
-   import { chefAgent } from "./agents/chefAgent";
-
-   export const mastra = new Mastra({
-     agents: { chefAgent },
-   });
-   ```
-
-## 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.
-
-1. 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
-   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
-   npx bun src/index.ts
-   ```
-
-   You should get an output similar to this:
-
-   ```text
-   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...
-   ```
-
-2. 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
-   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
-   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.
-
-   ```text
-   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!
-   ```
-
-3. 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](https://mastra.ai/docs/agents/overview).
-
-   Change your `src/index.ts` to the following:
-
-   ```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:
-
-   ```text
-   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.",
-     ]
-   }
-   ```
-
-## Running the Agent Server
-
-Learn how to interact with your agent through Mastra's API.
-
-1. You can run your agent as a service using the `mastra dev` command:
-
-   ```bash
-   mastra dev
-   ```
-
-   This will start a server exposing endpoints to interact with your registered agents. Within [Studio](https://mastra.ai/docs/getting-started/studio) you can test your agent through a UI.
-
-2. By default, `mastra dev` runs on `http://localhost:4111`. Your Chef Assistant agent will be available at:
-
-   ```text
-   POST http://localhost:4111/api/agents/chefAgent/generate
-   ```
-
-3. You can interact with the agent using `curl` from the command line:
-
-   ```bash
-   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..."
-   }
-   ```

package/.docs/guides/guide/code-review-bot.md

@@ -1,221 +0,0 @@
-# Building a Code Review Bot
-
-In this guide, you'll build a code review bot that automatically reviews pull requests using workspace skills. The bot loads coding standards from skill files and provides structured feedback. You'll learn how to create a workspace with a skills directory, define an [Agent Skill](https://agentskills.io) with review instructions and reference files, and connect it to an agent that performs automated reviews.
-
-## Prerequisites
-
-- Node.js `v22.13.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
-
-## Create the workspace
-
-In your `src/mastra/index.ts` file, import the [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) and [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) classes. On the `Workspace` instance, configure the `skills` option to point to a skills directory. The `skills` directory will live inside the filesystem's `basePath`.
-
-```typescript
-import { Mastra } from '@mastra/core';
-import { resolve } from 'node:path';
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: resolve(import.meta.dirname, '../../workspace'),
-  }),
-  skills: ['/skills'],
-});
-
-export const mastra = new Mastra({
-  workspace,
-});
-```
-
-At the root of your project, create a new folder called `workspace`. Inside that, create a `skills` folder. This is where you'll define the code standards skill in the next step.
-
-## Create the code standards skill
-
-Skills are structured directories containing a `SKILL.md` file with instructions for the agent. The code standards skill defines the review process and references a style guide.
-
-Inside `workspace/skills`, create a new folder called `code-standards`. Create a file called `SKILL.md` and add the review instructions.
-
-```markdown
----
-name: code-standards
-description: Automated code review standards and checks
----
-
-# Code Review Standards
-
-Review code systematically using these steps:
-
-1. **Critical Issues**: Security vulnerabilities, memory leaks, logic bugs, missing error handling
-2. **Code Quality**: Functions over 50 lines, code duplication, confusing names, missing types
-3. **Style Guide**: Check references/style-guide.md for naming and organization
-4. **Linting**: Flag common issues like use of `var`, leftover `console.log` statements, and `debugger` statements
-
-Provide feedback in this format:
-
-**Summary**: One sentence overview
-
-**Critical Issues**: List with line numbers
-
-**Suggestions**: Improvements that would help
-
-**Positive Notes**: What the code does well
-```
-
-Inside `workspace/skills/code-standards`, create a `references` folder to hold reference materials for the skill. Author a style guide file that outlines the project's coding conventions with the file name `style-guide.md`.
-
-````markdown
-# Style Guide
-
-## Naming
-
-- Variables/Functions: `camelCase`
-- Constants: `UPPER_SNAKE_CASE`
-- Files: `kebab-case.ts`
-- Booleans: Start with `is`, `has`, `should`
-
-## Code Organization
-
-```typescript
-// 1. Imports
-import { foo } from 'bar';
-
-// 2. Constants
-const MAX_SIZE = 100;
-
-// 3. Types
-interface User { id: string; }
-
-// 4. Functions
-function doSomething() {}
-
-// 5. Exports
-export { doSomething };
-```
-
-## Error Handling
-
-Always handle errors explicitly - never silently catch.
-
-## Comments
-
-Write "why" not "what".
-````
-
-## Create the review agent
-
-Now it's time to create the code review bot agent that uses the code-standards skill. Create a new file at `src/mastra/agents/code-reviewer.ts` and define the agent:
-
-```typescript
-import { Agent } from '@mastra/core/agent';
-
-export const codeReviewer = new Agent({
-  id: 'code-reviewer',
-  name: 'Code Review Bot',
-  instructions: `You are an automated code reviewer.
-
-When asked to review code:
-1. Activate the 'code-standards' skill
-2. Follow the review process from the skill
-3. Check against the style guide in skill references
-4. Be constructive and specific with line numbers`,
-  model: 'openai/gpt-4o',
-});
-```
-
-Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
-
-```typescript
-import { Mastra } from '@mastra/core';
-import { resolve } from 'node:path';
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
-import { codeReviewer } from './agents/code-reviewer';
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: resolve(import.meta.dirname, '../../workspace'),
-  }),
-  skills: ['/skills'],
-});
-
-export const mastra = new Mastra({
-  workspace,
-  agents: { codeReviewer },
-});
-```
-
-## Test the bot
-
-Start Mastra Studio and interact with the code review bot to see it in action.
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Open [localhost:4111](http://localhost:4111) and navigate to the code reviewer agent.
-
-Inside the chat input, provide a code snippet for review, such as:
-
-```text
-Review this code:
-
-function getData(id) {
-  var result = fetch('/api/data/' + id);
-  console.log(result);
-  return result;
-}
-```
-
-The bot should activate the `code-standards` skill and provide structured feedback. Since agent responses are non-deterministic, your output may vary, but you should see something similar to:
-
-```md
-**Summary**: Function has several issues with variable declaration,
-debugging statements, and missing error handling.
-
-**Critical Issues**:
-- Missing error handling for fetch (line 2)
-- No async/await for asynchronous operation (line 2)
-
-**Suggestions**:
-- Use const instead of var (line 2)
-- Remove console.log before committing (line 3)
-- Add TypeScript type for id parameter
-- Use template literals instead of concatenation
-
-**Positive Notes**:
-- Function name is clear and descriptive
-```
-
-## Next steps
-
-You can extend this bot to:
-
-- Add skills for different languages or frameworks
-- Create skills for security checks and performance reviews
-- Integrate with GitHub Actions for automatic PR reviews
-- Build a PR comment bot that leaves inline feedback
-
-Learn more:
-
-- [Agent Skills spec](https://agentskills.io)