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

package/.docs/raw/reference/rag/embeddings.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Embed | RAG | Mastra Docs"
+title: "Reference: Embed | RAG"
 description: Documentation for embedding functionality in Mastra using the AI SDK.
 ---
 
@@ -13,9 +13,10 @@ The `embed` function generates a vector embedding for a single text input:
 
 ```typescript
 import { embed } from "ai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const result = await embed({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   value: "Your text to embed",
   maxRetries: 2, // optional, defaults to 2
 });
@@ -80,7 +81,7 @@ For embedding multiple texts at once, use the `embedMany` function:
 import { embedMany } from "ai";
 
 const result = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: ["First text", "Second text", "Third text"],
   maxRetries: 2, // optional, defaults to 2
 });
@@ -142,17 +143,16 @@ const result = await embedMany({
 
 ```typescript
 import { embed, embedMany } from "ai";
-import { openai } from "@ai-sdk/openai";
 
 // Single embedding
 const singleResult = await embed({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   value: "What is the meaning of life?",
 });
 
 // Multiple embeddings
 const multipleResult = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: [
     "First question about life",
     "Second question about universe",

package/.docs/raw/reference/rag/extract-params.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: ExtractParams | RAG | Mastra Docs"
+title: "Reference: ExtractParams | RAG"
 description: Documentation for metadata extraction configuration in Mastra.
 ---
 

package/.docs/raw/reference/rag/graph-rag.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: GraphRAG | RAG | Mastra Docs"
+title: "Reference: GraphRAG | RAG"
 description: Documentation for the GraphRAG class in Mastra, which implements a graph-based approach to retrieval augmented generation.
 ---
 

package/.docs/raw/reference/rag/metadata-filters.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Metadata Filters | RAG | Mastra Docs"
+title: "Reference: Metadata Filters | RAG"
 description: Documentation for metadata filtering capabilities in Mastra, which allow for precise querying of vector search results across different vector stores.
 ---
 

package/.docs/raw/reference/rag/rerank.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: rerank() | RAG | Mastra Docs"
+title: "Reference: rerank() | RAG"
 description: Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
 ---
 
@@ -19,10 +19,9 @@ function rerank(
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerank } from "@mastra/rag";
 
-const model = openai("gpt-4o-mini");
+const model = "openai/gpt-5.1";
 
 const rerankedResults = await rerank(
   vectorSearchResults,

package/.docs/raw/reference/rag/rerankWithScorer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: rerankWithScorer() | RAG | Mastra Docs"
+title: "Reference: rerankWithScorer() | RAG"
 description: Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
 ---
 
@@ -19,7 +19,6 @@ function rerankWithScorer({
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerankWithScorer as rerank, CohereRelevanceScorer } from "@mastra/rag";
 
 const scorer = new CohereRelevanceScorer("rerank-v3.5");

package/.docs/raw/reference/server/create-route.mdx

@@ -0,0 +1,328 @@
+---
+title: "Reference: createRoute() | Server"
+description: "API reference for createRoute() function used to define type-safe routes with validation and OpenAPI generation."
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# createRoute()
+
+The `createRoute()` function creates type-safe routes with Zod validation. When an `openapiPath` is configured on the server adapter, it generates OpenAPI schema entries from the supplied Zod schemas.
+
+## Import
+
+```typescript copy
+import { createRoute } from '@mastra/server/server-adapter';
+```
+
+## Signature
+
+```typescript copy
+function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
+  config: RouteConfig<TPath, TQuery, TBody, TResponse, TResponseType>
+): ServerRoute
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "method",
+      type: "'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'",
+      description: "HTTP method",
+      isOptional: false,
+    },
+    {
+      name: "path",
+      type: "string",
+      description: "Route path with optional params (e.g., `/api/items/:id`)",
+      isOptional: false,
+    },
+    {
+      name: "responseType",
+      type: "'json' | 'stream'",
+      description: "Response format. Internal routes may use additional types (`datastream-response`, `mcp-http`, `mcp-sse`).",
+      isOptional: false,
+    },
+    {
+      name: "handler",
+      type: "ServerRouteHandler",
+      description: "Route handler function",
+      isOptional: false,
+    },
+    {
+      name: "pathParamSchema",
+      type: "ZodSchema",
+      description: "Validates URL path parameters",
+      isOptional: true,
+    },
+    {
+      name: "queryParamSchema",
+      type: "ZodSchema",
+      description: "Validates query string parameters",
+      isOptional: true,
+    },
+    {
+      name: "bodySchema",
+      type: "ZodSchema",
+      description: "Validates request body",
+      isOptional: true,
+    },
+    {
+      name: "responseSchema",
+      type: "ZodSchema",
+      description: "Documents response shape for OpenAPI",
+      isOptional: true,
+    },
+    {
+      name: "streamFormat",
+      type: "'sse' | 'stream'",
+      description: "Stream format (when responseType is 'stream')",
+      isOptional: true,
+    },
+    {
+      name: "maxBodySize",
+      type: "number",
+      description: "Override default body size limit in bytes",
+      isOptional: true,
+    },
+    {
+      name: "summary",
+      type: "string",
+      description: "OpenAPI summary",
+      isOptional: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "OpenAPI description",
+      isOptional: true,
+    },
+    {
+      name: "tags",
+      type: "string[]",
+      description: "OpenAPI tags",
+      isOptional: true,
+    },
+    {
+      name: "deprecated",
+      type: "boolean",
+      description: "Mark route as deprecated",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Handler parameters
+
+The handler receives validated parameters plus runtime context:
+
+```typescript copy showLineNumbers
+handler: async (params) => {
+  // From schemas (typed from Zod)
+  params.id;              // From pathParamSchema
+  params.filter;          // From queryParamSchema
+  params.name;            // From bodySchema
+
+  // Runtime context (always available)
+  params.mastra;          // Mastra instance
+  params.requestContext;  // Request-scoped context
+  params.tools;           // Available tools
+  params.abortSignal;     // Request cancellation signal
+  params.taskStore;       // A2A task storage
+}
+```
+
+## Return value
+
+Returns a `ServerRoute` object that can be registered with an adapter.
+
+## Examples
+
+### GET route with path params
+
+```typescript copy showLineNumbers
+import { createRoute } from '@mastra/server/server-adapter';
+import { z } from 'zod';
+
+const getAgent = createRoute({
+  method: 'GET',
+  path: '/api/agents/:agentId',
+  responseType: 'json',
+  pathParamSchema: z.object({
+    agentId: z.string(),
+  }),
+  responseSchema: z.object({
+    name: z.string(),
+    description: z.string().optional(),
+  }),
+  summary: 'Get agent by ID',
+  tags: ['Agents'],
+  handler: async ({ agentId, mastra }) => {
+    return mastra.getAgent(agentId);
+  },
+});
+```
+
+### POST route with body
+
+```typescript copy showLineNumbers
+const createItem = createRoute({
+  method: 'POST',
+  path: '/api/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string(),
+    value: z.number(),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    value: z.number(),
+  }),
+  handler: async ({ name, value, mastra }) => {
+    // name and value are typed from bodySchema
+    return { id: 'new-id', name, value };
+  },
+});
+```
+
+### Query params with coercion
+
+```typescript copy showLineNumbers
+const listItems = createRoute({
+  method: 'GET',
+  path: '/api/items',
+  responseType: 'json',
+  queryParamSchema: z.object({
+    page: z.coerce.number().default(0),
+    limit: z.coerce.number().default(50),
+    enabled: z.coerce.boolean().optional(),
+  }),
+  handler: async ({ page, limit, enabled, mastra }) => {
+    // page, limit, enabled are typed and coerced
+    return { items: [], page, limit };
+  },
+});
+```
+
+### Streaming route
+
+```typescript copy showLineNumbers
+const streamAgent = createRoute({
+  method: 'POST',
+  path: '/api/agents/:agentId/stream',
+  responseType: 'stream',
+  streamFormat: 'sse',
+  pathParamSchema: z.object({
+    agentId: z.string(),
+  }),
+  bodySchema: z.object({
+    messages: z.array(z.any()),
+  }),
+  handler: async ({ agentId, messages, mastra, abortSignal }) => {
+    const agent = mastra.getAgent(agentId);
+    return agent.stream({ messages, abortSignal });
+  },
+});
+```
+
+### Custom body size limit
+
+```typescript copy showLineNumbers
+const uploadRoute = createRoute({
+  method: 'POST',
+  path: '/api/upload',
+  responseType: 'json',
+  maxBodySize: 50 * 1024 * 1024, // 50MB
+  bodySchema: z.object({
+    file: z.string(),
+  }),
+  handler: async ({ file }) => {
+    return { uploaded: true };
+  },
+});
+```
+
+## Schema patterns
+
+### Passthrough for extensibility
+
+```typescript copy
+const bodySchema = z.object({
+  required: z.string(),
+}).passthrough(); // Allow unknown fields
+```
+
+### Date coercion
+
+```typescript copy
+const querySchema = z.object({
+  fromDate: z.coerce.date().optional(),
+  toDate: z.coerce.date().optional(),
+});
+```
+
+### Union types
+
+```typescript copy
+const bodySchema = z.object({
+  messages: z.union([
+    z.array(z.any()),
+    z.string(),
+  ]),
+});
+```
+
+## Error handling
+
+Throw an error with a `status` property to return specific HTTP status codes from handlers. If using Hono, you can use `HTTPException` from `hono/http-exception`:
+
+```typescript copy showLineNumbers
+import { createRoute } from '@mastra/server/server-adapter';
+import { HTTPException } from 'hono/http-exception';
+
+const getAgent = createRoute({
+  method: 'GET',
+  path: '/api/agents/:agentId',
+  responseType: 'json',
+  pathParamSchema: z.object({ agentId: z.string() }),
+  handler: async ({ agentId, mastra }) => {
+    const agent = mastra.getAgent(agentId);
+    if (!agent) {
+      throw new HTTPException(404, { message: `Agent '${agentId}' not found` });
+    }
+    return agent;
+  },
+});
+```
+
+For Express or framework-agnostic code, throw an error with a `status` property:
+
+```typescript copy showLineNumbers
+class HttpError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}
+
+// In handler:
+throw new HttpError(404, `Agent '${agentId}' not found`);
+```
+
+Common status codes:
+
+| Code | Meaning |
+|------|---------|
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 500 | Internal Server Error |
+
+## Related
+
+- [Server Routes](/reference/v1/server/routes) - Default Mastra routes
+- [MastraServer](/reference/v1/server/mastra-server) - Server adapter class
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters

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

@@ -0,0 +1,260 @@
+---
+title: "Reference: Express Adapter | Server"
+description: "API reference for the @mastra/express server adapter."
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# Express Adapter
+
+The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com).
+
+:::info
+
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
+
+:::
+
+## Installation
+
+<Steps>
+
+<StepItem>
+
+Install the Express adapter and Express framework:
+
+```bash copy
+npm install @mastra/express express
+```
+
+</StepItem>
+
+<StepItem>
+
+Create your server file:
+
+```typescript title="server.ts" copy
+import express from 'express';
+import { MastraServer } from '@mastra/express';
+import { mastra } from './mastra';
+
+const app = express();
+app.use(express.json()); // Required for body parsing
+
+const server = new MastraServer({ app, mastra });
+await server.init();
+
+app.listen(4111, () => {
+  console.log('Server running on port 4111');
+});
+```
+
+</StepItem>
+
+</Steps>
+
+:::note
+
+Express requires `express.json()` middleware for JSON body parsing. Add it before creating the `MastraServer`.
+
+:::
+
+## Full example
+
+```typescript title="server.ts" copy
+import express from 'express';
+import { MastraServer } from '@mastra/express';
+import { mastra } from './mastra';
+
+const app = express();
+app.use(express.json());
+
+const server = new MastraServer({
+  app,
+  mastra,
+  prefix: '/api/v2',
+  openapiPath: '/openapi.json',
+  bodyLimitOptions: {
+    maxSize: 10 * 1024 * 1024, // 10MB
+    onError: (err) => ({ error: 'Payload too large', maxSize: '10MB' }),
+  },
+  streamOptions: { redact: true },
+});
+
+await server.init();
+
+app.listen(4111);
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "app",
+      type: "Application",
+      description: "Express 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: "{ maxSize: number, onError: (err) => unknown }",
+      description: "Request body size limits",
+      isOptional: true,
+    },
+    {
+      name: "streamOptions",
+      type: "{ redact?: boolean }",
+      description: "Stream redaction config. When true, redacts sensitive data from streams.",
+      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: "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,
+    },
+  ]}
+/>
+
+## Differences from Hono
+
+| Aspect | Express | Hono |
+|--------|---------|------|
+| Body parsing | Requires `express.json()` | Handled by framework |
+| Context storage | `res.locals` | `c.get()` / `c.set()` |
+| Middleware signature | `(req, res, next)` | `(c, next)` |
+| Streaming | `res.write()` / `res.end()` | `stream()` helper |
+| AbortSignal | Created from `req.on('close')` | `c.req.raw.signal` |
+
+## Adding custom routes
+
+Add routes directly to the Express app:
+
+```typescript title="server.ts" copy
+const app = express();
+app.use(express.json());
+
+const server = new MastraServer({ app, mastra });
+
+// Before init - runs before Mastra middleware
+app.get('/early-health', (req, res) => res.json({ status: 'ok' }));
+
+await server.init();
+
+// After init - has access to Mastra context
+app.get('/custom', (req, res) => {
+  const mastraInstance = res.locals.mastra;
+  res.json({ agents: Object.keys(mastraInstance.listAgents()) });
+});
+
+app.listen(4111);
+```
+
+:::tip
+
+Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
+
+:::
+
+## Accessing context
+
+In Express middleware and routes, access Mastra context via `res.locals`:
+
+```typescript copy
+app.get('/custom', (req, res) => {
+  const mastra = res.locals.mastra;
+  const requestContext = res.locals.requestContext;
+  const abortSignal = res.locals.abortSignal;
+
+  const agent = mastra.getAgent('myAgent');
+  res.json({ agent: agent.name });
+});
+```
+
+Available properties on `res.locals`:
+
+| Key | Description |
+|-----|-------------|
+| `mastra` | Mastra instance |
+| `requestContext` | Request context map |
+| `abortSignal` | Request cancellation signal |
+| `tools` | Available tools |
+| `taskStore` | Task store for A2A operations |
+| `customRouteAuthConfig` | Per-route auth overrides |
+| `user` | Authenticated user (if auth configured) |
+
+## Adding middleware
+
+Add Express middleware before or after `init()`:
+
+```typescript title="server.ts" copy
+const app = express();
+app.use(express.json());
+
+// Middleware before init
+app.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+
+const server = new MastraServer({ app, mastra });
+await server.init();
+
+// Middleware after init has access to Mastra context
+app.use((req, res, next) => {
+  const mastra = res.locals.mastra;
+  // ...
+  next();
+});
+```
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [Server Adapters: Manual initialization](/docs/v1/server-db/server-adapters#manual-initialization) for details.
+
+## Examples
+
+- [Express Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-express-adapter) - Basic Express server setup
+
+## Related
+
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Shared adapter concepts
+- [Hono Adapter](/reference/v1/server/hono-adapter) - Alternative adapter
+- [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
+- [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes