@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

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

@@ -0,0 +1,218 @@
+# Cloudflare D1 Storage
+
+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 **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to D1, and Mastra Studio's 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.
+
+> **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.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/cloudflare-d1@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cloudflare-d1@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cloudflare-d1@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cloudflare-d1@latest
+```
+
+## Usage
+
+### Using with Cloudflare Workers
+
+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.
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+import { Mastra } from '@mastra/core'
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
+
+type Env = {
+  D1Database: D1Database // TypeScript type definition
+}
+
+// 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',
+        },
+      ],
+    }),
+  })
+}
+
+// Cloudflare Worker export
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const mastra = createMastra(env)
+
+    // Your handler logic here
+    return new Response('Hello from Mastra with D1!')
+  },
+}
+```
+
+> **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 cannot 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:
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+
+const storage = new D1Store({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
+  databaseId: process.env.CLOUDFLARE_D1_DATABASE_ID!, // D1 Database ID
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
+  tablePrefix: 'dev_', // Optional: isolate tables per environment
+})
+```
+
+### Wrangler Configuration
+
+Add the D1 database binding to your `wrangler.toml`:
+
+```toml
+[[d1_databases]]
+binding = "D1Database"  # Must match the property name in your Env type
+database_name = "your-database-name"
+database_id = "your-database-id"
+```
+
+Or in `wrangler.jsonc`:
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "D1Database",
+      "database_name": "your-database-name",
+      "database_id": "your-database-id",
+    },
+  ],
+}
+```
+
+## Parameters
+
+**binding?:** (`D1Database`): Cloudflare D1 Workers binding (for Workers runtime)
+
+**accountId?:** (`string`): Cloudflare Account ID (for REST API)
+
+**databaseId?:** (`string`): Cloudflare D1 Database ID (for REST API)
+
+**apiToken?:** (`string`): Cloudflare API Token (for REST API)
+
+**tablePrefix?:** (`string`): Optional prefix for all table names (useful for environment isolation)
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { D1Store } from '@mastra/cloudflare-d1'
+
+type Env = {
+  D1Database: 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
+    })
+
+    const mastra = new Mastra({
+      storage, // init() is called automatically
+    })
+
+    // Your handler logic here
+    return new Response('Success')
+  },
+}
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+
+type Env = {
+  D1Database: D1Database
+}
+
+// In a Cloudflare Worker
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const storage = new D1Store({
+      id: 'd1-storage',
+      binding: env.D1Database, // ✅ Use env.D1Database
+    })
+
+    // Required when using storage directly
+    await storage.init()
+
+    // Access domain-specific stores via getStore()
+    const memoryStore = await storage.getStore('memory')
+    const thread = await memoryStore?.getThreadById({ threadId: '...' })
+
+    return new Response('Success')
+  },
+}
+```
+
+> **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+
+### Transactions & Consistency
+
+Cloudflare D1 provides transactional guarantees for single-row operations. This means that multiple operations can be executed as a single, all-or-nothing unit of work.
+
+### Table Creation & Migrations
+
+Tables are created automatically when storage is initialized (and can be isolated per environment using the `tablePrefix` option), but advanced schema changes—such as adding columns, changing data types, or modifying indexes—require manual migration and careful planning to avoid data loss.

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

@@ -0,0 +1,88 @@
+# Cloudflare Storage
+
+The Cloudflare KV storage implementation provides a globally distributed, serverless key-value store solution using Cloudflare Workers KV.
+
+> **Observability Not Supported:** Cloudflare KV storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to KV, and Mastra Studio's observability features won't work with Cloudflare KV 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.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/cloudflare@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cloudflare@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cloudflare@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cloudflare@latest
+```
+
+## Usage
+
+```typescript
+import { CloudflareStore } from '@mastra/cloudflare'
+
+// --- Example 1: Using Workers Binding ---
+const storageWorkers = new CloudflareStore({
+  id: 'cloudflare-workers-storage',
+  bindings: {
+    threads: THREADS_KV, // KVNamespace binding for threads table
+    messages: MESSAGES_KV, // KVNamespace binding for messages table
+    // Add other tables as needed
+  },
+  keyPrefix: 'dev_', // Optional: isolate keys per environment
+})
+
+// --- Example 2: Using REST API ---
+const storageRest = new CloudflareStore({
+  id: 'cloudflare-rest-storage',
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
+  namespacePrefix: 'dev_', // Optional: isolate namespaces per environment
+})
+```
+
+## Parameters
+
+**id:** (`string`): Unique identifier for this storage instance.
+
+**bindings?:** (`Record<string, KVNamespace>`): Cloudflare Workers KV bindings (for Workers runtime)
+
+**accountId?:** (`string`): Cloudflare Account ID (for REST API)
+
+**apiToken?:** (`string`): Cloudflare API Token (for REST API)
+
+**namespacePrefix?:** (`string`): Optional prefix for all namespace names (useful for environment isolation)
+
+**keyPrefix?:** (`string`): Optional prefix for all keys (useful for environment isolation)
+
+### Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Consistency & Propagation
+
+Cloudflare KV is an eventually consistent store, meaning that data may not be immediately available across all regions after a write.
+
+### Key Structure & Namespacing
+
+Keys in Cloudflare KV are structured as a combination of a configurable prefix and a table-specific format (e.g., `threads:threadId`). For Workers deployments, `keyPrefix` is used to isolate data within a namespace; for REST API deployments, `namespacePrefix` is used to isolate entire namespaces between environments or applications.

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

