@mastra/mcp-docs-server 1.1.42 → 1.1.43

package/.docs/reference/pubsub/redis-streams.md

@@ -0,0 +1,108 @@
+# RedisStreamsPubSub
+
+`RedisStreamsPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation backed by [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/). It delivers events across processes and hosts, with persistence, consumer groups, and redelivery on failure.
+
+Use it for distributed deployments where several services share an event stream. For single-process delivery, use [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). For Google Cloud, use [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
+
+Each topic maps to a Redis stream key. Subscriptions with a group use a Redis consumer group, so members share work round-robin. Subscriptions without a group create a private consumer group, so every subscriber receives every event.
+
+`RedisStreamsPubSub` is a pull transport: consumers read events with `XREADGROUP`, so Mastra runs an orchestration worker to read on its behalf.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/redis-streams
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/redis-streams
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/redis-streams
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/redis-streams
+```
+
+## Usage example
+
+Provide a Redis connection URL.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  pubsub: new RedisStreamsPubSub({
+    url: 'redis://localhost:6379',
+  }),
+})
+```
+
+## Constructor parameters
+
+**url** (`string`): Redis connection URL. Falls back to \`redisOptions.url\`. (Default: `redis://localhost:6379`)
+
+**keyPrefix** (`string`): Prefix for stream keys. Each topic maps to \`\<keyPrefix>:\<topic>\`. (Default: `mastra:topic`)
+
+**blockMs** (`number`): How long, in milliseconds, each read blocks while waiting for new events. (Default: `1000`)
+
+**redisOptions** (`RedisClientOptions`): Options passed to the underlying \`redis\` client for advanced configuration.
+
+**maxStreamLength** (`number`): Approximate maximum number of entries kept per stream. Set to 0 to disable trimming. (Default: `10000`)
+
+**reclaimIntervalMs** (`number`): How often, in milliseconds, a subscription reclaims events that an earlier consumer read but never acknowledged. Set to 0 to disable. (Default: `30000`)
+
+**reclaimIdleMs** (`number`): Minimum idle time, in milliseconds, before a pending event is eligible for reclaim. Keep this well above typical processing time to avoid double delivery. (Default: `60000`)
+
+**maxDeliveryAttempts** (`number`): Maximum times an event is redelivered through \`nack\` before it is dropped. Pass \`Infinity\` to disable the cap. (Default: `5`)
+
+**logger** (`{ debug?: Function; warn?: Function }`): Optional logger for diagnostics. When omitted, suppressed errors are silent.
+
+## Properties
+
+**supportedModes** (`ReadonlyArray<"pull" | "push">`): Returns \`\["pull"]\`.
+
+## Methods
+
+`RedisStreamsPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.
+
+### `subscribe(topic, cb, options?)`
+
+Subscribes to a topic. With `options.group`, members of the group share events through a Redis consumer group. Without a group, the subscriber receives every event through a private consumer group.
+
+```typescript
+await pubsub.subscribe('workflow.events', (event, ack, nack) => {
+  console.log(event)
+})
+```
+
+### `flush()`
+
+Waits for in-flight publishes to complete.
+
+```typescript
+await pubsub.flush()
+```
+
+### `close()`
+
+Closes the Redis connections and stops all subscriptions. Call this during graceful shutdown.
+
+```typescript
+await pubsub.close()
+```
+
+## Redelivery and reclaim
+
+When a subscriber calls `nack`, the event is republished with an incremented `deliveryAttempt` and the original is acknowledged. Once an event reaches `maxDeliveryAttempts`, it is dropped instead of redelivered. Separately, each subscription periodically reclaims events that an earlier consumer in the group read but never acknowledged, controlled by `reclaimIntervalMs` and `reclaimIdleMs`.

package/.docs/reference/pubsub/unix-socket-pubsub.md

