@mastra/mcp-docs-server 0.13.32 → 0.13.33

package/.docs/raw/getting-started/project-structure.mdx

@@ -3,70 +3,73 @@ title: "Local Project Structure | Getting Started | Mastra Docs"
 description: Guide on organizing folders and files in Mastra, including best practices and recommended structures.
 ---
 
-import { FileTree } from "nextra/components";
+import { FileTree, Callout } from "nextra/components";
 
 # Project Structure
 
-This page provides a guide for organizing folders and files in Mastra. Mastra is a modular framework, and you can use any of the modules separately or together.
+Your new Mastra project, created with the `create mastra` command, comes with a predefined set of files and folders to help you get started.
 
-You could write everything in a single file, or separate each agent, tool, and workflow into their own files.
+Mastra is a framework, but it's **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and easy to navigate.
 
-We don't enforce a specific folder structure, but we do recommend some best practices, and the CLI will scaffold a project with a sensible structure.
+## Default project structure
 
-## Example Project Structure
-
-A default project created with the CLI looks like this:
+A project created with the `create mastra` command looks like this:
 
 <FileTree>
   <FileTree.Folder name="src" defaultOpen>
     <FileTree.Folder name="mastra" defaultOpen>
       <FileTree.Folder name="agents" defaultOpen>
-        <FileTree.File name="agent-name.ts" />
+        <FileTree.File name="weather-agent.ts" />
       </FileTree.Folder>
       <FileTree.Folder name="tools" defaultOpen>
-        <FileTree.File name="tool-name.ts" />
+        <FileTree.File name="weather-tool.ts" />
       </FileTree.Folder>
       <FileTree.Folder name="workflows" defaultOpen>
-        <FileTree.File name="workflow-name.ts" />
+        <FileTree.File name="weather-workflow.ts" />
+      </FileTree.Folder>
+      <FileTree.Folder name="scorers" defaultOpen>
+        <FileTree.File name="weather-scorer.ts" />
       </FileTree.Folder>
       <FileTree.File name="index.ts" />
     </FileTree.Folder>
   </FileTree.Folder>
-  <FileTree.File name=".env" />
+  <FileTree.File name=".env.example" />
   <FileTree.File name="package.json" />
   <FileTree.File name="tsconfig.json" />
 </FileTree>
-{/*
-```
-root/
-├── src/
-│   └── mastra/
-│       ├── agents/
-│       │   └── index.ts
-│       ├── tools/
-│       │   └── index.ts
-│       ├── workflows/
-│       │   └── index.ts
-│       ├── index.ts
-├── .env
-├── package.json
-├── tssconfig.json
-``` */}
-
-### Top-level Folders
-
-| Folder                 | Description                          |
-| ---------------------- | ------------------------------------ |
-| `src/mastra`           | Core application folder              |
-| `src/mastra/agents`    | Agent configurations and definitions |
-| `src/mastra/tools`     | Custom tool definitions              |
-| `src/mastra/workflows` | Workflow definitions                 |
-
-### Top-level Files
-
-| File                  | Description                                         |
-| --------------------- | --------------------------------------------------- |
-| `src/mastra/index.ts` | Main configuration file for Mastra                  |
-| `.env`                | Environment variables                               |
-| `package.json`        | Node.js project metadata, scripts, and dependencies |
-| `tsconfig.json`       | TypeScript compiler configuration                   |
+
+<Callout type="info">
+Tip - Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
+</Callout>
+
+### Folders
+
+Folders organize your agent's resources, like agents, tools, and workflows.
+
+| Folder                 | Description |
+| ---------------------- | ------------ |
+| `src/mastra`           | Entry point for all Mastra-related code and configuration.|
+| `src/mastra/agents`    | Define and configure your agents - their behavior, goals, and tools. |
+| `src/mastra/workflows` | Define multi-step workflows that orchestrate agents and tools together. |
+| `src/mastra/tools`     | Create reusable tools that your agents can call |
+| `src/mastra/mcp`       | (Optional) Implement custom MCP servers to share your tools with external agents |
+| `src/mastra/scorers`   | (Optional) Define scorers for evaluating agent performance over time |
+| `src/mastra/public`    | (Optional) Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime |
+
+### Top-level files
+
+Top-level files define how your Mastra project is configured, built, and connected to its environment.
+
+| File                  | Description |
+| --------------------- | ------------ |
+| `src/mastra/index.ts` | Central entry point where you configure and initialize Mastra. |
+| `.env.example`        | Template for environment variables — copy and rename to `.env` to add your secret [model provider](/models) keys. |
+| `package.json`        | Defines project metadata, dependencies, and available npm scripts. |
+| `tsconfig.json`       | Configures TypeScript options such as path aliases, compiler settings, and build output. |
+
+## Next steps
+
+- Read more about [Mastra's features](/docs#why-mastra).
+- Integrate Mastra with your frontend framework: [Next.js](/docs/frameworks/web-frameworks/next-js), [React](/docs/frameworks/web-frameworks/vite-react), or [Astro](/docs/frameworks/web-frameworks/astro).
+- Build an agent from scratch following one of our [guides](/guides).
+- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)!

