@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/reference/server/koa-adapter.mdx

@@ -0,0 +1,129 @@
+---
+title: "Reference: Koa Adapter | Server"
+description: "API reference for the @mastra/koa server adapter."
+packages:
+  - "@mastra/koa"
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# Koa Adapter
+
+The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com).
+
+:::info
+
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server/server-adapters).
+
+:::
+
+## Installation
+
+Install the Koa adapter and Koa framework:
+
+```bash
+npm install @mastra/koa@beta koa koa-bodyparser
+```
+
+## Usage example
+
+```typescript title="server.ts"
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+import { MastraServer } from '@mastra/koa';
+import { mastra } from './mastra';
+
+const app = new Koa();
+app.use(bodyParser());
+
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "app",
+      type: "Koa",
+      description: "Koa app instance",
+      isOptional: false,
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Mastra instance",
+      isOptional: false,
+    },
+    {
+      name: "prefix",
+      type: "string",
+      description: "Route path prefix (e.g., `/api/v2`)",
+      isOptional: true,
+      defaultValue: "''",
+    },
+    {
+      name: "openapiPath",
+      type: "string",
+      description: "Path to serve OpenAPI spec (e.g., `/openapi.json`)",
+      isOptional: true,
+      defaultValue: "''",
+    },
+    {
+      name: "bodyLimitOptions",
+      type: "BodyLimitOptions",
+      typeDescription: "{ maxSize: number, onError: (error: unknown) => unknown }",
+      description: "Request body size limits",
+      isOptional: true,
+    },
+    {
+      name: "streamOptions",
+      type: "StreamOptions",
+      typeDescription: "{ redact?: boolean }",
+      description: "Stream redaction config. When true (default), redacts sensitive data (system prompts, tool definitions, API keys) from stream chunks before sending to clients.",
+      isOptional: true,
+      defaultValue: "{ redact: true }",
+    },
+    {
+      name: "customRouteAuthConfig",
+      type: "Map<string, boolean>",
+      description: "Per-route auth overrides. Keys are `METHOD:PATH` (e.g., `GET:/api/health`). Value `false` makes route public, `true` requires auth.",
+      isOptional: true,
+    },
+    {
+      name: "tools",
+      type: "ToolsInput",
+      typeDescription: "Record<string, ToolAction | VercelTool>",
+      description: "Available tools for the server",
+      isOptional: true,
+    },
+    {
+      name: "taskStore",
+      type: "InMemoryTaskStore",
+      description: "Task store for A2A (Agent-to-Agent) operations",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](/docs/v1/server/server-adapters#manual-initialization) for details.
+
+## Examples
+
+- [Koa Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-koa-adapter) - Basic Koa server setup
+
+## Related
+
+- [Server Adapters](/docs/v1/server/server-adapters) - Shared adapter concepts
+- [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
+- [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes

package/.docs/raw/reference/server/mastra-server.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: MastraServer | Server"
 description: "API reference for the MastraServer abstract class used to create server adapters."
+packages:
+  - "@mastra/core"
+  - "@mastra/server"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -11,13 +14,13 @@ The `MastraServer` abstract class is the base for all server adapters. Extend th
 
 ## Import
 
-```typescript copy
-import { MastraServer } from '@mastra/server';
+```typescript
+import { MastraServer } from '@mastra/server/server-adapter';
 ```
 
 ## Type parameters
 
-```typescript copy
+```typescript
 MastraServer<TApp, TRequest, TResponse>
 ```
 
@@ -29,7 +32,7 @@ MastraServer<TApp, TRequest, TResponse>
 
 ## Constructor
 
-```typescript copy
+```typescript
 constructor(options: MastraServerOptions<TApp>)
 ```
 
@@ -61,6 +64,7 @@ constructor(options: MastraServerOptions<TApp>)
       type: "string",
       description: "Path to serve OpenAPI spec",
       isOptional: true,
+      defaultValue: "''",
     },
     {
       name: "bodyLimitOptions",
@@ -81,6 +85,18 @@ constructor(options: MastraServerOptions<TApp>)
       description: "Per-route auth overrides",
       isOptional: true,
     },