@@ -0,0 +1,52 @@
+# UnixSocketPubSub
+
+`UnixSocketPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation that delivers events across processes on a single host using a Unix domain socket. It elects one process as a broker, and other processes connect to it as clients. If the broker exits, the remaining clients elect a new broker automatically.
+
+Use it when several local processes need to share a stream, such as coordinating thread streams across the Mastra Code terminal interface. For single-process delivery, use [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). For distributed delivery across hosts, use [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
+
+`UnixSocketPubSub` is a push transport: events arrive without a read loop, so Mastra does not run a pull worker for it.
+
+## Usage example
+
+Pass a socket path that every participating process shares.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { UnixSocketPubSub } from '@mastra/core/events'
+
+export const mastra = new Mastra({
+  pubsub: new UnixSocketPubSub('/tmp/mastra/events.sock'),
+})
+```
+
+## Constructor parameters
+
+**socketPath** (`string`): Path to the Unix domain socket. All processes that share a stream must use the same path.
+
+**options** (`UnixSocketPubSubOptions`): Optional configuration.
+
+## Properties
+
+**socketPath** (`string`): The socket path passed to the constructor.
+
+**supportedModes** (`ReadonlyArray<"pull" | "push">`): Returns \`\["push"]\`.
+
+**isBroker** (`boolean`): Whether this instance currently acts as the broker.
+
+**remoteClientCount** (`number`): Number of remote clients connected to this broker. Always 0 when this instance is not the broker.
+
+## Methods
+
+`UnixSocketPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The method below is specific to this implementation.
+
+### `close()`
+
+Closes the socket connection and, when this instance is the broker, releases the broker role. Call this during graceful shutdown.
+
+```typescript
+await pubsub.close()
+```
+
+## Broker election
+
+The first process to bind the socket becomes the broker and routes events between all connected clients. Other processes connect as clients. When the broker exits, an exclusive lock file serializes the next election so exactly one client becomes the new broker, and the remaining clients resubscribe to it. This avoids a split-brain state where two processes both act as broker.

package/.docs/reference/storage/libsql.md

