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

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

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

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