+    {
+      name: "tools",
+      type: "Record<string, Tool>",
+      description: "Available tools for the server",
+      isOptional: true,
+    },
+    {
+      name: "taskStore",
+      type: "InMemoryTaskStore",
+      description: "Task store for A2A (Agent-to-Agent) operations",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -92,7 +108,7 @@ These methods must be implemented by adapters:
 
 Attach Mastra context to every request.
 
-```typescript copy
+```typescript
 abstract registerContextMiddleware(): void
 ```
 
@@ -106,7 +122,7 @@ abstract registerContextMiddleware(): void
 
 Register authentication and authorization middleware.
 
-```typescript copy
+```typescript
 abstract registerAuthMiddleware(): void
 ```
 
@@ -114,7 +130,7 @@ abstract registerAuthMiddleware(): void
 
 Register a single route with the framework.
 
-```typescript copy
+```typescript
 abstract registerRoute(
   app: TApp,
   route: ServerRoute,
@@ -126,7 +142,7 @@ abstract registerRoute(
 
 Extract parameters from the request.
 
-```typescript copy
+```typescript
 abstract getParams(
   route: ServerRoute,
   request: TRequest
@@ -141,7 +157,7 @@ abstract getParams(
 
 Send response based on route type.
 
-```typescript copy
+```typescript
 abstract sendResponse(
   route: ServerRoute,
   response: TResponse,
@@ -153,7 +169,7 @@ abstract sendResponse(
 
 Handle streaming responses.
 
-```typescript copy
+```typescript
 abstract stream(
   route: ServerRoute,
   response: TResponse,
@@ -167,7 +183,7 @@ abstract stream(
 
 Initialize the server by registering all middleware and routes.
 
-```typescript copy
+```typescript
 async init(): Promise<void>
 ```
 
@@ -180,7 +196,7 @@ Calls in order:
 
 Register all Mastra routes.
 
-```typescript copy
+```typescript
 async registerRoutes(): Promise<void>
 ```
 
@@ -188,7 +204,7 @@ async registerRoutes(): Promise<void>
 
 Get the framework app instance.
 
-```typescript copy
+```typescript
 getApp<T = TApp>(): T
 ```
 
@@ -196,7 +212,7 @@ getApp<T = TApp>(): T
 
 Validate path parameters with the route's Zod schema.
 
-```typescript copy
+```typescript
 async parsePathParams(
   route: ServerRoute,
   params: Record<string, string>
@@ -207,7 +223,7 @@ async parsePathParams(
 
 Validate query parameters with the route's Zod schema.
 
-```typescript copy
+```typescript
 async parseQueryParams(
   route: ServerRoute,
   params: Record<string, string>
@@ -218,29 +234,18 @@ async parseQueryParams(
 
 Validate request body with the route's Zod schema.
 
-```typescript copy
+```typescript
 async parseBody(
   route: ServerRoute,
   body: unknown
 ): Promise<unknown>
 ```
 
-### mergeRequestContext()
-
-Merge request context from multiple sources (query params and body).
-
-```typescript copy
-mergeRequestContext(options: {
-  paramsRequestContext?: Record<string, any>;
-  bodyRequestContext?: Record<string, any>;
-}): RequestContext
-```
-
 ### registerOpenAPIRoute()
 
 Register an endpoint that serves the OpenAPI specification.
 
-```typescript copy
+```typescript
 async registerOpenAPIRoute(
   app: TApp,
   config: OpenAPIConfig,
@@ -248,11 +253,24 @@ async registerOpenAPIRoute(
 ): Promise<void>
 ```
 
+## Protected methods
+
+### mergeRequestContext()
+
+Merge request context from multiple sources (query params and body).
+
+```typescript
+protected mergeRequestContext(options: {
+  paramsRequestContext?: Record<string, any>;
+  bodyRequestContext?: Record<string, any>;
+}): RequestContext
+```
+
 ## Types
 
 ### BodyLimitOptions
 
-```typescript copy
+```typescript
 interface BodyLimitOptions {
   maxSize: number;
   onError: (error: unknown) => unknown;
@@ -261,7 +279,7 @@ interface BodyLimitOptions {
 
 ### StreamOptions
 
-```typescript copy
+```typescript
 interface StreamOptions {
   redact?: boolean;
 }
@@ -269,8 +287,8 @@ interface StreamOptions {
 
 ## Example
 
-```typescript copy showLineNumbers
-import { MastraServer, ServerRoute } from '@mastra/server';
+```typescript
+import { MastraServer, ServerRoute } from '@mastra/server/server-adapter';
 import type { Mastra } from '@mastra/core';
 
 export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
@@ -311,6 +329,6 @@ export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
 
 ## Related
 
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters
-- [Custom Adapters](/docs/v1/server-db/custom-adapters) - Creating custom adapters
+- [Server Adapters](/docs/v1/server/server-adapters) - Using adapters
+- [Custom Adapters](/docs/v1/server/custom-adapters) - Creating custom adapters
 - [createRoute()](/reference/v1/server/create-route) - Creating custom routes

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Server Routes | Server"
 description: "API reference for HTTP routes registered by Mastra server adapters."
+packages:
+  - "@mastra/server"
 ---
 
 # Server Routes
@@ -58,16 +60,43 @@ Server adapters register these routes when you call `server.init()`. All routes
 |--------|------|-------------|
 | `GET` | `/api/workflows` | List all workflows |
 | `GET` | `/api/workflows/:workflowId` | Get workflow by ID |
+| `POST` | `/api/workflows/:workflowId/create-run` | Create a new workflow run |
+| `POST` | `/api/workflows/:workflowId/start-async` | Start workflow and await result |
 | `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 |
 
+### Create run request body
+
+```typescript
+{
+  resourceId?: string;     // Associate run with a resource (e.g., user ID)
+  disableScorers?: boolean; // Disable scorers for this run
+}
+```
+
+### Start-async request body
+
+```typescript
+{
+  resourceId?: string;     // Associate run with a resource (e.g., user ID)
+  inputData?: unknown;
+  initialState?: unknown;
+  requestContext?: Record<string, unknown>;
+  tracingOptions?: {
+    spanName?: string;
+    attributes?: Record<string, unknown>;
+  };
+}
+```
+
 ### Stream workflow request body
 
 ```typescript
 {
+  resourceId?: string;     // Associate run with a resource (e.g., user ID)
   inputData?: unknown;
   initialState?: unknown;
   requestContext?: Record<string, unknown>;
@@ -110,6 +139,7 @@ Server adapters register these routes when you call `server.init()`. All routes
 | `GET` | `/api/memory/threads/:threadId` | Get thread |
 | `POST` | `/api/memory/threads` | Create thread |
 | `DELETE` | `/api/memory/threads/:threadId` | Delete thread |
+| `POST` | `/api/memory/threads/:threadId/clone` | Clone thread |
 | `GET` | `/api/memory/threads/:threadId/messages` | Get thread messages |
 | `POST` | `/api/memory/threads/:threadId/messages` | Add message |
 
@@ -123,6 +153,48 @@ Server adapters register these routes when you call `server.init()`. All routes
 }
 ```
 
+### Clone thread request body
+
+```typescript
+{
+  newThreadId?: string;           // Custom ID for cloned thread
+  resourceId?: string;            // Override resource ID
+  title?: string;                 // Custom title for clone
+  metadata?: Record<string, unknown>;  // Additional metadata
+  options?: {
+    messageLimit?: number;        // Max messages to clone
+    messageFilter?: {
+      startDate?: Date;           // Clone messages after this date
+      endDate?: Date;             // Clone messages before this date
+      messageIds?: string[];      // Clone specific messages
+    };
+  };
+}
+```
+
+### Clone thread response
+
+```typescript
+{
+  thread: {
+    id: string;
+    resourceId: string;
+    title: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata: {
+      clone: {
+        sourceThreadId: string;
+        clonedAt: Date;
+        lastMessageId?: string;
+      };
+      // ... other metadata
+    };
+  };
+  clonedMessages: MastraDBMessage[];
+}
+```
+
 ## Vectors
 
 | Method | Path | Description |
@@ -201,15 +273,6 @@ Most list endpoints support:
 }
 ```
 
-Or offset-based:
-
-```typescript
-{
-  offset?: number; // Skip N items
-  limit?: number;  // Max items (default: 50)
-}
-```
-
 ### Filtering
 
 Workflow runs support:
@@ -247,4 +310,4 @@ Common status codes:
 ## Related
 
 - [createRoute()](/reference/v1/server/create-route) - Creating custom routes
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters
+- [Server Adapters](/docs/v1/server/server-adapters) - Using adapters

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

@@ -1,6 +1,9 @@
 ---
 title: "Reference: Cloudflare D1 Storage | Storage"
 description: Documentation for the Cloudflare D1 SQL storage implementation in Mastra.
+packages:
+  - "@mastra/cloudflare-d1"
+  - "@mastra/core"
 ---
 
 # Cloudflare D1 Storage
@@ -15,7 +18,7 @@ npm install @mastra/cloudflare-d1@beta
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { D1Store } from "@mastra/cloudflare-d1";
 
 type Env = {
@@ -99,7 +102,7 @@ The storage implementation handles schema creation and updates automatically. It
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { D1Store } from "@mastra/cloudflare-d1";
 
@@ -114,18 +117,20 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
-```typescript copy
+```typescript
 import { D1Store } from "@mastra/cloudflare-d1";
 
 const storage = new D1Store({
+  id: 'd1-storage',
   binding: D1Database,
 });
 
 // Required when using storage directly
 await storage.init();
 
-// Now you can use the storage
-await storage.getThread({ threadId: "..." });
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
 :::warning

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Cloudflare Storage | Storage"
 description: Documentation for the Cloudflare KV storage implementation in Mastra.
+packages:
+  - "@mastra/cloudflare"
 ---
 
 # Cloudflare Storage
@@ -9,17 +11,18 @@ The Cloudflare KV storage implementation provides a globally distributed, server
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/cloudflare@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```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
@@ -30,6 +33,7 @@ const storageWorkers = new CloudflareStore({
 
 // --- 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
@@ -40,6 +44,12 @@ const storageRest = new CloudflareStore({
 
 <PropertiesTable
   content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for this storage instance.",
+      isOptional: false,
+    },
     {
       name: "bindings",
       type: "Record<string, KVNamespace>",