@mastra/mcp-docs-server 1.1.35-alpha.3 → 1.1.35-alpha.30

package/.docs/reference/processors/response-cache.md

@@ -0,0 +1,114 @@
+# ResponseCache
+
+`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` (cache lookup; short-circuits on hit) and `processLLMResponse` (cache write on completion).
+
+The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have transformed the prompt — so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
+
+There is no agent-level option for response caching; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+const agent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })],
+})
+
+// First call hits the LLM and writes to the cache.
+await agent.generate('What is the capital of France?')
+
+// Second identical call replays the cached response.
+await agent.generate('What is the capital of France?')
+
+// Force a fresh call but still update the cache.
+await agent.generate('What is the capital of France?', {
+  requestContext: ResponseCache.context({ bust: true }),
+})
+```
+
+See [Response caching](https://mastra.ai/docs/agents/response-caching) for the conceptual overview, scoping rules, and recommended deployment patterns.
+
+## Constructor parameters
+
+**cache** (`MastraServerCache`): The cache backend. Required. Pass any \`MastraServerCache\` implementation — \`InMemoryServerCache\` for local development, \`RedisCache\` from \`@mastra/redis\` for production, or your own subclass for a custom backend.
+
+**ttl** (`number`): Time-to-live (seconds) for entries written by this processor. Defaults to 300 seconds (5 minutes), matching OpenRouter's reference implementation. (Default: `300`)
+
+**scope** (`string | null`): Tenant scope appended to the cache key. \`null\` opts out of scoping. When omitted, the processor falls back to the resource id resolved from the request context (\`MASTRA\_RESOURCE\_ID\_KEY\`) for automatic per-user isolation.
+
+**key** (`string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>`): Override the auto-derived cache key. Pass a string to pin a key, or a function that receives \`{ agentId, scope, model, prompt, stepNumber }\` and returns a key. If the function throws, the processor falls back to the deterministic hash so the call still benefits from caching.
+
+**bust** (`boolean`): Force a cache miss on every call: skip the read but still write on completion. Useful for explicit refresh paths. (Default: `false`)
+
+**agentId** (`string`): Logical id used in the cache key namespace. Defaults to \`'mastra-response-cache'\`. Set this to the owning agent's id when you want cache entries scoped per-agent. (Default: `'mastra-response-cache'`)
+
+## Static helpers
+
+`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail — prefer them over reading/writing the raw key.
+
+### `ResponseCache.context(options)`
+
+Build a fresh `RequestContext` preloaded with per-call response cache overrides.
+
+```typescript
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom', bust: true }),
+})
+```
+
+### `ResponseCache.applyContext(requestContext, options)`
+
+Merge per-call response cache overrides into an existing `RequestContext`. Returns the same context for chaining.
+
+```typescript
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+## ResponseCacheContextOptions
+
+The shape passed to `ResponseCache.context()` / `ResponseCache.applyContext()`.
+
+**key** (`string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>`): Overrides the auto-derived cache key for this request only.
+
+**scope** (`string | null`): Overrides the tenant scope for this request only. \`null\` opts out of scoping.
+
+**bust** (`boolean`): Skip the cache read but still write on completion.
+
+`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they are instance-level concerns that should not vary per request.
+
+## ResponseCacheKeyInputs
+
+The argument passed to a `key` function (constructor or per-call). All fields contribute to the deterministic hash by default.
+
+**agentId** (`string`): Logical processor id used to namespace the cache key.
+
+**scope** (`string | null | undefined`): Resolved scope for this request, or \`null\` when scoping is disabled.
+
+**model** (`{ provider?: string; modelId?: string; specVersion?: string }`): Provider/model identity. Different models produce different responses.
+
+**prompt** (`LanguageModelV2Prompt`): The exact prompt the provider would receive, post memory load and post any prompt-modifying input processors.
+
+**stepNumber** (`number`): 0-indexed step number within the agentic loop. Greater than zero for tool steps.
+
+## Helper exports
+
+- `buildResponseCacheKey(inputs)` — the deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
+- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS` — the default `ttl` (`300`).
+- `RESPONSE_CACHE_CONTEXT_KEY` — the `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline); prefer the helpers.
+
+## Related
+
+- [Response caching](https://mastra.ai/docs/agents/response-caching)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Processor interface](https://mastra.ai/reference/processors/processor-interface)

package/.docs/reference/processors/tool-call-filter.md

@@ -19,6 +19,11 @@ const filterSpecific = new ToolCallFilter({
 const filterAfterRecentTools = new ToolCallFilter({
   filterAfterToolSteps: 2,
 })
+
+// Preserve compact model-facing output for filtered completed tool results
+const filterWithCompactToolHistory = new ToolCallFilter({
+  preserveModelOutput: true,
+})
 ```
 
 ## Constructor parameters
@@ -29,6 +34,8 @@ const filterAfterRecentTools = new ToolCallFilter({
 
 **options.filterAfterToolSteps** (`number`): Enables filtering during agent loops and preserves tool calls and results from this many recent tool-producing steps. If undefined, step filtering is disabled
 
+**options.preserveModelOutput** (`boolean`): Preserves compact model-facing output from completed filtered tool results with providerMetadata.mastra.modelOutput. Raw tool args and raw results are removed
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'tool-call-filter'
@@ -53,6 +60,27 @@ const filter = new ToolCallFilter({
 })
 ```
 
+## Preserve compact model output
+
+Set `preserveModelOutput: true` to retain compact `toModelOutput` history for completed tool results that the filter removes. This keeps the model-facing output as text in the prompt while removing the raw `toolInvocation.args` and raw `toolInvocation.result` payloads.
+
+Only completed tool results with `providerMetadata.mastra.modelOutput` are preserved. Tool calls, incomplete results, and results without stored model output are still filtered.
+
+```typescript
+const filter = new ToolCallFilter({
+  preserveModelOutput: true,
+})
+```
+
+Combine `preserveModelOutput` with `exclude` to preserve compact output only for filtered tools:
+
+```typescript
+const filter = new ToolCallFilter({
+  exclude: ['searchDatabase'],
+  preserveModelOutput: true,
+})
+```
+
 ## Extended usage example
 
 ```typescript

package/.docs/reference/storage/clickhouse.md

@@ -51,7 +51,7 @@ import { Mastra } from '@mastra/core'
 import { MastraCompositeStore } from '@mastra/core/storage'
 import { PostgresStore } from '@mastra/pg'
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 const observabilityStore = new ObservabilityStorageClickhouseVNext({
   url: process.env.CLICKHOUSE_URL!,
@@ -74,14 +74,14 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),
 })
 ```
 
-`DefaultExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
+`MastraStorageExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for details.
 
 ### Observability with the legacy domain
 
@@ -226,7 +226,7 @@ import { Mastra } from '@mastra/core'
 import { MastraCompositeStore } from '@mastra/core/storage'
 import { PostgresStore } from '@mastra/pg'
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new MastraCompositeStore({
@@ -247,7 +247,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),
@@ -287,14 +287,14 @@ In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()
 
 ClickHouse is the recommended backend for production observability:
 
-- **Insert-only strategy**: `DefaultExporter` writes completed spans in batches without per-span updates, which is the highest-throughput strategy available.
+- **Insert-only strategy**: `MastraStorageExporter` writes completed spans in batches without per-span updates, which is the highest-throughput strategy available.
 - **Columnar compression**: Span attributes and log payloads compress well compared to the same data in row-oriented databases.
 
-For the full strategy matrix and production guidance, see the [`DefaultExporter` reference](https://mastra.ai/docs/observability/tracing/exporters/default).
+For the full strategy matrix and production guidance, see the [`MastraStorageExporter` reference](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
 
 ## Related
 
 - [Storage overview](https://mastra.ai/reference/storage/overview)
 - [Composite storage](https://mastra.ai/reference/storage/composite)
-- [`DefaultExporter`](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [`MastraStorageExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)
 - [Observability overview](https://mastra.ai/docs/observability/overview)

package/.docs/reference/storage/cloudflare-d1.md

@@ -2,7 +2,7 @@
 
 The Cloudflare D1 storage implementation provides a serverless SQL database solution using Cloudflare D1, supporting relational operations and transactional consistency.
 
-> **Observability Not Supported:** Cloudflare D1 storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to D1, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with D1 as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Cloudflare D1 storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to D1, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with D1 as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
 > **Row Size Limit:** Cloudflare D1 enforces a **1 MiB maximum row size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
 

package/.docs/reference/storage/cloudflare.md

@@ -5,7 +5,7 @@ Mastra provides two Cloudflare storage implementations:
 - **Cloudflare KV** (`CloudflareKVStorage`): A globally distributed, eventually consistent key-value store
 - **Cloudflare Durable Objects** (`CloudflareDOStorage`): A strongly consistent, SQLite-based storage using Durable Objects
 
-> **Observability Not Supported:** Cloudflare storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Cloudflare as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Cloudflare storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Cloudflare as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
 ## Installation
 

package/.docs/reference/storage/composite.md

@@ -242,4 +242,4 @@ const storage = new MastraCompositeStore({
 
 > **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that have not migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
 
-> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [DefaultExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/default) for the full list of supported providers.
+> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for the full list of supported providers.

package/.docs/reference/storage/convex.md

@@ -2,7 +2,7 @@
 
 The Convex storage implementation provides a serverless storage solution using [Convex](https://convex.dev), a full-stack TypeScript development platform with real-time sync and automatic caching.
 
-> **Observability Not Supported:** Convex storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to Convex, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Convex storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to Convex, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
 > **Record Size Limit:** Convex enforces a **1 MiB maximum record size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage like S3, Cloudflare R2, or [Convex file storage](https://docs.convex.dev/file-storage).