@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/streaming/workflows/timeTravelStream.md

@@ -0,0 +1,142 @@
+# Run.timeTravelStream()
+
+The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const output = run.timeTravelStream({
+  step: 'step2',
+  inputData: { value: 10 },
+})
+
+// Process events as they arrive
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload)
+}
+
+// Get the final result
+const result = await output.result
+```
+
+## Parameters
+
+All parameters are the same as [`Run.timeTravel()`](https://mastra.ai/reference/workflows/run-methods/timeTravel). See the [timeTravel reference](https://mastra.ai/reference/workflows/run-methods/timeTravel) for detailed parameter documentation.
+
+## Returns
+
+**output:** (`WorkflowRunOutput<WorkflowResult<TState, TInput, TOutput, TSteps>>`): An object containing both the stream and result promise
+
+**output.fullStream:** (`ReadableStream<WorkflowStreamEvent>`): A readable stream that emits workflow events as execution progresses
+
+**output.result:** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow execution result
+
+**output.traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled
+
+## Stream events
+
+The stream emits various workflow events during execution:
+
+- `workflow-step-start`: Emitted when a step begins execution
+- `workflow-step-finish`: Emitted when a step completes successfully
+- `workflow-step-error`: Emitted when a step encounters an error
+- `workflow-step-suspended`: Emitted when a step suspends
+- Additional events depending on step types (agents, tools, etc.)
+
+## Extended usage examples
+
+### Processing events during time travel
+
+```typescript
+const run = await workflow.createRun()
+
+const output = run.timeTravelStream({
+  step: 'step2',
+  inputData: { value: 10 },
+})
+
+for await (const event of output.fullStream) {
+  switch (event.type) {
+    case 'workflow-step-start':
+      console.log(`Starting step: ${event.payload.stepName}`)
+      break
+    case 'workflow-step-finish':
+      console.log(`Completed step: ${event.payload.stepName}`)
+      break
+    case 'workflow-step-error':
+      console.error(`Error in step: ${event.payload.stepName}`, event.payload.error)
+      break
+  }
+}
+
+const result = await output.result
+console.log('Time travel completed:', result)
+```
+
+### Time travel stream with context
+
+```typescript
+const output = run.timeTravelStream({
+  step: 'step2',
+  context: {
+    step1: {
+      status: 'success',
+      payload: { value: 0 },
+      output: { step1Result: 2 },
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+    },
+  },
+})
+
+for await (const event of output.fullStream) {
+  // Handle events
+  console.log(event)
+}
+
+const result = await output.result
+```
+
+### Time travel stream with nested workflows
+
+```typescript
+const output = run.timeTravelStream({
+  step: ['nestedWorkflow', 'step3'],
+  inputData: { value: 10 },
+  nestedStepsContext: {
+    nestedWorkflow: {
+      step2: {
+        status: 'success',
+        payload: { step1Result: 2 },
+        output: { step2Result: 3 },
+        startedAt: Date.now(),
+        endedAt: Date.now(),
+      },
+    },
+  },
+})
+
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload)
+}
+
+const result = await output.result
+```
+
+## Notes
+
+- The stream closes automatically when time travel execution completes or encounters an error
+- You can process events from the stream while the workflow is still executing
+- The `result` promise resolves only after all steps have completed
+- Stream events follow the same format as regular workflow streaming
+- Time travel streaming requires storage to be configured since it relies on persisted workflow snapshots
+
+## Related
+
+- [Run.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
+- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming)
+- [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream)
+- [Run.resumeStream()](https://mastra.ai/reference/streaming/workflows/resumeStream)

package/.docs/reference/templates/overview.md

@@ -0,0 +1,194 @@
+# Overview
+
+This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.
+
+Mastra templates are pre-built project structures that demonstrate specific use cases and patterns. They provide:
+
+- **Working examples** - Complete, functional Mastra applications
+- **Best practices** - Proper project structure and coding conventions
+- **Educational resources** - Learn Mastra patterns through real implementations
+- **Quick starts** - Bootstrap projects faster than building from scratch
+
+## Using Templates
+
+### Installation
+
+Install a template using the `create-mastra` command:
+
+```bash
+npx create-mastra@latest --template template-name
+```
+
+This creates a complete project with all necessary code and configuration.
+
+### Setup Process
+
+After installation:
+
+1. **Navigate to project directory**:
+
+   ```bash
+   cd your-project-name
+   ```
+
+2. **Configure environment variables**:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` with required API keys as documented in the template's README.
+
+3. **Install dependencies** (if not done automatically):
+
+   ```bash
+   npm install
+   ```
+
+4. **Start development server**:
+
+   ```bash
+   npm run dev
+   ```
+
+### Template Structure
+
+All templates follow this standardized structure:
+
+## Creating Templates
+
+### Requirements
+
+Templates must meet these technical requirements:
+
+#### Project Structure
+
+- **Mastra code location**: All Mastra code must be in `src/mastra/` directory
+
+- **Component organization**:
+
+  - Agents: `src/mastra/agents/`
+  - Tools: `src/mastra/tools/`
+  - Workflows: `src/mastra/workflows/`
+  - Main config: `src/mastra/index.ts`
+
+#### TypeScript Configuration
+
+Use the standard Mastra TypeScript configuration:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+#### Environment Configuration
+
+Include a `.env.example` file with all required environment variables:
+
+```bash
+# LLM provider API keys (choose one or more)
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
+
+# Other service API keys as needed
+OTHER_SERVICE_API_KEY=your_api_key_here
+```
+
+### Code Standards
+
+#### LLM Provider
+
+We recommend using OpenAI, Anthropic, or Google model providers for templates. Choose the provider that best fits your use case:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const agent = new Agent({
+  name: 'example-agent',
+  model: 'openai/gpt-5.1', // or other provider strings
+  instructions: 'Your agent instructions here',
+})
+```
+
+#### Compatibility Requirements
+
+Templates must be:
+
+- **Single projects** - Not monorepos with multiple applications
+- **Framework-free** - No Next.js, Express, or other web framework boilerplate
+- **Mastra-focused** - Demonstrate Mastra functionality without additional layers
+- **Mergeable** - Structure code for easy integration into existing projects
+- **Node.js compatible** - Support Node.js v22.13.0 and later
+- **ESM modules** - Use ES modules (`"type": "module"` in package.json)
+
+### Documentation Requirements
+
+#### README Structure
+
+Every template must include a comprehensive README:
+
+```markdown
+# Template Name
+
+Brief description of what the template demonstrates.
+
+## Overview
+
+Detailed explanation of the template's functionality and use case.
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your API keys
+2. Install dependencies: `npm install`
+3. Run the project: `npm run dev`
+
+## Environment Variables
+
+- `OPENAI_API_KEY`: Your OpenAI API key. Get one at [OpenAI Platform](https://platform.openai.com/api-keys)
+- `ANTHROPIC_API_KEY`: Your Anthropic API key. Get one at [Anthropic Console](https://console.anthropic.com/settings/keys)
+- `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
+- `OTHER_API_KEY`: Description of what this key is for
+
+## Usage
+
+Instructions on how to use the template and examples of expected behavior.
+
+## Customization
+
+Guidelines for modifying the template for different use cases.
+```
+
+#### Code Comments
+
+Include clear comments explaining:
+
+- Complex logic or algorithms
+- API integrations and their purpose
+- Configuration options and their effects
+- Example usage patterns
+
+### Quality Standards
+
+Templates must demonstrate:
+
+- **Code quality** - Clean, well-commented, maintainable code
+- **Error handling** - Proper handling for external APIs and user inputs
+- **Type safety** - Full TypeScript typing with Zod validation
+- **Testing** - Verified functionality with fresh installations
+
+For information on contributing your own templates to the Mastra ecosystem, see the [Contributing Templates](https://mastra.ai/docs/community/contributing-templates) guide in the community section.
+
+> **Info:** Templates provide an excellent way to learn Mastra patterns and accelerate development. Contributing templates helps the entire community build better AI applications.

package/.docs/reference/tools/create-tool.md

@@ -0,0 +1,237 @@
+# createTool()
+
+The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
+
+## Usage example
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const tool = createTool({
+  id: 'test-tool',
+  description: 'Reverse the input string',
+  inputSchema: z.object({
+    input: z.string(),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+  execute: async inputData => {
+    const reversed = inputData.input.split('').reverse().join('')
+
+    return {
+      output: reversed,
+    }
+  },
+})
+```
+
+## Example with MCP Annotations
+
+When exposing tools via MCP (Model Context Protocol), you can add annotations to describe tool behavior and customize how clients display the tool. These MCP-specific properties are grouped under the `mcp` property:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('City name or coordinates'),
+  }),
+  // MCP-specific properties
+  mcp: {
+    // Annotations for client behavior hints
+    annotations: {
+      title: 'Weather Lookup', // Human-readable display name
+      readOnlyHint: true, // Tool doesn't modify environment
+      destructiveHint: false, // Tool doesn't perform destructive updates
+      idempotentHint: true, // Same args = same result
+      openWorldHint: true, // Interacts with external API
+    },
+    // Custom metadata for client-specific functionality
+    _meta: {
+      version: '1.0.0',
+      category: 'weather',
+    },
+  },
+  execute: async inputData => {
+    const weather = await fetchWeather(inputData.location)
+    return { weather }
+  },
+})
+```
+
+## Parameters
+
+**id:** (`string`): A unique identifier for the tool.
+
+**description:** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
+
+**inputSchema?:** (`Zod schema`): A Zod schema defining the expected input parameters for the tool's \`execute\` function.
+
+**outputSchema?:** (`Zod schema`): A Zod schema defining the expected output structure of the tool's \`execute\` function.
+
+**suspendSchema?:** (`Zod schema`): A Zod schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
+
+**resumeSchema?:** (`Zod schema`): A Zod schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.
+
+**requireApproval?:** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
+
+**mcp?:** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
+
+**requestContextSchema?:** (`Zod schema`): A Zod schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
+
+**execute:** (`function`): input:z.infer\<TInput>The validated input data based on inputSchemacontext?:ToolExecutionContextOptional execution context containing metadataRequestContextTracingContextAbortSignalAgentToolExecutionContextWorkflowToolExecutionContextMCPToolExecutionContext
+
+**onInputStart?:** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onInputDelta?:** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onInputAvailable?:** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onOutput?:** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+## Returns
+
+The `createTool()` function returns a `Tool` object.
+
+**Tool:** (`object`): An object representing the defined tool, ready to be added to an agent.
+
+## Tool Lifecycle Hooks
+
+Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
+
+### Available Hooks
+
+#### onInputStart
+
+Called when tool call input streaming begins, before any input data is received.
+
+```typescript
+export const tool = createTool({
+  id: 'example-tool',
+  description: 'Example tool with hooks',
+  onInputStart: ({ toolCallId, messages, abortSignal }) => {
+    console.log(`Tool ${toolCallId} input streaming started`)
+  },
+})
+```
+
+#### onInputDelta
+
+Called for each incremental chunk of input text as it streams in. Useful for showing real-time progress or parsing partial JSON.
+
+```typescript
+export const tool = createTool({
+  id: 'example-tool',
+  description: 'Example tool with hooks',
+  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
+    console.log(`Received input chunk: ${inputTextDelta}`)
+  },
+})
+```
+
+#### onInputAvailable
+
+Called when the complete tool input is available and has been parsed and validated against the `inputSchema`.
+
+```typescript
+export const tool = createTool({
+  id: 'example-tool',
+  description: 'Example tool with hooks',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
+    console.log(`Tool received complete input:`, input)
+    // input is fully typed based on inputSchema
+  },
+})
+```
+
+#### onOutput
+
+Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
+
+```typescript
+export const tool = createTool({
+  id: 'example-tool',
+  description: 'Example tool with hooks',
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async input => {
+    return { result: 'Success' }
+  },
+  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
+    console.log(`${toolName} execution completed:`, output)
+    // output is fully typed based on outputSchema
+  },
+})
+```
+
+### Hook Execution Order
+
+For a typical streaming tool call, the hooks are invoked in this order:
+
+1. **onInputStart** - Input streaming begins
+2. **onInputDelta** - Called multiple times as chunks arrive
+3. **onInputAvailable** - Complete input is parsed and validated
+4. Tool's **execute** function runs
+5. **onOutput** - Tool has completed successfully
+
+### Hook Parameters
+
+All hooks receive a parameter object with these common properties:
+
+- `toolCallId` (string): Unique identifier for this specific tool call
+- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
+
+Additionally:
+
+- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
+- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
+- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
+- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
+
+### Error Handling
+
+Hook errors are caught and logged automatically, but do not prevent tool execution from continuing. If a hook throws an error, it will be logged to the console but will not fail the tool call.
+
+## MCP Tool Annotations
+
+When exposing tools via the Model Context Protocol (MCP), you can provide annotations that describe tool behavior. These annotations help MCP clients like OpenAI Apps SDK understand how to present and handle your tools.
+
+MCP-specific properties are grouped under the `mcp` property, which includes `annotations` and `_meta`:
+
+```typescript
+mcp: {
+  annotations: { /* behavior hints */ },
+  _meta: { /* custom metadata */ },
+}
+```
+
+### ToolAnnotations Properties
+
+**title?:** (`string`): A human-readable title for the tool. Used for display purposes in UI components.
+
+**readOnlyHint?:** (`boolean`): If true, the tool does not modify its environment. This hint indicates the tool only reads data and has no side effects. Defaults to false.
+
+**destructiveHint?:** (`boolean`): If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. This hint helps clients determine if confirmation should be required. Defaults to true.
+
+**idempotentHint?:** (`boolean`): If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment. This hint indicates idempotent behavior. Defaults to false.
+
+**openWorldHint?:** (`boolean`): If true, this tool may interact with an 'open world' of external entities (e.g., web search, external APIs). If false, the tool's domain is closed and fully defined. Defaults to true.
+
+These annotations follow the [MCP specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations) and are passed through when tools are listed via MCP.
+
+## Related
+
+- [MCP Overview](https://mastra.ai/docs/mcp/overview)
+- [Using Tools with Agents](https://mastra.ai/docs/agents/using-tools)
+- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Tool Streaming](https://mastra.ai/docs/streaming/tool-streaming)
+- [Request Context](https://mastra.ai/docs/server/request-context)

package/.docs/reference/tools/document-chunker-tool.md

@@ -0,0 +1,89 @@
+# createDocumentChunkerTool()
+
+The `createDocumentChunkerTool()` function creates a tool for splitting documents into smaller chunks for efficient processing and retrieval. It supports different chunking strategies and configurable parameters.
+
+## Basic Usage
+
+```typescript
+import { createDocumentChunkerTool, MDocument } from '@mastra/rag'
+
+const document = new MDocument({
+  text: 'Your document content here...',
+  metadata: { source: 'user-manual' },
+})
+
+const chunker = createDocumentChunkerTool({
+  doc: document,
+  params: {
+    strategy: 'recursive',
+    size: 512,
+    overlap: 50,
+    separator: '\n',
+  },
+})
+
+const { chunks } = await chunker.execute()
+```
+
+## Parameters
+
+**doc:** (`MDocument`): The document to be chunked
+
+**params?:** (`ChunkParams`): Configuration parameters for chunking (Default: `Default chunking parameters`)
+
+### ChunkParams
+
+**strategy?:** (`'recursive'`): The chunking strategy to use (Default: `'recursive'`)
+
+**size?:** (`number`): Target size of each chunk in tokens/characters (Default: `512`)
+
+**overlap?:** (`number`): Number of overlapping tokens/characters between chunks (Default: `50`)
+
+**separator?:** (`string`): Character(s) to use as chunk separator (Default: `'\n'`)
+
+## Returns
+
+**chunks:** (`DocumentChunk[]`): Array of document chunks with their content and metadata
+
+## Example with Custom Parameters
+
+```typescript
+const technicalDoc = new MDocument({
+  text: longDocumentContent,
+  metadata: {
+    type: 'technical',
+    version: '1.0',
+  },
+})
+
+const chunker = createDocumentChunkerTool({
+  doc: technicalDoc,
+  params: {
+    strategy: 'recursive',
+    size: 1024, // Larger chunks
+    overlap: 100, // More overlap
+    separator: '\n\n', // Split on double newlines
+  },
+})
+
+const { chunks } = await chunker.execute()
+
+// Process the chunks
+chunks.forEach((chunk, index) => {
+  console.log(`Chunk ${index + 1} length: ${chunk.content.length}`)
+})
+```
+
+## Tool Details
+
+The chunker is created as a Mastra tool with the following properties:
+
+- **Tool ID**: `Document Chunker {strategy} {size}`
+- **Description**: `Chunks document using {strategy} strategy with size {size} and {overlap} overlap`
+- **Input Schema**: Empty object (no additional inputs required)
+- **Output Schema**: Object containing the chunks array
+
+## Related
+
+- [MDocument](https://mastra.ai/reference/rag/document)
+- [createVectorQueryTool](https://mastra.ai/reference/tools/vector-query-tool)