@mastra/mcp-docs-server 1.0.0-beta.6 → 1.0.0-beta.8

package/.docs/raw/reference/observability/tracing/exporters/langfuse.mdx

@@ -117,3 +117,46 @@ const exporter = new LangfuseExporter({
 - `MODEL_GENERATION` spans → Langfuse generations
 - All other spans → Langfuse spans
 - Event spans → Langfuse events
+
+## Prompt Linking
+
+Link LLM generations to [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management) using the `withLangfusePrompt` helper:
+
+```typescript
+import { buildTracingOptions } from "@mastra/observability";
+import { withLangfusePrompt } from "@mastra/langfuse";
+import { Langfuse } from "langfuse";
+
+const langfuse = new Langfuse({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+});
+
+const prompt = await langfuse.getPrompt("customer-support");
+
+const agent = new Agent({
+  name: "support-agent",
+  instructions: prompt.prompt,
+  model: openai("gpt-4o"),
+  defaultGenerateOptions: {
+    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+  },
+});
+```
+
+### Helper Functions
+
+#### `withLangfusePrompt(prompt)`
+
+Adds Langfuse prompt metadata to tracing options.
+
+```typescript
+// With Langfuse SDK prompt object
+withLangfusePrompt(prompt)
+
+// With manual fields
+withLangfusePrompt({ name: "my-prompt", version: 1 })
+withLangfusePrompt({ id: "prompt-uuid" })
+```
+
+When `metadata.langfuse.prompt` is set on a `MODEL_GENERATION` span (with either `id` alone, or `name` + `version`), the exporter automatically links the generation to the prompt in Langfuse.

package/.docs/raw/reference/observability/tracing/exporters/otel.mdx

@@ -7,12 +7,6 @@ import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # OtelExporter
 
-:::warning
-
-The OtelExporter is currently **experimental**. APIs and configuration options may change in future releases.
-
-:::
-
 Sends Tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.
 
 ## Constructor
@@ -317,38 +311,6 @@ const exporter = new OtelExporter({
 });
 ```
 
-## Span Mapping
-
-The exporter maps Mastra AI spans to OpenTelemetry spans following GenAI semantic conventions:
-
-### Span Names
-
-- `MODEL_GENERATION` → `chat {model}` or `tool_selection {model}`
-- `TOOL_CALL` → `tool.execute {tool_name}`
-- `AGENT_RUN` → `agent.{agent_id}`
-- `WORKFLOW_RUN` → `workflow.{workflow_id}`
-
-### Span Kinds
-
-- Root agent/workflow spans → `SERVER`
-- LLM calls → `CLIENT`
-- Tool calls → `INTERNAL` or `CLIENT`
-- Workflow steps → `INTERNAL`
-
-### Attributes
-
-The exporter maps to standard OTEL GenAI attributes:
-
-| Mastra Attribute                    | OTEL Attribute                   |
-| ----------------------------------- | -------------------------------- |
-| `model`                             | `gen_ai.request.model`           |
-| `provider`                          | `gen_ai.system`                  |
-| `inputTokens` / `promptTokens`      | `gen_ai.usage.input_tokens`      |
-| `outputTokens` / `completionTokens` | `gen_ai.usage.output_tokens`     |
-| `temperature`                       | `gen_ai.request.temperature`     |
-| `maxOutputTokens`                   | `gen_ai.request.max_tokens`      |
-| `finishReason`                      | `gen_ai.response.finish_reasons` |
-
 ## Protocol Requirements
 
 Different providers require different OTEL exporter packages:
@@ -360,13 +322,35 @@ Different providers require different OTEL exporter packages:
 | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  | Traceloop, Custom          |
 | Zipkin        | `@opentelemetry/exporter-zipkin`           | Zipkin collectors          |
 
-## Parent-Child Relationships
 
-The exporter preserves span hierarchy from Mastra's Tracing:
+## Tags Support
 
-- Uses `parentSpanId` directly from Mastra spans
-- Maintains correct nesting for agents, workflows, LLM calls, and tools
-- Exports complete traces with all relationships intact
+The OtelExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are stored as the `mastra.tags` attribute.
+
+### Usage
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute for maximum backend compatibility:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+:::note
+While the OpenTelemetry specification supports native array attributes, many backends (Jaeger, Zipkin, Tempo) have limited array support. JSON strings ensure consistent behavior across all observability platforms.
+:::
 
 ## Related
 

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

@@ -0,0 +1,314 @@
+---
+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';
+```
+
+## 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';
+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 `HTTPException` to return specific HTTP status codes from handlers:
+
+```typescript copy showLineNumbers
+import { createRoute, HTTPException } from '@mastra/server';
+
+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;
+  },
+});
+```
+
+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,193 @@
+---
+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";
+
+# 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 showLineNumbers
+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 showLineNumbers
+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);
+```
+
+## 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 showLineNumbers
+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 showLineNumbers
+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 |
+| `user` | Authenticated user (if auth configured) |
+
+## Adding middleware
+
+Add Express middleware before or after `init()`:
+
+```typescript title="server.ts" copy showLineNumbers
+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