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

package/.docs/raw/workflows/variables.mdx

@@ -0,0 +1,248 @@
+---
+title: "Data Mapping with Workflow Variables | Mastra Docs"
+description: "Learn how to use workflow variables to map data between steps and create dynamic data flows in your Mastra workflows."
+---
+
+# Data Mapping with Workflow Variables
+
+Workflow variables in Mastra provide a powerful mechanism for mapping data between steps, allowing you to create dynamic data flows and pass information from one step to another.
+
+## Understanding Workflow Variables
+
+In Mastra workflows, variables serve as a way to:
+
+- Map data from trigger inputs to step inputs
+- Pass outputs from one step to inputs of another step
+- Access nested properties within step outputs
+- Create more flexible and reusable workflow steps
+
+## Using Variables for Data Mapping
+
+### Basic Variable Mapping
+
+You can map data between steps using the `variables` property when adding a step to your workflow:
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+const workflow = new Workflow({
+  name: 'data-mapping-workflow',
+  triggerSchema: z.object({
+    inputData: z.string(),
+  }),
+});
+
+workflow
+  .step(step1, {
+    variables: {
+      // Map trigger data to step input
+      inputData: { step: 'trigger', path: 'inputData' }
+    }
+  })
+  .then(step2, {
+    variables: {
+      // Map output from step1 to input for step2
+      previousValue: { step: step1, path: 'outputField' }
+    }
+  })
+  .commit();
+```
+
+### Accessing Nested Properties
+
+You can access nested properties using dot notation in the `path` field:
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+workflow
+  .step(step1)
+  .then(step2, {
+    variables: {
+      // Access a nested property from step1's output
+      nestedValue: { step: step1, path: 'nested.deeply.value' }
+    }
+  })
+  .commit();
+```
+
+### Mapping Entire Objects
+
+You can map an entire object by using `.` as the path:
+
+```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
+workflow
+  .step(step1, {
+    variables: {
+      // Map the entire trigger data object
+      triggerData: { step: 'trigger', path: '.' }
+    }
+  })
+  .commit();
+```
+
+## Variable Resolution
+
+When a workflow executes, Mastra resolves variables at runtime by:
+
+1. Identifying the source step specified in the `step` property
+2. Retrieving the output from that step
+3. Navigating to the specified property using the `path`
+4. Injecting the resolved value into the target step's context as the `inputData` property
+
+## Examples
+
+### Mapping from Trigger Data
+
+This example shows how to map data from the workflow trigger to a step:
+
+```typescript showLineNumbers filename="src/mastra/workflows/trigger-mapping.ts" copy
+import { Step, Workflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+// Define a step that needs user input
+const processUserInput = new Step({
+  id: "processUserInput",
+  execute: async ({ context }) => {
+    // The inputData will be available in context because of the variable mapping
+    const { inputData } = context.inputData;
+
+    return {
+      processedData: `Processed: ${inputData}`
+    };
+  },
+});
+
+// Create the workflow
+const workflow = new Workflow({
+  name: "trigger-mapping",
+  triggerSchema: z.object({
+    inputData: z.string(),
+  }),
+});
+
+// Map the trigger data to the step
+workflow
+  .step(processUserInput, {
+    variables: {
+      inputData: { step: 'trigger', path: 'inputData' },
+    }
+  })
+  .commit();
+```
+
+### Mapping Between Steps
+
+This example demonstrates mapping data from one step to another:
+
+```typescript showLineNumbers filename="src/mastra/workflows/step-mapping.ts" copy
+import { Step, Workflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+// Step 1: Generate data
+const generateData = new Step({
+  id: "generateData",
+  outputSchema: z.object({
+    nested: z.object({
+      value: z.string(),
+    }),
+  }),
+  execute: async () => {
+    return {
+      nested: {
+        value: "step1-data"
+      }
+    };
+  },
+});
+
+// Step 2: Process the data from step 1
+const processData = new Step({
+  id: "processData",
+  inputSchema: z.object({
+    previousValue: z.string(),
+  }),
+  execute: async ({ context }) => {
+    // previousValue will be available because of the variable mapping
+    const { previousValue } = context.inputData;
+
+    return {
+      result: `Processed: ${previousValue}`
+    };
+  },
+});
+
+// Create the workflow
+const workflow = new Workflow({
+  name: "step-mapping",
+});
+
+// Map data from step1 to step2
+workflow
+  .step(generateData)
+  .then(processData, {
+    variables: {
+      // Map the nested.value property from generateData's output
+      previousValue: { step: generateData, path: 'nested.value' },
+    }
+  })
+  .commit();
+```
+
+## Type Safety
+
+Mastra provides type safety for variable mappings when using TypeScript:
+
+```typescript showLineNumbers filename="src/mastra/workflows/type-safe.ts" copy
+import { Step, Workflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+// Define schemas for better type safety
+const triggerSchema = z.object({
+  inputValue: z.string(),
+});
+
+type TriggerType = z.infer<typeof triggerSchema>;
+
+// Step with typed context
+const step1 = new Step({
+  id: "step1",
+  outputSchema: z.object({
+    nested: z.object({
+      value: z.string(),
+    }),
+  }),
+  execute: async ({ context }) => {
+    // TypeScript knows the shape of triggerData
+    const triggerData = context.getStepResult<TriggerType>('trigger');
+
+    return {
+      nested: {
+        value: `processed-${triggerData?.inputValue}`
+      }
+    };
+  },
+});
+
+// Create the workflow with the schema
+const workflow = new Workflow({
+  name: "type-safe-workflow",
+  triggerSchema,
+});
+
+workflow.step(step1).commit();
+```
+
+## Best Practices
+
+1. **Validate Inputs and Outputs**: Use `inputSchema` and `outputSchema` to ensure data consistency.
+
+2. **Keep Mappings Simple**: Avoid overly complex nested paths when possible.
+
+3. **Consider Default Values**: Handle cases where mapped data might be undefined.
+
+## Comparison with Direct Context Access
+
+While you can access previous step results directly via `context.steps`, using variable mappings offers several advantages:
+
+| Feature | Variable Mapping | Direct Context Access |
+| ------- | --------------- | --------------------- |
+| Clarity | Explicit data dependencies | Implicit dependencies |
+| Reusability | Steps can be reused with different mappings | Steps are tightly coupled |
+| Type Safety | Better TypeScript integration | Requires manual type assertions |

