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

package/.docs/reference/server/register-api-route.md

@@ -0,0 +1,249 @@
+# registerApiRoute()
+
+The `registerApiRoute()` function creates custom HTTP routes that integrate with the Mastra server. Routes can include OpenAPI metadata to appear in the Swagger UI documentation.
+
+## Import
+
+```typescript
+import { registerApiRoute } from '@mastra/core/server'
+```
+
+## Parameters
+
+### path
+
+The URL path for the route. Supports path parameters using `:param` syntax.
+
+```typescript
+registerApiRoute("/items/:itemId", { ... })
+```
+
+**Note:** Paths cannot start with `/api/` as this prefix is reserved for Mastra server routes.
+
+### options
+
+**method:** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route
+
+**handler?:** (`Handler`): Route handler function receiving Hono Context. Use either \`handler\` or \`createHandler\`, not both.
+
+**createHandler?:** (`(c: Context) => Promise<Handler>`): Async factory function to create the handler. Use either \`handler\` or \`createHandler\`, not both.
+
+**middleware?:** (`MiddlewareHandler | MiddlewareHandler[]`): Route-specific middleware functions
+
+**openapi?:** (`DescribeRouteOptions`): OpenAPI metadata for Swagger UI documentation
+
+## OpenAPI Options
+
+The `openapi` property accepts standard OpenAPI 3.1 operation fields from [hono-openapi](https://github.com/honojs/middleware/tree/main/packages/openapi). Routes without an `openapi` property are not included in Swagger UI.
+
+**summary?:** (`string`): Short summary of the operation
+
+**description?:** (`string`): Detailed description of the operation
+
+**tags?:** (`string[]`): Tags for grouping in Swagger UI. Defaults to \['custom'] if not specified.
+
+**deprecated?:** (`boolean`): Mark the operation as deprecated
+
+**parameters?:** (`ParameterObject[]`): Path, query, and header parameters
+
+**requestBody?:** (`RequestBodyObject`): Request body specification
+
+**responses?:** (`ResponsesObject`): Response specifications by status code
+
+**security?:** (`SecurityRequirementObject[]`): Security requirements for the operation
+
+## Return Value
+
+Returns an `ApiRoute` object to be passed to `server.apiRoutes` in the Mastra configuration.
+
+## Handler Context
+
+The handler receives a Hono `Context` object with access to:
+
+```typescript
+handler: async c => {
+  // Get the Mastra instance
+  const mastra = c.get('mastra')
+
+  // Get request context
+  const requestContext = c.get('requestContext')
+
+  // Access path parameters
+  const itemId = c.req.param('itemId')
+
+  // Access query parameters
+  const filter = c.req.query('filter')
+
+  // Access request body
+  const body = await c.req.json()
+
+  // Return JSON response
+  return c.json({ data: 'value' })
+}
+```
+
+## Examples
+
+### Basic GET Route
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/health-check', {
+        method: 'GET',
+        handler: async c => {
+          return c.json({ status: 'ok' })
+        },
+      }),
+    ],
+  },
+})
+```
+
+### Route with Path Parameters
+
+```typescript
+registerApiRoute('/users/:userId/posts/:postId', {
+  method: 'GET',
+  handler: async c => {
+    const userId = c.req.param('userId')
+    const postId = c.req.param('postId')
+
+    return c.json({ userId, postId })
+  },
+})
+```
+
+### POST Route with Body
+
+```typescript
+registerApiRoute('/items', {
+  method: 'POST',
+  handler: async c => {
+    const body = await c.req.json()
+    const mastra = c.get('mastra')
+
+    // Process the request...
+
+    return c.json({ id: 'new-id', ...body }, 201)
+  },
+})
+```
+
+### Route with Middleware
+
+```typescript
+registerApiRoute('/protected', {
+  method: 'GET',
+  middleware: [
+    async (c, next) => {
+      const token = c.req.header('Authorization')
+      if (!token) {
+        return c.json({ error: 'Unauthorized' }, 401)
+      }
+      await next()
+    },
+  ],
+  handler: async c => {
+    return c.json({ data: 'protected content' })
+  },
+})
+```
+
+### Route with OpenAPI Documentation
+
+```typescript
+import { z } from 'zod'
+
+const ItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+})
+
+registerApiRoute('/items/:itemId', {
+  method: 'GET',
+  openapi: {
+    summary: 'Get item by ID',
+    description: 'Retrieves a single item by its unique identifier',
+    tags: ['Items'],
+    parameters: [
+      {
+        name: 'itemId',
+        in: 'path',
+        required: true,
+        description: 'The item ID',
+        schema: { type: 'string' },
+      },
+    ],
+    responses: {
+      200: {
+        description: 'Item found',
+        content: {
+          'application/json': {
+            schema: ItemSchema, // Zod schemas are converted to JSON Schema during OpenAPI generation
+          },
+        },
+      },
+      404: {
+        description: 'Item not found',
+      },
+    },
+  },
+  handler: async c => {
+    const itemId = c.req.param('itemId')
+    return c.json({ id: itemId, name: 'Example', price: 9.99 })
+  },
+})
+```
+
+### Using createHandler
+
+For routes that need async initialization:
+
+```typescript
+registerApiRoute('/dynamic', {
+  method: 'GET',
+  createHandler: async c => {
+    // Perform async setup
+    const config = await loadConfig()
+
+    return async c => {
+      return c.json({ config })
+    }
+  },
+})
+```
+
+## Error Handling
+
+Throw errors with status codes using Hono's `HTTPException`:
+
+```typescript
+import { HTTPException } from 'hono/http-exception'
+
+registerApiRoute('/items/:itemId', {
+  method: 'GET',
+  handler: async c => {
+    const itemId = c.req.param('itemId')
+    const item = await findItem(itemId)
+
+    if (!item) {
+      throw new HTTPException(404, { message: 'Item not found' })
+    }
+
+    return c.json(item)
+  },
+})
+```
+
+## Related
+
+- [Custom API Routes Guide](https://mastra.ai/docs/server/custom-api-routes) - Usage guide with examples
+- [Server Middleware](https://mastra.ai/docs/server/middleware) - Global middleware configuration
+- [createRoute()](https://mastra.ai/reference/server/create-route) - Type-safe route creation for server adapters
+- [Server Routes](https://mastra.ai/reference/server/routes) - Built-in Mastra server routes

package/.docs/reference/server/routes.md

@@ -0,0 +1,306 @@
+# Server Routes
+
+Server adapters register these routes when you call `server.init()`. All routes are prefixed with the `prefix` option if configured.
+
+## Agents
+
+| Method | Path                                         | Description             |
+| ------ | -------------------------------------------- | ----------------------- |
+| `GET`  | `/api/agents`                                | List all agents         |
+| `GET`  | `/api/agents/:agentId`                       | Get agent by ID         |
+| `POST` | `/api/agents/:agentId/generate`              | Generate agent response |
+| `POST` | `/api/agents/:agentId/stream`                | Stream agent response   |
+| `GET`  | `/api/agents/:agentId/tools`                 | List agent tools        |
+| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool      |
+
+### Generate request body
+
+```typescript
+{
+  messages: CoreMessage[] | string;       // Required
+  instructions?: string;                   // System instructions
+  system?: string;                         // System prompt
+  context?: CoreMessage[];                 // Additional context
+  memory?: { key: string } | boolean;      // Memory config
+  resourceId?: string;                     // Resource identifier
+  threadId?: string;                       // Thread identifier
+  runId?: string;                          // Run identifier
+  maxSteps?: number;                       // Max tool steps
+  activeTools?: string[];                  // Tools to enable
+  toolChoice?: ToolChoice;                 // Tool selection mode
+  requestContext?: Record<string, unknown>; // Request context
+  output?: ZodSchema;                      // Structured output schema
+}
+```
+
+### Generate response
+
+```typescript
+{
+  text: string;
+  toolCalls?: ToolCall[];
+  finishReason: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+  };
+}
+```
+
+## Workflows
+
+| Method | Path                                      | Description                     |
+| ------ | ----------------------------------------- | ------------------------------- |
+| `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>;
+  closeOnSuspend?: boolean;
+}
+```
+
+### Resume request body
+
+```typescript
+{
+  step?: string | string[];
+  resumeData?: unknown;
+  requestContext?: Record<string, unknown>;
+}
+```
+
+## Tools
+
+| Method | Path                         | Description    |
+| ------ | ---------------------------- | -------------- |
+| `GET`  | `/api/tools`                 | List all tools |
+| `GET`  | `/api/tools/:toolId`         | Get tool by ID |
+| `POST` | `/api/tools/:toolId/execute` | Execute tool   |
+
+### Execute tool request body
+
+```typescript
+{
+  data: unknown;  // Tool input data
+  requestContext?: Record<string, unknown>;
+}
+```
+
+## Memory
+
+| Method   | Path                                     | Description         |
+| -------- | ---------------------------------------- | ------------------- |
+| `GET`    | `/api/memory/threads`                    | List threads        |
+| `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         |
+
+### Create thread request body
+
+```typescript
+{
+  resourceId: string;
+  title?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### 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    |
+| ------ | --------------------------------- | -------------- |
+| `POST` | `/api/vectors/:vectorName/upsert` | Upsert vectors |
+| `POST` | `/api/vectors/:vectorName/query`  | Query vectors  |
+| `POST` | `/api/vectors/:vectorName/delete` | Delete vectors |
+
+### Upsert request body
+
+```typescript
+{
+  vectors: Array<{
+    id: string
+    values: number[]
+    metadata?: Record<string, unknown>
+  }>
+}
+```
+
+### Query request body
+
+```typescript
+{
+  vector: number[];
+  topK?: number;
+  filter?: Record<string, unknown>;
+  includeMetadata?: boolean;
+}
+```
+
+## MCP
+
+| Method | Path                               | Description        |
+| ------ | ---------------------------------- | ------------------ |
+| `GET`  | `/api/mcp/servers`                 | List MCP servers   |
+| `GET`  | `/api/mcp/servers/:serverId/tools` | List server tools  |
+| `POST` | `/api/mcp/:serverId`               | MCP HTTP transport |
+| `GET`  | `/api/mcp/:serverId/sse`           | MCP SSE transport  |
+
+## Logs
+
+| Method | Path               | Description        |
+| ------ | ------------------ | ------------------ |
+| `GET`  | `/api/logs`        | List logs          |
+| `GET`  | `/api/logs/:runId` | Get logs by run ID |
+
+### Query parameters
+
+```typescript
+{
+  page?: number;
+  perPage?: number;
+  transportId?: string;
+}
+```
+
+## Telemetry
+
+| Method | Path                                   | Description     |
+| ------ | -------------------------------------- | --------------- |
+| `GET`  | `/api/telemetry/traces`                | List traces     |
+| `GET`  | `/api/telemetry/traces/:traceId`       | Get trace       |
+| `GET`  | `/api/telemetry/traces/:traceId/spans` | Get trace spans |
+
+## Common query parameters
+
+### Pagination
+
+Most list endpoints support:
+
+```typescript
+{
+  page?: number;   // Page number (0-indexed)
+  perPage?: number; // Items per page (default: 10)
+}
+```
+
+### Filtering
+
+Workflow runs support:
+
+```typescript
+{
+  fromDate?: string;  // ISO date string
+  toDate?: string;    // ISO date string
+  status?: string;    // Run status filter
+  resourceId?: string; // Filter by resource
+}
+```
+
+## Error responses
+
+All routes return errors in this format:
+
+```typescript
+{
+  error: string;      // Error message
+  details?: unknown;  // Additional details
+}
+```
+
+Common status codes:
+
+| Code | Meaning                              |
+| ---- | ------------------------------------ |
+| 400  | Bad Request - Invalid parameters     |
+| 401  | Unauthorized - Missing/invalid auth  |
+| 403  | Forbidden - Insufficient permissions |
+| 404  | Not Found - Resource doesn't exist   |
+| 500  | Internal Server Error                |
+
+## Related
+
+- [createRoute()](https://mastra.ai/reference/server/create-route) - Creating custom routes
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Using adapters