@mastra/mcp-docs-server 0.13.1 → 0.13.2-alpha.0

package/.docs/raw/local-dev/mastra-dev.mdx

@@ -1,172 +1,170 @@
 ---
-title: "Inspecting Agents with `mastra dev` | Mastra Local Dev Docs"
+title: "Inspecting agents and workflows with mastra dev | Mastra Local Dev Docs"
 description: Documentation for the Mastra local development environment for Mastra applications.
 ---
 
 import YouTube from "@/components/youtube";
+import { Tabs, Tab } from "@/components/tabs";
 
-# Local Development Environment
+# Playground
 
-Mastra provides a local development environment where you can test your agents, workflows, and tools while developing locally.
+Mastra provides a local development environment where you can test your agents, workflows, and tools during development.
 
-<YouTube id="spGlcTEjuXY" />
+Start the local development server by running:
 
-## Launch Development Server
+<Tabs items={["npm", "Mastra CLI"]}>
+  <Tab>
+    ```bash copy
+    npm run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    mastra dev
+    ```
+  </Tab>
+</Tabs>
 
-You can launch the Mastra development environment using the Mastra CLI by running:
+The local development server provides access to the following interfaces:
 
-```bash
-mastra dev
-```
+- Playground: [http://localhost:4111/](http://localhost:4111/)
+- Mastra API: [http://localhost:4111/api](http://localhost:4111/api)
+- OpenAPI Spec: [http://localhost:4111/openapi.json](http://localhost:4111/openapi.json)
+- Swagger UI – API explorer: [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui)
 
-By default, the server runs on localhost at http://localhost:4111. Custom port and host can be configured via the
-mastra server config.
+## Local Development Playground
 
-```typescript
-import { Mastra } from "@mastra/core";
+The Playground lets you interact with your agents, workflows, and tools. It provides dedicated interfaces for testing each component of your Mastra application during development and is available at: [http://localhost:4111/](http://localhost:4111/).
 
-export const mastra = new Mastra({
-  server: {
-    port: "4111",
-    host: "0.0.0.0",
-  },
-});
-```
+<YouTube id="spGlcTEjuXY" startTime={126}/>
+
+### Agents
+
+Quickly test and debug your agents during development using the interactive chat interface in the Agent Playground.
+
+![Agents Playground](/image/local-dev/local-dev-agents-playground.jpg)
+
+Key features:
+
+- **Chat Interface**: Talk to your agent and see how it responds in real time.
+- **Model Settings**: Tweak settings like temperature and top-p to see how they affect output.
+- **Agent Endpoints**: See the available REST API routes your agent exposes and how to use them.
+- **Agent Traces**: Step through what the agent did behind the scenes, tool calls, decisions, and more.
+- **Agent Evals**: Run tests against your agent and see how well it performs.
+
+### Workflows
 
-## Dev Playground
+Validate workflows by supplying defined inputs and visualizing each step within the Workflow Playground.
 
-`mastra dev` serves a playground UI for interacting with your agents, workflows, and tools. The playground provides dedicated interfaces for testing each component of your Mastra application during development.
+![Workflows Playground](/image/local-dev/local-dev-workflow-playground.jpg)
 
-### Agent Playground
+Key features:
 
-The Agent playground provides an interactive chat interface where you can test and debug your agents during development. Key features include:
+- **Workflow Visualization**: See your workflow as a visual graph so you can follow the steps and branches at a glance.
+- **Step Inputs & Outputs**: Check the data going into and coming out of each step to see how everything flows.
+- **Run Workflows**: Test your workflow with real inputs to validate the logic and debug any issues.
+- **Execution JSON**: Get the full picture of a run as raw JSON—inputs, outputs, errors, and results included.
+- **Workflow Traces**: Dig into a detailed breakdown of each step, including data flow, tool calls, and any errors along the way.
 
-- **Chat Interface**: Directly interact with your agents to test their responses and behavior.
-- **Prompt CMS**: Experiment with different system instructions for your agent:
-  - A/B test different prompt versions.
-  - Track performance metrics for each variant.
-  - Select and deploy the most effective prompt version.
-- **Agent Traces**: View detailed execution traces to understand how your agent processes requests, including:
-  - Prompt construction.
-  - Tool usage.
-  - Decision-making steps.
-  - Response generation.
-- **Agent Evals**: When you've set up [Agent evaluation metrics](/docs/evals/overview), you can:
-  - Run evaluations directly from the playground.
-  - View evaluation results and metrics.
-  - Compare agent performance across different test cases.
+### Tools
 
-### Workflow Playground
+Quickly test and debug custom tools in isolation using the Tools Playground, without running a full agent or workflow.
 
-The Workflow playground helps you visualize and test your workflow implementations:
+![Tools Playground](/image/local-dev/local-dev-tools-playground.jpg)
 
-- **Workflow Visualization**: Workflow graph visualization.
+Key features:
 
-- **Run Workflows**:
+- **Test Tools in Isolation**: Try out individual tools on their own without running a full agent or workflow.
+- **Input & Responses**: Send sample inputs to see how the tool responds.
+- **Tool Usage**: Find out which agents rely on this tool and how they’re using it.
 
-  - Trigger test workflow runs with custom input data.
-  - Debug workflow logic and conditions.
-  - Simulate different execution paths.
-  - View detailed execution logs for each step.
 
-- **Workflow Traces**: Examine detailed execution traces that show:
-  - Step-by-step workflow progression.
-  - State transitions and data flow.
-  - Tool invocations and their results.
-  - Decision points and branching logic.
-  - Error handling and recovery paths.
+### MCP Servers
 
-### Tools Playground
+Explore connection details, tool usage, and IDE configuration for local MCP server development.
 
-The Tools playground allows you to test your custom tools in isolation:
+![MCP Servers Playground](/image/local-dev/local-dev-mcp-server-playground.jpg)
+
+Key features:
+
+- **Connection Details**: Access the endpoints and config needed to wire up your MCP environment.
+- **Available Tools**:  See all tools currently published, including their names, versions, and which agents use them.
+- **IDE Configuration**: Grab ready-to-use config you can drop into your local setup for testing and publishing tools.
 
-- Test individual tools without running a full agent or workflow.
-- Input test data and view tool responses.
-- Debug tool implementation and error handling.
-- Verify tool input/output schemas.
-- Monitor tool performance and execution time.
 
 ## REST API Endpoints
 
-`mastra dev` also spins up REST API routes for your agents and workflows via the local [Mastra Server](/docs/deployment/server). This allows you to test your API endpoints before deployment. See [Mastra Dev reference](/reference/cli/dev#routes) for more details about all endpoints.
+The local development server exposes a set of REST API routes via the [Mastra Server](/docs/deployment/server), allowing you to test and interact with your agents and workflows before deployment.
 
-You can then leverage the [Mastra Client](/docs/deployment/client) SDK to interact with your served REST API routes seamlessly.
+For a full overview of available API routes, including agents, tools, and workflows, see the [Routes reference](/reference/cli/dev#routes).
 
 ## OpenAPI Specification
 
-`mastra dev` provides an OpenAPI spec at http://localhost:4111/openapi.json
+The local development server includes an OpenAPI specification available at: [http://localhost:4111/openapi.json](http://localhost:4111/openapi.json).
 
-To enable OpenAPI documentation in your Mastra instance, add the following configuration:
+To include OpenAPI documentation in your production server, enable it in the Mastra instance:
 
-```typescript
-import { Mastra } from "@mastra/core";
+```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
+  // ...
   server: {
     build: {
-      openAPIDocs: true, // Enable OpenAPI documentation
-      // ... other build config options
-    },
+      openAPIDocs: true
+    }
   },
 });
 ```
 
 ## Swagger UI
 
-Swagger UI provides an interactive interface for testing your API endpoints at `mastra dev` provides an OpenAPI spec at http://localhost:4111/swagger-ui.
-To enable Swagger UI in your Mastra instance, add the following configuration:
+The local development server includes an interactive Swagger UI - API explorer available at: [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui).
+
+To include Swagger UI in your production server, enable it in the Mastra instance:
 
-```typescript
-import { Mastra } from "@mastra/core";
+```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
+  // ...
   server: {
     build: {
-      openAPIDocs: true, // Enable OpenAPI documentation
-      swaggerUI: true, // Enable Swagger UI
-      // ... other build config options
+      swaggerUI: true
     },
   },
 });
 ```
 
-## Local Dev Architecture
-
-The local development server is designed to run without any external dependencies or containerization. This is achieved through:
-
-- **Dev Server**: Uses [Hono](https://hono.dev) as the underlying framework to power the [Mastra Server](/docs/deployment/server).
-
-- **In-Memory Storage**: Uses [LibSQL](https://libsql.org/) memory adapters for:
+## Architecture
 
-  - Agent memory management.
-  - Trace storage.
-  - Evals storage.
-  - Workflow snapshots.
+The local development server runs fully self-contained without external dependencies or containers. It leverages:
 
-- **Vector Storage**: Uses [FastEmbed](https://github.com/qdrant/fastembed) for:
-  - Default embedding generation.
-  - Vector storage and retrieval.
-  - Semantic search capabilities.
+- **Dev Server** powered by [Hono](https://hono.dev) for the core [Mastra Server](/docs/deployment/server).
+- **In-Memory Storage** via [LibSQL](https://libsql.org/) adapters for agent memory, traces, evals, and workflow snapshots.
+- **Vector Storage** using [FastEmbed](https://github.com/qdrant/fastembed) for embeddings, vector search, and semantic retrieval.
 
-This architecture allows you to start developing immediately without setting up databases or vector stores, while still maintaining production-like behavior in your local environment.
+This setup lets you start developing immediately with production-like behavior, no database or vector store setup required.
 
-### Model settings
+## Configuration
 
-The local development server also lets you configure the model settings in Overview > Model Settings.
+By default, the server runs on port `4111`. You can customize the host and port through the Mastra server configuration.
 
-You can configure the following settings:
+```typescript {6,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
 
-- **Temperature**: Controls randomness in model outputs. Higher values (0-2) produce more creative responses while lower values make outputs more focused and deterministic.
-- **Top P**: Sets cumulative probability threshold for token sampling. Lower values (0-1) make outputs more focused by considering only the most likely tokens.
-- **Top K**: Limits the number of tokens considered for each generation step. Lower values produce more focused outputs by sampling from fewer options.
-- **Frequency Penalty**: Reduces repetition by penalizing tokens based on their frequency in previous text. Higher values (0-2) discourage reuse of common tokens.
-- **Presence Penalty**: Reduces repetition by penalizing tokens that appear in previous text. Higher values (0-2) encourage the model to discuss new topics.
-- **Max Tokens**: Maximum number of tokens allowed in the model's response. Higher values allow for longer outputs but may increase latency.
-- **Max Steps**: Maximum number of steps a workflow or agent can execute before stopping. Prevents infinite loops and runaway processes.
-- **Max Retries**: Number of times to retry failed API calls or model requests before giving up. Helps handle temporary failures gracefully.
+export const mastra = new Mastra({
+  // ...
+  server: {
+    port: 8080,
+    host: "0.0.0.0",
+  },
+});
+```
 
-## Summary
 
-`mastra dev` makes it easy to develop, debug, and iterate on your AI logic in a self-contained environment before deploying to production.
+## Next steps
 
-- [Mastra Dev reference](../../reference/cli/dev.mdx)
+- [Mastra Cloud](/docs/mastra-cloud/overview)
+- [Deployment Overview](/docs/deployment/overview)
+- [Mastra Client SDK](/docs/client-js/overview)

package/.docs/raw/workflows/input-data-mapping.mdx

@@ -85,10 +85,10 @@ You can rename step outputs using the object syntax in `.map()`. In the example
 ```typescript {3} showLineNumbers
   .then(step)
   .map({
-    details: {
+    details: mapVariable({
       step: step,
       path: "value"
-    }
+    })
   })
 ```
 
@@ -111,9 +111,9 @@ export const testWorkflow = createWorkflow({
 testWorkflow
   .then(cityCoordinatesStep)
   .map({
-    details: {
+    details: mapVariable({
       initData: testWorkflow,
       path: "value"
-    }
+    })
   })
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.1",
+  "version": "0.13.2-alpha.0",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.57",
     "zod-to-json-schema": "^3.24.5",
-    "@mastra/mcp": "^0.10.4"
+    "@mastra/mcp": "^0.10.5-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.14.4",
@@ -48,7 +48,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.3",
     "@internal/lint": "0.0.13",
-    "@mastra/core": "0.10.6"
+    "@mastra/core": "0.10.7-alpha.1"
   },
   "peerDependencies": {
     "@mastra/core": "^0.10.0-alpha.0"

package/.docs/raw/local-dev/add-to-existing-project.mdx

@@ -1,43 +0,0 @@
----
-title: "Adding to an Existing Project | Mastra Local Development Docs"
-description: "Add Mastra to your existing Node.js applications"
----
-
-# Adding to an Existing Project
-
-You can add Mastra to an existing project using the CLI:
-
-```bash npm2yarn copy
-npm install -g mastra@latest
-mastra init
-```
-
-Changes made to project:
-
-1. Creates `src/mastra` directory with entry point
-2. Adds required dependencies
-3. Configures TypeScript compiler options
-
-## Interactive Setup
-
-Running commands without arguments starts a CLI prompt for:
-
-1. Component selection
-2. LLM provider configuration
-3. API key setup
-4. Example code inclusion
-
-## Non-Interactive Setup
-
-To initialize mastra in non-interactive mode use the following command arguments:
-
-```bash
-Arguments:
-  --components     Specify components: agents, tools, workflows
-  --llm            LLM provider: openai, anthropic, groq, google or cerebras
-  --llm-api-key    Provider API key
-  --example        Include example implementation
-  --dir            Directory for Mastra files (defaults to src/)
-```
-
-For more details, refer to the [mastra init CLI documentation](../../reference/cli/init).

package/.docs/raw/local-dev/creating-a-new-project.mdx

@@ -1,53 +0,0 @@
----
-title: "Creating a new Project | Mastra Local Development Docs"
-description: "Create new Mastra projects or add Mastra to existing Node.js applications using the CLI"
----
-
-# Creating a new project
-
-You can create a new project using the `create-mastra` package:
-
-```bash npm2yarn copy
-npm create mastra@latest
-```
-
-You can also create a new project by using the `mastra` CLI directly:
-
-```bash npm2yarn copy
-npm install -g mastra@latest
-mastra create
-```
-
-## Interactive Setup
-
-Running commands without arguments starts a CLI prompt for:
-
-1. Project name
-1. Component selection
-1. LLM provider configuration
-1. API key setup
-1. Example code inclusion
-
-## Non-Interactive Setup
-
-To initialize mastra in non-interactive mode use the following command arguments:
-
-```bash
-Arguments:
-  --components     Specify components: agents, tools, workflows
-  --llm-provider   LLM provider: openai, anthropic, groq, google, or cerebras
-  --add-example    Include example implementation
-  --llm-api-key    Provider API key
-  --project-name   Project name that will be used in package.json and as the project directory name
-```
-
-Generated project structure:
-
-```
-my-project/
-├── src/
-│   └── mastra/
-│       └── index.ts    # Mastra entry point
-├── package.json
-└── tsconfig.json
-```