@mastra/mcp-docs-server 1.1.26-alpha.8 → 1.1.26

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

@@ -34,59 +34,59 @@ bun add @mastra/cloudflare-d1@latest
 
 ## Usage
 
-### Using with Cloudflare Workers
+### Using with Mastra CloudflareDeployer
 
-When using D1Store in a Cloudflare Worker, you need to access the D1 binding from the worker's `env` parameter at runtime. The `D1Database` in your type definition is only for TypeScript type checking—the actual binding is provided by the Workers runtime.
+The standard way to use D1Store with Mastra on Cloudflare is with `CloudflareDeployer`. Import `env` from `cloudflare:workers` and initialize `D1Store` inline inside `new Mastra({...})`.
 
 ```typescript
+import { env } from 'cloudflare:workers'
 import { D1Store } from '@mastra/cloudflare-d1'
 import { Mastra } from '@mastra/core'
 import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
 
-type Env = {
-  D1Database: D1Database // TypeScript type definition
-}
+export const mastra = new Mastra({
+  storage: new D1Store({ binding: env.DB }),
+  deployer: new CloudflareDeployer({
+    name: 'my-worker',
+    d1_databases: [
+      {
+        binding: 'DB',
+        database_name: 'your-database-name',
+        database_id: 'your-database-id',
+      },
+    ],
+  }),
+})
+```
+
+> **Note:** When using `import { env } from 'cloudflare:workers'`, `D1Store` must be initialized inline inside `new Mastra({...})` — not extracted to a module-level variable. Alternatively, initialize `D1Store` inside the `fetch` handler after `env` is available. See [CloudflareDeployer reference](https://mastra.ai/reference/deployer/cloudflare) for details.
 
-// Factory function to create Mastra with D1 binding
-function createMastra(env: Env) {
-  const storage = new D1Store({
-    binding: env.D1Database, // ✅ Access the actual binding from env
-    tablePrefix: 'dev_', // Optional: isolate tables per environment
-  })
-
-  return new Mastra({
-    storage,
-    deployer: new CloudflareDeployer({
-      name: 'my-worker',
-      d1_databases: [
-        {
-          binding: 'D1Database', // Must match the property name in Env type
-          database_name: 'your-database-name',
-          database_id: 'your-database-id',
-        },
-      ],
-    }),
-  })
+### Using in a Cloudflare Worker without HTTP routes
+
+If you want to call Mastra directly in a Worker — for example, to run an agent or trigger a workflow — without serving HTTP routes, you don't need `CloudflareDeployer`. Access the D1 binding from the worker's `env` parameter and call Mastra programmatically.
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+import { Mastra } from '@mastra/core'
+
+type Env = {
+  DB: D1Database
 }
 
-// Cloudflare Worker export
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-    const mastra = createMastra(env)
+    const mastra = new Mastra({
+      storage: new D1Store({ binding: env.DB }),
+    })
 
-    // Your handler logic here
-    return new Response('Hello from Mastra with D1!')
+    const agent = mastra.getAgent('my-agent')
+    const result = await agent.generate('Hello')
+
+    return Response.json({ text: result.text })
   },
 }
 ```
 
-> **Important: Understanding D1 Bindings:** In the `Env` type definition, `D1Database: D1Database` serves two purposes:
->
-> - The **property name** (`D1Database`) must match the `binding` name in your `wrangler.toml`
-> - The **type** (`: D1Database`) is from `@cloudflare/workers-types` for TypeScript type checking
->
-> At runtime, Cloudflare Workers provides the actual D1 database instance via `env.D1Database`. You can't use `D1Database` directly outside of the worker's context.
-
 ### Using with REST API
 
 For non-Workers environments (Node.js, serverless functions, etc.), use the REST API approach:
@@ -108,7 +108,7 @@ Add the D1 database binding to your `wrangler.toml`:
 
 ```toml
 [[d1_databases]]
