@mastra/mcp-docs-server 1.2.15-alpha.19 → 1.2.15-alpha.21

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

@@ -1,211 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# 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. You'll then access the agent through Mastra's local API endpoints.
-
-## 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 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.6-sol',
-   })
-   ```
-
-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 },
-   })
-   ```
-
-## Interact 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/structured-output).
-
-   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.",
-     ]
-   }
-   ```
-
-## Run 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/studio/overview) 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/publishing-mcp-server.md

@@ -1,137 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Publishing an MCP server
-
-This example guides you through setting up a basic Mastra MCPServer using the stdio transport, building it, and preparing it for publishing to NPM.
-
-## Install dependencies
-
-Install the necessary packages:
-
-**npm**:
-
-```bash
-npm install @mastra/mcp @mastra/core tsup
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/mcp @mastra/core tsup
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/mcp @mastra/core tsup
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/mcp @mastra/core tsup
-```
-
-## Setting up an MCP server
-
-1. Create a file for your stdio server, for example, `src/mastra/stdio.ts`.
-
-2. Add the following code to the file. Remember to import your actual Mastra tools and name the server appropriately.
-
-   ```typescript
-   #!/usr/bin/env node
-   import { MCPServer } from '@mastra/mcp'
-   import { weatherTool } from './tools'
-
-   const server = new MCPServer({
-     name: 'my-mcp-server',
-     version: '1.0.0',
-     tools: { weatherTool },
-   })
-
-   server.startStdio().catch(error => {
-     console.error('Error running MCP server:', error)
-     process.exit(1)
-   })
-   ```
-
-3. Update your `package.json` to include the `bin` entry pointing to your built server file and a script to build the server with both ESM and CJS outputs.
-
-   ```json
-   {
-     "bin": "dist/stdio.mjs",
-     "scripts": {
-       "build:mcp": "tsup src/mastra/stdio.ts --format esm,cjs --no-splitting --dts && echo '#!/usr/bin/env node' | cat - dist/stdio.mjs > temp && mv temp dist/stdio.mjs && chmod +x dist/stdio.mjs"
-     }
-   }
-   ```
-
-   The build command generates both ESM (`.mjs`) and CJS (`.cjs`) outputs for maximum compatibility. The shebang (`#!/usr/bin/env node`) is prepended to the ESM artifact to make it directly executable, and the `bin` entry points to this file.
-
-4. Run the build command:
-
-   **npm**:
-
-   ```bash
-   npm run build:mcp
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm run build:mcp
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn build:mcp
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun run build:mcp
-   ```
-
-   This will compile your server code into both ESM and CJS formats and make the ESM output file executable. On Unix-like systems, the `chmod +x` step makes the file directly executable. Windows users may need to use WSL or handle execution through Node.js directly.
-
-## Publishing to NPM
-
-To make your MCP server available for others (or yourself) to use via `npx` or as a dependency, you can publish it to NPM.
-
-1. Ensure you have an NPM account and are logged in (`npm login`).
-
-2. Make sure your package name in `package.json` is unique and available.
-
-3. Run the publish command from your project root after building:
-
-   ```bash
-   npm publish --access public
-   ```
-
-   For more details on publishing packages, refer to the [NPM documentation](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages).
-
-## Using a published MCP server
-
-Once published, your MCP server can be used by an `MCPClient` by specifying the command to run your package. You can also use any other MCP client like Claude desktop, Cursor, or Windsurf.
-
-```typescript
-import { MCPClient } from '@mastra/mcp'
-
-const mcp = new MCPClient({
-  servers: {
-    // Give this MCP server instance a name
-    yourServerName: {
-      command: 'npx',
-      args: ['-y', '@your-org-name/your-package-name@latest'], // Replace with your package name
-    },
-  },
-})
-
-// You can then get tools or toolsets from this configuration to use in your agent
-const tools = await mcp.listTools()
-const toolsets = await mcp.listToolsets()
-```
-
-Note: If you published without an organization scope, the `args` might be `["-y", "your-package-name@latest"]`.

package/.docs/guides/guide/slack-assistant.md

