@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/organized/code-examples/crypto-chatbot.md

@@ -0,0 +1,96 @@
+### package.json
+```json
+{
+  "name": "examples-crypto-chatbot",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbo",
+    "build": "tsx db/migrate && next build",
+    "start": "next start",
+    "lint": "next lint",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "npx tsx ./db/migrate.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@ai-sdk/react": "^1.1.21",
+    "@mastra/core": "link:../../packages/core",
+    "@mastra/memory": "link:../../packages/memory",
+    "@mastra/pg": "link:../../stores/pg",
+    "@next/env": "^15.2.2",
+    "@radix-ui/react-alert-dialog": "^1.1.6",
+    "@radix-ui/react-dialog": "^1.1.6",
+    "@radix-ui/react-dropdown-menu": "^2.1.6",
+    "@radix-ui/react-icons": "^1.3.2",
+    "@radix-ui/react-label": "^2.1.2",
+    "@radix-ui/react-select": "^2.1.6",
+    "@radix-ui/react-separator": "^1.1.2",
+    "@radix-ui/react-slot": "^1.1.2",
+    "@radix-ui/react-tooltip": "^1.1.8",
+    "@radix-ui/react-visually-hidden": "^1.1.2",
+    "@vercel/analytics": "^1.5.0",
+    "@vercel/blob": "^0.24.1",
+    "@vercel/postgres": "^0.10.0",
+    "ai": "latest",
+    "bcrypt-ts": "^5.0.3",
+    "class-variance-authority": "^0.7.1",
+    "classnames": "^2.5.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "diff-match-patch": "^1.0.5",
+    "dotenv": "^16.4.7",
+    "drizzle-orm": "^0.37.0",
+    "framer-motion": "^11.18.2",
+    "geist": "^1.3.1",
+    "lucide-react": "^0.446.0",
+    "next": "15.0.3-canary.2",
+    "next-auth": "5.0.0-beta.25",
+    "next-themes": "^0.3.0",
+    "orderedmap": "^2.1.1",
+    "pg": "^8.13.3",
+    "postgres": "^3.4.5",
+    "prosemirror-example-setup": "^1.2.3",
+    "prosemirror-inputrules": "^1.4.0",
+    "prosemirror-markdown": "^1.13.1",
+    "prosemirror-model": "^1.24.1",
+    "prosemirror-schema-basic": "^1.2.3",
+    "prosemirror-schema-list": "^1.5.1",
+    "prosemirror-state": "^1.4.3",
+    "prosemirror-view": "^1.38.1",
+    "react": "19.0.0-rc-45804af1-20241021",
+    "react-dom": "19.0.0-rc-45804af1-20241021",
+    "react-markdown": "^9.1.0",
+    "remark-gfm": "^4.0.1",
+    "server-only": "^0.0.1",
+    "sonner": "^1.7.4",
+    "swr": "^2.3.3",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss-animate": "^1.0.7",
+    "usehooks-ts": "^3.1.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.16",
+    "@types/d3-scale": "^4.0.9",
+    "@types/node": "^20.17.24",
+    "@types/pdf-parse": "^1.1.4",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "drizzle-kit": "^0.25.0",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "14.2.5",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-import-resolver-typescript": "^3.8.4",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-tailwindcss": "^3.18.0",
+    "postcss": "^8.5.3",
+    "prettier": "^3.5.3",
+    "tailwindcss": "^3.4.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "version": "0.0.1"
+}
+
+```

package/.docs/organized/code-examples/fireworks-r1.md