-binding = "D1Database"  # Must match the property name in your Env type
+binding = "DB"
 database_name = "your-database-name"
 database_id = "your-database-id"
 ```
@@ -119,7 +119,7 @@ Or in `wrangler.jsonc`:
 {
   "d1_databases": [
     {
-      "binding": "D1Database",
+      "binding": "DB",
       "database_name": "your-database-name",
       "database_id": "your-database-id",
     },
@@ -158,14 +158,14 @@ import { Mastra } from '@mastra/core'
 import { D1Store } from '@mastra/cloudflare-d1'
 
 type Env = {
-  D1Database: D1Database
+  DB: D1Database
 }
 
 // In a Cloudflare Worker
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     const storage = new D1Store({
-      binding: env.D1Database, // ✅ Use env.D1Database
+      binding: env.DB,
     })
 
     const mastra = new Mastra({
@@ -184,7 +184,7 @@ If you're using storage directly without Mastra, you must call `init()` explicit
 import { D1Store } from '@mastra/cloudflare-d1'
 
 type Env = {
-  D1Database: D1Database
+  DB: D1Database
 }
 
 // In a Cloudflare Worker
@@ -192,7 +192,7 @@ export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     const storage = new D1Store({
       id: 'd1-storage',
-      binding: env.D1Database, // ✅ Use env.D1Database
+      binding: env.DB,
     })
 
     // Required when using storage directly

package/.docs/reference/storage/redis.md

@@ -0,0 +1,266 @@
+# Redis Storage
+
+The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [node-redis](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.
+
+## Installation
+
+```bash
+npm install @mastra/redis
+```
+
+## Usage
+
+### Using Connection String
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  connectionString: 'redis://localhost:6379',
+})
+
+await storage.init()
+```
+
+### Using Host/Port Configuration
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  host: 'localhost',
+  port: 6379,
+  password: 'your-password',
+  db: 0,
+})
+
+await storage.init()
+```
+
+### Using Pre-configured Client
+
+For advanced configurations like Sentinel or Cluster, you can pass a pre-configured redis client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: 'redis://localhost:6379',
+  socket: {
+    reconnectStrategy: retries => Math.min(retries * 50, 2000),
+  },
+})
+
+// Connect the client before passing to RedisStore
+await client.connect()
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  client,
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for the storage instance
+
+**connectionString** (`string`): Redis connection URL (e.g., \`redis\://localhost:6379\` or \`redis\://:password\@localhost:6379\`)
+
+**host** (`string`): Redis host address
+
+**port** (`number`): Redis port number (Default: `6379`)
+
+**password** (`string`): Redis password for authentication
+
+**db** (`number`): Redis database number (Default: `0`)
+
+**client** (`RedisClient`): Pre-configured redis client (from the \`redis\` package) for advanced setups
+
+> **Note:** You must provide either `connectionString`, `host`, or `client`. These options are mutually exclusive.
+
+## Additional Notes
+
+### Key Structure
+
+The Redis storage implementation uses the following key patterns:
+
+- Threads: `mastra_threads:id:{threadId}`
+- Messages: `mastra_messages:threadId:{threadId}:id:{messageId}`
+- Message index: `msg-idx:{messageId}` (for fast lookups)
+- Thread messages sorted set: `thread:{threadId}:messages`
+- Workflow snapshots: `mastra_workflow_snapshot:namespace:{ns}:workflow_name:{name}:run_id:{id}`
+- Scores: `mastra_scorers:id:{scoreId}`
+- Resources: `mastra_resources:{resourceId}`
+
+### Redis Sentinel
+
+For high-availability deployments using Redis Sentinel, create a custom client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: 'redis://sentinel-host:26379',
+  // Configure sentinel options as needed for your setup
+})
+
+await client.connect()
+
+const storage = new RedisStore({
+  id: 'redis-sentinel-storage',
+  client,
+})
+```
+
+### Redis Cluster
+
+For Redis Cluster deployments, use the cluster client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createCluster } from 'redis'
+
+const cluster = createCluster({
+  rootNodes: [
+    { url: 'redis://node-1:6379' },
+    { url: 'redis://node-2:6379' },
+    { url: 'redis://node-3:6379' },
+  ],
+})
+
+await cluster.connect()
+
+const storage = new RedisStore({
+  id: 'redis-cluster-storage',
+  client: cluster,
+})
+```
+
+### Accessing the Underlying Client
+
+You can access the underlying redis client for custom operations:
+
+```typescript
+const storage = new RedisStore({
+  id: 'redis-storage',
+  connectionString: 'redis://localhost:6379',
+})
+
+await storage.init()
+
+const client = storage.getClient()
+
+// Custom Redis operations
+await client.set('custom-key', 'value')
+const value = await client.get('custom-key')
+```
+
+### Closing Connections
+
+When shutting down your application, close the Redis connection:
+
+```typescript
+await storage.close()
+```
+
+## Usage Example
+
+### Adding memory to an agent
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { RedisStore } from '@mastra/redis'
+
+export const redisAgent = new Agent({
+  id: 'redis-agent',
+  name: 'Redis Agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-4o',
+  memory: new Memory({
+    storage: new RedisStore({
+      id: 'redis-agent-storage',
+      connectionString: process.env.REDIS_URL!,
+    }),
+    options: {
+      lastMessages: 10,
+    },
+  }),
+})
+```
+
+### Using the agent
+
+```typescript
+import 'dotenv/config'
+
+import { mastra } from './mastra'
+
+const threadId = '123'
+const resourceId = 'user-456'
+
+const agent = mastra.getAgent('redisAgent')
+
+const message = await agent.stream('My name is Mastra', {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+})
+
+await message.textStream.pipeTo(new WritableStream())
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+  },
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+### Using with Mastra instance
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'mastra-storage',
+  host: 'localhost',
+  port: 6379,
+})
+
+const mastra = new Mastra({
+  storage, // init() called automatically
+})
+```
+
+If using storage directly without Mastra, call `init()` explicitly:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  host: 'localhost',
+  port: 6379,
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```

package/.docs/reference/streaming/agents/stream.md

@@ -206,6 +206,14 @@ const stream = await agent.stream('message for agent')
 
 **options.tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
 
+**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See \[Sub-agent versioning]\(/docs/editor/overview#sub-agent-versioning).
+
+**options.versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors.
+
+**options.versions.agents.versionId** (`string`): Target a specific version by ID.
+
+**options.versions.agents.status** (`'draft' | 'published'`): Target the latest version with this publication status.
+
 ## Returns
 
 **stream** (`MastraModelOutput<Output>`): Returns a MastraModelOutput instance that provides access to the streaming output.

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -32,6 +32,8 @@ if (result!.status === 'suspended') {
 
 **step** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
 
+**forEachIndex** (`number`): Target a specific iteration of a suspended \`.foreach()\` step. Pass the zero-based index of the iteration to resume; other iterations remain suspended. Omit to resume all suspended iterations of the step with the same \`resumeData\`.
+
 **tracingOptions** (`TracingOptions`): Options for Tracing configuration.
 
 **tracingOptions.metadata** (`Record<string, any>`): Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.