package/LICENSE

@@ -0,0 +1,44 @@
+Elastic License 2.0 (ELv2)
+
+**Acceptance**
+By using the software, you agree to all of the terms and conditions below.
+
+**Copyright License**
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below
+
+**Limitations**
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+**Patents**
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+**Notices**
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+**No Other Rights**
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+**Termination**
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+**No Liability**
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+**Definitions**
+The _licensor_ is the entity offering these terms, and the _software_ is the software the licensor makes available under these terms, including any portion of it.
+
+_you_ refers to the individual or entity agreeing to these terms.
+
+_your company_ is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. _control_ means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+_your licenses_ are all the licenses granted to you for the software under these terms.
+
+_use_ means anything you do with the software requiring one of your licenses.
+
+_trademark_ means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,129 @@
+# @mastra/mcp-docs-server
+
+A Model Context Protocol (MCP) server that provides AI assistants with direct access to Mastra.ai's complete knowledge base. This includes comprehensive documentation with MDX support, a collection of production-ready code examples, technical blog posts, and detailed package changelogs. The server integrates with popular AI development environments like Cursor and Windsurf, as well as Mastra agents, making it easy to build documentation-aware AI assistants that can provide accurate, up-to-date information about Mastra.ai's ecosystem.
+
+## Installation
+
+### In Cursor
+
+Create or update `.cursor/mcp.json` in your project root:
+
+MacOS/Linux
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+Windows
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+This will make all Mastra documentation tools available in your Cursor workspace.
+Note that the MCP server wont be enabled by default. You'll need to go to Cursor settings -> MCP settings and click "enable" on the Mastra MCP server.
+
+### In Windsurf
+
+Create or update `~/.codeium/windsurf/mcp_config.json`:
+
+MacOS/Linux
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+Windows
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+This will make all Mastra documentation tools available in your Windsurf workspace.
+Note that Windsurf MCP tool calling doesn't work very well. You will need to fully quit and re-open Windsurf after adding this.
+If a tool call fails you will need to go into Windsurf MCP settings and re-start the MCP server.
+
+### In a Mastra Agent
+
+```typescript
+import { MCPConfiguration } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+// Configure MCP with the docs server
+const mcp = new MCPConfiguration({
+  servers: {
+    mastra: {
+      command: 'npx',
+      args: ['-y', '@mastra/mcp-docs-server@latest'],
+    },
+  },
+});
+
+// Create an agent with access to all documentation tools
+const agent = new Agent({
+  name: 'Documentation Assistant',
+  instructions: 'You help users find and understand Mastra.ai documentation.',
+  model: openai('gpt-4'),
+  tools: await mcp.getTools(),
+});
+
+// Or use toolsets dynamically in generate/stream
+const response = await agent.stream('Show me the quick start example', {
+  toolsets: await mcp.getToolsets(),
+});
+```
+
+## Tools
+
+### Documentation Tool (`mastraDocs`)
+
+- Get Mastra.ai documentation by requesting specific paths
+- Explore both general guides and API reference documentation
+- Automatically lists available paths when a requested path isn't found
+
+### Examples Tool (`mastraExamples`)
+
+- Access code examples showing Mastra.ai implementation patterns
+- List all available examples
+- Get detailed source code for specific examples
+
+### Blog Tool (`mastraBlog`)
+
+- Access technical blog posts and articles
+- Posts are properly formatted with code block handling
+- Supports various date formats in blog metadata
+
+### Changes Tool (`mastraChanges`)
+
+- Access package changelogs
+- List all available package changelogs
+- Get detailed changelog content for specific packages

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { FastMCP } from 'tylerbarnes-fastmcp-fix';
+declare const server: FastMCP<undefined>;
+export { server };