@@ -0,0 +1,159 @@
+### package.json
+```json
+{
+  "name": "fireworks-r1",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "chat": "bun run --watch src/chat.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.1.15",
+    "@ai-sdk/fireworks": "^0.1.14",
+    "@mastra/core": "workspace:*",
+    "@mastra/mcp": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "@types/tinycolor2": "^1.4.6",
+    "chalk": "^5.4.1",
+    "gradient-string": "^3.0.0",
+    "ora": "^8.2.0",
+    "tinycolor2": "^1.6.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.27",
+    "dotenv": "^16.4.7",
+    "mastra": "workspace:*",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}
+
+```
+
+### chat.ts
+```typescript
+import crypto from 'node:crypto';
+import { maskStreamTags } from '@mastra/core/utils';
+import tinycolor from 'tinycolor2';
+import ora from 'ora';
+import chalk from 'chalk';
+import Readline from 'readline';
+
+import 'dotenv/config.js';
+
+import gradient from 'gradient-string';
+import { agent } from './mastra/agents';
+
+type AsyncIterableStream<T> = AsyncIterable<T> & ReadableStream<T>;
+
+function makeThinkStream(textStream: AsyncIterableStream<string>) {
+  const thinking = ora({
+    text: chalk.bold(`thinking`),
+    spinner: {
+      interval: 80,
+      frames: ['⢎ ', '⠎⠁', '⠊⠑', '⠈⠱', ' ⡱', '⢀⡰', '⢄⡠', '⢆⡀'],
+    },
+    color: 'green',
+  });
+
+  let thought = ``;
+  const start = Date.now();
+  const grad = gradient(['darkslategray', 'white', 'midnightblue']);
+
+  return maskStreamTags(textStream, 'think', {
+    onStart: () => {
+      thinking.start();
+    },
+    onMask: chunk => {
+      if (chunk.includes(`think`)) return;
+      thought += chunk;
+      thought = thought
+        .substring(Math.max(0, thought.length - 80))
+        .split(`\n`)
+        .join(` `);
+      thinking.suffixText = grad(thought);
+    },
+    onEnd: () => {
+      thinking.suffixText = grad(thought.substring(Math.max(0, thought.length - 90)));
+      thinking.succeed(`thought ${chalk.bold(`for ${Math.ceil((Date.now() - start) / 1000)}s`)}`);
+      console.log(`\n${chalk.bold.green(`Fireworks R1:`)}`);
+    },
+  });
+}
+
+const resourceId = 'SOME_USER_ID';
+const threadId = crypto.randomUUID();
+async function main() {
+  console.clear(); // clear all previous output
+
+  while (true) {
+    const rl = Readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      history: ["What's the meaning of life?"],
+    });
+    process.stdout.write(`\n\n`);
+    const answer: string = await new Promise(res => {
+      rl.question(chalk.grey('\n> '), answer => {
+        setImmediate(() => res(answer));
+      });
+    });
+    console.log(); // print a line between prompt and response
+
+    const { textStream } = await agent.stream(answer, {
+      threadId,
+      resourceId,
+    });
+
+    for await (const chunk of makeThinkStream(textStream)) {
+      process.stdout.write(chalk.hex(tinycolor('seagreen').toHex())(chunk));
+    }
+    rl.close();
+  }
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { fireworks } from '@ai-sdk/fireworks';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+
+if (!process.env.FIREWORKS_API_KEY) {
+  throw new Error(`FIREWORKS_API_KEY env var is required for this example to work`);
+}
+
+export const agent = new Agent({
+  model: fireworks(`accounts/fireworks/models/deepseek-r1`),
+
+  name: 'Example agent',
+  instructions: `You are a helpful and intelligent AI agent.`,
+  memory: new Memory(),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { createLogger } from '@mastra/core/logger';
+import { agent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { agent },
+  logger: createLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+});
+
+```

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

@@ -0,0 +1,63 @@
+### package.json
+```json
+{
+  "name": "examples-mcp-registry-registry",
+  "type": "module",
+  "private": true,
+  "description": "",
+  "main": "index.js",
+  "version": "0.0.1",
+  "scripts": {
+    "start-deployed": "npx bun src/with-deployed.ts",
+    "start": "npx bun src/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/mcp": "workspace:*",
+    "@mastra/mcp-registry-registry": "workspace:*",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  }
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { MCPConfiguration } from '@mastra/mcp';
+
+const mcp = new MCPConfiguration({
+  servers: {
+    registry: {
+      command: 'node',
+      args: ['../../packages/mcp-registry-registry/dist/stdio.js'],
+    },
+  },
+});
+
+export const mcpRegistryAgent = new Agent({
+  name: 'MCP Registry Agent',
+  instructions: `You are a helpful assistant that provides information about MCP registries. You can search for registries by ID, tag, or name.`,
+  model: openai('gpt-4o'),
+  tools: await mcp.getTools(),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+import { createLogger } from '@mastra/core/logger';
+import { mcpRegistryAgent } from './agents/index';
+
+export const mastra = new Mastra({
+  agents: { mcpRegistryAgent },
+  logger: createLogger({ name: 'MCP Registry', level: 'info' }),
+});
+
+```

package/.docs/organized/code-examples/memory-todo-agent.md