package/.docs/raw/getting-started/studio.mdx

@@ -0,0 +1,158 @@
+---
+title: "Playground"
+description: Guide on installing Mastra and setting up the necessary prerequisites for running it with various LLM providers.
+---
+
+import YouTube from "@/components/youtube";
+import { Tabs, Tab } from "@/components/tabs";
+import { VideoPlayer } from "@/components/video-player"
+import { Callout } from "nextra/components";
+
+# Playground
+
+Playground helps you build agents quickly. It provides an interactive UI for testing your agents and workflows, along with a REST API that exposes your Mastra application as a local service. This lets you start building without having to integrate Mastra into your project right away.
+
+As your project evolves, Playground enables you to iterate quickly. Features like Observability and Scorers give you visibility into performance at every stage of development.
+
+To get started, run Playground locally using the instructions below, or [deploy to Mastra Cloud](/docs/mastra-cloud/setting-up) to access the Playground remotely and collaborate with your team.
+
+<YouTube id="spGlcTEjuXY" startTime={126}/>
+
+## Launch Playground
+
+If you created your application with `create mastra`, start the local development server using the `dev` script. You can also run it directly with `mastra dev`.
+
+<Tabs items={["npm", "pnpm", "yarn", "bun", "mastra"]}>
+  <Tab>
+    ```bash copy
+    npm run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    mastra dev
+    ```
+  </Tab>
+</Tabs>
+
+Once the server's running, you can:
+
+- Open the Playground UI at http://localhost:4111/ to test your agent interactively.
+- Visit  http://localhost:4111/swagger-ui to discover and interact with the underlying REST API.
+
+## Playground UI
+
+The Playground UI provides an interactive development environment for you to test your agents, workflows, and tools, observe exactly what happens under the hood with each interaction, and tweak things as you go. 
+
+### Agents
+
+
+Chat with your agent directly, dynamically switch [models](/models), and tweak settings like temperature and top-p to understand how they affect the output.
+
+<VideoPlayer
+  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4"
+/>
+
+When you interact with your agent, you can follow each step of its reasoning, view tool call outputs, and [observe](#observability) traces and logs to see how responses are generated. You can also attach [scorers](#scorers) to measure and compare response quality over time.
+
+### Workflows
+
+Visualize your workflow as a graph and run it step by step with a custom input. During execution, the interface updates in real time to show the active step and the path taken.
+
+<VideoPlayer
+  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406027/local-dev-workflows-playground_100_rbc466.mp4"
+/>
+
+When running a workflow, you can also view detailed traces showing tool calls, raw JSON outputs, and any errors that might have occured along the way.
+
+### Tools
+
+Run tools in isolation to observe their behavior. Test them before assigning them to your agent, or isolate them to debug issues should something go wrong.
+
+<VideoPlayer
+  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406316/local-dev-agents-tools_100_fe1jdt.mp4"
+/>
+### MCP
+List the MCP servers attached to your Mastra instance and explore their available tools.
+
+![MCP Servers Playground](/image/local-dev/local-dev-mcp-server-playground.jpg)
+
+### Observability
+
+
+When you run an agent or workflow, the Observability tab displays traces that highlight the key AI operations such as model calls, tool executions, and workflow steps. Follow these traces to see how data moves, where time is spent, and what's happening under the hood. 
+
+![](https://mastra.ai/_next/image?url=%2Ftracingafter.png&w=1920&q=75)
+
+AI Tracing filters out low-level framework details so your traces stay focused and readable.
+
+
+### Scorers
+
+The Scorers tab displays the results of your agent's scorers as they run. When messages pass through your agent, the defined scorers evaluate each output asynchronously and render their results here. This allows you to understand how your scorers respond to different interactions, compare performance across test cases, and identify areas for improvement.
+
+## REST API
+
+The local development server exposes a complete set of REST API routes, allowing you to programmatically interact with your agents, workflows, and tools during development. This is particularly helpful if you plan to deploy the Mastra server, since the local development server uses the exact same API routes as the [production server](/docs/server-db/production-server), allowing you to develop and test against it with full parity.
+
+You can explore all available endpoints in the OpenAPI specification at http://localhost:4111/openapi.json, which details every endpoint and its request and response schemas. 
+
+To explore the API interactively, visit the Swagger UI at http://localhost:4111/swagger-ui. Here, you can discover endpoints and test them directly from your browser.
+
+<Callout type="info">
+The OpenAPI and Swagger endpoints are disabled in production by default. To enable them, set `server.build.openAPIDocs` and `server.build.swaggerUI` to `true` respectively.
+</Callout>
+
+## Configuration
+
+### Port
+
+By default, the development server runs at http://localhost:4111. You can change the `host` and `port` in the Mastra server configuration:
+
+```typescript
+import { Mastra } from "@mastra/core/mastra";
+
+export const mastra = new Mastra({
+  server: {
+    port: 8080,
+    host: "0.0.0.0",
+  },
+});
+```
+
+### Local HTTPS
+
+Mastra supports local HTTPS development through the [`--https`](/reference/cli/mastra#--https) flag, which automatically creates and manages certificates for your project. When you run `mastra dev --https`, a private key and certificate are generated for localhost (or your configured host). For custom certificate management, you can provide your own key and certificate files through the server configuration:
+
+```typescript
+import { Mastra } from "@mastra/core/mastra";
+import fs from 'node:fs';
+
+export const mastra = new Mastra({
+  server: {
+    https: {
+      key: fs.readFileSync('path/to/key.pem'),
+      cert: fs.readFileSync('path/to/cert.pem')
+    }
+  },
+});
+```
+## Next steps
+
+- Learn more about Mastra's suggested [project structure](/docs/getting-started/project-structure).
+- Integrate Mastra with your frontend framework of choice - [Next.js](/docs/frameworks/web-frameworks/next-js), [React](/docs/frameworks/web-frameworks/vite-react), or [Astro](/docs/frameworks/web-frameworks/astro).

package/.docs/raw/reference/workflows/step.mdx

@@ -152,4 +152,4 @@ const step1 = createStep({
 ## Related
 
 - [Control flow](../../docs/workflows/control-flow.mdx)
-- [Using agents and tools](../../docs/workflows/using-with-agents-and-tools.mdx)
+- [Using agents and tools](../../docs/workflows/agents-and-tools.mdx)

package/.docs/raw/tools-mcp/overview.mdx

@@ -1,11 +1,11 @@
 ---
-title: "Tools Overview | Tools & MCP | Mastra Docs"
+title: "Using Tools | Tools & MCP | Mastra Docs"
 description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
 ---
 
 import { Steps } from "nextra/components";
 
-# Tools Overview
+# Using Tools
 
 Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
 

package/.docs/raw/workflows/agents-and-tools.mdx

@@ -0,0 +1,131 @@
+---
+title: "Agents and Tools | Workflows | Mastra Docs"
+description: "Learn how to call agents and tools from workflow steps and choose between execute functions and step composition."
+---
+
+# Agents and Tools
+
+Workflow steps can call agents to leverage LLM reasoning or call tools for type-safe logic. You can either invoke them from within a step's `execute` function or compose them directly as steps using `createStep()`.
+
+## Using agents in workflows
+
+Use agents in workflow steps when you need reasoning, language generation, or other LLM-based tasks. Call from a step's `execute` function for more control over the agent call (e.g., track conversation history or return structured output). Compose agents as steps when you don't need to modify how the agent is invoked.
+
+### Calling agents
+
+Call agents inside a step's `execute` function using `.generate()` or `.stream()`. This lets you modify the agent call and handle the response before passing it to the next step.
+
+```typescript {7-12} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  // ...
+  execute: async ({ inputData, mastra }) => {
+    const { message } = inputData;
+
+    const testAgent = mastra.getAgent("testAgent");
+    const response = await testAgent.generate(`Convert this message into bullet points: ${message}`, {
+      memory: {
+        thread: "user-123",
+        resource: "test-123"
+      }
+    });
+
+    return {
+      list: response.text
+    };
+  }
+});
+```
+
+> See [Calling Agents](../../examples/agents/calling-agents.mdx) for more examples.
+
+### Agents as steps
+
+Compose an agent as a step using `createStep()` when you don't need to modify the agent call. Use `.map()` to transform the previous step's output into a `prompt` the agent can use.
+
+![Agent as step](/image/workflows/workflows-agent-tools-agent-step.jpg)
+
+```typescript {1,3,8-13} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { testAgent } from "../agents/test-agent";
+
+const step1 = createStep(testAgent);
+
+export const testWorkflow = createWorkflow({
+  // ...
+})
+  .map(async ({ inputData }) => {
+    const { message } = inputData;
+    return {
+      prompt: `Convert this message into bullet points: ${message}`
+    };
+  })
+  .then(step1)
+  .then(step2)
+  .commit();
+```
+
+> See [Input Data Mapping](./input-data-mapping.mdx) for more information.
+
+## Using tools in workflows
+
+Use tools in workflow steps to leverage existing tool logic. Call from a step's `execute` function when you need to prepare context or process responses. Compose tools as steps when you don't need to modify how the tool is used.
+
+### Calling tools
+
+Call tools inside a step's `execute` function using `.execute()`. This gives you more control over the tool's input context, or process its response before passing it to the next step.
+
+```typescript {8-13,16} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { testTool } from "../tools/test-tool";
+
+const step2 = createStep({
+  // ...
+  execute: async ({ inputData, runtimeContext }) => {
+    const { formatted } = inputData;
+
+    const response = await testTool.execute({
+      context: {
+        text: formatted
+      },
+      runtimeContext
+    });
+
+    return {
+      emphasized: response.emphasized
+    };
+  }
+});
+```
+
+> See [Calling Tools](../../examples/tools/calling-tools.mdx) for more examples.
+
+### Tools as steps
+
+Compose a tool as a step using `createStep()` when the previous step's output matches the tool's input context. You can use `.map()` to transform the previous step's output if they don't.
+
+![Tool as step](/image/workflows/workflows-agent-tools-tool-step.jpg)
+
+```typescript {1,3,9-14} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { testTool } from "../tools/test-tool";
+
+const step2 = createStep(testTool);
+
+export const testWorkflow = createWorkflow({
+  // ...
+})
+  .then(step1)
+  .map(async ({ inputData }) => {
+    const { formatted } = inputData;
+    return {
+      text: formatted
+    };
+  })
+  .then(step2)
+  .commit();
+```
+
+> See [Input Data Mapping](./input-data-mapping.mdx) for more information.
+
+## Related
+
+- [Using Agents](../agents/overview.mdx)
+- [Using Tools](../tools-mcp/overview.mdx)
+

package/.docs/raw/workflows/overview.mdx

@@ -31,7 +31,9 @@ Mastra workflows operate using these principles:
 
 Steps are the building blocks of workflows. Create a step using `createStep()` with `inputSchema` and `outputSchema` to define the data it accepts and returns.
 
-```typescript {6,9,14} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+The `execute` function defines what the step does. Use it to call functions in your codebase, external APIs, agents, or tools.
+
+```typescript {6,9,15} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createStep } from "@mastra/core/workflows";
 
 const step1 = createStep({
@@ -44,6 +46,7 @@ const step1 = createStep({
   }),
   execute: async ({ inputData }) => {
     const { message } = inputData;
+
     return {
       formatted: message.toUpperCase()
     };
@@ -53,6 +56,10 @@ const step1 = createStep({
 
 > See the [Step Class](../../reference/workflows/step.mdx) for a full list of configuration options.
 
+### Using agents and tools
+
+Workflow steps can also call registered agents or import and execute tools directly, visit the [Agents and Tools](./agents-and-tools.mdx) page for more information.
+
 ## Creating a workflow
 
 Create a workflow using `createWorkflow()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. Add steps using `.then()` and complete the workflow with `.commit()`.
@@ -81,13 +88,11 @@ export const testWorkflow = createWorkflow({
 
 ### Understanding control flow
 
-Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured.
+Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured. Visit the [Control Flow](./control-flow.mdx) page for more information.
 
-> See [Control Flow](./control-flow.mdx) for more information.
+#### Composing workflow steps
 
-#### Composing steps
-
-When using `.then()`, steps run sequentially. The `inputSchema` of each step must match the `outputSchema` of the step before it. The final step’s `outputSchema` doesn’t need to match the workflow’s `outputSchema`, which can be defined independently.
+When using `.then()`, steps run sequentially. Each step’s `inputSchema` must match the `outputSchema` of the previous step. The final step’s `outputSchema` should match the workflow’s `outputSchema` to ensure end-to-end type safety.
 
 ```typescript {4,7,14,17,24,27} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
@@ -116,7 +121,7 @@ export const testWorkflow = createWorkflow({
     message: z.string()
   }),
   outputSchema: z.object({
-    output: z.string()
+    emphasized: z.string()
   })
 })
   .then(step1)
@@ -200,23 +205,21 @@ The workflow output includes the full execution lifecycle, showing the input and
 {
   "status": "success",
   "steps": {
-    "input": {
-      "message": "Hello world"
-    },
+    // ...
     "step-1": {
+      "status": "success",
       "payload": {
         "message": "Hello world"
       },
-      "status": "success",
       "output": {
         "formatted": "HELLO WORLD"
       },
     },
     "step-2": {
+      "status": "success",
       "payload": {
         "formatted": "HELLO WORLD"
       },
-      "status": "success",
       "output": {
         "emphasized": "HELLO WORLD!!!"
       },
@@ -260,7 +263,6 @@ const step1 = createStep({
 
 Use the Mastra [Playground](../server-db/local-dev-playground.mdx) to easily run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
 
-
 ## Related
 
 For a closer look at workflows, see our [Workflow Guide](../../guides/guide/ai-recruiter.mdx), which walks through the core concepts with a practical example.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 0.13.33
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @mastra/core@0.22.1
+
+## 0.13.33-alpha.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @mastra/core@0.22.1-alpha.0
+
 ## 0.13.32
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.32",
+  "version": "0.13.33",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,8 +33,8 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@mastra/core": "0.22.0",
-    "@mastra/mcp": "^0.14.0"
+    "@mastra/mcp": "^0.14.0",
+    "@mastra/core": "0.22.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.5",
@@ -49,8 +49,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.51",
-    "@mastra/core": "0.22.0"
+    "@mastra/core": "0.22.1",
+    "@internal/lint": "0.0.52"
   },
   "homepage": "https://mastra.ai",
   "repository": {