@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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

@@ -0,0 +1,369 @@
+---
+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: "maxRetries",
+      type: "number",
+      isOptional: true,
+      defaultValue: "2",
+      description: "Maximum number of retries. Set to 0 to disable retries.",
+    },
+    {
+      name: "memoryOptions",
+      type: "MemoryConfig",
+      isOptional: true,
+      description: "Configuration options for memory management. See MemoryConfig section below for details.",
+    },
+    {
+      name: "onFinish",
+      type: "StreamTextOnFinishCallback | StreamObjectOnFinishCallback",
+      isOptional: true,
+      description: "Callback function called when streaming is complete.",
+    },
+    {
+      name: "onStepFinish",
+      type: "GenerateTextOnStepFinishCallback<any> | never",
+      isOptional: true,
+      description: "Callback function called after each step during streaming. Unavailable for structured output",
+    },
+    {
+      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: "isEnabled",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Enable or disable telemetry. Disabled by default while experimental.",
+    },
+    {
+      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: "functionId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for this function. Used to group telemetry data by function.",
+    },
+    {
+      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: "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: "textStream",
+      type: "AsyncIterable<string>",
+      isOptional: true,
+      description: "Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.",
+    },
+    {
+      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: "object",
+      type: "Promise<object>",
+      isOptional: true,
+      description: "Promise that resolves to the final structured output. Present when using either `output` or `experimental_output` options.",
+    }
+  ]}
+/>
+
+## 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,55 @@
+---
+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
+
+## Deployers
+When a Deployer is used, the build output is automatically prepared for the target platform e.g
+- [Vercel Deployer](/reference/deployers/vercel)
+- [Netlify Deployer](/reference/deployers/netlify) 
+- [Cloudflare Deployer](/reference/deployers/cloudflare)
+

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

@@ -0,0 +1,134 @@
+---
+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 routes 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 routes by default:
+
+### System Routes
+- **GET `/api`**: Get API status.
+
+### Agent Routes
+
+Agents are expected to be exported from `src/mastra/agents`.
+
+- **GET `/api/agents`**: Lists the registered agents found in your Mastra folder.
+- **GET `/api/agents/:agentId`**: Get agent by ID.
+- **GET `/api/agents/:agentId/evals/ci`**: Get CI evals by agent ID.
+- **GET `/api/agents/:agentId/evals/live`**: Get live evals by agent ID.
+- **POST `/api/agents/:agentId/generate`**: Sends a text-based prompt to the specified agent, returning the agent's response.
+- **POST `/api/agents/:agentId/stream`**: Stream a response from an agent.
+- **POST `/api/agents/:agentId/instructions`**: Update an agent's instructions.
+- **POST `/api/agents/:agentId/instructions/enhance`**: Generate an improved system prompt from instructions.
+- **GET `/api/agents/:agentId/speakers`**: Get available speakers for an agent.
+- **POST `/api/agents/:agentId/speak`**: Convert text to speech using the agent's voice provider.
+- **POST `/api/agents/:agentId/listen`**: Convert speech to text using the agent's voice provider.
+- **POST `/api/agents/:agentId/tools/:toolId/execute`**: Execute a tool through an agent.
+
+### Tool Routes
+
+Tools are expected to be exported from `src/mastra/tools` (or the configured tools directory).
+
+- **GET `/api/tools`**: Get all tools.
+- **GET `/api/tools/:toolId`**: Get tool by ID.
+- **POST `/api/tools/:toolId/execute`**: 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).
+
+- **GET `/api/workflows`**: Get all workflows.
+- **GET `/api/workflows/:workflowId`**: Get workflow by ID.
+- **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.
+- **POST `/api/workflows/:workflowId/resume`**: Resume a suspended workflow step.
+- **POST `/api/workflows/:workflowId/resume-async`**: Resume a suspended workflow step asynchronously.
+- **POST `/api/workflows/:workflowId/createRun`**: Create a new workflow run.
+- **POST `/api/workflows/:workflowId/start-async`**: Execute/Start a workflow asynchronously.
+- **GET `/api/workflows/:workflowId/watch`**: Watch workflow transitions in real-time.
+
+### Memory Routes
+- **GET `/api/memory/status`**: Get memory status.
+- **GET `/api/memory/threads`**: Get all threads.
+- **GET `/api/memory/threads/:threadId`**: Get thread by ID.
+- **GET `/api/memory/threads/:threadId/messages`**: Get messages for a thread.
+- **POST `/api/memory/threads`**: Create a new thread.
+- **PATCH `/api/memory/threads/:threadId`**: Update a thread.
+- **DELETE `/api/memory/threads/:threadId`**: Delete a thread.
+- **POST `/api/memory/save-messages`**: Save messages.
+
+### Telemetry Routes
+- **GET `/api/telemetry`**: Get all traces.
+
+### Log Routes
+- **GET `/api/logs`**: Get all logs.
+- **GET `/api/logs/transports`**: List of all log transports.
+- **GET `/api/logs/:runId`**: Get logs by run ID.
+
+### Vector Routes
+- **POST `/api/vector/:vectorName/upsert`**: Upsert vectors into an index.
+- **POST `/api/vector/:vectorName/create-index`**: Create a new vector index.
+- **POST `/api/vector/:vectorName/query`**: Query vectors from an index.
+- **GET `/api/vector/:vectorName/indexes`**: List all indexes for a vector store.
+- **GET `/api/vector/:vectorName/indexes/:indexName`**: Get details about a specific index.
+- **DELETE `/api/vector/:vectorName/indexes/:indexName`**: Delete a specific index.
+
+### OpenAPI Specification
+
+- **GET `/openapi.json`**: Returns an auto-generated OpenAPI specification for your project's routes.
+- **GET `/swagger-ui`**: Access Swagger UI for API documentation.
+
+## 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?" }
+    ]
+  }'
+```

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,107 @@
+# 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 responses from the agent for real-time interactions:
+
+
+```typescript
+const response = await agent.stream({
+  messages: [
+    {
+      role: "user",
+      content: "Tell me a story",
+    },
+  ],
+});
+
+// Process data stream with the processDataStream util
+ response.processDataStream({
+      onTextPart: (text) => {
+        process.stdout.write(text);
+      },
+      onFilePart: (file) => {
+        console.log(file);
+      },
+      onDataPart: (data) => {
+        console.log(data);
+      },
+      onErrorPart: (error) => {
+        console.error(error);
+      },
+  });
+
+// You can also read from response body directly
+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();
+```