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

package/.docs/reference/rag/rerank.md

@@ -0,0 +1,75 @@
+# rerank()
+
+The `rerank()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.
+
+```typescript
+function rerank(
+  results: QueryResult[],
+  query: string,
+  modelConfig: ModelConfig,
+  options?: RerankerFunctionOptions,
+): Promise<RerankResult[]>
+```
+
+## Usage Example
+
+```typescript
+import { rerank } from '@mastra/rag'
+
+const model = 'openai/gpt-5.1'
+
+const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to production?', model, {
+  weights: {
+    semantic: 0.5,
+    vector: 0.3,
+    position: 0.2,
+  },
+  topK: 3,
+})
+```
+
+## Parameters
+
+**results:** (`QueryResult[]`): The vector search results to rerank
+
+**query:** (`string`): The search query text used to evaluate relevance
+
+**model:** (`MastraLanguageModel`): The language Model to use for reranking
+
+**options?:** (`RerankerFunctionOptions`): Options for the reranking model
+
+The rerank function accepts any LanguageModel from the Vercel AI SDK. When using the Cohere model `rerank-v3.5`, it will automatically use Cohere's reranking capabilities.
+
+> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+
+### RerankerFunctionOptions
+
+**weights?:** (`WeightConfig`): numbersemantic?:number (default: 0.4)Weight for semantic relevancenumbervector?:number (default: 0.4)Weight for vector similaritynumberposition?:number (default: 0.2)Weight for position-based scoring
+
+**queryEmbedding?:** (`number[]`): Embedding of the query
+
+**topK?:** (`number`): Number of top results to return (Default: `3`)
+
+## Returns
+
+The function returns an array of `RerankResult` objects:
+
+**result:** (`QueryResult`): The original query result
+
+**score:** (`number`): Combined reranking score (0-1)
+
+**details:** (`ScoringDetails`): Detailed scoring information
+
+### ScoringDetails
+
+**semantic:** (`number`): Semantic relevance score (0-1)
+
+**vector:** (`number`): Vector similarity score (0-1)
+
+**position:** (`number`): Position-based score (0-1)
+
+**queryAnalysis?:** (`object`): numbermagnitude:Magnitude of the querynumber\[]dominantFeatures:Dominant features of the query
+
+## Related
+
+- [createVectorQueryTool](https://mastra.ai/reference/tools/vector-query-tool)

package/.docs/reference/rag/rerankWithScorer.md

@@ -0,0 +1,80 @@
+# rerankWithScorer()
+
+The `rerankWithScorer()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.
+
+```typescript
+function rerankWithScorer({
+  results: QueryResult[],
+  query: string,
+  scorer: RelevanceScoreProvider,
+  options?: RerankerFunctionOptions,
+}): Promise<RerankResult[]>;
+```
+
+## Usage Example
+
+```typescript
+import { rerankWithScorer as rerank, CohereRelevanceScorer } from '@mastra/rag'
+
+const scorer = new CohereRelevanceScorer('rerank-v3.5')
+
+const rerankedResults = await rerank({
+  results: vectorSearchResults,
+  query: 'How do I deploy to production?',
+  scorer,
+  options: {
+    weights: {
+      semantic: 0.5,
+      vector: 0.3,
+      position: 0.2,
+    },
+    topK: 3,
+  },
+})
+```
+
+## Parameters
+
+**results:** (`QueryResult[]`): The vector search results to rerank
+
+**query:** (`string`): The search query text used to evaluate relevance
+
+**scorer:** (`RelevanceScoreProvider`): The relevance scorer to use for reranking
+
+**options?:** (`RerankerFunctionOptions`): Options for the reranking model
+
+The `rerankWithScorer` function accepts any `RelevanceScoreProvider` from @mastra/rag.
+
+> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+
+### RerankerFunctionOptions
+
+**weights?:** (`WeightConfig`): numbersemantic?:number (default: 0.4)Weight for semantic relevancenumbervector?:number (default: 0.4)Weight for vector similaritynumberposition?:number (default: 0.2)Weight for position-based scoring
+
+**queryEmbedding?:** (`number[]`): Embedding of the query
+
+**topK?:** (`number`): Number of top results to return (Default: `3`)
+
+## Returns
+
+The function returns an array of `RerankResult` objects:
+
+**result:** (`QueryResult`): The original query result
+
+**score:** (`number`): Combined reranking score (0-1)
+
+**details:** (`ScoringDetails`): Detailed scoring information
+
+### ScoringDetails
+
+**semantic:** (`number`): Semantic relevance score (0-1)
+
+**vector:** (`number`): Vector similarity score (0-1)
+
+**position:** (`number`): Position-based score (0-1)
+
+**queryAnalysis?:** (`object`): numbermagnitude:Magnitude of the querynumber\[]dominantFeatures:Dominant features of the query
+
+## Related
+
+- [createVectorQueryTool](https://mastra.ai/reference/tools/vector-query-tool)

package/.docs/reference/server/create-route.md

@@ -0,0 +1,262 @@
+# 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
+import { createRoute } from '@mastra/server/server-adapter'
+```
+
+## Signature
+
+```typescript
+function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
+  config: RouteConfig<TPath, TQuery, TBody, TResponse, TResponseType>,
+): ServerRoute
+```
+
+## Parameters
+
+**method:** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method
+
+**path:** (`string`): Route path with optional params (e.g., \`/api/items/:id\`)
+
+**responseType:** (`'json' | 'stream'`): Response format. Internal routes may use additional types (\`datastream-response\`, \`mcp-http\`, \`mcp-sse\`).
+
+**handler:** (`ServerRouteHandler`): Route handler function
+
+**pathParamSchema?:** (`ZodSchema`): Validates URL path parameters
+
+**queryParamSchema?:** (`ZodSchema`): Validates query string parameters
+
+**bodySchema?:** (`ZodSchema`): Validates request body
+
+**responseSchema?:** (`ZodSchema`): Documents response shape for OpenAPI
+
+**streamFormat?:** (`'sse' | 'stream'`): Stream format (when responseType is 'stream')
+
+**maxBodySize?:** (`number`): Override default body size limit in bytes
+
+**summary?:** (`string`): OpenAPI summary
+
+**description?:** (`string`): OpenAPI description
+
+**tags?:** (`string[]`): OpenAPI tags
+
+**deprecated?:** (`boolean`): Mark route as deprecated
+
+## Handler parameters
+
+The handler receives validated parameters plus runtime context:
+
+```typescript
+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
+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
+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
+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
+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
+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
+const bodySchema = z
+  .object({
+    required: z.string(),
+  })
+  .passthrough() // Allow unknown fields
+```
+
+### Date coercion
+
+```typescript
+const querySchema = z.object({
+  fromDate: z.coerce.date().optional(),
+  toDate: z.coerce.date().optional(),
+})
+```
+
+### Union types
+
+```typescript
+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
+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
+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](https://mastra.ai/reference/server/routes) - Default Mastra routes
+- [MastraServer](https://mastra.ai/reference/server/mastra-server) - Server adapter class
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Using adapters

package/.docs/reference/server/express-adapter.md

@@ -0,0 +1,176 @@
+# 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](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the Express adapter and Express framework:
+
+**npm**:
+
+```bash
+npm install @mastra/express@latest express
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/express@latest express
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/express@latest express
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/express@latest express
+```
+
+## Usage example
+
+```typescript
+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')
+})
+```
+
+> **Note:** Express requires `express.json()` middleware for JSON body parsing. Add it before creating the `MastraServer`.
+
+## Constructor parameters
+
+**app:** (`Application`): Express app instance
+
+**mastra:** (`Mastra`): Mastra instance
+
+**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)
+
+**openapiPath?:** (`string`): Path to serve OpenAPI spec (e.g., \`/openapi.json\`) (Default: `''`)
+
+**bodyLimitOptions?:** (`{ maxSize: number, onError: (err) => unknown }`): Request body size limits
+
+**streamOptions?:** (`{ redact?: boolean }`): Stream redaction config. When true, redacts sensitive data from streams. (Default: `{ redact: true }`)
+
+**customRouteAuthConfig?:** (`Map<string, boolean>`): Per-route auth overrides. Keys are \`METHOD:PATH\` (e.g., \`GET:/api/health\`). Value \`false\` makes route public, \`true\` requires auth.
+
+**tools?:** (`Record<string, Tool>`): Available tools for the server
+
+**taskStore?:** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions?:** (`MCPOptions`): MCP transport options. Set \`serverless: true\` for stateless environments like Cloudflare Workers or Vercel Edge.
+
+## 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
+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
+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
+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 [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.
+
+## Examples
+
+- [Express Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-express-adapter) - Basic Express server setup
+
+## Related
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Shared adapter concepts
+- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server) - Full API reference
+- [createRoute() Reference](https://mastra.ai/reference/server/create-route) - Creating type-safe custom routes

package/.docs/reference/server/fastify-adapter.md

@@ -0,0 +1,90 @@
+# Fastify Adapter
+
+The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev).
+
+> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the Fastify adapter and Fastify framework:
+
+**npm**:
+
+```bash
+npm install @mastra/fastify@latest fastify
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastify@latest fastify
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastify@latest fastify
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastify@latest fastify
+```
+
+## Usage example
+
+```typescript
+import Fastify from 'fastify'
+import { MastraServer } from '@mastra/fastify'
+import { mastra } from './mastra'
+
+const app = Fastify({ logger: true })
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.listen({ port: 3000 }, (err, address) => {
+  if (err) {
+    console.error(err)
+    process.exit(1)
+  }
+  console.log(`Server running on ${address}`)
+})
+```
+
+## Constructor parameters
+
+**app:** (`FastifyInstance`): Fastify app instance
+
+**mastra:** (`Mastra`): Mastra instance
+
+**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)
+
+**openapiPath?:** (`string`): Path to serve OpenAPI spec (e.g., \`/openapi.json\`) (Default: `''`)
+
+**bodyLimitOptions?:** (`BodyLimitOptions`): Request body size limits
+
+**streamOptions?:** (`StreamOptions`): Stream redaction config. When true (default), redacts sensitive data (system prompts, tool definitions, API keys) from stream chunks before sending to clients. (Default: `{ redact: true }`)
+
+**customRouteAuthConfig?:** (`Map<string, boolean>`): Per-route auth overrides. Keys are \`METHOD:PATH\` (e.g., \`GET:/api/health\`). Value \`false\` makes route public, \`true\` requires auth.
+
+**tools?:** (`ToolsInput`): Available tools for the server
+
+**taskStore?:** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions?:** (`MCPOptions`): MCP transport options. Set \`serverless: true\` for stateless environments like Cloudflare Workers or Vercel Edge.
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.
+
+## Examples
+
+- [Fastify Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-fastify-adapter) - Basic Fastify server setup
+
+## Related
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Shared adapter concepts
+- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server) - Full API reference
+- [createRoute() Reference](https://mastra.ai/reference/server/create-route) - Creating type-safe custom routes