@@ -1,193 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Building a Slack assistant
-
-In this guide, you'll build a Mastra agent that responds to messages and mentions on Slack. You'll learn how to configure a channel adapter, set up a Slack app with the right permissions, connect it to your agent via a webhook, and test the interaction.
-
-## 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) if needed.
-- A [Slack workspace](https://slack.com/) where you can create apps
-
-## Create the agent
-
-Install the Slack adapter:
-
-**npm**:
-
-```bash
-npm install @chat-adapter/slack
-```
-
-**pnpm**:
-
-```bash
-pnpm add @chat-adapter/slack
-```
-
-**Yarn**:
-
-```bash
-yarn add @chat-adapter/slack
-```
-
-**Bun**:
-
-```bash
-bun add @chat-adapter/slack
-```
-
-Create a new file `src/mastra/agents/slack-agent.ts` and define your agent:
-
-```ts
-import { Agent } from '@mastra/core/agent'
-import { createSlackAdapter } from '@chat-adapter/slack'
-
-export const slackAgent = new Agent({
-  id: 'slack-agent',
-  name: 'Slack Agent',
-  instructions:
-    'You are a helpful assistant. Answer questions, help with tasks, and have natural conversations.',
-  model: 'anthropic/claude-opus-4-7',
-  channels: {
-    adapters: {
-      slack: createSlackAdapter(),
-    },
-  },
-})
-```
-
-The `channels` property tells Mastra to generate a webhook endpoint for each adapter. In this case, the Slack adapter handles event verification, signature validation, and message formatting automatically.
-
-Register the agent in your `src/mastra/index.ts` file:
-
-```ts
-import { Mastra } from '@mastra/core'
-import { slackAgent } from './agents/slack-agent'
-
-export const mastra = new Mastra({
-  agents: { slackAgent },
-})
-```
-
-## Create a Slack app
-
-You need a Slack app to connect your agent to a workspace.
-
-Go to <https://api.slack.com/apps> and select **Create New App** > **From scratch**. Give it a name and select your workspace.
-
-Navigate to **OAuth & Permissions** and scroll to **Bot Token Scopes**. Add the following scopes:
-
-- `app_mentions:read`
-- `channels:history`
-- `channels:read`
-- `chat:write`
-- `users:read`
-
-At the top of **OAuth & Permissions**, select **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
-
-Go to **Basic Information** > **App Credentials** and copy the **Signing Secret** (e.g. `c3a4...`).
-
-Ensure **Socket Mode** is turned **off** under **Settings** > **Socket Mode**.
-
-Add the credentials to your `.env` file:
-
-```bash
-SLACK_SIGNING_SECRET=your-signing-secret
-SLACK_BOT_TOKEN=xoxb-your-bot-token
-```
-
-The adapter reads these environment variables by default. See the [Chat SDK Slack adapter docs](https://chat-sdk.dev/adapters/slack) for more details.
-
-## Connect the webhook
-
-Slack delivers events to your agent via a webhook. Mastra generates this endpoint automatically for each channel adapter.
-
-Start the dev server:
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-During local development, Slack needs a public URL to reach your local server. Open a new terminal and start a tunnel:
-
-```bash
-npx cloudflared tunnel --url http://localhost:4111
-```
-
-This outputs a temporary public URL like `https://triple-arms-solutions-kit.trycloudflare.com`. The URL changes each time you restart the tunnel.
-
-In your Slack app settings, go to **Event Subscriptions** and toggle **Enable Events** to **On**.
-
-Set the **Request URL** to your tunnel URL with the agent webhook path:
-
-```text
-https://<your-tunnel-url>/api/agents/slack-agent/channels/slack/webhook
-```
-
-Slack sends a verification request. If your dev server is running, it responds with a green checkmark.
-
-Under **Subscribe to bot events**, add:
-
-- `app_mention`
-- `message.channels`
-
-Select **Save Changes**. Slack requires you to reinstall the app after changing event subscriptions. Go to **OAuth & Permissions** and select **Reinstall to Workspace** to apply the updated permissions.
-
-> **Note:** The tunnel URL is for local development only. When you [deploy your application](https://mastra.ai/docs/deployment/overview), update the **Request URL** in your Slack app's **Event Subscriptions** to your production URL (e.g. `https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook`).
-
-## Test the agent
-
-Before testing with Slack, you can refine your agent's behavior in [Studio](https://mastra.ai/docs/studio/overview). Open <http://localhost:4111/> to chat with your agent and adjust its instructions. Inspect traces to see how responses are generated.
-
-Once you're happy with the agent's responses, test the Slack integration. Invite the bot to a channel in Slack:
-
-```text
-/invite @your-bot-name
-```
-
-Mention the bot in the channel:
-
-```text
-@your-bot-name What can you help me with?
-```
-
-The agent responds in the thread. Output may vary depending on the model and instructions.
-
-## Next steps
-
-You can extend this agent to:
-
-- [Deploy your application](https://mastra.ai/docs/deployment/overview) and update the Slack **Request URL** to your production endpoint
-- Add more adapters (Discord, Telegram) to the same agent so it responds on multiple platforms
-- Configure [multimodal content](https://mastra.ai/docs/capabilities/channels/overview) to let your agent process images, video, and audio shared in chat
-- Add [tools](https://mastra.ai/docs/agents/using-tools) to give the agent access to external APIs and data
-
-Learn more:
-
-- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
-- [Studio](https://mastra.ai/docs/studio/overview)
-- [Deployment overview](https://mastra.ai/docs/deployment/overview)
-- [Chat SDK adapter docs](https://chat-sdk.dev)

package/.docs/guides/guide/stock-agent.md

@@ -1,132 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Building an AI stock agent
-
-In this guide, you'll create an agent that fetches the previous day's closing stock price for a symbol. You'll create a tool and add it to an agent, then use the agent to fetch stock prices.
-
-## 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/stockAgent.ts` and define your agent:
-
-   ```ts
-   import { Agent } from '@mastra/core/agent'
-
-   export const stockAgent = new Agent({
-     id: 'stock-agent',
-     name: 'Stock 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.',
-     model: 'openai/gpt-5.6-sol',
-   })
-   ```
-
-2. In your `src/mastra/index.ts` file, register the agent:
-
-   ```ts
-   import { Mastra } from '@mastra/core'
-   import { stockAgent } from './agents/stockAgent'
-
-   export const mastra = new Mastra({
-     agents: { stockAgent },
-   })
-   ```
-
-## Creating the stock price tool
-
-The Stock Agent doesn't yet know anything about current stock prices. To change this, create a tool and add it to the agent.
-
-1. Create a new file `src/mastra/tools/stockPrices.ts`. Inside, add a `stockPrices` tool that will fetch the last day's closing stock price for a given symbol:
-
-   ```ts
-   import { createTool } from '@mastra/core/tools'
-   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']
-   }
-
-   export const stockPrices = createTool({
-     id: 'Get Stock Price',
-     inputSchema: z.object({
-       symbol: z.string(),
-     }),
-     description: `Fetches the last day's closing stock price for a given symbol`,
-     execute: async inputData => {
-       console.log('Using tool to fetch stock price for', inputData.symbol)
-       return {
-         symbol: inputData.symbol,
-         currentPrice: await getStockPrice(inputData.symbol),
-       }
-     },
-   })
-   ```
-
-2. Inside `src/mastra/agents/stockAgent.ts` import your newly created `stockPrices` tool and add it to the agent.
-
-   ```ts
-   import { Agent } from '@mastra/core/agent'
-   import { stockPrices } from '../tools/stockPrices'
-
-   export const stockAgent = new Agent({
-     id: 'stock-agent',
-     name: 'Stock 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.',
-     model: 'openai/gpt-5.6-sol',
-     tools: {
-       stockPrices,
-     },
-   })
-   ```
-
-## 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/studio/overview) you can test your `stockAgent` and `stockPrices` tool through a UI.
-
-2. By default, `mastra dev` runs on `http://localhost:4111`. Your Stock agent will be available at:
-
-   ```text
-   POST http://localhost:4111/api/agents/stockAgent/generate
-   ```
-
-3. You can interact with the agent using `curl` from the command line:
-
-   ```bash
-   curl -X POST http://localhost:4111/api/agents/stockAgent/generate \
-     -H "Content-Type: application/json" \
-     -d '{
-       "messages": [
-         { "role": "user", "content": "What is the current stock price of Apple (AAPL)?" }
-       ]
-     }'
-   ```
-
-   You should receive a JSON response similar to:
-
-   ```json
-   {
-     "text": "The current price of Apple (AAPL) is $174.55.",
-     "agent": "Stock Agent"
-   }
-   ```
-
-   This indicates that your agent successfully processed the request, used the `stockPrices` tool to fetch the stock price, and returned the result.