@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.16-alpha.1

package/.docs/guides/guide/notes-mcp-server.md

@@ -1,418 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# 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](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)
-
-## 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.
-
-1. Add `@mastra/mcp` to your project:
-
-   **npm**:
-
-   ```bash
-   npm install @mastra/mcp@latest
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add @mastra/mcp@latest
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn add @mastra/mcp@latest
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add @mastra/mcp@latest
-   ```
-
-2. After following the default [installation guide](https://mastra.ai/guides/getting-started/quickstart) your project will include files that are not relevant for this guide. You can safely remove them:
-
-   ```bash
-   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
-   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',
-     }),
-   })
-   ```
-
-3. Create a dedicated directory for your MCP server's logic and a `notes` directory for your notes:
-
-   ```bash
-   mkdir notes src/mastra/mcp
-   ```
-
-   Create the following files:
-
-   ```bash
-   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:
-
-   ```text
-   <your-project-name>/
-   ├── notes/
-   └── src/
-       └── mastra/
-           ├── index.ts
-           ├── mcp/
-           │   ├── server.ts
-           │   ├── resources.ts
-           │   └── prompts.ts
-           └── tools/
-   ```
-
-## Creating the MCP server
-
-Let's add the MCP server!
-
-1. In `src/mastra/mcp/server.ts`, define the MCP server instance:
-
-   ```typescript
-   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
-   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,
-     },
-   })
-   ```
-
-2. 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
-   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
-   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,
-   })
-   ```
-
-3. 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
-   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
-   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,
-     },
-   })
-   ```
-
-4. 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
-   npm install unified remark-parse gray-matter @types/unist
-   ```
-
-   Implement the prompts in `src/mastra/mcp/prompts.ts`:
-
-   ```typescript
-   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
-   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,
-     },
-   })
-   ```
-
-## 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](https://mastra.ai/docs/studio/overview):
-
-```bash
-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 selecting **Submit** you'll have a new `test.md` file inside `notes`.

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"]`.