package/dist/index.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs/promises';
+import { FastMCP } from 'tylerbarnes-fastmcp-fix';
+import { blogTool } from './tools/blog';
+import { changesTool } from './tools/changes';
+import { docsTool } from './tools/docs';
+import { examplesTool } from './tools/examples';
+import { fromPackageRoot } from './utils';
+// console.error('Starting Mastra Documentation Server...');
+// console.error('Docs base dir:', path.join(__dirname, '../.docs/raw/'));
+const server = new FastMCP({
+    name: 'Mastra Documentation Server',
+    version: JSON.parse(await fs.readFile(fromPackageRoot(`package.json`), 'utf8')).version,
+});
+// Add tools
+server.addTool(blogTool);
+server.addTool(docsTool);
+server.addTool(examplesTool);
+server.addTool(changesTool);
+export { server };

package/dist/prepare-docs/code-examples.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Scans example directories and creates flattened code example files
+ */
+export declare function prepareCodeExamples(): Promise<void>;

package/dist/prepare-docs/code-examples.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fromPackageRoot, fromRepoRoot, log } from '../utils';
+const EXAMPLES_SOURCE = fromRepoRoot('examples');
+const OUTPUT_DIR = fromPackageRoot('.docs/organized/code-examples');
+/**
+ * Scans example directories and creates flattened code example files
+ */
+export async function prepareCodeExamples() {
+    // Clean up existing output directory
+    try {
+        await fs.rm(OUTPUT_DIR, { recursive: true, force: true });
+    }
+    catch {
+        // Ignore errors if directory doesn't exist
+    }
+    // Ensure output directory exists
+    await fs.mkdir(OUTPUT_DIR, { recursive: true });
+    // Get all example directories
+    const examples = await fs.readdir(EXAMPLES_SOURCE, { withFileTypes: true });
+    const exampleDirs = examples.filter(entry => entry.isDirectory());
+    for (const dir of exampleDirs) {
+        const examplePath = path.join(EXAMPLES_SOURCE, dir.name);
+        const outputFile = path.join(OUTPUT_DIR, `${dir.name}.md`);
+        // Collect all relevant files
+        const files = [];
+        // First add package.json if it exists
+        try {
+            const packageJson = await fs.readFile(path.join(examplePath, 'package.json'), 'utf-8');
+            files.push({
+                path: 'package.json',
+                content: packageJson,
+            });
+        }
+        catch {
+            // Skip if no package.json
+        }
+        // Then scan for TypeScript files in src
+        try {
+            const srcPath = path.join(examplePath, 'src');
+            await scanDirectory(srcPath, srcPath, files);
+        }
+        catch {
+            // Skip if no src directory
+        }
+        // If we found any files, generate markdown and check line count
+        if (files.length > 0) {
+            const output = files
+                .map(file => `### ${file.path}\n\`\`\`${getFileType(file.path)}\n${file.content}\n\`\`\`\n`)
+                .join('\n');
+            const totalLines = output.split('\n').length;
+            // Skip if total lines would exceed 500
+            if (totalLines > 500) {
+                log(`Skipping ${dir.name}: ${totalLines} lines exceeds limit of 500`);
+                continue;
+            }
+            await fs.writeFile(outputFile, output, 'utf-8');
+            log(`Generated ${dir.name}.md with ${totalLines} lines`);
+        }
+    }
+}
+/**
+ * Recursively scan a directory for TypeScript files
+ */
+async function scanDirectory(basePath, currentPath, files) {
+    const entries = await fs.readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(currentPath, entry.name);
+        const relativePath = path.relative(basePath, fullPath);
+        if (entry.isDirectory()) {
+            await scanDirectory(basePath, fullPath, files);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.ts')) {
+            const content = await fs.readFile(fullPath, 'utf-8');
+            files.push({
+                path: relativePath,
+                content,
+            });
+        }
+    }
+}
+/**
+ * Get the appropriate code fence language based on file extension
+ */
+function getFileType(filePath) {
+    if (filePath === 'package.json')
+        return 'json';
+    if (filePath.endsWith('.ts'))
+        return 'typescript';
+    return '';
+}