@@ -0,0 +1,164 @@
+### package.json
+```json
+{
+  "name": "memory-todo-agent",
+  "type": "module",
+  "description": "",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "chat": "bun run src/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "ai": "latest",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0"
+  },
+  "version": "0.1.6"
+}
+
+```
+
+### index.ts
+```typescript
+import { maskStreamTags } from '@mastra/core/utils';
+import chalk from 'chalk';
+import { randomUUID } from 'crypto';
+import ora from 'ora';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra/index';
+
+const agent = mastra.getAgent('todoAgent');
+
+let threadId = ``;
+threadId = randomUUID();
+threadId = `d4e58927-ca27-46f9-8559-0c792e76e6f6`; // long thread
+console.log(threadId);
+
+const resourceId = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n👨‍🍳 Agent:`);
+  let message = '';
+
+  const memorySpinner = ora('saving memory');
+
+  const maskedStream = maskStreamTags(res.textStream, 'working_memory', {
+    onStart: () => memorySpinner.start(),
+    onEnd: () => {
+      if (memorySpinner.isSpinning) {
+        memorySpinner.succeed();
+        process.stdin.resume();
+      }
+    },
+  });
+
+  for await (const chunk of maskedStream) {
+    process.stdout.write(chunk);
+  }
+
+  return message;
+}
+
+async function main() {
+  const isFirstChat = Boolean(await agent.getMemory()?.getThreadById({ threadId })) === false;
+
+  await logRes(
+    await agent.stream(
+      [
+        {
+          role: 'system',
+          content: !isFirstChat
+            ? `Chat with user started now ${new Date().toISOString()}. Don't mention this message. This means some time has passed between this message and the one before. The user left and came back again. Say something to start the conversation up again.`
+            : `Chat with user started now ${new Date().toISOString()}.`,
+        },
+      ],
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  const rl = Readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  while (true) {
+    const answer: string = await new Promise(res => {
+      rl.question(chalk.grey('\n> '), answer => {
+        setImmediate(() => res(answer));
+      });
+    });
+
+    await logRes(
+      await agent.stream(answer, {
+        threadId,
+        resourceId,
+      }),
+    );
+  }
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+
+const memory = new Memory({
+  options: {
+    lastMessages: 1,
+    semanticRecall: false,
+    workingMemory: {
+      enabled: true,
+      template: `
+# Todo List
+## Active Items
+- Example (Due: Feb 7 3028, Started: Feb 7 2025)
+  - Description: This is an example task - replace with whatever the user needs
+
+## Completed Items
+- None yet
+`,
+    },
+  },
+});
+
+export const todoAgent = new Agent({
+  name: 'TODO Agent',
+  instructions:
+    'You are a helpful todolist AI agent. Help the user manage their todolist. If there is no list yet ask them what to add! If there is a list always print it out when the chat starts. For each item add emojis, dates, titles (with an index number starting at 1), descriptions, and statuses. For each piece of info add an emoji to the left of it. Also support subtask lists with bullet points inside a box. Help the user timebox each task by asking them how long it will take. You MUST save the todolist in every response message by printing out <working_memory> blocks. If you do not save it in working_memory you will forget - you only have access to one previous message at any time. The user is expecting you to save your memory in every interaction. If the user expresses any preference on how the list should be displayed, save that info in working_memory so you know how to format it later.',
+
+  model: openai('gpt-4o-mini'),
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { todoAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { todoAgent },
+  logger: false,
+});
+
+```

package/.docs/organized/code-examples/memory-with-context.md

@@ -0,0 +1,167 @@
+### package.json
+```json
+{
+  "name": "memory-with-context",
+  "type": "module",
+  "description": "",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "chat": "bun run src/chat.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.2.1",
+    "@mastra/core": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### chat.ts
+```typescript
+import { maskStreamTags } from '@mastra/core/utils';
+import chalk from 'chalk';
+import { randomUUID } from 'crypto';
+import ora from 'ora';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra/index';
+
+const agent = mastra.getAgent('memoryAgent');
+
+let threadId = ``;
+threadId = randomUUID();
+// threadId = `0b3faadd-7e21-49ec-b613-e519448dab81`; // long thread
+console.log(threadId);
+
+const resourceId = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n👨‍🍳 Agent:`);
+  let message = '';
+
+  const thinkSpinner = ora('thinking');
+
+  const thinkMaskedStream = maskStreamTags(res.textStream, 'think', {
+    onStart: () => thinkSpinner.start(),
+    onEnd: () => {
+      if (thinkSpinner.isSpinning) {
+        thinkSpinner.succeed();
+        process.stdin.resume();
+      }
+    },
+  });
+
+  const memorySpinner = ora('saving memory');
+
+  const maskedStream = maskStreamTags(thinkMaskedStream, 'working_memory', {
+    onStart: () => memorySpinner.start(),
+    onEnd: () => {
+      if (memorySpinner.isSpinning) {
+        memorySpinner.succeed();
+        process.stdin.resume();
+      }
+    },
+  });
+
+  for await (const chunk of maskedStream) {
+    process.stdout.write(chunk);
+  }
+
+  return message;
+}
+
+async function main() {
+  const isFirstChat = Boolean(await agent.getMemory()?.getThreadById({ threadId })) === false;
+
+  await logRes(
+    await agent.stream(
+      [
+        {
+          role: 'system',
+          content: !isFirstChat
+            ? `Chat with user started now ${new Date().toISOString()}. Don't mention this message. This means some time has passed between this message and the one before. The user left and came back again. Say something to start the conversation up again.`
+            : `Chat with user started now ${new Date().toISOString()}.`,
+        },
+      ],
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  const rl = Readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  while (true) {
+    process.stdout.write(`\n`);
+    const answer: string = await new Promise(res => {
+      rl.question(chalk.grey('\n> '), answer => {
+        setImmediate(() => res(answer));
+      });
+    });
+
+    await logRes(
+      await agent.stream(answer, {
+        threadId,
+        resourceId,
+      }),
+    );
+  }
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+
+const memory = new Memory({
+  options: {
+    lastMessages: 4,
+    semanticRecall: {
+      topK: 1,
+      messageRange: 0,
+    },
+    workingMemory: {
+      enabled: true,
+    },
+  },
+});
+
+export const memoryAgent = new Agent({
+  name: 'Memory Agent',
+  instructions: 'You are a helpful AI agent, looking to assist however you can.',
+  model: openai('gpt-4o-mini'),
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { memoryAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { memoryAgent },
+});
+
+```