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

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

@@ -0,0 +1,268 @@
+### package.json
+```json
+{
+  "name": "memory-with-upstash",
+  "type": "module",
+  "version": "1.0.1",
+  "description": "",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "prestart": "docker compose up -d",
+    "start": "npx bun src/index.ts",
+    "poststart": "docker compose down"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "@mastra/pg": "workspace:*",
+    "@mastra/upstash": "workspace:*"
+  },
+  "devDependencies": {
+    "dotenv": "^16.4.7",
+    "tsx": "^4.19.3"
+  }
+}
+
+```
+
+### bubble.ts
+```typescript
+type BubbleStyle = 'simple' | 'rounded';
+
+interface BubbleOptions {
+  style?: BubbleStyle;
+  maxWidth?: number;
+}
+
+interface BubbleCharacters {
+  topLeft: string;
+  topRight: string;
+  bottomLeft: string;
+  bottomRight: string;
+  horizontal: string;
+  vertical: string;
+}
+
+class MessageBubble {
+  private readonly defaultMaxWidth = 80;
+  private readonly defaultStyle: BubbleStyle = 'simple';
+
+  private readonly styleCharacters: Record<BubbleStyle, BubbleCharacters> = {
+    rounded: {
+      topLeft: '╭',
+      topRight: '╮',
+      bottomLeft: '╰',
+      bottomRight: '╯',
+      horizontal: '─',
+      vertical: '│',
+    },
+    simple: {
+      topLeft: '+',
+      topRight: '+',
+      bottomLeft: '+',
+      bottomRight: '+',
+      horizontal: '-',
+      vertical: '|',
+    },
+  };
+
+  private wrapText(text: string, maxWidth: number): string[] {
+    const lines: string[] = [];
+    const rawLines = text.split('\n');
+
+    rawLines.forEach((line: string) => {
+      const isListItem = line.trim().match(/^[-*•]\s/);
+      const indent = isListItem ? 2 : 0;
+      const availableWidth = maxWidth - indent;
+
+      if (line.trim() === '') {
+        lines.push('');
+        return;
+      }
+
+      let currentLine = '';
+      const words = line.trim().split(' ');
+
+      words.forEach((word: string) => {
+        if (currentLine === '' && isListItem) {
+          currentLine = '  ' + word;
+        } else if (currentLine === '') {
+          currentLine = word;
+        } else if ((currentLine + ' ' + word).length <= maxWidth) {
+          currentLine += ' ' + word;
+        } else {
+          lines.push(currentLine);
+          currentLine = isListItem ? '  ' + word : word;
+        }
+      });
+
+      if (currentLine) {
+        lines.push(currentLine);
+      }
+    });
+
+    return lines;
+  }
+
+  private validateOptions(options: BubbleOptions): void {
+    if (options.maxWidth && options.maxWidth < 20) {
+      throw new Error('maxWidth must be at least 20 characters');
+    }
+    if (options.style && !this.styleCharacters[options.style]) {
+      throw new Error('Invalid style. Must be either "simple" or "rounded"');
+    }
+  }
+
+  public print(message: string, options: BubbleOptions = {}): void {
+    this.validateOptions(options);
+
+    const maxWidth = options.maxWidth || this.defaultMaxWidth;
+    const style = options.style || this.defaultStyle;
+    const chars = this.styleCharacters[style];
+
+    // Process and wrap the text
+    const wrappedLines = this.wrapText(message, maxWidth - 4);
+    const contentWidth = Math.min(maxWidth - 4, Math.max(...wrappedLines.map(line => line.length)));
+
+    // Create borders
+    const topBorder = chars.topLeft + chars.horizontal.repeat(contentWidth + 2) + chars.topRight;
+    const bottomBorder = chars.bottomLeft + chars.horizontal.repeat(contentWidth + 2) + chars.bottomRight;
+
+    // Print the bubble
+    console.log(topBorder);
+    wrappedLines.forEach(line => {
+      console.log(`${chars.vertical} ${line.padEnd(contentWidth)} ${chars.vertical}`);
+    });
+    console.log(bottomBorder);
+    console.log('  ╰╯');
+  }
+}
+
+// Example usage:
+export const bubble = new MessageBubble();
+
+```
+
+### index.ts
+```typescript
+import { randomUUID } from 'crypto';
+
+import { mastra } from './mastra';
+
+function log(message: string) {
+  console.log(`\n>>Prompt: ${message}
+`);
+  return message;
+}
+
+const agent = mastra.getAgent('chefAgent');
+const threadId = randomUUID();
+const resourceId = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n👨‍🍳 Chef:`);
+  for await (const chunk of res.textStream) {
+    process.stdout.write(chunk);
+  }
+  console.log(`\n\n`);
+}
+
+async function main() {
+  await logRes(
+    await agent.stream(
+      log(
+        'In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make? Please keep your answer brief, only give me the high level steps.',
+      ),
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  await logRes(
+    await agent.stream(
+      log(
+        "Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.",
+      ),
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  await logRes(
+    await agent.stream(log('What did we cook before I went to my friends house?'), {
+      threadId,
+      resourceId,
+      memoryOptions: {
+        lastMessages: 3,
+      },
+    }),
+  );
+
+  process.exit(0);
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core';
+import { Memory } from '@mastra/memory';
+import { PgVector } from '@mastra/pg';
+import { UpstashStore } from '@mastra/upstash';
+
+const memory = new Memory({
+  storage: new UpstashStore({
+    url: 'http://localhost:8089',
+    token: 'test_token',
+  }),
+  vector: new PgVector(`postgresql://postgres:postgres@localhost:5433`),
+  options: {
+    lastMessages: 1,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+});
+
+export const chefAgent = new Agent({
+  name: 'chefAgent',
+  memory,
+  instructions:
+    'You are Michel, a practical and experienced home chef who helps people cook great meals with whatever ingredients they have available. Your first priority is understanding what ingredients and equipment the user has access to, then suggesting achievable recipes. You explain cooking steps clearly and offer substitutions when needed, maintaining a friendly and encouraging tone throughout.',
+  model: openai('gpt-4o'),
+});
+
+export const memoryAgent = new Agent({
+  name: 'Memory Agent',
+  memory,
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions. You may have conversations that last hours, days, months, or years. If you don't know it already you should ask for the users name and some info about them.",
+  model: openai('gpt-4o'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { chefAgent, memoryAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { chefAgent, memoryAgent },
+});
+
+```

package/.docs/organized/code-examples/quick-start.md

@@ -0,0 +1,129 @@
+### package.json
+```json
+{
+  "name": "examples-quick-start",
+  "type": "module",
+  "private": true,
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.17.27",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "zod": "^3.24.2"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.1.15",
+    "@ai-sdk/groq": "latest",
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "@mastra/loggers": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "ai": "latest"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### index.ts
+```typescript
+import { z } from 'zod';
+
+import { mastra } from './mastra';
+
+const specieSchema = z.object({
+  species: z.string(),
+});
+
+const main = async () => {
+  const agentCat = mastra.getAgent('catOne');
+
+  try {
+    const result = await agentCat.generate('What is the most popular cat species?', {
+      output: specieSchema,
+    });
+
+    const res = specieSchema.parse(result?.object);
+
+    console.log(res.species);
+
+    const { start } = mastra.getWorkflow('logCatWorkflow').createRun();
+
+    await start({ triggerData: { name: res.species } });
+  } catch (err) {
+    console.error(err);
+  }
+};
+
+main();
+
+```
+
+### mastra/agents/agent.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core';
+
+export const catOne = new Agent({
+  name: 'cat-one',
+  instructions:
+    'You are a feline expert with comprehensive knowledge of all cat species, from domestic breeds to wild big cats. As a lifelong cat specialist, you understand their behavior, biology, social structures, and evolutionary history in great depth. If you are asked for a specie name, do not return a paragraph, a succint two or three letter name of the species will suffice.',
+  model: openai('gpt-4o'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { createLogger, Mastra } from '@mastra/core';
+
+import { catOne } from './agents/agent';
+import { logCatWorkflow } from './workflow';
+
+export const mastra = new Mastra({
+  agents: { catOne },
+  workflows: {
+    logCatWorkflow,
+  },
+  logger: createLogger({
+    name: 'Mastra',
+    level: 'debug',
+  }),
+});
+
+```
+
+### mastra/workflow/index.ts
+```typescript
+import { Workflow, Step } from '@mastra/core';
+import { z } from 'zod';
+
+const logCatName = new Step({
+  id: 'logCatName',
+  outputSchema: z.object({
+    rawText: z.string(),
+  }),
+  execute: async ({ context }) => {
+    const name = context?.getStepResult<{ name: string }>('trigger')?.name;
+    console.log(`Hello, ${name} 🐈`);
+    return { rawText: `Hello ${name}` };
+  },
+});
+
+export const logCatWorkflow = new Workflow({
+  name: 'log-cat-workflow',
+  triggerSchema: z.object({
+    name: z.string(),
+  }),
+});
+
+logCatWorkflow.step(logCatName).commit();
+
+```

package/.docs/organized/code-examples/stock-price-tool.md

@@ -0,0 +1,124 @@
+### package.json
+```json
+{
+  "name": "examples-stock-price-tool",
+  "type": "module",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "dev": "mastra dev",
+    "test": "cross-env NODE_OPTIONS='--experimental-vm-modules --max-old-space-size=8192' jest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "jest": "^29.7.0",
+    "mastra": "workspace:*",
+    "ts-jest": "^29.2.6"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### index.ts
+```typescript
+import { mastra } from './mastra';
+
+async function main() {
+  const stockAgent = mastra.getAgent('stockAgent');
+  const response = await stockAgent.generate('What is the current stock price of Apple (AAPL)?');
+
+  const toolCall: any = response.toolResults.find((result: any) => result.toolName === 'stockPrices');
+
+  const currentPrice = toolCall?.result?.currentPrice;
+
+  console.log(`The current price of Apple (AAPL) is $${currentPrice}`);
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+
+import { stockPrices } from '../tools/stock-price';
+
+export const stockAgent = new 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-4o'),
+  tools: {
+    stockPrices,
+  },
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { stockAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { stockAgent },
+});
+
+```
+
+### mastra/tools/stock-price.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export 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 ({ context }) => {
+    console.log('Using tool to fetch stock price for', context.symbol);
+    return {
+      symbol: context.symbol,
+      currentPrice: await getStockPrice(context.symbol),
+    };
+  },
+});
+
+```
+
+### mastra/tools/tools.test.ts
+```typescript
+import { describe, it, expect } from 'vitest';
+
+import { getStockPrice } from './stock-price';
+
+describe('Test Tools', () => {
+  it('should run the stockPrices', async () => {
+    const result = await getStockPrice('AAPL');
+
+    console.log(result);
+    expect(result).toBeDefined();
+  });
+});
+
+```