@mastra/mcp-docs-server 1.1.35-alpha.6 → 1.1.35

package/.docs/reference/cli/mastra.md

@@ -464,10 +464,42 @@ mastra auth tokens revoke <token-id>
 
 ## `mastra lint`
 
-The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
+The `mastra lint` command validates the structure and code of your Mastra project.
+
+By default, `mastra lint` runs project checks against your source files and configuration. Use `--preflight` to also run bundle checks against `.mastra/output` before deployment.
+
+```bash
+mastra lint --preflight
+```
 
 It accepts [common flags](#common-flags).
 
+### Flags
+
+#### `--preflight`
+
+Runs deployment preflight checks against the built Mastra output. This builds the project before checking it unless you also pass `--skip-build`.
+
+#### `--skip-build`
+
+Skips the build step and reuses the existing `.mastra/output` directory. This flag only applies when `--preflight` is set.
+
+#### `--env-file <file>`
+
+Uses the specified environment file for preflight validation. This flag only applies when `--preflight` is set.
+
+#### `--strict`
+
+Treats warnings as errors.
+
+#### `--json`
+
+Emits machine-readable JSON output.
+
+#### `--debug`
+
+Enables debug logs.
+
 ## `mastra scorers`
 
 The `mastra scorers` command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.
@@ -550,6 +582,470 @@ See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to
 
 It accepts [common flags](#common-flags).
 
+## `mastra api`
+
+Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra Platform projects, or self-hosted Mastra servers.
+
+```bash
+mastra api agent list --pretty
+mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
+mastra api tool execute get-weather '{"location":"San Francisco"}'
+```
+
+Use `mastra api <resource> <action> --help` to see examples for a command.
+
+### Output
+
+Success responses are written to `stdout` as JSON. Single-resource commands return:
+
+```json
+{ "data": {} }
+```
+
+List commands return a `data` array and pagination metadata:
+
+```json
+{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
+```
+
+Errors are written to `stderr` as JSON and return a non-zero exit code:
+
+```json
+{
+  "error": {
+    "code": "SERVER_UNREACHABLE",
+    "message": "Could not connect to target server",
+    "details": {}
+  }
+}
+```
+
+### Target resolution
+
+The command resolves the target server in this order:
+
+1. `--url <url>` for an explicit remote or self-hosted server.
+2. `http://localhost:4111` for a local `mastra dev` server.
+3. `.mastra-project.json` for a Mastra Platform project.
+
+Automatic platform auth is only used when the CLI resolves a Mastra Platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets do not receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
+
+### Flags
+
+#### `--url <url>`
+
+Target a specific Mastra server URL.
+
+```bash
+mastra api --url https://example.com agent list
+```
+
+#### `--header <"Key: Value">`
+
+Send a custom HTTP header. Repeat the flag to send multiple headers.
+
+```bash
+mastra api --url https://example.com --header "Authorization: Bearer $TOKEN" agent list
+```
+
+#### `--timeout <ms>`
+
+Set the request timeout in milliseconds. Defaults to `30000`. Workflow run start and resume commands default to `120000`.
+
+#### `--pretty`
+
+Pretty-print JSON output. Defaults to `false`.
+
+#### `--schema`
+
+Print the CLI-oriented request schema for a command that accepts JSON input. The schema comes from the target server's route contracts and includes the command shape, positionals, examples, request schemas, and response shape.
+
+`--schema` is available on leaf commands that accept JSON input. It is not available as a top-level `mastra api` flag.
+
+```bash
+mastra api agent run --schema
+mastra api tool execute --schema
+```
+
+### Input model
+
+Commands that accept input take one inline JSON argument. Do not pass file paths or stdin.
+
+```bash
+mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}'
+```
+
+Use positional arguments for stable IDs and JSON for filters or payloads. For routes that require both query parameters and a request body, pass one JSON object. The CLI splits the input according to the server route schema.
+
+```bash
+mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","threadId":"thread_abc123","title":"Support conversation"}'
+```
+
+List commands accept `page` and `perPage` in the JSON input when the target route supports pagination:
+
+```bash
+mastra api score list '{"page":0,"perPage":50}'
+```
+
+### Get command-specific help
+
+Each `mastra api` leaf command includes command-specific examples in its help output. Use `--help` on the exact command you want to call:
+
+```bash
+mastra api agent run --help
+mastra api tool execute --help
+mastra api memory current update --help
+mastra api workflow run resume --help
+```
+
+Use `--schema` on commands that accept JSON input to inspect the request shape returned by the target server:
+
+```bash
+mastra api agent run --schema
+mastra api thread create --schema
+mastra api score create --schema
+```
+
+Some commands have important runtime requirements. For example, `mastra api memory current update` requires working memory to be enabled for the memory instance, and `mastra api workflow run resume` only works for suspended workflow runs.
+
+### Commands
+
+#### `mastra api agent list`
+
+Lists the agents registered on the target server. Pass optional JSON input for route-supported filters.
+
+```bash
+mastra api agent list [input]
+```
+
+#### `mastra api agent get`
+
+Gets metadata for one registered agent.
+
+```bash
+mastra api agent get <agentId>
+```
+
+#### `mastra api agent run`
+
+Runs an agent with JSON input. Use command help to see examples for text prompts, chat messages, and memory thread options.
+
+```bash
+mastra api agent run <agentId> <input>
+```
+
+#### `mastra api workflow list`
+
+Lists workflows registered on the target server. Pass optional JSON input for route-supported filters.
+
+```bash
+mastra api workflow list [input]
+```
+
+#### `mastra api workflow get`
+
+Gets metadata for one registered workflow.
+
+```bash
+mastra api workflow get <workflowId>
+```
+
+#### `mastra api workflow run start`
+
+Starts a workflow run with JSON input. Workflow start commands use a longer default timeout than most commands because runs can take longer to complete.
+
+```bash
+mastra api workflow run start <workflowId> <input>
+```
+
+#### `mastra api workflow run list`
+
+Lists runs for a workflow. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api workflow run list <workflowId> [input]
+```
+
+#### `mastra api workflow run get`
+
+Gets one workflow run by ID.
+
+```bash
+mastra api workflow run get <workflowId> <runId>
+```
+
+#### `mastra api workflow run resume`
+
+Resumes a suspended workflow run with JSON input. The run must be in a suspended state.
+
+```bash
+mastra api workflow run resume <workflowId> <runId> <input>
+```
+
+#### `mastra api workflow run cancel`
+
+Cancels a workflow run.
+
+```bash
+mastra api workflow run cancel <workflowId> <runId>
+```
+
+#### `mastra api tool list`
+
+Lists tools registered on the target server. Pass optional JSON input for route-supported filters.
+
+```bash
+mastra api tool list [input]
+```
+
+#### `mastra api tool get`
+
+Gets metadata and schemas for one tool.
+
+```bash
+mastra api tool get <toolId>
+```
+
+#### `mastra api tool execute`
+
+Executes a tool with JSON input. Raw tool input is wrapped as the route `data` field unless you pass an explicit `data` object.
+
+```bash
+mastra api tool execute <toolId> <input>
+```
+
+#### `mastra api mcp list`
+
+Lists Model Context Protocol (MCP) servers registered on the target server. Pass optional JSON input for route-supported filters.
+
+```bash
+mastra api mcp list [input]
+```
+
+#### `mastra api mcp get`
+
+Gets metadata for one MCP server.
+
+```bash
+mastra api mcp get <id>
+```
+
+#### `mastra api mcp tool list`
+
+Lists tools exposed by an MCP server. Pass optional JSON input for route-supported filters.
+
+```bash
+mastra api mcp tool list <serverId> [input]
+```
+
+#### `mastra api mcp tool get`
+
+Gets metadata and schemas for one MCP tool.
+
+```bash
+mastra api mcp tool get <serverId> <toolId>
+```
+
+#### `mastra api mcp tool execute`
+
+Executes an MCP tool with JSON input. Raw tool input is wrapped as the route `data` field unless you pass an explicit `data` object.
+
+```bash
+mastra api mcp tool execute <serverId> <toolId> <input>
+```
+
+#### `mastra api thread list`
+
+Lists memory threads. Pass optional JSON input for route-supported filters.
+
+```bash
+mastra api thread list [input]
+```
+
+#### `mastra api thread get`
+
+Gets one memory thread by ID.
+
+```bash
+mastra api thread get <threadId>
+```
+
+#### `mastra api thread create`
+
+Creates a memory thread. Pass one JSON input object; the CLI splits fields such as `agentId` into query parameters when required by the server route.
+
+```bash
+mastra api thread create <input>
+```
+
+#### `mastra api thread update`
+
+Updates a memory thread. Pass one JSON input object for fields such as `agentId`, `resourceId`, `title`, or `metadata`.
+
+```bash
+mastra api thread update <threadId> <input>
+```
+
+#### `mastra api thread delete`
+
+Deletes a memory thread. Pass JSON input for route-required query parameters such as `agentId` and `resourceId`.
+
+```bash
+mastra api thread delete <threadId> <input>
+```
+
+#### `mastra api thread messages`
+
+Lists messages for a memory thread. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api thread messages <threadId> [input]
+```
+
+#### `mastra api memory search`
+
+Searches long-term memory. Use `--help` or `--schema` to inspect required fields such as `agentId`, `resourceId`, and `searchQuery`.
+
+```bash
+mastra api memory search <input>
+```
+
+#### `mastra api memory current get`
+
+Reads current working memory for a thread.
+
+```bash
+mastra api memory current get <input>
+```
+
+#### `mastra api memory current update`
+
+Updates current working memory for a thread. Working memory must be enabled for the memory instance.
+
+```bash
+mastra api memory current update <input>
+```
+
+#### `mastra api memory status`
+
+Gets memory status for an agent and optional thread or resource context.
+
+```bash
+mastra api memory status <input>
+```
+
+#### `mastra api trace list`
+
+Lists observability traces. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api trace list [input]
+```
+
+#### `mastra api trace get`
+
+Gets one observability trace by ID.
+
+```bash
+mastra api trace get <traceId>
+```
+
+#### `mastra api log list`
+
+Lists observability logs. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api log list [input]
+```
+
+#### `mastra api score create`
+
+Creates an observability score. The input uses the server score body shape; inspect it with `--schema`.
+
+```bash
+mastra api score create <input>
+```
+
+#### `mastra api score list`
+
+Lists observability scores. Pass optional JSON input for filters such as run ID or pagination.
+
+```bash
+mastra api score list [input]
+```
+
+#### `mastra api score get`
+
+Gets one observability score by ID.
+
+```bash
+mastra api score get <scoreId>
+```
+
+#### `mastra api dataset list`
+
+Lists datasets. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api dataset list [input]
+```
+
+#### `mastra api dataset get`
+
+Gets one dataset by ID.
+
+```bash
+mastra api dataset get <datasetId>
+```
+
+#### `mastra api dataset create`
+
+Creates a dataset with JSON input.
+
+```bash
+mastra api dataset create <input>
+```
+
+#### `mastra api dataset items`
+
+Lists items in a dataset. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api dataset items <datasetId> [input]
+```
+
+#### `mastra api experiment list`
+
+Lists experiments for a dataset. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api experiment list <datasetId> [input]
+```
+
+#### `mastra api experiment get`
+
+Gets one experiment by ID.
+
+```bash
+mastra api experiment get <datasetId> <experimentId>
+```
+
+#### `mastra api experiment run`
+
+Starts an experiment for a dataset with JSON input.
+
+```bash
+mastra api experiment run <datasetId> <input>
+```
+
+#### `mastra api experiment results`
+
+Lists results for an experiment. Pass optional JSON input for route-supported filters or pagination.
+
+```bash
+mastra api experiment results <datasetId> <experimentId> [input]
+```
+
 ## Common flags
 
 ### `--dir`

package/.docs/reference/client-js/agents.md

@@ -151,6 +151,95 @@ for await (const part of uiMessageStream) {
 }
 ```
 
+### `sendSignal()`
+
+Send a signal to an active agent run or memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the signal.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const result = await agent.sendSignal({
+  signal: {
+    type: 'user-message',
+    contents: 'Also consider the customer note I just added.',
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+console.log(result.runId)
+```
+
+Use `ifActive.behavior` and `ifIdle.behavior` to control whether Mastra delivers, persists, discards, or wakes from a signal:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Store this for later.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'persist',
+  },
+})
+```
+
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Start from this signal.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
+    },
+  },
+})
+```
+
+Returns `{ accepted: true, runId: string }`.
+
+**signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to contextual XML before the next model call.
+
+**runId** (`string`): Run ID to target directly.
+
+**resourceId** (`string`): Resource ID for the memory thread. Use with \`threadId\` for thread-targeted signals.
+
+**threadId** (`string`): Thread ID to target. Use with \`resourceId\` for thread-targeted signals.
+
+**ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**ifIdle.streamOptions** (`Omit<AgentExecutionOptions, 'messages'>`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`.
+
+### `subscribeToThread()`
+
+Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendSignal()`.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+await subscription.processDataStream({
+  onChunk: async chunk => {
+    console.log(chunk)
+  },
+})
+```
+
+`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted.
+
+**resourceId** (`string`): Resource ID for the memory thread.
+
+**threadId** (`string`): Thread ID to subscribe to.
+
 ### `streamUntilIdle()`
 
 Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
@@ -161,7 +250,7 @@ const response = await agent.streamUntilIdle('Research solana for me', {
     thread: 'thread-1',
     resource: 'resource-1',
   },
-  maxIdleMs: 5 * 60_000,
+  maxIdleMs: 5 * 60_000, //optional
 })
 
 response.processDataStream({
@@ -173,6 +262,31 @@ response.processDataStream({
 })
 ```
 
+### `resumeStreamUntilIdle()`
+
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `resumeStream()`:
+
+```typescript
+const response = await agent.resumeStreamUntilIdle(
+  { approved: true, selectedOption: 'plan-b' },
+  {
+    memory: {
+      thread: 'thread-1',
+      resource: 'resource-1',
+    },
+    runId: 'run-123',
+    toolCallId: 'tool-call-456', // optional
+    maxIdleMs: 5 * 60_000, //optional
+  },
+)
+
+await response.processDataStream({
+  onChunk: chunk => {
+    console.log(chunk)
+  },
+})
+```
+
 The stream emits the same chunk types as `stream()`, plus `background-task-*` chunks for task lifecycle events. Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full server-side API and [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the payload shapes.
 
 ### `getTool()`

package/.docs/reference/client-js/responses.md

@@ -59,6 +59,8 @@ for await (const event of stream) {
 }
 ```
 
+Streaming responses can also include tool events. Tool-call streams use `response.output_item.added`, `response.function_call_arguments.delta`, `response.function_call_arguments.done`, and `response.output_item.done` events. Tool results appear as `function_call_output` items with `<toolCallId>:output` IDs.
+
 **Returns:** `Promise<ResponsesStream>`.
 
 #### `retrieve(responseId, requestContext?)`
@@ -130,6 +132,8 @@ Use [`client.conversations`](https://mastra.ai/reference/client-js/conversations
 
 If the model calls a function, that activity appears in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
 
+When `stream: true`, function calls are also emitted as Responses stream events. Read `response.function_call_arguments.delta` events for partial argument chunks and prefer `response.function_call_arguments.done` for the finalized arguments payload and tool name. Read `response.output_item.done` events for completed `function_call` and `function_call_output` items. Tool output items use `<toolCallId>:output` IDs.
+
 ## Structured output
 
 Use `text.format` when you want JSON output.

package/.docs/reference/configuration.md

@@ -175,20 +175,20 @@ Custom ID generator function for creating unique identifiers. Mastra passes opti
 > **Warning:** This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users won't need to configure this option.
 
 ```typescript
+import { v4 as uuid } from '@lukeed/uuid'
 import { Mastra } from '@mastra/core'
-import { nanoid } from 'nanoid'
 
 export const mastra = new Mastra({
   idGenerator: context => {
     if (context?.idType === 'message' && context?.threadId) {
-      return `msg-${context.threadId}-${nanoid(8)}`
+      return `msg-${context.threadId}-${uuid()}`
     }
 
     if (context?.idType === 'run' && context?.source && context?.entityId) {
-      return `${context.source}-run-${context.entityId}-${nanoid(6)}`
+      return `${context.source}-run-${context.entityId}-${uuid()}`
     }
 
-    return nanoid()
+    return uuid()
   },
 })
 ```
@@ -277,7 +277,7 @@ Visit the [Observability documentation](https://mastra.ai/docs/observability/ove
 ```typescript
 import { Mastra } from '@mastra/core'
 import { LibSQLStore } from '@mastra/libsql'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new LibSQLStore({
@@ -288,7 +288,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),