@mastra/mcp-docs-server 1.1.5 → 1.1.6

package/.docs/docs/server/auth/workos.md

@@ -0,0 +1,186 @@
+# MastraAuthWorkos Class
+
+The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses WorkOS authentication. Make sure to:
+
+1. Create a WorkOS account at [workos.com](https://workos.com/)
+2. Set up an Application in your WorkOS Dashboard
+3. Configure your redirect URIs and allowed origins
+4. Set up Organizations and configure user roles as needed
+
+```env
+WORKOS_API_KEY=sk_live_...
+WORKOS_CLIENT_ID=client_...
+```
+
+> **Note:** You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
+>
+> For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
+
+## Installation
+
+Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
+
+```bash
+npm install @mastra/auth-workos@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID,
+    }),
+  },
+})
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthWorkos` checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:
+
+1. Retrieves the user's organization memberships using their user ID
+2. Extracts all roles from their memberships
+3. Checks if any role has the slug 'admin'
+4. Grants access only if the user has admin role in at least one organization
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+const workosAuth = new MastraAuthWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+  authorizeUser: async user => {
+    return !!user
+  },
+})
+```
+
+> **Info:** Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
+
+## Client-side setup
+
+When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
+
+### Installing WorkOS SDK
+
+First, install the WorkOS SDK in your application:
+
+```bash
+npm install @workos-inc/node
+```
+
+### Exchanging code for access token
+
+After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
+
+```typescript
+import { WorkOS } from '@workos-inc/node'
+
+const workos = new WorkOS(process.env.WORKOS_API_KEY)
+
+export const authenticateWithWorkos = async (code: string, clientId: string) => {
+  const authenticationResponse = await workos.userManagement.authenticateWithCode({
+    code,
+    clientId,
+  })
+
+  return authenticationResponse.accessToken
+}
+```
+
+> **Note:** Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: 'https://<mastra-api-url>',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+  })
+}
+```
+
+> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+>
+> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
+
+**React**:
+
+```typescript
+import { WorkOS } from '@workos-inc/node'
+import { MastraClient } from '@mastra/client-js'
+
+const workos = new WorkOS(process.env.WORKOS_API_KEY)
+
+export const callMastraWithWorkos = async (code: string, clientId: string) => {
+  const authenticationResponse = await workos.userManagement.authenticateWithCode({
+    code,
+    clientId,
+  })
+
+  const token = authenticationResponse.accessToken
+
+  const mastra = new MastraClient({
+    baseUrl: 'http://localhost:4111',
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  })
+
+  const weatherAgent = mastra.getAgent('weatherAgent')
+  const response = await weatherAgent.generate("What's the weather like in Nairobi")
+
+  return response.text
+}
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-workos-access-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```

package/.docs/docs/server/auth.md

