@mastra/mcp-docs-server 0.13.9-alpha.0 → 0.13.9-alpha.2

package/.docs/organized/code-examples/workflow-with-separate-steps.md

@@ -20,15 +20,21 @@
 import { mastra } from './mastra';
 
 async function main() {
-  const myWorkflow = mastra.getWorkflow('myWorkflow');
-  const { start } = myWorkflow.createRun();
+  const run = await mastra.getWorkflow('myWorkflow').createRunAsync();
   try {
-    const res = await start({
-      triggerData: {
-        inputValue: 30,
+    const res = await run.start({
+      inputData: {
+        inputValue: 12,
       },
     });
-    console.log(res.results);
+
+    if (res.status === 'success') {
+      console.log(res.result);
+    } else if (res.status === 'failed') {
+      console.log('Workflow failed:', res.error);
+    } else {
+      console.log('Workflow suspended:', res.suspended);
+    }
   } catch (e) {
     console.log(e);
   }
@@ -54,64 +60,101 @@ export const mastra = new Mastra({
 
 ### mastra/workflows/index.ts
 ```typescript
-import { Step, Workflow } from '@mastra/core/workflows';
+import { createStep, createWorkflow } from '@mastra/core/workflows';
 import { z } from 'zod';
 
-const stepOne = new Step({
+const stepOne = createStep({
   id: 'stepOne',
-  execute: async ({ context }) => {
-    const triggerData = context?.triggerData;
-    const doubledValue = triggerData.inputValue * 2;
-    return { doubledValue };
+  inputSchema: z.object({
+    inputValue: z.number(),
+  }),
+  outputSchema: z.object({
+    doubledValue: z.number(),
+    isOriginalOdd: z.boolean(), // Track original parity
+  }),
+  execute: async ({ inputData }) => {
+    const doubledValue = inputData.inputValue * 2;
+    const isOriginalOdd = inputData.inputValue % 2 === 1;
+    return { doubledValue, isOriginalOdd };
   },
 });
 
-const stepTwo = new Step({
+const stepTwo = createStep({
   id: 'stepTwo',
-  execute: async ({ context }) => {
-    if (context?.steps.stepOne.status !== 'success') {
-      throw new Error('stepOne failed');
-    }
-    const stepOneResult = context?.steps.stepOne?.output;
-    const incrementedValue = stepOneResult.doubledValue + 1;
+  inputSchema: z.object({
+    doubledValue: z.number(),
+    isOriginalOdd: z.boolean(),
+  }),
+  outputSchema: z.object({
+    incrementedValue: z.number(),
+  }),
+  execute: async ({ inputData }) => {
+    // Increment only if original input was odd
+    const incrementedValue = inputData.doubledValue + (inputData.isOriginalOdd ? 1 : 0);
     return { incrementedValue };
   },
 });
 
-const stepThree = new Step({
+const stepThree = createStep({
   id: 'stepThree',
-  execute: async ({ context }) => {
-    const triggerData = context?.triggerData;
-    const tripledValue = triggerData.inputValue * 3;
+  inputSchema: z.object({
+    incrementedValue: z.number(),
+  }),
+  outputSchema: z.object({
+    tripledValue: z.number(),
+  }),
+  execute: async ({ inputData, getStepResult }) => {
+    try {
+      const stepTwoResult = getStepResult(stepTwo);
+      if (!stepTwoResult || typeof stepTwoResult.incrementedValue !== 'number') {
+        throw new Error('stepTwo failed or returned invalid data');
+      }
+    } catch (error) {
+      throw new Error(`stepTwo failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+
+    const tripledValue = inputData.incrementedValue * 3;
     return { tripledValue };
   },
 });
 
-const stepFour = new Step({
+const stepFour = createStep({
   id: 'stepFour',
-  execute: async ({ context }) => {
-    if (context?.steps.stepThree.status !== 'success') {
-      throw new Error('stepThree failed');
+  inputSchema: z.object({
+    tripledValue: z.number(),
+  }),
+  outputSchema: z.object({
+    isEven: z.boolean(),
+  }),
+  execute: async ({ inputData, getStepResult }) => {
+    try {
+      const stepThreeResult = getStepResult(stepThree);
+      if (!stepThreeResult || typeof stepThreeResult.tripledValue !== 'number') {
+        throw new Error('stepThree failed or returned invalid data');
+      }
+    } catch (error) {
+      throw new Error(`stepThree failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
-    const stepThreeResult = context?.steps.stepThree?.output;
-    const isEven = stepThreeResult.tripledValue % 2 === 0;
+
+    const isEven = inputData.tripledValue % 2 === 0;
     return { isEven };
   },
 });
 
-export const myWorkflow = new Workflow({
-  name: 'my-workflow',
-  triggerSchema: z.object({
+export const myWorkflow = createWorkflow({
+  id: 'my-workflow',
+  inputSchema: z.object({
     inputValue: z.number(),
   }),
-});
-
-myWorkflow.step(stepOne).then(stepTwo).step(stepThree).then(stepFour).commit();
-
-const { start } = myWorkflow.createRun();
-
-const result = await start({ triggerData: { inputValue: 3 } });
+  outputSchema: z.object({
+    isEven: z.boolean(),
+  }),
+})
+  .then(stepOne)
+  .then(stepTwo)
+  .then(stepThree)
+  .then(stepFour);
 
-console.log(result);
+myWorkflow.commit();
 
 ```

package/.docs/raw/agents/overview.mdx

@@ -100,6 +100,7 @@ await testAgent.generate([
       {
         type: 'image',
         image: "https://example.com/images/test-image.jpg",
+        mimeType: "image/jpeg"
       },
       {
         type: 'text',

package/.docs/raw/course/02-agent-tools-mcp/14-getting-github-mcp-url.md

@@ -1,16 +1,35 @@
-# Getting a Composio GitHub MCP URL
+# Getting a Smithery GitHub MCP URL
 
-First, you'll need to get a Composio GitHub MCP URL. This typically requires:
+First, you'll need to get a Smithery GitHub MCP URL. This typically requires:
 
-1. Setting up the Composio GitHub integration
-2. Authenticating with your GitHub account
-3. Getting your unique MCP URL
+1. Setting up a Smithery account
+2. Creating a personal access token with your GitHub account
+3. Getting your unique MCP URL via the Smithery packages
 
-For this example, we'll use an environment variable to store the URL:
+For this example, we'll use an environment variable to store the Smithery API key and profile name which can be found in the Smithery interface.
 
 ```bash
 # Add this to your .env file
-COMPOSIO_MCP_GITHUB=https://your-composio-github-mcp-url.com
+SMITHERY_API_KEY=your_smithery_api_key
+SMITHERY_PROFILE=your_smithery_profile_name
 ```
 
-Using an environment variable keeps your configuration secure and flexible. This approach allows you to easily switch between different GitHub accounts or environments without modifying your code. It also prevents sensitive information from being committed to your repository.
+Using an environment variable keeps your configuration secure and flexible. It also prevents sensitive information from being committed to your repository.
+
+We will use the Smithery packages to authenticate and create a streamable HTTP URL for the MCP server configuration
+
+```bash
+pnpm install @smithery/sdk
+```
+
+```ts
+import { createSmitheryUrl } from "@smithery/sdk";
+
+const smitheryGithubMCPServerUrl = createSmitheryUrl(
+  "https://server.smithery.ai/@smithery-ai/github",
+  {
+    apiKey: process.env.SMITHERY_API_KEY,
+    profile: process.env.SMITHERY_PROFILE,
+  },
+);
+```

package/.docs/raw/course/02-agent-tools-mcp/15-updating-mcp-config-github.md

@@ -9,7 +9,7 @@ const mcp = new MCPClient({
       url: new URL(process.env.ZAPIER_MCP_URL || ""),
     },
     github: {
-      url: new URL(process.env.COMPOSIO_MCP_GITHUB || ""),
+      url: smitheryGithubMCPServerUrl,
     },
   },
 });

package/.docs/raw/memory/memory-processors.mdx

@@ -97,9 +97,10 @@ const memoryWithMultipleProcessors = new Memory({
 
 You can create custom logic by extending the base `MemoryProcessor` class.
 
-```typescript copy showLineNumbers {4-19,23-26}
-import { Memory, CoreMessage } from "@mastra/memory";
-import { MemoryProcessor, MemoryProcessorOpts } from "@mastra/core/memory";
+```typescript copy showLineNumbers {5-20,24-27}
+import { Memory } from "@mastra/memory";
+import { CoreMessage, MemoryProcessorOpts } from "@mastra/core";
+import { MemoryProcessor } from "@mastra/core/memory";
 
 class ConversationOnlyFilter extends MemoryProcessor {
   constructor() {

package/.docs/raw/memory/semantic-recall.mdx

@@ -2,6 +2,8 @@
 
 If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
 
+> **📹 Watch**: What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
+
 ## How Semantic Recall Works
 
 Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent conversation history](./overview.mdx#conversation-history).

package/.docs/raw/memory/working-memory.mdx

@@ -43,7 +43,7 @@ const agent = new Agent({
 
 Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
 
-<YouTube id="ik-ld_XA96s" />
+<YouTube id="UMy_JHLf1n8" />
 
 ## Memory Persistence Scopes
 

package/.docs/raw/rag/chunking-and-embedding.mdx

@@ -25,21 +25,37 @@ Use `chunk` to split documents into manageable pieces. Mastra supports multiple
 - `html`: HTML structure-aware splitting
 - `json`: JSON structure-aware splitting
 - `latex`: LaTeX structure-aware splitting
+- `sentence`: Sentence-aware splitting
+
+**Note:** Each strategy accepts different parameters optimized for its chunking approach.
 
 Here's an example of how to use the `recursive` strategy:
 
 ```ts showLineNumbers copy
 const chunks = await doc.chunk({
   strategy: "recursive",
-  size: 512,
+  maxSize: 512,
   overlap: 50,
-  separator: "\n",
+  separators: ["\n"],
   extract: {
     metadata: true, // Optionally extract metadata
   },
 });
 ```
 
+For text where preserving sentence structure is important, here's an example of how to use the `sentence` strategy:
+
+```ts showLineNumbers copy
+const chunks = await doc.chunk({
+  strategy: "sentence",
+  maxSize: 450,
+  minSize: 50,
+  overlap: 0,
+  sentenceEnders: ["."],
+  keepSeparator: true,
+});
+```
+
 **Note:** Metadata extraction may use LLM calls, so ensure your API key is set.
 
 We go deeper into chunking strategies in our [chunk documentation](/reference/rag/chunk.mdx).
@@ -130,7 +146,7 @@ const doc = MDocument.fromText(`
 // Create chunks
 const chunks = await doc.chunk({
   strategy: "recursive",
-  size: 256,
+  maxSize: 256,
   overlap: 50,
 });
 

package/.docs/raw/reference/rag/chunk.mdx

@@ -42,21 +42,30 @@ const chunksWithMetadata = await doc.chunk({
 
 ## Parameters
 
+The following parameters are available for all chunking strategies.
+**Important:** Each strategy will only utilize a subset of these parameters relevant to its specific use case.
+
 <PropertiesTable
   content={[
     {
       name: "strategy",
-      type: "'recursive' | 'character' | 'token' | 'markdown' | 'html' | 'json' | 'latex'",
+      type: "'recursive' | 'character' | 'token' | 'markdown' | 'html' | 'json' | 'latex' | 'sentence'",
       isOptional: true,
       description:
         "The chunking strategy to use. If not specified, defaults based on document type. Depending on the chunking strategy, there are additional optionals. Defaults: .md files → 'markdown', .html/.htm → 'html', .json → 'json', .tex → 'latex', others → 'recursive'",
     },
+    {
+      name: "maxSize",
+      type: "number",
+      isOptional: true,
+      defaultValue: "4000",
+      description: "Maximum size of each chunk. **Note:** Some strategy configurations (markdown with headers, HTML with headers) ignore this parameter.",
+    },
     {
       name: "size",
       type: "number",
       isOptional: true,
-      defaultValue: "512",
-      description: "Maximum size of each chunk",
+      description: "**Deprecated:** Use `maxSize` instead. This parameter will be removed in the next major version.",
     },
     {
       name: "overlap",
@@ -66,33 +75,38 @@ const chunksWithMetadata = await doc.chunk({
       description: "Number of characters/tokens that overlap between chunks.",
     },
     {
-      name: "separator",
-      type: "string",
+      name: "lengthFunction",
+      type: "(text: string) => number",
+      isOptional: true,
+      description: "Function to calculate text length. Defaults to character count.",
+    },
+    {
+      name: "keepSeparator",
+      type: "boolean | 'start' | 'end'",
       isOptional: true,
-      defaultValue: "\\n\\n",
       description:
-        "Character(s) to split on. Defaults to double newline for text content.",
+        "Whether to keep the separator at the start or end of chunks",
     },
     {
-      name: "isSeparatorRegex",
+      name: "addStartIndex",
       type: "boolean",
       isOptional: true,
       defaultValue: "false",
-      description: "Whether the separator is a regex pattern",
+      description: "Whether to add start index metadata to chunks.",
     },
     {
-      name: "keepSeparator",
-      type: "'start' | 'end'",
+      name: "stripWhitespace",
+      type: "boolean",
       isOptional: true,
-      description:
-        "Whether to keep the separator at the start or end of chunks",
+      defaultValue: "true",
+      description: "Whether to strip whitespace from chunks.",
     },
     {
       name: "extract",
       type: "ExtractParams",
       isOptional: true,
       description:
-        "Metadata extraction configuration. See [ExtractParams reference](./extract-params) for details.",
+        "Metadata extraction configuration. See [ExtractParams reference](/reference/rag/extract-params) for details.",
     },
   ]}
 />
@@ -102,6 +116,32 @@ const chunksWithMetadata = await doc.chunk({
 Strategy-specific options are passed as top-level parameters alongside the strategy parameter. For example:
 
 ```typescript showLineNumbers copy
+// Character strategy example
+const chunks = await doc.chunk({
+  strategy: "character",
+  separator: ".", // Character-specific option
+  isSeparatorRegex: false, // Character-specific option
+  maxSize: 300, // general option
+});
+
+// Recursive strategy example
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  separators: ["\n\n", "\n", " "], // Recursive-specific option
+  language: "markdown", // Recursive-specific option
+  maxSize: 500, // general option
+});
+
+// Sentence strategy example
+const chunks = await doc.chunk({
+  strategy: "sentence",
+  maxSize: 450, // Required for sentence strategy
+  minSize: 50, // Sentence-specific option
+  sentenceEnders: ["."], // Sentence-specific option
+  fallbackToCharacters: false, // Sentence-specific option
+  keepSeparator: true, // general option
+});
+
 // HTML strategy example
 const chunks = await doc.chunk({
   strategy: "html",
@@ -109,8 +149,6 @@ const chunks = await doc.chunk({
     ["h1", "title"],
     ["h2", "subtitle"],
   ], // HTML-specific option
-  sections: [["div.content", "main"]], // HTML-specific option
-  size: 500, // general option
 });
 
 // Markdown strategy example
@@ -121,7 +159,6 @@ const chunks = await doc.chunk({
     ["##", "section"],
   ], // Markdown-specific option
   stripHeaders: true, // Markdown-specific option
-  overlap: 50, // general option
 });
 
 // Token strategy example
@@ -129,12 +166,105 @@ const chunks = await doc.chunk({
   strategy: "token",
   encodingName: "gpt2", // Token-specific option
   modelName: "gpt-3.5-turbo", // Token-specific option
-  size: 1000, // general option
+  maxSize: 1000, // general option
 });
 ```
 
 The options documented below are passed directly at the top level of the configuration object, not nested within a separate options object.
 
+### Character
+
+<PropertiesTable
+  content={[
+    {
+      name: "separator",
+      type: "string",
+      isOptional: true,
+      defaultValue: "\\n\\n",
+      description: "Character(s) to split on. Defaults to double newline for text content.",
+    },
+    {
+      name: "isSeparatorRegex",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether the separator is a regex pattern",
+    },
+  ]}
+/>
+
+### Recursive
+
+<PropertiesTable
+  content={[
+    {
+      name: "separators",
+      type: "string[]",
+      isOptional: true,
+      description: "Array of separators to try in order of preference. The strategy will attempt to split on the first separator, then fall back to subsequent ones.",
+    },
+    {
+      name: "isSeparatorRegex",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether the separators are regex patterns",
+    },
+    {
+      name: "language",
+      type: "Language",
+      isOptional: true,
+      description: "Programming or markup language for language-specific splitting behavior. See Language enum for supported values.",
+    },
+  ]}
+/>
+
+### Sentence
+
+<PropertiesTable
+  content={[
+    {
+      name: "maxSize",
+      type: "number",
+      description: "Maximum size of each chunk (required for sentence strategy)",
+    },
+    {
+      name: "minSize",
+      type: "number",
+      isOptional: true,
+      defaultValue: "50",
+      description: "Minimum size of each chunk. Chunks smaller than this will be merged with adjacent chunks when possible.",
+    },
+    {
+      name: "targetSize",
+      type: "number",
+      isOptional: true,
+      description: "Preferred target size for chunks. Defaults to 80% of maxSize. The strategy will try to create chunks close to this size.",
+    },
+    {
+      name: "sentenceEnders",
+      type: "string[]",
+      isOptional: true,
+      defaultValue: "['.', '!', '?']",
+      description: "Array of characters that mark sentence endings for splitting boundaries.",
+    },
+    {
+      name: "fallbackToWords",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Whether to fall back to word-level splitting for sentences that exceed maxSize.",
+    },
+    {
+      name: "fallbackToCharacters",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Whether to fall back to character-level splitting for words that exceed maxSize. Only applies if fallbackToWords is enabled.",
+    },
+  ]}
+/>
+
 ### HTML
 
 <PropertiesTable
@@ -160,6 +290,8 @@ The options documented below are passed directly at the top level of the configu
   ]}
 />
 
+**Important:** When using the HTML strategy, all general options are ignored. Use `headers` for header-based splitting or `sections` for section-based splitting. If used together, `sections` will be ignored.
+
 ### Markdown
 
 <PropertiesTable
@@ -167,6 +299,7 @@ The options documented below are passed directly at the top level of the configu
     {
       name: "headers",
       type: "Array<[string, string]>",
+      isOptional: true,
       description: "Array of [header level, metadata key] pairs",
     },
     {
@@ -184,6 +317,8 @@ The options documented below are passed directly at the top level of the configu
   ]}
 />
 
+**Important:** When using the `headers` option, the markdown strategy ignores all general options and content is split based on the markdown header structure. To use size-based chunking with markdown, omit the `headers` parameter.
+
 ### Token
 
 <PropertiesTable
@@ -200,6 +335,18 @@ The options documented below are passed directly at the top level of the configu
       isOptional: true,
       description: "Name of the model for tokenization",
     },
+    {
+      name: "allowedSpecial",
+      type: "Set<string> | 'all'",
+      isOptional: true,
+      description: "Set of special tokens allowed during tokenization, or 'all' to allow all special tokens",
+    },
+    {
+      name: "disallowedSpecial",
+      type: "Set<string> | 'all'",
+      isOptional: true,
+      description: "Set of special tokens to disallow during tokenization, or 'all' to disallow all special tokens",
+    },
   ]}
 />
 
@@ -233,6 +380,10 @@ The options documented below are passed directly at the top level of the configu
   ]}
 />
 
+### Latex
+
+The Latex strategy uses only the general chunking options listed above. It provides LaTeX-aware splitting optimized for mathematical and academic documents.
+
 ## Return Value
 
 Returns a `MDocument` instance containing the chunked documents. Each chunk includes:

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

@@ -258,6 +258,31 @@ export const cityCoordinatesTool = createTool({
 });
 ```
 
+## Using workflows in agents
+
+You can also use Workflows in Agents. This agent is able to choose between using the test tool or the test workflow.
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { testTool } from "../tools/test-tool";
+import { testWorkflow } from "../workflows/test-workflow";
+
+export const testAgent = new Agent({
+  name: "test-agent",
+  description: "Create facts for a country based on the city",
+  instructions: `Return an interesting fact about the country based on the city provided`,
+  model: openai("gpt-4o"),
+  workflows: {
+    test_workflow: testWorkflow
+  },
+  tools: {
+    test_tool: testTool
+  },
+});
+```
+
+
 ## Exposing workflows with `MCPServer`
 
 You can convert your workflows into tools by passing them into an instance of a Mastra `MCPServer`. This allows any MCP-compatible client to access your workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.9-alpha.0",
+  "version": "0.13.9-alpha.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,8 +32,8 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5",
-    "@mastra/mcp": "^0.10.9",
-    "@mastra/core": "0.12.2-alpha.0"
+    "@mastra/core": "0.13.0-alpha.2",
+    "@mastra/mcp": "^0.10.10-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.17.1",
@@ -43,13 +43,13 @@
     "@wong2/mcp-cli": "^1.10.0",
     "cross-env": "^7.0.3",
     "eslint": "^9.30.1",
-    "hono": "^4.8.9",
+    "hono": "^4.8.11",
     "tsup": "^8.5.0",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.26",
-    "@mastra/core": "0.12.2-alpha.0"
+    "@mastra/core": "0.13.0-alpha.2",
+    "@internal/lint": "0.0.26"
   },
   "scripts": {
     "prepare-docs": "cross-env PREPARE=true node dist/prepare-docs/prepare.js",