@@ -0,0 +1,235 @@
+# Composite Storage
+
+`MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
+
+## Installation
+
+`MastraCompositeStore` is included in `@mastra/core`:
+
+**npm**:
+
+```bash
+npm install @mastra/core@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/core@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/core@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/core@latest
+```
+
+You'll also need to install the storage providers you want to compose:
+
+**npm**:
+
+```bash
+npm install @mastra/pg@latest @mastra/libsql@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/pg@latest @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/pg@latest @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/pg@latest @mastra/libsql@latest
+```
+
+## Storage domains
+
+Mastra organizes storage into five specialized domains, each handling a specific type of data. Each domain can be backed by a different storage adapter, and domain classes are exported from each storage package.
+
+| Domain          | Description                                                                                                                                                                           |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`        | Conversation persistence for agents. Stores threads (conversation sessions), messages, resources (user identities), and working memory (persistent context across conversations).     |
+| `workflows`     | Workflow execution state. When workflows suspend for human input, external events, or scheduled resumption, their state is persisted here to enable resumption after server restarts. |
+| `scores`        | Evaluation results from Mastra's evals system. Scores and metrics are persisted here for analysis and comparison over time.                                                           |
+| `observability` | Telemetry data including traces and spans. Agent interactions, tool calls, and LLM requests generate spans collected into traces for debugging and performance analysis.              |
+| `agents`        | Agent configurations for stored agents. Enables agents to be defined and updated at runtime without code deployments.                                                                 |
+
+## Usage
+
+### Basic composition
+
+Import domain classes directly from each store package and compose them:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { WorkflowsPG, ScoresPG } from '@mastra/pg'
+import { MemoryLibSQL } from '@mastra/libsql'
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    domains: {
+      memory: new MemoryLibSQL({ url: 'file:./local.db' }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    },
+  }),
+})
+```
+
+### With a default storage
+
+Use `default` to specify a fallback storage, then override specific domains:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { MemoryLibSQL } from '@mastra/libsql'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: {
+      memory: new MemoryLibSQL({ url: 'file:./local.db' }),
+    },
+  }),
+})
+```
+
+## Options
+
+**id:** (`string`): Unique identifier for this storage instance.
+
+**default?:** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in \`domains\` will use this storage's domains as fallbacks.
+
+**domains?:** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over the default storage.
+
+**domains.memory?:** (`MemoryStorage`): Storage for threads, messages, and resources.
+
+**domains.workflows?:** (`WorkflowsStorage`): Storage for workflow snapshots.
+
+**domains.scores?:** (`ScoresStorage`): Storage for evaluation scores.
+
+**domains.observability?:** (`ObservabilityStorage`): Storage for traces and spans.
+
+**domains.agents?:** (`AgentsStorage`): Storage for stored agent configurations.
+
+**disableInit?:** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
+
+## Initialization
+
+`MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const storage = new MastraCompositeStore({
+  id: 'composite',
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+  },
+})
+
+export const mastra = new Mastra({
+  storage, // init() called automatically
+})
+```
+
+If using storage directly, call `init()` explicitly:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MemoryPG } from '@mastra/pg'
+
+const storage = new MastraCompositeStore({
+  id: 'composite',
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+  },
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```
+
+## Use cases
+
+### Separate databases for different workloads
+
+Use a local database for development while keeping production data in a managed service:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg'
+import { MemoryLibSQL } from '@mastra/libsql'
+
+const storage = new MastraCompositeStore({
+  id: 'composite',
+  domains: {
+    // Use local SQLite for development, PostgreSQL for production
+    memory:
+      process.env.NODE_ENV === 'development'
+        ? new MemoryLibSQL({ url: 'file:./dev.db' })
+        : new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+  },
+})
+```
+
+### Specialized storage for observability
+
+Observability data can quickly overwhelm general-purpose databases in production. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day.
+
+**ClickHouse** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg'
+import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
+
+const storage = new MastraCompositeStore({
+  id: 'composite',
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    observability: new ObservabilityStorageClickhouse({
+      url: process.env.CLICKHOUSE_URL,
+      username: process.env.CLICKHOUSE_USERNAME,
+      password: process.env.CLICKHOUSE_PASSWORD,
+    }),
+  },
+})
+```
+
+> **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.

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

