@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.11

package/.docs/raw/reference/server/routes.mdx

@@ -0,0 +1,250 @@
+---
+title: "Reference: Server Routes | Server"
+description: "API reference for HTTP routes registered by Mastra server adapters."
+---
+
+# Server Routes
+
+Server adapters register these routes when you call `server.init()`. All routes are prefixed with the `prefix` option if configured.
+
+## Agents
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/agents` | List all agents |
+| `GET` | `/api/agents/:agentId` | Get agent by ID |
+| `POST` | `/api/agents/:agentId/generate` | Generate agent response |
+| `POST` | `/api/agents/:agentId/stream` | Stream agent response |
+| `GET` | `/api/agents/:agentId/tools` | List agent tools |
+| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool |
+
+### Generate request body
+
+```typescript
+{
+  messages: CoreMessage[] | string;       // Required
+  instructions?: string;                   // System instructions
+  system?: string;                         // System prompt
+  context?: CoreMessage[];                 // Additional context
+  memory?: { key: string } | boolean;      // Memory config
+  resourceId?: string;                     // Resource identifier
+  threadId?: string;                       // Thread identifier
+  runId?: string;                          // Run identifier
+  maxSteps?: number;                       // Max tool steps
+  activeTools?: string[];                  // Tools to enable
+  toolChoice?: ToolChoice;                 // Tool selection mode
+  requestContext?: Record<string, unknown>; // Request context
+  output?: ZodSchema;                      // Structured output schema
+}
+```
+
+### Generate response
+
+```typescript
+{
+  text: string;
+  toolCalls?: ToolCall[];
+  finishReason: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+  };
+}
+```
+
+## Workflows
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/workflows` | List all workflows |
+| `GET` | `/api/workflows/:workflowId` | Get workflow by ID |
+| `POST` | `/api/workflows/:workflowId/stream` | Stream workflow execution |
+| `POST` | `/api/workflows/:workflowId/resume` | Resume suspended workflow |
+| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously |
+| `GET` | `/api/workflows/:workflowId/runs` | List workflow runs |
+| `GET` | `/api/workflows/:workflowId/runs/:runId` | Get specific run |
+
+### Stream workflow request body
+
+```typescript
+{
+  inputData?: unknown;
+  initialState?: unknown;
+  requestContext?: Record<string, unknown>;
+  closeOnSuspend?: boolean;
+}
+```
+
+### Resume request body
+
+```typescript
+{
+  step?: string | string[];
+  resumeData?: unknown;
+  requestContext?: Record<string, unknown>;
+}
+```
+
+## Tools
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/tools` | List all tools |
+| `GET` | `/api/tools/:toolId` | Get tool by ID |
+| `POST` | `/api/tools/:toolId/execute` | Execute tool |
+
+### Execute tool request body
+
+```typescript
+{
+  data: unknown;  // Tool input data
+  requestContext?: Record<string, unknown>;
+}
+```
+
+## Memory
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/memory/threads` | List threads |
+| `GET` | `/api/memory/threads/:threadId` | Get thread |
+| `POST` | `/api/memory/threads` | Create thread |
+| `DELETE` | `/api/memory/threads/:threadId` | Delete thread |
+| `GET` | `/api/memory/threads/:threadId/messages` | Get thread messages |
+| `POST` | `/api/memory/threads/:threadId/messages` | Add message |
+
+### Create thread request body
+
+```typescript
+{
+  resourceId: string;
+  title?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+## Vectors
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/vectors/:vectorName/upsert` | Upsert vectors |
+| `POST` | `/api/vectors/:vectorName/query` | Query vectors |
+| `POST` | `/api/vectors/:vectorName/delete` | Delete vectors |
+
+### Upsert request body
+
+```typescript
+{
+  vectors: Array<{
+    id: string;
+    values: number[];
+    metadata?: Record<string, unknown>;
+  }>;
+}
+```
+
+### Query request body
+
+```typescript
+{
+  vector: number[];
+  topK?: number;
+  filter?: Record<string, unknown>;
+  includeMetadata?: boolean;
+}
+```
+
+## MCP
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/mcp/servers` | List MCP servers |
+| `GET` | `/api/mcp/servers/:serverId/tools` | List server tools |
+| `POST` | `/api/mcp/:serverId` | MCP HTTP transport |
+| `GET` | `/api/mcp/:serverId/sse` | MCP SSE transport |
+
+## Logs
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/logs` | List logs |
+| `GET` | `/api/logs/:runId` | Get logs by run ID |
+
+### Query parameters
+
+```typescript
+{
+  page?: number;
+  perPage?: number;
+  transportId?: string;
+}
+```
+
+## Telemetry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/telemetry/traces` | List traces |
+| `GET` | `/api/telemetry/traces/:traceId` | Get trace |
+| `GET` | `/api/telemetry/traces/:traceId/spans` | Get trace spans |
+
+## Common query parameters
+
+### Pagination
+
+Most list endpoints support:
+
+```typescript
+{
+  page?: number;   // Page number (0-indexed)
+  perPage?: number; // Items per page (default: 10)
+}
+```
+
+Or offset-based:
+
+```typescript
+{
+  offset?: number; // Skip N items
+  limit?: number;  // Max items (default: 50)
+}
+```
+
+### Filtering
+
+Workflow runs support:
+
+```typescript
+{
+  fromDate?: string;  // ISO date string
+  toDate?: string;    // ISO date string
+  status?: string;    // Run status filter
+  resourceId?: string; // Filter by resource
+}
+```
+
+## Error responses
+
+All routes return errors in this format:
+
+```typescript
+{
+  error: string;      // Error message
+  details?: unknown;  // Additional details
+}
+```
+
+Common status codes:
+
+| Code | Meaning |
+|------|---------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing/invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Resource doesn't exist |
+| 500 | Internal Server Error |
+
+## Related
+
+- [createRoute()](/reference/v1/server/create-route) - Creating custom routes
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters

package/.docs/raw/reference/storage/cloudflare-d1.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Cloudflare D1 Storage | Storage | Mastra Docs"
+title: "Reference: Cloudflare D1 Storage | Storage"
 description: Documentation for the Cloudflare D1 SQL storage implementation in Mastra.
 ---
 
@@ -95,6 +95,43 @@ The storage implementation handles schema creation and updates automatically. It
 - `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 copy
+import { Mastra } from "@mastra/core";
+import { D1Store } from "@mastra/cloudflare-d1";
+
+const storage = new D1Store({
+  binding: D1Database,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { D1Store } from "@mastra/cloudflare-d1";
+
+const storage = new D1Store({
+  binding: D1Database,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::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.

package/.docs/raw/reference/storage/cloudflare.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Cloudflare Storage | Storage | Mastra Docs"
+title: "Reference: Cloudflare Storage | Storage"
 description: Documentation for the Cloudflare KV storage implementation in Mastra.
 ---
 

package/.docs/raw/reference/storage/convex.mdx

@@ -0,0 +1,164 @@
+---
+title: "Reference: Convex Storage | Storage"
+description: Documentation for the Convex storage implementation in Mastra.
+---
+
+# 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.
+
+## Installation
+
+```bash copy
+npm install @mastra/convex@beta
+```
+
+## 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 copy
+import { defineSchema } from 'convex/server';
+import {
+  mastraThreadsTable,
+  mastraMessagesTable,
+  mastraResourcesTable,
+  mastraWorkflowSnapshotsTable,
+  mastraScoresTable,
+  mastraVectorIndexesTable,
+  mastraVectorsTable,
+  mastraDocumentsTable,
+} from '@mastra/convex/server';
+
+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 copy
+import { mastraStorage } from '@mastra/convex/server';
+
+export const handle = mastraStorage;
+```
+
+### 3. Deploy to Convex
+
+```bash copy
+npx convex dev
+# or for production
+npx convex deploy
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { ConvexStore } from "@mastra/convex";
+
+const storage = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "deploymentUrl",
+      type: "string",
+      description:
+        "Convex deployment URL (e.g., https://your-project.convex.cloud)",
+      isOptional: false,
+    },
+    {
+      name: "adminAuthToken",
+      type: "string",
+      description:
+        "Convex admin authentication token for backend access",
+      isOptional: false,
+    },
+    {
+      name: "storageFunction",
+      type: "string",
+      description:
+        "Path to the storage mutation function (default: 'mastra/storage:handle')",
+      isOptional: true,
+      defaultValue: "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](../vectors/convex)
+- [Convex Documentation](https://docs.convex.dev/)
+

package/.docs/raw/reference/storage/dynamodb.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: DynamoDB Storage | Storage | Mastra Docs"
+title: "Reference: DynamoDB Storage | Storage"
 description: "Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB."
 ---
 

package/.docs/raw/reference/storage/lance.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: LanceDB Storage | Storage | Mastra Docs"
+title: "Reference: LanceDB Storage | Storage"
 description: Documentation for the LanceDB storage implementation in Mastra.
 ---
 
@@ -73,6 +73,39 @@ The LanceStorage implementation automatically handles schema creation and update
 - `jsonb`, `json` → Utf8 (serialized)
 - `binary` → Binary
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { LanceStorage } from "@mastra/lance";
+
+const storage = await LanceStorage.create("my-storage", "/path/to/db");
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { LanceStorage } from "@mastra/lance";
+
+const storage = await LanceStorage.create("my-storage", "/path/to/db");
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::
+
 ### Deployment Options
 
 LanceDB storage can be configured for different deployment scenarios:

package/.docs/raw/reference/storage/libsql.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: LibSQL Storage | Storage | Mastra Docs"
+title: "Reference: LibSQL Storage | Storage"
 description: Documentation for the LibSQL storage implementation in Mastra.
 ---
 
@@ -74,3 +74,40 @@ 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
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  url: "file:./storage.db",
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  url: "file:./storage.db",
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::

package/.docs/raw/reference/storage/mongodb.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MongoDB Storage | Storage | Mastra Docs"
+title: "Reference: MongoDB Storage | Storage"
 description: Documentation for the MongoDB storage implementation in Mastra.
 ---
 
@@ -93,6 +93,45 @@ The storage implementation handles collection creation and management automatica
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { MongoDBStore } from "@mastra/mongodb";
+
+const storage = new MongoDBStore({
+  url: process.env.MONGODB_URL,
+  dbName: process.env.MONGODB_DATABASE,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the collections:
+
+```typescript copy
+import { MongoDBStore } from "@mastra/mongodb";
+
+const storage = new MongoDBStore({
+  url: process.env.MONGODB_URL,
+  dbName: process.env.MONGODB_DATABASE,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, collections won't be created and storage operations will fail silently or throw errors.
+:::
+
 ## Vector Search Capabilities
 
 MongoDB storage includes built-in vector search capabilities for AI applications:

package/.docs/raw/reference/storage/mssql.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MSSQL Storage | Storage | Mastra Docs"
+title: "Reference: MSSQL Storage | Storage"
 description: Documentation for the MSSQL storage implementation in Mastra.
 ---
 
@@ -101,6 +101,43 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::
+
 ### Direct Database and Pool Access
 
 `MSSQLStore` exposes the mssql connection pool as public fields: