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

package/.docs/raw/reference/agents/stream.mdx

@@ -0,0 +1,361 @@
+---
+title: "Reference: Agent.stream() | Streaming | Agents | Mastra Docs"
+description: Documentation for the `.stream()` method in Mastra agents, which enables real-time streaming of responses.
+---
+
+# `stream()`
+
+The `stream()` method enables real-time streaming of responses from an agent. This method accepts `messages` and an optional `options` object as parameters, similar to `generate()`.
+
+## Parameters
+
+### `messages`
+
+The `messages` parameter can be:
+
+- A single string
+- An array of strings
+- An array of message objects with `role` and `content` properties
+
+The message object structure:
+
+```typescript
+interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+```
+
+### `options` (Optional)
+
+An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more. 
+
+<PropertiesTable
+  content={[
+    {
+      name: "abortSignal",
+      type: "AbortSignal",
+      isOptional: true,
+      description: "Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.",
+    },
+    {
+      name: "context",
+      type: "CoreMessage[]",
+      isOptional: true,
+      description: "Additional context messages to provide to the agent.",
+    },
+    {
+      name: "experimental_output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description: "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      isOptional: true,
+      description: "Custom instructions that override the agent's default instructions for this specific generation. Useful for dynamically modifying agent behavior without creating a new agent instance.",
+    },
+    {
+      name: "maxSteps",
+      type: "number",
+      isOptional: true,
+      defaultValue: "5",
+      description: "Maximum number of steps allowed during streaming.",
+    },
+    {
+      name: "memoryOptions",
+      type: "MemoryConfig",
+      isOptional: true,
+      description: "Configuration options for memory management. See MemoryConfig section below for details.",
+    },
+    {
+      name: "onFinish",
+      type: "(result: string) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called when streaming is complete.",
+    },
+    {
+      name: "onStepFinish",
+      type: "(step: string) => void",
+      isOptional: true,
+      description: "Callback function called after each step during streaming.",
+    },
+    {
+      name: "output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description: "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for the user or resource interacting with the agent. Must be provided if threadId is provided.",
+    },
+    {
+      name: "telemetry",
+      type: "TelemetrySettings",
+      isOptional: true,
+      description: "Settings for telemetry collection during streaming. See TelemetrySettings section below for details.",
+    },
+    {
+      name: "temperature",
+      type: "number",
+      isOptional: true,
+      description: "Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.",
+    },
+    {
+      name: "threadId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for the conversation thread. Allows for maintaining context across multiple interactions. Must be provided if resourceId is provided.",
+    },
+    {
+      name: "toolChoice",
+      type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
+      isOptional: true,
+      defaultValue: "'auto'",
+      description: "Controls how the agent uses tools during streaming.",
+    },
+    {
+      name: "toolsets",
+      type: "ToolsetsInput",
+      isOptional: true,
+      description: "Additional toolsets to make available to the agent during this stream.",
+    }
+  ]}
+/>
+
+#### MemoryConfig
+
+Configuration options for memory management:
+
+<PropertiesTable
+  content={[
+    {
+      name: "lastMessages",
+      type: "number | false",
+      isOptional: true,
+      description: "Number of most recent messages to include in context. Set to false to disable.",
+    },
+    {
+      name: "semanticRecall",
+      type: "boolean | object",
+      isOptional: true,
+      description: "Configuration for semantic memory recall. Can be boolean or detailed config.",
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "topK",
+              type: "number",
+              isOptional: true,
+              description: "Number of most semantically similar messages to retrieve.",
+            }
+          ]
+        },
+        {
+          type: "number | object",
+          parameters: [
+            {
+              name: "messageRange",
+              type: "number | { before: number; after: number }",
+              isOptional: true,
+              description: "Range of messages to consider for semantic search. Can be a single number or before/after configuration.",
+            }
+          ]
+        }
+      ]
+    },
+    {
+      name: "workingMemory",
+      type: "object",
+      isOptional: true,
+      description: "Configuration for working memory.",
+      properties: [
+        {
+          type: "boolean",
+          parameters: [
+            {
+              name: "enabled", 
+              type: "boolean", 
+              isOptional: true, 
+              description: "Whether to enable working memory."
+            }
+          ]
+        },
+        {
+          type: "string",
+          parameters: [
+            {
+              name: "template",
+              type: "string",
+              isOptional: true,
+              description: "Template to use for working memory.",
+            }
+          ]
+        },
+        {
+          type: "'text-stream' | 'tool-call'",
+          parameters: [
+            {
+              name: "type",
+              type: "'text-stream' | 'tool-call'",
+              isOptional: true,
+              description: "Type of content to use for working memory.",
+            }
+          ]
+        }
+      ]
+    },
+    {
+      name: "threads",
+      type: "object",
+      isOptional: true,
+      description: "Thread-specific memory configuration.",
+      properties: [
+        {
+          type: "boolean",
+          parameters: [
+            {
+              name: "generateTitle",
+              type: "boolean",
+              isOptional: true,
+              description: "Whether to automatically generate titles for new threads.",
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+
+#### TelemetrySettings
+
+Settings for telemetry collection during streaming:
+
+<PropertiesTable
+  content={[
+    {
+      name: "functionId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for this function. Used to group telemetry data by function.",
+    },
+    {
+      name: "isEnabled",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Enable or disable telemetry. Disabled by default while experimental.",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, AttributeValue>",
+      isOptional: true,
+      description: "Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.",
+    },
+    {
+      name: "recordInputs",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Enable or disable input recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
+    },
+    {
+      name: "recordOutputs",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Enable or disable output recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
+    },
+    {
+      name: "tracer",
+      type: "Tracer",
+      isOptional: true,
+      description: "A custom OpenTelemetry tracer instance to use for the telemetry data. See OpenTelemetry documentation for details.",
+    }
+  ]}
+/>
+
+## Returns
+
+The return value of the `stream()` method depends on the options provided, specifically the `output` option.
+
+### PropertiesTable for Return Values
+
+<PropertiesTable
+  content={[
+    {
+      name: "object",
+      type: "Promise<object>",
+      isOptional: true,
+      description: "Promise that resolves to the final structured output. Present when using either `output` or `experimental_output` options.",
+    },
+    {
+      name: "objectStream",
+      type: "AsyncIterable<object>",
+      isOptional: true,
+      description: "Stream of structured data. Present only when using `output` option with a schema.",
+    },
+    {
+      name: "partialObjectStream",
+      type: "AsyncIterable<object>",
+      isOptional: true,
+      description: "Stream of structured data. Present only when using `experimental_output` option.",
+    },
+    {
+      name: "textStream",
+      type: "AsyncIterable<string>",
+      isOptional: true,
+      description: "Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.",
+    }
+  ]}
+/>
+
+## Examples
+
+### Basic Text Streaming
+
+```typescript
+const stream = await myAgent.stream([
+  { role: "user", content: "Tell me a story." }
+]);
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Structured Output Streaming with Thread Context
+
+```typescript
+const schema = {
+  type: 'object',
+  properties: {
+    summary: { type: 'string' },
+    nextSteps: { type: 'array', items: { type: 'string' } }
+  },
+  required: ['summary', 'nextSteps']
+};
+
+const response = await myAgent.stream(
+  "What should we do next?",
+  {
+    output: schema,
+    threadId: "project-123",
+    onFinish: text => console.log("Finished:", text)
+  }
+);
+
+for await (const chunk of response.textStream) {
+  console.log(chunk);
+}
+
+const result = await response.object;
+console.log("Final structured result:", result);
+```
+
+The key difference between Agent's `stream()` and LLM's `stream()` is that Agents maintain conversation context through `threadId`, can access tools, and integrate with the agent's memory system.

package/.docs/raw/reference/cli/build.mdx

@@ -0,0 +1,48 @@
+---
+title: "mastra build"
+description: "Build your Mastra project for production deployment"
+---
+
+The `mastra build` command bundles your Mastra project into a production-ready Hono server. Hono is a lightweight web framework that provides type-safe routing and middleware support, making it ideal for deploying Mastra agents as HTTP endpoints.
+
+## Usage
+
+```bash
+mastra build [options]
+```
+
+## Options
+
+- `--dir <path>`: Directory containing your Mastra project (default: current directory)
+
+## What It Does
+
+1. Locates your Mastra entry file (either `src/mastra/index.ts` or `src/mastra/index.js`)
+2. Creates a `.mastra` output directory
+3. Bundles your code using Rollup with:
+   - Tree shaking for optimal bundle size
+   - Node.js environment targeting
+   - Source map generation for debugging
+
+## Example
+
+```bash
+# Build from current directory
+mastra build
+
+# Build from specific directory
+mastra build --dir ./my-mastra-project
+```
+
+## Output
+
+The command generates a production bundle in the `.mastra` directory, which includes:
+- A Hono-based HTTP server with your Mastra agents exposed as endpoints
+- Bundled JavaScript files optimized for production
+- Source maps for debugging
+- Required dependencies
+
+This output is suitable for:
+- Deploying to cloud servers (EC2, Digital Ocean)
+- Running in containerized environments
+- Using with container orchestration systems

package/.docs/raw/reference/cli/deploy.mdx

@@ -0,0 +1,22 @@
+---
+title: "`mastra deploy` Reference | Deployment | Mastra CLI"
+description: Documentation for the mastra deploy command, which deploys Mastra projects to platforms like Vercel and Cloudflare.
+---
+
+# `mastra deploy` Reference
+
+## `mastra deploy vercel`
+
+Deploy your Mastra project to Vercel.
+
+## `mastra deploy cloudflare`
+
+Deploy your Mastra project to Cloudflare.
+
+## `mastra deploy netlify`
+
+Deploy your Mastra project to Netlify.
+
+### Flags
+
+- `-d, --dir <dir>`: Path to your mastra folder

package/.docs/raw/reference/cli/dev.mdx

@@ -0,0 +1,97 @@
+---
+title: "`mastra dev` Reference | Local Development | Mastra CLI"
+description: Documentation for the mastra dev command, which starts a development server for agents, tools, and workflows.
+---
+
+# `mastra dev` Reference
+
+The `mastra dev` command starts a development server that exposes REST endpoints for your agents, tools, and workflows,
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "--dir",
+      type: "string",
+      description:
+        "Specifies the path to your Mastra folder (containing agents, tools, and workflows). Defaults to the current working directory.",
+      isOptional: true,
+    },
+    {
+      name: "--tools",
+      type: "string",
+      description:
+        "Comma-separated paths to additional tool directories that should be registered. For example: 'src/tools/dbTools,src/tools/scraperTools'.",
+      isOptional: true,
+    },
+    {
+      name: "--port",
+      type: "number",
+      description:
+        "Specifies the port number for the development server. Defaults to 4111.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Routes
+
+Starting the server with `mastra dev` exposes a set of REST endpoints by default:
+
+### Agent Routes
+
+Agents are expected to be exported from `src/mastra/agents`.
+
+• `GET /api/agents`
+  - Lists the registered agents found in your Mastra folder.
+• `POST /api/agents/:agentId/generate`
+  - Sends a text-based prompt to the specified agent, returning the agent's response.
+
+### Tool Routes
+
+Tools are expected to be exported from `src/mastra/tools` (or the configured tools directory).
+
+• `POST /api/tools/:toolName`
+  - Invokes a specific tool by name, passing input data in the request body.
+
+### Workflow Routes
+
+Workflows are expected to be exported from `src/mastra/workflows` (or the configured workflows directory).
+
+• `POST /api/workflows/:workflowName/start`
+  - Starts the specified workflow.
+• `POST /api/workflows/:workflowName/:instanceId/event`
+  - Sends an event or trigger signal to an existing workflow instance.
+• `GET /api/workflows/:workflowName/:instanceId/status`
+  - Returns status info for a running workflow instance.
+
+### OpenAPI Specification
+
+• `GET /openapi.json`
+  - Returns an auto-generated OpenAPI specification for your project's endpoints.
+
+## Additional Notes
+
+The port defaults to 4111.
+
+Make sure you have your environment variables set up in your `.env.development` or `.env` file for any providers you use (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
+
+### Example request
+
+To test an agent after running `mastra dev`:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/myAgent/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      { "role": "user", "content": "Hello, how can you assist me today?" }
+    ]
+  }'
+```
+
+## Related Docs
+
+- [REST Endpoints Overview](../../local-dev/mastra-dev.mdx) – More detailed usage of the dev server and agent endpoints.
+- [mastra deploy](../../deployment/deployment.mdx) – Deploy your project to Vercel or Cloudflare.

package/.docs/raw/reference/cli/init.mdx

@@ -0,0 +1,43 @@
+---
+title: "`mastra init` reference | Project Creation | Mastra CLI"
+description: Documentation for the mastra init command, which creates a new Mastra project with interactive setup options.
+---
+
+# `mastra init` Reference
+
+## `mastra init`
+
+This creates a new Mastra project. You can run it in three different ways:
+
+1. **Interactive Mode (Recommended)**
+   Run without flags to use the interactive prompt, which will guide you through:
+
+   - Choosing a directory for Mastra files
+   - Selecting components to install (Agents, Tools, Workflows)
+   - Choosing a default LLM provider (OpenAI, Anthropic, or Groq)
+   - Deciding whether to include example code
+
+2. **Quick Start with Defaults**
+
+   ```bash
+   mastra init --default
+   ```
+
+   This sets up a project with:
+
+   - Source directory: `src/`
+   - All components: agents, tools, workflows
+   - OpenAI as the default provider
+   - No example code
+
+3. **Custom Setup**
+   ```bash
+   mastra init --dir src/mastra --components agents,tools --llm openai --example
+   ```
+   Options:
+   - `-d, --dir`: Directory for Mastra files (defaults to src/mastra)
+   - `-c, --components`: Comma-separated list of components (agents, tools, workflows)
+   - `-l, --llm`: Default model provider (openai, anthropic, or groq)
+   - `-k, --llm-api-key`: API key for the selected LLM provider (will be added to .env file)
+   - `-e, --example`: Include example code
+   - `-ne, --no-example`: Skip example code

package/.docs/raw/reference/client-js/agents.mdx

@@ -0,0 +1,90 @@
+# Agents API
+
+The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
+
+## Getting All Agents
+
+Retrieve a list of all available agents:
+
+```typescript
+const agents = await client.getAgents();
+```
+
+## Working with a Specific Agent
+
+Get an instance of a specific agent:
+
+```typescript
+const agent = client.getAgent("agent-id");
+```
+
+## Agent Methods
+
+### Get Agent Details
+
+Retrieve detailed information about an agent:
+
+```typescript
+const details = await agent.details();
+```
+
+### Generate Response
+
+Generate a response from the agent:
+
+```typescript
+const response = await agent.generate({
+  messages: [
+    {
+      role: "user",
+      content: "Hello, how are you?",
+    },
+  ],
+  threadId: "thread-1", // Optional: Thread ID for conversation context
+  resourceid: "resource-1", // Optional: Resource ID
+  output: {}, // Optional: Output configuration
+});
+```
+
+### Stream Response
+
+Stream a response from the agent for real-time interactions:
+
+```typescript
+const response = await agent.stream({
+  messages: [
+    {
+      role: "user",
+      content: "Tell me a story",
+    },
+  ],
+});
+
+// Read from response body
+const reader = response.body.getReader();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  console.log(new TextDecoder().decode(value));
+}
+```
+
+### Get Agent Tool
+
+Retrieve information about a specific tool available to the agent:
+
+```typescript
+const tool = await agent.getTool("tool-id");
+```
+
+### Get Agent Evaluations
+
+Get evaluation results for the agent:
+
+```typescript
+// Get CI evaluations
+const evals = await agent.evals();
+
+// Get live evaluations
+const liveEvals = await agent.liveEvals();
+```

package/.docs/raw/reference/client-js/error-handling.mdx

@@ -0,0 +1,38 @@
+# Error Handling
+
+The Mastra Client SDK includes built-in retry mechanism and error handling capabilities.
+
+## Error Handling
+
+All API methods can throw errors that you can catch and handle:
+
+```typescript
+try {
+  const agent = client.getAgent("agent-id");
+  const response = await agent.generate({
+    messages: [{ role: "user", content: "Hello" }],
+  });
+} catch (error) {
+  console.error("An error occurred:", error.message);
+}
+```
+
+## Retry Mechanism
+
+The client automatically retries failed requests with exponential backoff:
+
+```typescript
+const client = new MastraClient({
+  baseUrl: "http://localhost:4111",
+  retries: 3, // Number of retry attempts
+  backoffMs: 300, // Initial backoff time
+  maxBackoffMs: 5000, // Maximum backoff time
+});
+```
+
+### How Retries Work
+
+1. First attempt fails → Wait 300ms
+2. Second attempt fails → Wait 600ms
+3. Third attempt fails → Wait 1200ms
+4. Final attempt fails → Throw error