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

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

@@ -1,80 +0,0 @@
-# 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

@@ -1,80 +0,0 @@
-# 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

@@ -1,260 +0,0 @@
-# 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

@@ -1,176 +0,0 @@
-# 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

@@ -1,90 +0,0 @@
-# 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