@mastra/mcp-docs-server 1.2.19-alpha.4 → 1.2.19

package/.docs/models/providers.md

@@ -14,8 +14,11 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [302.AI](https://mastra.ai/models/providers/302ai)
 - [Abacus](https://mastra.ai/models/providers/abacus)
 - [abliteration.ai](https://mastra.ai/models/providers/abliteration-ai)
+- [AgentRouter](https://mastra.ai/models/providers/agentrouter)
+- [Agnes AI](https://mastra.ai/models/providers/agnes)
 - [AI-ROUTER](https://mastra.ai/models/providers/ai-router)
 - [ai&](https://mastra.ai/models/providers/aiand)
+- [Aixy](https://mastra.ai/models/providers/aixy)
 - [AKI.IO](https://mastra.ai/models/providers/aki-io)
 - [Alibaba](https://mastra.ai/models/providers/alibaba)
 - [Alibaba (China)](https://mastra.ai/models/providers/alibaba-cn)
@@ -77,6 +80,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [InferX](https://mastra.ai/models/providers/inferx)
 - [Infomaniak](https://mastra.ai/models/providers/infomaniak)
 - [IO.NET](https://mastra.ai/models/providers/io-net)
+- [IteraCompute](https://mastra.ai/models/providers/iteracompute)
 - [Jalapeno Cloud](https://mastra.ai/models/providers/jalapeno)
 - [Jiekou.AI](https://mastra.ai/models/providers/jiekou)
 - [Kenari](https://mastra.ai/models/providers/kenari)
@@ -87,6 +91,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Lilac](https://mastra.ai/models/providers/lilac)
 - [Llama](https://mastra.ai/models/providers/llama)
 - [LLM Gateway](https://mastra.ai/models/providers/llmgateway-providers)
+- [LLM Tech](https://mastra.ai/models/providers/llmtech)
 - [LLMTR](https://mastra.ai/models/providers/llmtr)
 - [LMStudio](https://mastra.ai/models/providers/lmstudio)
 - [LongCat](https://mastra.ai/models/providers/longcat)
@@ -110,6 +115,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [NanoGPT](https://mastra.ai/models/providers/nano-gpt)
 - [NEAR AI Cloud](https://mastra.ai/models/providers/nearai)
 - [Nebius Token Factory](https://mastra.ai/models/providers/nebius)
+- [NeoSmith](https://mastra.ai/models/providers/neosmith)
 - [Neuralwatt](https://mastra.ai/models/providers/neuralwatt)
 - [Nova](https://mastra.ai/models/providers/nova)
 - [NovitaAI](https://mastra.ai/models/providers/novita-ai)
@@ -118,8 +124,10 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Ollama Cloud](https://mastra.ai/models/providers/ollama-cloud)
 - [OpenCode Go](https://mastra.ai/models/providers/opencode-go)
 - [OpenCode Zen](https://mastra.ai/models/providers/opencode)
+- [Opper](https://mastra.ai/models/providers/opper)
 - [OrcaRouter](https://mastra.ai/models/providers/orcarouter)
 - [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)
+- [Pendra](https://mastra.ai/models/providers/pendra)
 - [Perplexity](https://mastra.ai/models/providers/perplexity)
 - [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)
 - [Pioneer](https://mastra.ai/models/providers/pioneer)
@@ -141,6 +149,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn)
 - [Snowflake Cortex](https://mastra.ai/models/providers/snowflake-cortex)
 - [STACKIT](https://mastra.ai/models/providers/stackit)
+- [Standard Compute](https://mastra.ai/models/providers/standardcompute)
 - [StepFun (China)](https://mastra.ai/models/providers/stepfun)
 - [StepFun (Global)](https://mastra.ai/models/providers/stepfun-ai)
 - [StepFun Step Plan (China)](https://mastra.ai/models/providers/stepfun-step-plan)

package/.docs/reference/agents/channels.md

@@ -162,7 +162,7 @@ const agent = new Agent({
 
 ## Custom typing status
 
-Pass a function to `typingStatus` to customize the status copy. The function is called once per stream chunk; return a string to set the status, or `false` / `null` / `undefined` to leave the current status unchanged. Return values are de-duplicated so the platform only sees a call when the status changes.
+Pass a function to `typingStatus` to customize the status copy. The function is called once per stream chunk; return a string to set the status, or `false` / `null` / `undefined` to leave the current status unchanged. Return values are de-duplicated so the platform only sees a call when the status changes. When the run ends, any status it set is cleared automatically so runs that finish without posting a message don't leave a stale status on the thread.
 
 `defaultTypingStatus` is exported from `@mastra/core/channels` so you can fall back to the built-in defaults for chunks you don't handle.
 

package/.docs/reference/ai-sdk/handle-chat-stream.md

@@ -49,6 +49,17 @@ export async function POST(req: Request) {
 }
 ```
 
+## Keeping connections alive
+
+Proxies and load balancers often close a connection that sends no bytes for a while, which drops the response during long reasoning bursts or slow tool calls. Wrap the encoded response with [`withSseHeartbeat()`](https://mastra.ai/reference/ai-sdk/with-sse-heartbeat) to emit periodic SSE comments while the stream is idle:
+
+```typescript
+import { handleChatStream, withSseHeartbeat } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+
+return withSseHeartbeat(createUIMessageStreamResponse({ stream }), 15000)
+```
+
 ## Parameters
 
 **version** (`'v5' | 'v6' | 'v7'`): Selects the AI SDK stream contract to emit. Omit it or pass 'v5' for the existing default behavior. Pass 'v6' when your app is typed against AI SDK v6 response helpers. Pass 'v7' when your app is typed against AI SDK v7. (Default: `'v5'`)

package/.docs/reference/ai-sdk/with-sse-heartbeat.md

@@ -0,0 +1,47 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# withSseHeartbeat()
+
+Wraps a server-sent events `Response` so it emits periodic `: heartbeat` comments while the underlying stream is idle. Proxies and load balancers often close connections that send no bytes for a while, which drops responses during long reasoning bursts or slow tool calls.
+
+Use this when you build the response yourself with [`handleChatStream()`](https://mastra.ai/reference/ai-sdk/handle-chat-stream), [`handleWorkflowStream()`](https://mastra.ai/reference/ai-sdk/handle-workflow-stream), or [`handleNetworkStream()`](https://mastra.ai/reference/ai-sdk/handle-network-stream). [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) applies the same wrapper internally through its `heartbeatMs` option.
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript
+import { handleChatStream, withSseHeartbeat } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '@/src/mastra'
+
+export async function POST(req: Request) {
+  const params = await req.json()
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    version: 'v7',
+    params,
+  })
+  return withSseHeartbeat(createUIMessageStreamResponse({ stream }), 15000)
+}
+```
+
+Wrap the response after it has been encoded. `handleChatStream()` returns a stream of UI message chunks, and heartbeats are raw SSE comments that only exist once those chunks are serialized to the wire format.
+
+## Parameters
+
+**response** (`Response`): The server-sent events response to wrap. Status, status text, and headers are preserved.
+
+**heartbeatMs** (`number`): Interval in milliseconds between heartbeats. Omit it or pass a value of 0 or less to disable heartbeats.
+
+## Returns
+
+A `Response` that streams the source body with heartbeat comments inserted during idle periods. The input response is returned unchanged when `heartbeatMs` is omitted, is `0` or less, or the response has no body.
+
+## Behavior
+
+- Heartbeats are only inserted between complete SSE frames, so a partially delivered frame is never split.
+- Source data, stream completion, and stream errors always take priority over a due heartbeat.
+- Canceling the wrapped response cancels the source stream and clears the pending heartbeat timer.
+- A `RangeError` is thrown when heartbeats are enabled with a value that can't be scheduled with a timer, meaning a non-finite number or a value greater than `2147483647`. Use `assertValidHeartbeatMs()` to apply the same check to user-supplied configuration before you start streaming.

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

@@ -1100,9 +1100,9 @@ For runtime commands, the command resolves the target server in this order:
 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 don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
+Automatic Platform authentication is used when the CLI resolves a project from `.mastra-project.json` or recognizes an explicit Mastra-hosted Studio, Factory, or observability URL. Localhost and arbitrary explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
-For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. Both resolve credentials in this order:
+For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets the United States endpoint at `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. When the CLI selects either hosted target automatically, it resolves credentials in this order:
 
 1. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
 2. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your environment.
@@ -1111,7 +1111,13 @@ For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targ
 
 Learning commands also send `X-Mastra-Organization-Id`, resolved from an explicit `--header`, `MASTRA_ORGANIZATION_ID` in your environment, or `.mastra-project.json`, in that order.
 
-Use `--url` and `--header` when you need to override the default hosted observability target or credentials.
+European Union observability data is stored at `https://observability.eu.mastra.ai`. Pass that trusted host with `--url`; it uses the same Platform credential resolution as the default United States endpoint:
+
+```bash
+mastra api --url https://observability.eu.mastra.ai trace list
+```
+
+Use `--url` and `--header` when you need to override another target or its credentials.
 
 ### Flags
 
@@ -1527,7 +1533,7 @@ mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","p
 
 #### Observability with `curl`
 
-You can call the hosted observability API directly with your platform access token and project ID:
+You can call the hosted observability API directly with your platform access token and project ID. The examples below use the United States host. Substitute `https://observability.eu.mastra.ai` for a European Union environment. The [hosted feedback query API](https://mastra.ai/docs/mastra-platform/api) documents feedback endpoints that don't have CLI commands:
 
 ```bash
 curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \

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

@@ -92,7 +92,7 @@ const scores = await mastraClient.listScoresBySpan({
 
 ## Feedback
 
-Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
+Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform feedback query API. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
 
 ### Creating feedback
 

package/.docs/reference/index.md

@@ -45,6 +45,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [toAISdkV4Messages()](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v4-messages)
 - [toAISdkV5Messages()](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v5-messages)
 - [withMastra()](https://mastra.ai/reference/ai-sdk/with-mastra)
+- [withSseHeartbeat()](https://mastra.ai/reference/ai-sdk/with-sse-heartbeat)
 - [workflowRoute()](https://mastra.ai/reference/ai-sdk/workflow-route)
 - [workflowSnapshotToStream()](https://mastra.ai/reference/ai-sdk/workflow-snapshot-to-stream)
 - [Auth0](https://mastra.ai/reference/auth/auth0)
@@ -244,6 +245,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Feedback](https://mastra.ai/reference/observability/feedback)
 - [PinoLogger](https://mastra.ai/reference/logging/pino-logger)
 - [Automatic Metrics](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [Metric queries](https://mastra.ai/reference/observability/metrics/queries)
 - [Configuration](https://mastra.ai/reference/observability/tracing/configuration)
 - [Instances](https://mastra.ai/reference/observability/tracing/instances)
 - [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces)
@@ -277,6 +279,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PubSub](https://mastra.ai/reference/pubsub/base)
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams)
 - [UnixSocketPubSub](https://mastra.ai/reference/pubsub/unix-socket-pubsub)
+- [ValkeyStreamsPubSub](https://mastra.ai/reference/pubsub/valkey-streams)
 - [Overview](https://mastra.ai/reference/rag/overview)
 - [Chunking and Embedding](https://mastra.ai/reference/rag/chunking-and-embedding)
 - [DatabaseConfig](https://mastra.ai/reference/rag/database-config)
@@ -293,6 +296,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.chunk()](https://mastra.ai/reference/rag/chunk)
 - [Overview](https://mastra.ai/reference/schedules/overview)
 - [createRoute()](https://mastra.ai/reference/server/create-route)
+- [Elysia Adapter](https://mastra.ai/reference/server/elysia-adapter)
 - [Express Adapter](https://mastra.ai/reference/server/express-adapter)
 - [Fastify Adapter](https://mastra.ai/reference/server/fastify-adapter)
 - [Hono Adapter](https://mastra.ai/reference/server/hono-adapter)
@@ -308,6 +312,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/storage/overview)
 - [Composite Storage](https://mastra.ai/reference/storage/composite)
 - [Retention (prune)](https://mastra.ai/reference/storage/retention)
+- [Turso Storage](https://mastra.ai/reference/storage/turso)
 - [ChunkType](https://mastra.ai/reference/streaming/ChunkType)
 - [smoothStream()](https://mastra.ai/reference/streaming/smoothStream)
 - [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput)

package/.docs/reference/observability/feedback.md

@@ -54,6 +54,8 @@ await mastra.observability.addFeedback?.({
 
 **feedback** (`FeedbackInput`): Feedback payload to add.
 
+Without `correlationContext`, the method looks up `traceId` in configured observability storage. If the trace or requested span isn't found, Mastra logs a warning and drops the feedback event. Configure `MastraStorageExporter` when adding feedback by ID after execution, including when `MastraPlatformExporter` handles remote export.
+
 ### `createFeedback(args)`
 
 Creates one feedback record through the observability storage domain. Storage-level calls write directly to the store, so include `timestamp`.
@@ -375,6 +377,8 @@ Use `FeedbackFilter` in `listFeedback()` and OLAP query `filters`.
 
 ## HTTP routes
 
+These routes belong to a Mastra runtime and use its configured observability storage. They're separate from the [unversioned Mastra Platform feedback query API](https://mastra.ai/docs/mastra-platform/api), which doesn't provide a feedback creation route.
+
 | Method | Path                                      | Purpose                      | Permission           |
 | ------ | ----------------------------------------- | ---------------------------- | -------------------- |
 | `GET`  | `/api/observability/feedback`             | List feedback records        | None derived         |

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -136,5 +136,5 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ## Related
 
 - [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
-- [Querying metrics](https://mastra.ai/docs/observability/metrics/querying)
+- [Metric queries](https://mastra.ai/reference/observability/metrics/queries)
 - [Studio observability](https://mastra.ai/docs/studio/observability)