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

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

@@ -309,4 +309,56 @@ const server = new MCPServer({
 For an agent to be exposed as a tool, it must have a non-empty `description` string. Similarly, for a workflow to be exposed, its `description` must also be a non-empty string. If the description is missing or empty for either, `MCPServer` will throw an error during initialization.
 Workflows will use their `inputSchema` for the tool's input.
 
+### Tools with Structured Outputs
+
+You can define an `outputSchema` for your tools to enforce a specific structure for the tool's output. This is useful for ensuring that the tool returns data in a consistent and predictable format, which can then be validated by the client.
+
+When a tool includes an `outputSchema`, its `execute` function **must** return an object containing a `structuredContent` property. The value of `structuredContent` must conform to the `outputSchema`. Mastra will automatically validate this output on both the server and client sides.
+
+Here's an example of a tool with an `outputSchema`:
+
+```typescript filename="src/tools/structured-tool.ts"
+import { createTool } from '@mastra/core';
+import { z } from 'zod';
+
+export const structuredTool = createTool({
+  description: 'A test tool that returns structured data.',
+  parameters: z.object({
+    input: z.string().describe('Some input string.'),
+  }),
+  outputSchema: z.object({
+    processedInput: z.string().describe('The processed input string.'),
+    timestamp: z.string().describe('An ISO timestamp.'),
+  }),
+  execute: async ({ input }) => {
+    // When outputSchema is defined, you must return a structuredContent object
+    return {
+      structuredContent: {
+        processedInput: `processed: ${input}`,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  },
+});
+```
+
+When this tool is called, the MCP client will receive both the structured data and a text representation of it.
+
+```
+Tool result
+
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"processedInput\": \"hello\", \"timestamp\": \"2025-06-19T16:53:16.472Z\"}"
+    }
+  ],
+  "structuredContent": {
+    "processedInput": "processed: hello",
+    "timestamp": "2025-06-19T16:53:16.472Z",
+  }
+}
+```
+
 For detailed usage and examples, see the [`MCPServer` reference documentation](/reference/tools/mcp-server).

package/.docs/raw/workflows/inngest-workflow.mdx

@@ -163,7 +163,7 @@ export const mastra = new Mastra({
 ```sh
 docker run --rm -p 8288:8288 \
   inngest/inngest \
-  inngest dev -u http://host.docker.internal:4111/inngest/api
+  inngest dev -u http://host.docker.internal:4111/api/inngest
 ```
 
 > **Note:** The URL after `-u` tells the Inngest dev server where to find your Mastra `/api/inngest` endpoint.

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/.docs/raw/workflows/pausing-execution.mdx

@@ -0,0 +1,60 @@
+---
+title: "Pausing Execution | Mastra Docs"
+description: "Pausing execution in Mastra workflows allows you to pause execution while waiting for external input or resources via .sleep(), .sleepUntil() and .waitForEvent()."
+---
+
+# Sleep & Events
+
+Pausing execution in Mastra workflows allows you to pause execution while waiting for external input or resources via `sleep()`, `sleepUntil()` and `waitForEvent()`.
+
+This sets the workflow status to `waiting`.
+
+## sleep()
+
+`sleep()` pauses execution for a specified number of milliseconds.
+
+```typescript
+workflow
+    .then(step1)
+    .sleep(1000)
+    .then(step2)
+    .commit();
+```
+
+## sleepUntil()
+
+`sleepUntil()` pauses execution until a specified date.
+
+```typescript
+workflow
+    .then(step1)
+    .sleepUntil(new Date(Date.now() + 1000))
+    .then(step2)
+    .commit();
+```
+
+## waitForEvent()
+
+`waitForEvent()` pauses execution until an event is received. Events can be sent to the workflow using `run.sendEvent()`. The event name and the step to resume after the event is received are provided as arguments to `waitForEvent()`.
+
+`.sendEvent()` takes as arguments the event name and the event data. The event data is optional and can be any JSON-serializable value.
+
+```typescript
+workflow
+    .then(step1)
+    .waitForEvent('my-event-name', step2)
+    .then(step3)
+    .commit();
+
+const run = await workflow.createRun()
+run.start({})
+
+setTimeout(() => {
+    run.sendEvent('my-event-name', {
+        data1: 'hello',
+        data2: {
+            anyData: 12
+        }
+    })
+}, 2e3)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.1",
+  "version": "0.13.2-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -24,15 +24,15 @@
   "author": "",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.13.0",
     "date-fns": "^4.1.0",
     "exit-hook": "^4.0.0",
     "jsdom": "^26.1.0",
     "turndown": "^7.2.0",
     "uuid": "^11.1.0",
-    "zod": "^3.25.57",
+    "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5",
-    "@mastra/mcp": "^0.10.4"
+    "@mastra/mcp": "^0.10.5-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.14.4",
@@ -41,14 +41,14 @@
     "@types/turndown": "^5.0.5",
     "@wong2/mcp-cli": "^1.10.0",
     "cross-env": "^7.0.3",
-    "eslint": "^9.28.0",
+    "eslint": "^9.29.0",
     "hono": "^4.7.11",
     "tsup": "^8.5.0",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3",
     "@internal/lint": "0.0.13",
-    "@mastra/core": "0.10.6"
+    "@mastra/core": "0.10.7-alpha.2"
   },
   "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
-```

package/.docs/raw/mastra-cloud/deploying.mdx

@@ -1,142 +0,0 @@
----
-title: Deploying to Mastra Cloud
-description: GitHub-based deployment process for Mastra applications
----
-
-# Deploying to Mastra Cloud
-
-> **Beta Notice**
-> Mastra Cloud is currently in **public beta**.
-
-This page describes the deployment process for Mastra applications to Mastra Cloud using GitHub integration.
-
-## Prerequisites
-
-- A GitHub account
-- A GitHub repository containing a Mastra application
-- Access to Mastra Cloud
-
-## Deployment Process
-
-Mastra Cloud uses a Git-based deployment workflow similar to platforms like Vercel and Netlify:
-
-1. **Import GitHub Repository**
-
-   - From the Projects dashboard, click "Add new"
-   - Select the repository containing your Mastra application
-   - Click "Import" next to the desired repository
-
-2. **Configure Deployment Settings**
-
-   - Set the project name (defaults to repository name)
-   - Select branch to deploy (typically `main`)
-   - Configure the Mastra directory path (defaults to `src/mastra`)
-   - Add necessary environment variables (like API keys)
-
-3. **Deploy from Git**
-   - After initial configuration, deployments are triggered by pushes to the selected branch
-   - Mastra Cloud automatically builds and deploys your application
-   - Each deployment creates an atomic snapshot of your agents and workflows
-
-## Automatic Deployments
-
-Mastra Cloud follows a Git-driven workflow:
-
-1. Make changes to your Mastra application locally
-2. Commit changes to the `main` branch
-3. Push to GitHub
-4. Mastra Cloud automatically detects the push and creates a new deployment
-5. Once the build completes, your application is live
-
-## Deployment Domains
-
-Each project receives two URLs:
-
-1. **Project-specific domain**: `https://[project-name].mastra.cloud`
-
-   - Example: `https://gray-acoustic-helicopter.mastra.cloud`
-
-2. **Deployment-specific domain**: `https://[deployment-id].mastra.cloud`
-   - Example: `https://young-loud-caravan-6156280f-ad56-4ec8-9701-6bb5271fd73d.mastra.cloud`
-
-These URLs provide direct access to your deployed agents and workflows.
-
-## Viewing Deployments
-
-![Deployments List](../../../../../public/image/cloud-agents.png)
-
-The deployments section in the dashboard shows:
-
-- **Title**: Deployment identifier (based on commit hash)
-- **Status**: Current state (success or archived)
-- **Branch**: The branch used (typically `main`)
-- **Commit**: The Git commit hash
-- **Updated At**: Timestamp of the deployment
-
-Each deployment represents an atomic snapshot of your Mastra application at a specific point in time.
-
-## Interacting with Agents
-
-![Agent Interface](../../../../../public/image/cloud-agent.png)
-
-After deployment, interact with your agents:
-
-1. Navigate to your project in the dashboard
-2. Go to the Agents section
-3. Select an agent to view its details and interface
-4. Use the Chat tab to communicate with your agent
-5. View the agent's configuration in the right panel:
-   - Model information (e.g., OpenAI)
-   - Available tools (e.g., getWeather)
-   - Complete system prompt
-6. Use suggested prompts (like "What capabilities do you have?") or enter custom messages
-
-The interface shows the agent's branch (typically "main") and indicates whether conversation memory is enabled.
-
-## Monitoring Logs
-
-The Logs section provides detailed information about your application:
-
-- **Time**: When the log entry was created
-- **Level**: Log level (info, debug)
-- **Hostname**: Server identification
-- **Message**: Detailed log information, including:
-  - API initialization
-  - Storage connections
-  - Agent and workflow activity
-
-These logs help debug and monitor your application's behavior in the production environment.
-
-## Workflows
-
-![Workflows Interface](../../../../../public/image/cloud-workflows.png)
-
-The Workflows section allows you to view and interact with your deployed workflows:
-
-1. View all workflows in your project
-2. Examine workflow structure and steps
-3. Access execution history and performance data
-
-## Database Usage
-
-Mastra Cloud tracks database utilization metrics:
-
-- Number of reads
-- Number of writes
-- Storage used (MB)
-
-These metrics appear in the project overview, helping you monitor resource consumption.
-
-## Deployment Configuration
-
-Configure your deployment through the dashboard:
-
-1. Navigate to your project settings
-2. Set environment variables (like `OPENAI_API_KEY`)
-3. Configure project-specific settings
-
-Changes to configuration require a new deployment to take effect.
-
-## Next Steps
-
-After deployment, [trace and monitor execution](./observability.mdx) using the observability tools.