@mastra/mcp-docs-server 0.0.1-alpha.1

package/.docs/organized/changelogs/mastra.md

@@ -0,0 +1,302 @@
+# mastra
+
+## 0.4.0-alpha.2
+
+### Patch Changes
+
+- da8d9bb: Enable public dir copying if it exists
+- 5baf1ec: animate new traces
+- 65f2a4c: Add Mastra Docs MCP to the pnpm create mastra TUI with the option to install in Cursor or Windsurf
+- 9116d70: Handle the different workflow methods in workflow graph
+- 0709d99: add prop for dynamic empty text
+- Updated dependencies [cc7f392]
+- Updated dependencies [fc2f89c]
+- Updated dependencies [dfbb131]
+- Updated dependencies [0850b4c]
+- Updated dependencies [da8d9bb]
+- Updated dependencies [9116d70]
+  - @mastra/deployer@0.2.1-alpha.2
+  - @mastra/core@0.6.1-alpha.2
+
+## 0.4.0-alpha.1
+
+### Minor Changes
+
+- f9b6ab5: add Cerebras as a llm provider to create-mastra@latest
+
+### Patch Changes
+
+- 5052613: Added a new `mastra create --project-name <string>` flag so coder agents can create new Mastra projects with a one line command.
+- 1291e89: Add resizable-panel to playground-ui and use in agent and workflow sidebars
+- 9ba1e97: update playground ui for mastra and create-mastra
+- Updated dependencies [f4854ee]
+- Updated dependencies [afaf73f]
+- Updated dependencies [44631b1]
+- Updated dependencies [6e559a0]
+- Updated dependencies [5f43505]
+- Updated dependencies [61ad5a4]
+  - @mastra/core@0.6.1-alpha.1
+  - @mastra/deployer@0.2.1-alpha.1
+
+## 0.3.2-alpha.0
+
+### Patch Changes
+
+- 1405e46: update the Groq model the create-mastra@latest sets
+- Updated dependencies [7bcfaee]
+  - @mastra/core@0.6.1-alpha.0
+  - @mastra/deployer@0.2.1-alpha.0
+
+## 0.3.1
+
+### Patch Changes
+
+- c49f798: remove hardcoded localhost url in playground
+- 63cebd4: Fixed a bug with the new tool discovery feature where a missing tools/index.ts would crash the process
+- d3d6fae: Deprecate mastra dev --env flag
+- Updated dependencies [16b98d9]
+- Updated dependencies [1c8cda4]
+- Updated dependencies [95b4144]
+- Updated dependencies [3729dbd]
+- Updated dependencies [c2144f4]
+  - @mastra/core@0.6.0
+  - @mastra/deployer@0.2.0
+
+## 0.3.1-alpha.1
+
+### Patch Changes
+
+- c49f798: remove hardcoded localhost url in playground
+- 63cebd4: Fixed a bug with the new tool discovery feature where a missing tools/index.ts would crash the process
+- Updated dependencies [16b98d9]
+- Updated dependencies [1c8cda4]
+- Updated dependencies [95b4144]
+- Updated dependencies [c2144f4]
+  - @mastra/core@0.6.0-alpha.1
+  - @mastra/deployer@0.2.0-alpha.1
+
+## 0.3.1-alpha.0
+
+### Patch Changes
+
+- d3d6fae: Deprecate mastra dev --env flag
+- Updated dependencies [3729dbd]
+  - @mastra/core@0.5.1-alpha.0
+  - @mastra/deployer@0.1.9-alpha.0
+
+## 0.3.0
+
+### Minor Changes
+
+- dd7a09a: Added new MCPConfiguration class for managing multiple MCP server tools/toolsets. Fixed a bug where MCPClient env would overwrite PATH env var. Fixed a bug where MCP servers would be killed non-gracefully leading to printing huge errors on every code save when running mastra dev
+
+### Patch Changes
+
+- 5fae49e: Configurable timeout on npm create mastra
+- 91d2e30: Fix init in non npm project
+- 960690d: Improve client-js workflow watch dx
+- af7466e: fixes in playground ui
+- dbd9f2d: Handle different condition types on workflow graph
+- 07a7470: Move WorkflowTrigger to playground-ui package and use in dev playground
+- 52e0418: Split up action types between tools and workflows
+- a80bdaf: persist data in run tab in dev
+- e5149bb: Fix playground-ui agent-evals tab-content
+- 8deb34c: Better workflow watch api + watch workflow by runId
+- 36d970e: Make tools discovery work in mastra dev
+- 144b3d5: Update traces table UI, agent Chat UI
+  Fix get workflows breaking
+- 62565c1: --no-timeout npm create mastra flag
+- 9035565: Update tools dev playground inputs for different fieldtypes
+- fd4a1d7: Update cjs bundling to make sure files are split
+- Updated dependencies [a910463]
+- Updated dependencies [59df7b6]
+- Updated dependencies [22643eb]
+- Updated dependencies [6feb23f]
+- Updated dependencies [f2d6727]
+- Updated dependencies [7a7a547]
+- Updated dependencies [29f3a82]
+- Updated dependencies [3d0e290]
+- Updated dependencies [e9fbac5]
+- Updated dependencies [301e4ee]
+- Updated dependencies [ee667a2]
+- Updated dependencies [dfbe4e9]
+- Updated dependencies [dab255b]
+- Updated dependencies [1e8bcbc]
+- Updated dependencies [f6678e4]
+- Updated dependencies [9e81f35]
+- Updated dependencies [c93798b]
+- Updated dependencies [a85ab24]
+- Updated dependencies [dbd9f2d]
+- Updated dependencies [59df7b6]
+- Updated dependencies [caefaa2]
+- Updated dependencies [c151ae6]
+- Updated dependencies [52e0418]
+- Updated dependencies [d79aedf]
+- Updated dependencies [8deb34c]
+- Updated dependencies [c2dde91]
+- Updated dependencies [5d41958]
+- Updated dependencies [144b3d5]
+- Updated dependencies [03236ec]
+- Updated dependencies [3764e71]
+- Updated dependencies [df982db]
+- Updated dependencies [a171b37]
+- Updated dependencies [506f1d5]
+- Updated dependencies [02ffb7b]
+- Updated dependencies [731dd8a]
+- Updated dependencies [0461849]
+- Updated dependencies [2259379]
+- Updated dependencies [aeb5e36]
+- Updated dependencies [f2301de]
+- Updated dependencies [358f069]
+- Updated dependencies [fd4a1d7]
+- Updated dependencies [960690d]
+- Updated dependencies [c139344]
+  - @mastra/core@0.5.0
+  - @mastra/deployer@0.1.8
+
+## 0.3.0-alpha.12
+
+### Patch Changes
+
+- 07a7470: Move WorkflowTrigger to playground-ui package and use in dev playground
+- Updated dependencies [a85ab24]
+  - @mastra/core@0.5.0-alpha.12
+  - @mastra/deployer@0.1.8-alpha.12
+
+## 0.3.0-alpha.11
+
+### Patch Changes
+
+- dbd9f2d: Handle different condition types on workflow graph
+- 8deb34c: Better workflow watch api + watch workflow by runId
+- 36d970e: Make tools discovery work in mastra dev
+- fd4a1d7: Update cjs bundling to make sure files are split
+- Updated dependencies [7a7a547]
+- Updated dependencies [c93798b]
+- Updated dependencies [dbd9f2d]
+- Updated dependencies [8deb34c]
+- Updated dependencies [5d41958]
+- Updated dependencies [a171b37]
+- Updated dependencies [fd4a1d7]
+  - @mastra/deployer@0.1.8-alpha.11
+  - @mastra/core@0.5.0-alpha.11
+
+## 0.3.0-alpha.10
+
+### Minor Changes
+
+- dd7a09a: Added new MCPConfiguration class for managing multiple MCP server tools/toolsets. Fixed a bug where MCPClient env would overwrite PATH env var. Fixed a bug where MCP servers would be killed non-gracefully leading to printing huge errors on every code save when running mastra dev
+
+### Patch Changes
+
+- Updated dependencies [a910463]
+  - @mastra/core@0.5.0-alpha.10
+  - @mastra/deployer@0.1.8-alpha.10
+
+## 0.2.9-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [e9fbac5]
+- Updated dependencies [1e8bcbc]
+- Updated dependencies [aeb5e36]
+- Updated dependencies [f2301de]
+  - @mastra/deployer@0.1.8-alpha.9
+  - @mastra/core@0.5.0-alpha.9
+
+## 0.2.9-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [506f1d5]
+  - @mastra/core@0.5.0-alpha.8
+  - @mastra/deployer@0.1.8-alpha.8
+
+## 0.2.9-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [ee667a2]
+  - @mastra/core@0.5.0-alpha.7
+  - @mastra/deployer@0.1.8-alpha.7
+
+## 0.2.9-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [f6678e4]
+  - @mastra/core@0.5.0-alpha.6
+  - @mastra/deployer@0.1.8-alpha.6
+
+## 0.2.9-alpha.5
+
+### Patch Changes
+
+- 91d2e30: Fix init in non npm project
+- af7466e: fixes in playground ui
+- 52e0418: Split up action types between tools and workflows
+- a80bdaf: persist data in run tab in dev
+- 9035565: Update tools dev playground inputs for different fieldtypes
+- Updated dependencies [22643eb]
+- Updated dependencies [6feb23f]
+- Updated dependencies [f2d6727]
+- Updated dependencies [301e4ee]
+- Updated dependencies [dfbe4e9]
+- Updated dependencies [9e81f35]
+- Updated dependencies [caefaa2]
+- Updated dependencies [c151ae6]
+- Updated dependencies [52e0418]
+- Updated dependencies [03236ec]
+- Updated dependencies [3764e71]
+- Updated dependencies [df982db]
+- Updated dependencies [0461849]
+- Updated dependencies [2259379]
+- Updated dependencies [358f069]
+  - @mastra/core@0.5.0-alpha.5
+  - @mastra/deployer@0.1.8-alpha.5
+
+## 0.2.9-alpha.4
+
+### Patch Changes
+
+- 144b3d5: Update traces table UI, agent Chat UI
+  Fix get workflows breaking
+- Updated dependencies [d79aedf]
+- Updated dependencies [144b3d5]
+  - @mastra/core@0.5.0-alpha.4
+  - @mastra/deployer@0.1.8-alpha.4
+
+## 0.2.9-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [3d0e290]
+  - @mastra/core@0.5.0-alpha.3
+  - @mastra/deployer@0.1.8-alpha.3
+
+## 0.2.9-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [02ffb7b]
+  - @mastra/core@0.5.0-alpha.2
+  - @mastra/deployer@0.1.8-alpha.2
+
+## 0.2.9-alpha.1
+
+### Patch Changes
+
+- e5149bb: Fix playground-ui agent-evals tab-content
+- Updated dependencies [dab255b]
+  - @mastra/core@0.5.0-alpha.1
+  - @mastra/deployer@0.1.8-alpha.1
+
+## 0.2.9-alpha.0
+
+### Patch Changes
+
+- 5fae49e: Configurable timeout on npm create mastra
+- 960690d: Improve client-js workflow watch dx
+- 62565c1: --no-timeout npm create mastra flag
+
+... 1959 more lines hidden. See full changelog in package directory.

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