@@ -0,0 +1,161 @@
+# Convex Storage
+
+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 **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to Convex, and Mastra Studio's 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.
+
+> **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).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/convex@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/convex@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/convex@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/convex@latest
+```
+
+## Convex Setup
+
+Before using `ConvexStore`, you need to set up the Convex schema and storage handler in your Convex project.
+
+### 1. Set up Convex Schema
+
+In `convex/schema.ts`:
+
+```typescript
+import { defineSchema } from 'convex/server'
+import {
+  mastraThreadsTable,
+  mastraMessagesTable,
+  mastraResourcesTable,
+  mastraWorkflowSnapshotsTable,
+  mastraScoresTable,
+  mastraVectorIndexesTable,
+  mastraVectorsTable,
+  mastraDocumentsTable,
+} from '@mastra/convex/schema'
+
+export default defineSchema({
+  mastra_threads: mastraThreadsTable,
+  mastra_messages: mastraMessagesTable,
+  mastra_resources: mastraResourcesTable,
+  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
+  mastra_scorers: mastraScoresTable,
+  mastra_vector_indexes: mastraVectorIndexesTable,
+  mastra_vectors: mastraVectorsTable,
+  mastra_documents: mastraDocumentsTable,
+})
+```
+
+### 2. Create the Storage Handler
+
+In `convex/mastra/storage.ts`:
+
+```typescript
+import { mastraStorage } from '@mastra/convex/server'
+
+export const handle = mastraStorage
+```
+
+### 3. Deploy to Convex
+
+```bash
+npx convex dev
+# or for production
+npx convex deploy
+```
+
+## Usage
+
+```typescript
+import { ConvexStore } from '@mastra/convex'
+
+const storage = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+})
+```
+
+## Parameters
+
+**deploymentUrl:** (`string`): Convex deployment URL (e.g., https\://your-project.convex.cloud)
+
+**adminAuthToken:** (`string`): Convex admin authentication token for backend access
+
+**storageFunction?:** (`string`): Path to the storage mutation function (default: 'mastra/storage:handle') (Default: `mastra/storage:handle`)
+
+## Constructor Examples
+
+```ts
+import { ConvexStore } from '@mastra/convex'
+
+// Basic configuration
+const store = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+})
+
+// With custom storage function path
+const storeCustom = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+  storageFunction: 'custom/path:handler',
+})
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation uses typed Convex tables for each Mastra domain:
+
+| Domain    | Convex Table                | Purpose              |
+| --------- | --------------------------- | -------------------- |
+| Threads   | `mastra_threads`            | Conversation threads |
+| Messages  | `mastra_messages`           | Chat messages        |
+| Resources | `mastra_resources`          | User working memory  |
+| Workflows | `mastra_workflow_snapshots` | Workflow state       |
+| Scorers   | `mastra_scorers`            | Evaluation data      |
+| Fallback  | `mastra_documents`          | Unknown tables       |
+
+### Architecture
+
+All typed tables include:
+
+- An `id` field for Mastra's record ID (distinct from Convex's auto-generated `_id`)
+- A `by_record_id` index for efficient lookups by Mastra ID
+
+This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.
+
+### Environment Variables
+
+Set these environment variables for your deployment:
+
+- `CONVEX_URL` – Your Convex deployment URL
+- `CONVEX_ADMIN_KEY` – Admin authentication token (get from Convex dashboard)
+
+## Related
+
+- [Convex Vector Store](https://mastra.ai/reference/vectors/convex)
+- [Convex Documentation](https://docs.convex.dev/)