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

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

@@ -1,218 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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

@@ -1,235 +0,0 @@
-# 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

@@ -1,161 +0,0 @@
-# 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/)