@@ -0,0 +1,385 @@
+### package.json
+```json
+{
+  "name": "examples-agent",
+  "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": "ISC",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  }
+}
+
+```
+
+### index.ts
+```typescript
+import { z } from 'zod';
+import { mastra } from './mastra';
+
+const agent = mastra.getAgent('chefAgent');
+const responsesAgent = mastra.getAgent('chefAgentResponses');
+
+async function text() {
+  // Query 1: Basic pantry ingredients
+  const query1 =
+    '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 1: ${query1}`);
+
+  const pastaResponse = await agent.generate(query1);
+  console.log('\n👨‍🍳 Chef Michel:', pastaResponse.text);
+  console.log('\n-------------------\n');
+}
+
+async function generateText() {
+  // Query 1: Basic pantry ingredients
+
+  const query1 =
+    '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 1: ${query1}`);
+
+  const pastaResponse = await agent.generate(query1);
+
+  console.log('\n👨‍🍳 Chef Michel:', pastaResponse.text);
+  console.log('\n-------------------\n');
+}
+
+async function textStream() {
+  // Query 2: More ingredients
+  const query2 =
+    "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 2: ${query2}`);
+
+  const curryResponse = await agent.stream(query2);
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of curryResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function generateStream() {
+  // Query 2: More ingredients
+  const query2 =
+    "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 2: ${query2}`);
+
+  const curryResponse = await agent.stream([query2]);
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of curryResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function textObject() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate(query3, {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function experimentalTextObject() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate(query3, {
+    experimental_output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function textObjectJsonSchema() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate(query3, {
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['ingredients', 'steps'],
+      properties: {
+        ingredients: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              name: { type: 'string' },
+              amount: { type: 'number' },
+            },
+            required: ['name', 'amount'],
+          },
+        },
+        steps: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+    },
+  });
+
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function generateObject() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate([query3], {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function streamObject() {
+  // Query 8: Generate a lasagna recipe
+  const query8 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 8: ${query8}`);
+
+  const lasagnaStreamResponse = await agent.stream(query8, {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of lasagnaStreamResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function generateStreamObject() {
+  // Query 9: Generate a lasagna recipe
+  const query9 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 9: ${query9}`);
+
+  const lasagnaStreamResponse = await agent.stream([query9], {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of lasagnaStreamResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function generateExperimentalStreamObject() {
+  // Query 9: Generate a lasagna recipe
+  const query9 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 9: ${query9}`);
+
+  const lasagnaStreamResponse = await agent.stream([query9], {
+    experimental_output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of lasagnaStreamResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function main() {
+  // await text();
+
+  // await experimentalTextObject();
+
+  // await generateExperimentalStreamObject();
+
+  // await generateText();
+
+  // await textStream();
+
+  // await generateStream();
+
+  // await textObject();
+
+  // await textObjectJsonSchema();
+
+  // await generateObject();
+
+  // await streamObject();
+
+  // await generateStreamObject();
+
+  const query1 = 'What happened in San Francisco last week?';
+
+  const pastaResponse = await responsesAgent.generate(query1, {
+    instructions: 'You take every recipe you get an exaggerate it and use weird ingredients.',
+  });
+
+  console.log(pastaResponse.text);
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+
+import { cookingTool } from '../tools/index.js';
+import { makeCoreTool } from '@mastra/core';
+
+export const chefAgent = new Agent({
+  name: 'Chef Agent',
+  instructions: `
+    YOU MUST USE THE TOOL cooking-tool
+    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-mini'),
+  tools: {
+    cookingTool,
+  },
+});
+
+export const chefAgentResponses = new Agent({
+  name: 'Chef Agent',
+  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.responses('gpt-4o'),
+  tools: {
+    web_search_preview: openai.tools.webSearchPreview(),
+  },
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+import { createLogger } from '@mastra/core/logger';
+
+import { chefAgent, chefAgentResponses } from './agents/index';
+
+export const mastra = new Mastra({
+  agents: { chefAgent, chefAgentResponses },
+  logger: createLogger({ name: 'Chef', level: 'info' }),
+  serverMiddleware: [
+    {
+      handler: (c, next) => {
+        console.log('Middleware called');
+        return next();
+      },
+    },
+  ],
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export const cookingTool = createTool({
+  id: 'cooking-tool',
+  description: 'My tool description',
+  inputSchema: z.object({}),
+  execute: async () => {
+    console.log('My tool is running!');
+    return 'My tool result';
+  },
+});
+
+```