@@ -93,6 +93,12 @@ storage: new LibSQLStore({
 
 **authToken** (`string`): Authentication token for remote libSQL databases.
 
+## Managed tables
+
+The storage implementation creates the core storage tables automatically, including `mastra_notifications` for notification inbox records and delivery metadata.
+
+`LibSQLStore` exposes notification storage through `getStore('notifications')`.
+
 ## Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/storage/overview):

package/.docs/reference/storage/mongodb.md

@@ -97,6 +97,9 @@ The storage implementation handles collection creation and management automatica
 - `mastra_traces`: Stores telemetry and tracing data
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
+- `mastra_notifications`: Stores notification inbox records and delivery metadata
+
+`MongoDBStore` exposes notification storage through `getStore('notifications')`.
 
 ### Initialization
 

package/.docs/reference/storage/postgresql.md

@@ -132,6 +132,9 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_traces`: Stores telemetry and tracing data
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
+- `mastra_notifications`: Stores notification inbox records and delivery metadata
+
+`PostgresStore` exposes notification storage through `getStore('notifications')`.
 
 ### Observability
 

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mastra/mcp-docs-server
 
+## 1.1.43
+
+### Patch Changes
+
+- Updated dependencies [[`c973db4`](https://github.com/mastra-ai/mastra/commit/c973db428df1b564ff0c35d4b2a90e8f4f1e13fd), [`552285e`](https://github.com/mastra-ai/mastra/commit/552285e5af43cfc680a0972032cab8de8776c6a0), [`77e686c`](https://github.com/mastra-ai/mastra/commit/77e686c264e493e99ae5024e4dfe3ea5d5a09718), [`ece8dba`](https://github.com/mastra-ai/mastra/commit/ece8dba7ec1a5089eee8c33167cd762bfa91e509), [`e751af2`](https://github.com/mastra-ai/mastra/commit/e751af219433fbf4c7035b2d771b4c9ec8813b05), [`e2a8380`](https://github.com/mastra-ai/mastra/commit/e2a838017a7657850404c1e94c70d79ffdc6f14a), [`be3f1cd`](https://github.com/mastra-ai/mastra/commit/be3f1cd81f0e2a649e8eac15a024d542d814aef8), [`a34d9db`](https://github.com/mastra-ai/mastra/commit/a34d9dbc39fedb722f271318e9355ecee70489ab)]:
+  - @mastra/core@1.39.0
+  - @mastra/mcp@1.9.1
+
+## 1.1.43-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`c973db4`](https://github.com/mastra-ai/mastra/commit/c973db428df1b564ff0c35d4b2a90e8f4f1e13fd), [`552285e`](https://github.com/mastra-ai/mastra/commit/552285e5af43cfc680a0972032cab8de8776c6a0), [`77e686c`](https://github.com/mastra-ai/mastra/commit/77e686c264e493e99ae5024e4dfe3ea5d5a09718), [`ece8dba`](https://github.com/mastra-ai/mastra/commit/ece8dba7ec1a5089eee8c33167cd762bfa91e509), [`e751af2`](https://github.com/mastra-ai/mastra/commit/e751af219433fbf4c7035b2d771b4c9ec8813b05), [`e2a8380`](https://github.com/mastra-ai/mastra/commit/e2a838017a7657850404c1e94c70d79ffdc6f14a), [`be3f1cd`](https://github.com/mastra-ai/mastra/commit/be3f1cd81f0e2a649e8eac15a024d542d814aef8), [`a34d9db`](https://github.com/mastra-ai/mastra/commit/a34d9dbc39fedb722f271318e9355ecee70489ab)]:
+  - @mastra/core@1.39.0-alpha.0
+  - @mastra/mcp@1.9.1-alpha.0
+
 ## 1.1.42
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.42",
+  "version": "1.1.43",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.9.0",
-    "@mastra/core": "1.38.0"
+    "@mastra/core": "1.39.0",
+    "@mastra/mcp": "^1.9.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.75",
-    "@internal/lint": "0.0.100",
-    "@mastra/core": "1.38.0"
+    "@internal/lint": "0.0.101",
+    "@mastra/core": "1.39.0",
+    "@internal/types-builder": "0.0.76"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/docs/agents/response-caching.md

@@ -1,150 +0,0 @@
-# Response Caching
-
-> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
-
-Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
-
-Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. Mastra doesn't provide an agent-level option. To enable caching, register the processor explicitly. This keeps the API surface small while Mastra collects feedback; per-call overrides flow through `RequestContext`.
-
-## When to use response caching
-
-Reach for it when the same request shape repeats across users or sessions, for example prompt templates, suggested-prompt buttons, agentic search re-asks, or guardrail LLMs that classify the same input over and over. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
-
-## Quickstart
-
-Add a `ResponseCache` to the agent's `inputProcessors` and pass any `MastraServerCache` as the backend. For development, `InMemoryServerCache` works out of the box:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { InMemoryServerCache } from '@mastra/core/cache'
-import { ResponseCache } from '@mastra/core/processors'
-
-const cache = new InMemoryServerCache()
-
-export const searchAgent = new Agent({
-  name: 'Search Agent',
-  instructions: 'You answer questions concisely.',
-  model: 'openai/gpt-5',
-  inputProcessors: [new ResponseCache({ cache, ttl: 600 })], // 10 minutes
-})
-```
-
-The first call runs the LLM normally and writes the response to the cache. Subsequent calls with an identical resolved prompt return the cached response without invoking the LLM.
-
-## Per-call overrides via RequestContext
-
-Per-call config flows through `RequestContext`. Use `ResponseCache.context()` to build a fresh context, or `ResponseCache.applyContext()` to merge into one you already have:
-
-```typescript
-import { ResponseCache } from '@mastra/core/processors'
-import { RequestContext } from '@mastra/core/request-context'
-
-// Fresh context with the override
-await agent.stream('hello', {
-  requestContext: ResponseCache.context({ key: 'custom-key', bust: true }),
-})
-
-// Or merge into an existing context
-const ctx = new RequestContext()
-ctx.set('caller-meta', { userId: 'u-123' })
-ResponseCache.applyContext(ctx, { bust: true })
-await agent.stream('hello', { requestContext: ctx })
-```
-
-Three fields are overridable per call:
-
-- `key`: String or function. Overrides the auto-derived cache key for this request only.
-- `scope`: String or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
-- `bust`: Boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
-
-`cache`, `ttl`, and `agentId` stay on the constructor. They're instance-level concerns and not safe to vary per call.
-
-## Tenant scoping
-
-By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Two users never see each other's cached responses.
-
-Override explicitly when you need a different scope:
-
-```typescript
-new Agent({
-  // ...
-  inputProcessors: [
-    new ResponseCache({
-      cache,
-      scope: 'org-123', // explicit tenant scope
-    }),
-  ],
-})
-```
-
-Pass `scope: null` to deliberately share entries across all callers. Only use this for known-public, non-personalized content.
-
-## Custom cache backend
-
-`ResponseCache` accepts any `MastraServerCache`. For production, use `RedisCache` from `@mastra/redis`:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { ResponseCache } from '@mastra/core/processors'
-import { RedisCache } from '@mastra/redis'
-
-const cache = new RedisCache({ url: process.env.REDIS_URL })
-
-export const agent = new Agent({
-  name: 'Cached Agent',
-  instructions: '...',
-  model: 'openai/gpt-5',
-  inputProcessors: [new ResponseCache({ cache })],
-})
-```
-
-For a custom backend, extend `MastraServerCache` and implement its abstract methods (the processor only calls `get` and `set`).
-
-## How caching is implemented
-
-`ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
-
-This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model. The key is created _after_ memory has loaded and earlier input processors have run, and each step in an agentic tool loop is independently cached.
-
-## What's in the cache key
-
-When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
-
-### Customize the cache key
-
-Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):
-
-```typescript
-import { ResponseCache, buildResponseCacheKey } from '@mastra/core/processors'
-
-await agent.stream(input, {
-  requestContext: ResponseCache.context({
-    // Cache only on the model id and the resolved prompt tail — ignore
-    // step number, scope, etc.
-    key: ({ model, prompt }) => `qa:${model.modelId}:${JSON.stringify(prompt).slice(-200)}`,
-  }),
-})
-
-// Or reuse the deterministic helper while overriding individual fields:
-await agent.stream(input, {
-  requestContext: ResponseCache.context({
-    key: inputs => buildResponseCacheKey({ ...inputs, scope: 'global' }),
-  }),
-})
-```
-
-If the function throws, the processor falls back to the default key derivation so the call still benefits from caching.
-
-## How cache hits work
-
-When the processor finds a cache hit, it short-circuits the LLM call by returning the cached chunks from `processLLMRequest`. The agentic loop synthesizes a stream from those chunks instead of calling the model. `agent.generate()` collects them into a `FullOutput`; `agent.stream()` returns a `MastraModelOutput` whose chunks come from the cached buffer, so consumers iterating `fullStream` or awaiting `text`, `usage`, and `finishReason` see the cached values.
-
-Cache writes happen after the response completes. Failed runs (errors, tripwire activations) aren't cached, so the next call retries cleanly.
-
-## Related
-
-- [`ResponseCache` reference](https://mastra.ai/reference/processors/response-cache)
-- [Processors](https://mastra.ai/docs/agents/processors)
-- [Guardrails](https://mastra.ai/docs/agents/guardrails)
-- [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream)
-- [Agent.generate()](https://mastra.ai/reference/agents/generate)