@@ -0,0 +1,38 @@
+# Auth Overview
+
+Mastra lets you choose how you handle authentication, so you can secure access to your application's endpoints using the identity system that fits your stack.
+
+You can start with simple shared secret JWT authentication and switch to providers like Supabase, Firebase Auth, Auth0, Clerk, or WorkOS when you need more advanced identity features.
+
+## Default behavior
+
+Authentication is optional in Mastra. When you configure authentication:
+
+- **All built-in API routes** (`/api/agents/*`, `/api/workflows/*`, etc.) require authentication by default
+- **Custom API routes** also require authentication by default
+- **Public access** can be enabled on custom routes using `requiresAuth: false`
+
+If no authentication is configured, all routes are publicly accessible.
+
+See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for controlling authentication on custom endpoints.
+
+## Available providers
+
+### Built-in
+
+- [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth) - Token-to-user mapping for development and API keys
+- [JSON Web Token (JWT)](https://mastra.ai/docs/server/auth/jwt) - HMAC-signed JWT verification
+
+### Third-party integrations
+
+- [Auth0](https://mastra.ai/docs/server/auth/auth0)
+- [Better Auth](https://mastra.ai/docs/server/auth/better-auth)
+- [Clerk](https://mastra.ai/docs/server/auth/clerk)
+- [Firebase](https://mastra.ai/docs/server/auth/firebase)
+- [Supabase](https://mastra.ai/docs/server/auth/supabase)
+- [WorkOS](https://mastra.ai/docs/server/auth/workos)
+
+### Advanced
+
+- [Composite Auth](https://mastra.ai/docs/server/auth/composite-auth) - Combine multiple auth providers
+- [Custom Auth Provider](https://mastra.ai/docs/server/auth/custom-auth-provider) - Build your own provider

package/.docs/docs/server/custom-adapters.md

@@ -0,0 +1,378 @@
+# Custom Adapters
+
+Create a custom adapter when you need to run Mastra with a framework other than Hono or Express. This might be necessary if you have specific request/response handling requirements that `@mastra/hono` and `@mastra/express` don't support.
+
+A custom adapter translates between Mastra's route definitions and your framework's routing system. You'll implement methods that register middleware, handle requests, and send responses using your framework's APIs.
+
+> **Info:** Use any of these prebuilt server adapters:
+>
+> - [@mastra/hono](https://mastra.ai/reference/server/hono-adapter)
+> - [@mastra/express](https://mastra.ai/reference/server/express-adapter)
+> - [@mastra/fastify](https://mastra.ai/reference/server/fastify-adapter)
+> - [@mastra/koa](https://mastra.ai/reference/server/koa-adapter)
+
+## Abstract class
+
+The `MastraServer` abstract class from `@mastra/server/server-adapter` provides the foundation for all adapters. It handles route registration logic, parameter validation, and other shared functionality. Your custom adapter extends this class and implements the framework-specific parts.
+
+The class takes three type parameters that represent your framework's types:
+
+```typescript
+import { MastraServer } from '@mastra/server/server-adapter'
+
+export class MyFrameworkServer extends MastraServer<
+  // Your framework's app type (e.g., FastifyInstance)
+  MyApp,
+  // Your framework's request type (e.g., FastifyRequest)
+  MyRequest,
+  // Your framework's response type (e.g., FastifyReply)
+  MyResponse
+> {
+  // Implement abstract methods
+}
+```
+
+These type parameters ensure type safety throughout your adapter implementation and enable proper typing when accessing framework-specific APIs.
+
+## Required methods
+
+You must implement these six abstract methods. Each handles a specific part of the request lifecycle, from attaching context to sending responses.
+
+### registerContextMiddleware()
+
+This method runs first and attaches Mastra context to every incoming request. Route handlers need access to the Mastra instance, tools, and other context to function. How you attach this context depends on your framework — Express uses `res.locals`, Hono uses `c.set()`, and other frameworks have their own patterns.
+
+```typescript
+registerContextMiddleware(): void {
+  this.app.use('*', (req, res, next) => {
+    // Attach context to your framework's request/response
+    res.locals.mastra = this.mastra;
+    res.locals.requestContext = new RequestContext();
+    res.locals.tools = this.tools;
+    res.locals.abortSignal = createAbortSignal(req);
+    next();
+  });
+}
+```
+
+Context to attach:
+
+| Key              | Type                   | Description                      |
+| ---------------- | ---------------------- | -------------------------------- |
+| `mastra`         | `Mastra`               | The Mastra instance              |
+| `requestContext` | `RequestContext`       | Request-scoped context map       |
+| `tools`          | `Record<string, Tool>` | Available tools                  |
+| `abortSignal`    | `AbortSignal`          | Request cancellation signal      |
+| `taskStore`      | `InMemoryTaskStore`    | A2A task storage (if configured) |
+
+### registerAuthMiddleware()
+
+Register authentication and authorization middleware. This method should check if authentication is configured on the Mastra instance and skip registration entirely if not. When auth is configured, you'll typically register two middleware functions: one for authentication (validating tokens and setting the user) and one for authorization (checking if the user can access the requested resource).
+
+```typescript
+registerAuthMiddleware(): void {
+  const authConfig = this.mastra.getServer()?.auth;
+  if (!authConfig) return;
+
+  // Register authentication (validate token, set user)
+  this.app.use('*', async (req, res, next) => {
+    const token = extractToken(req);
+    const user = await authConfig.authenticateToken?.(token, req);
+    if (!user) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+    res.locals.user = user;
+    next();
+  });
+
+  // Register authorization (check permissions)
+  this.app.use('*', async (req, res, next) => {
+    const allowed = await authConfig.authorize?.(
+      req.path,
+      req.method,
+      res.locals.user,
+      res
+    );
+    if (!allowed) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    next();
+  });
+}
+```
+
+### registerRoute()
+
+Register a single route with your framework. This method is called once for each Mastra route during initialization. It receives a `ServerRoute` object containing the path, HTTP method, handler function, and Zod schemas for validation. Your implementation should wire this up to your framework's routing system.
+
+```typescript
+async registerRoute(
+  app: MyApp,
+  route: ServerRoute,
+  { prefix }: { prefix?: string }
+): Promise<void> {
+  const path = `${prefix || ''}${route.path}`;
+  const method = route.method.toLowerCase();
+
+  app[method](path, async (req, res) => {
+    try {
+      // 1. Extract parameters
+      const params = await this.getParams(route, req);
+
+      // 2. Validate with Zod schemas
+      const queryParams = await this.parseQueryParams(route, params.queryParams);
+      const body = await this.parseBody(route, params.body);
+
+      // 3. Build handler params
+      const handlerParams = {
+        ...params.urlParams,
+        ...queryParams,
+        ...(typeof body === 'object' ? body : {}),
+        mastra: this.mastra,
+        requestContext: res.locals.requestContext,
+        tools: res.locals.tools,
+        abortSignal: res.locals.abortSignal,
+        taskStore: this.taskStore,
+      };
+
+      // 4. Call handler
+      const result = await route.handler(handlerParams);
+
+      // 5. Send response
+      return this.sendResponse(route, res, result);
+    } catch (error) {
+      const status = error.status ?? error.details?.status ?? 500;
+      return res.status(status).json({ error: error.message });
+    }
+  });
+}
+```
+
+### getParams()
+
+Extract URL parameters, query parameters, and request body from the incoming request. Different frameworks expose these values in different ways—Express uses `req.params`, `req.query`, and `req.body`, while other frameworks may use different property names or require method calls. This method normalizes the extraction for your framework.
+
+```typescript
+async getParams(
+  route: ServerRoute,
+  request: MyRequest
+): Promise<{
+  urlParams: Record<string, string>;
+  queryParams: Record<string, string>;
+  body: unknown;
+}> {
+  return {
+    // From route path (e.g., :agentId)
+    urlParams: request.params,
+    // From URL query string
+    queryParams: request.query,
+    // From request body
+    body: request.body,
+  };
+}
+```
+
+### sendResponse()
+
+Send the response back to the client based on the route's response type. Mastra routes can return different response types: JSON for most API responses, streams for agent generation, and special types for MCP transports. Your implementation should handle each type appropriately for your framework.
+
+```typescript
+async sendResponse(
+  route: ServerRoute,
+  response: MyResponse,
+  result: unknown
+): Promise<unknown> {
+  switch (route.responseType) {
+    case 'json':
+      return response.json(result);
+
+    case 'stream':
+      return this.stream(route, response, result);
+
+    case 'datastream-response':
+      // Return AI SDK Response directly
+      return result;
+
+    case 'mcp-http':
+      // Handle MCP HTTP transport
+      return this.handleMcpHttp(response, result);
+
+    case 'mcp-sse':
+      // Handle MCP SSE transport
+      return this.handleMcpSse(response, result);
+
+    default:
+      return response.json(result);
+  }
+}
+```
+
+### stream()
+
+Handle streaming responses for agent generation. When an agent generates a response, it produces a stream of chunks that should be sent to the client as they become available. This method reads from the stream, optionally applies redaction to hide sensitive data, and writes chunks to the response in the appropriate format (SSE or newline-delimited JSON).
+
+```typescript
+async stream(
+  route: ServerRoute,
+  response: MyResponse,
+  result: unknown
+): Promise<unknown> {
+  const isSSE = route.streamFormat === 'sse';
+
+  // Set streaming headers based on format
+  response.setHeader('Content-Type', isSSE ? 'text/event-stream' : 'text/plain');
+  response.setHeader('Transfer-Encoding', 'chunked');
+
+  const reader = result.fullStream.getReader();
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      // Apply redaction if enabled
+      const chunk = this.streamOptions.redact
+        ? redactChunk(value)
+        : value;
+
+      // Format based on stream format
+      if (isSSE) {
+        response.write(`data: ${JSON.stringify(chunk)}\n\n`);
+      } else {
+        response.write(JSON.stringify(chunk) + '\x1E');
+      }
+    }
+
+    // Send completion marker (SSE uses data: [DONE], other formats use record separator)
+    if (isSSE) {
+      response.write('data: [DONE]\n\n');
+    }
+    response.end();
+  } catch (error) {
+    reader.cancel();
+    throw error;
+  }
+}
+```
+
+## Helper methods
+
+The base class provides helper methods you can use in your implementation. These handle common tasks like parameter validation and route registration, so you don't need to reimplement them:
+
+| Method                                                              | Description                                                 |
+| ------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `parsePathParams(route, params)`                                    | Validate path params with Zod schema                        |
+| `parseQueryParams(route, params)`                                   | Validate query params with Zod schema                       |
+| `parseBody(route, body)`                                            | Validate body with Zod schema                               |
+| `mergeRequestContext({ paramsRequestContext, bodyRequestContext })` | Merge request context from multiple sources                 |
+| `registerRoutes()`                                                  | Register all Mastra routes (calls `registerRoute` for each) |
+| `registerOpenAPIRoute(app, config, { prefix })`                     | Register OpenAPI spec endpoint                              |
+
+The `parse*` methods use Zod schemas defined on each route to validate input and return typed results. If validation fails, they throw an error with details about what went wrong.
+
+## Constructor
+
+Your adapter's constructor should accept the same options as the base class and pass them to `super()`. You can add additional framework-specific options if needed:
+
+```typescript
+constructor(options: {
+  app: MyApp;
+  mastra: Mastra;
+  prefix?: string;
+  openapiPath?: string;
+  bodyLimitOptions?: BodyLimitOptions;
+  streamOptions?: StreamOptions;
+  customRouteAuthConfig?: Map<string, boolean>;
+}) {
+  super(options);
+}
+```
+
+See [Server Adapters](https://mastra.ai/docs/server/server-adapters) for full documentation on each option.
+
+## Full example
+
+Here's a skeleton implementation showing all the required methods. This uses pseudocode for framework-specific parts—replace with your framework's actual APIs:
+
+```typescript
+import { MastraServer, ServerRoute } from '@mastra/server/server-adapter'
+import type { Mastra } from '@mastra/core'
+
+export class MyFrameworkServer extends MastraServer<MyApp, MyRequest, MyResponse> {
+  constructor(options: { app: MyApp; mastra: Mastra; prefix?: string }) {
+    super(options)
+  }
+
+  registerContextMiddleware(): void {
+    this.app.use('*', (req, res, next) => {
+      res.locals.mastra = this.mastra
+      res.locals.requestContext = this.mergeRequestContext({
+        paramsRequestContext: req.query.requestContext,
+        bodyRequestContext: req.body?.requestContext,
+      })
+      res.locals.tools = this.tools ?? {}
+      res.locals.abortSignal = createAbortSignal(req)
+      next()
+    })
+  }
+
+  registerAuthMiddleware(): void {
+    const authConfig = this.mastra.getServer()?.auth
+    if (!authConfig) return
+    // ... implement auth middleware
+  }
+
+  async registerRoute(
+    app: MyApp,
+    route: ServerRoute,
+    { prefix }: { prefix?: string },
+  ): Promise<void> {
+    // ... implement route registration
+  }
+
+  async getParams(route: ServerRoute, request: MyRequest) {
+    return {
+      urlParams: request.params,
+      queryParams: request.query,
+      body: request.body,
+    }
+  }
+
+  async sendResponse(route: ServerRoute, response: MyResponse, result: unknown) {
+    if (route.responseType === 'stream') {
+      return this.stream(route, response, result)
+    }
+    return response.json(result)
+  }
+
+  async stream(route: ServerRoute, response: MyResponse, result: unknown) {
+    // ... implement streaming
+  }
+}
+```
+
+## Usage
+
+Once your adapter is implemented, use it the same way as the provided adapters:
+
+```typescript
+import { MyFrameworkServer } from './my-framework-adapter'
+import { mastra } from './mastra'
+
+const app = createMyFrameworkApp()
+const server = new MyFrameworkServer({ app, mastra })
+
+await server.init()
+
+app.listen(4111)
+```
+
+> **Tip:** The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server-adapters/hono/src/index.ts) and [@mastra/express](https://github.com/mastra-ai/mastra/blob/main/server-adapters/express/src/index.ts) implementations are good references when building your custom adapter. They show how to handle framework-specific patterns for context storage, middleware registration, and response handling.
+
+## Related
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Overview and shared concepts
+- [Hono Adapter](https://mastra.ai/reference/server/hono-adapter) - Reference implementation
+- [Express Adapter](https://mastra.ai/reference/server/express-adapter) - Reference implementation
+- [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