package/dist/prepare-docs/copy-raw.d.ts

@@ -0,0 +1 @@
+export declare function copyRaw(): Promise<void>;

package/dist/prepare-docs/copy-raw.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fromPackageRoot, fromRepoRoot, log } from '../utils';
+const DOCS_SOURCE = fromRepoRoot('docs/src/pages/docs');
+const DOCS_DEST = fromPackageRoot('.docs/raw');
+async function copyDir(src, dest) {
+    // Create destination directory
+    await fs.mkdir(dest, { recursive: true });
+    // Read source directory
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            // Recursively copy directories
+            await copyDir(srcPath, destPath);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+            // Copy only MDX files
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+export async function copyRaw() {
+    try {
+        // Clean up existing docs directory if it exists
+        try {
+            await fs.rm(DOCS_DEST, { recursive: true });
+        }
+        catch {
+            // Ignore if directory doesn't exist
+        }
+        // Copy docs
+        await copyDir(DOCS_SOURCE, DOCS_DEST);
+        log('✅ Documentation files copied successfully');
+    }
+    catch (error) {
+        console.error('❌ Failed to copy documentation files:', error);
+        process.exit(1);
+    }
+}

package/dist/prepare-docs/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/prepare-docs/index.js

@@ -0,0 +1,8 @@
+import { prepare } from './prepare';
+try {
+    await prepare();
+}
+catch (error) {
+    console.error('Error preparing documentation:', error);
+    process.exit(1);
+}

package/dist/prepare-docs/package-changes.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Scans package directories and creates organized changelog files
+ */
+export declare function preparePackageChanges(): Promise<void>;