@mastra/mcp-docs-server 0.13.24-alpha.0 → 0.13.24-alpha.3

package/.docs/raw/reference/auth/workos.mdx

@@ -0,0 +1,128 @@
+---
+title: "MastraAuthWorkos Class"
+description: "API reference for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication."
+---
+
+# 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 `experimental_auth` option.
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID
+    }),
+  },
+});
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`WORKOS_API_KEY` and `WORKOS_CLIENT_ID`) set. In that case, simply use `new MastraAuthWorkos()` without any arguments.
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Your WorkOS API key. This is used to authenticate with the WorkOS API for user verification and organization management.",
+      isOptional: true,
+      defaultValue: "process.env.WORKOS_API_KEY"
+    },
+    {
+      name: "clientId",
+      type: "string",
+      description: "Your WorkOS Client ID. This identifies your application when exchanging authorization codes for access tokens.",
+      isOptional: true,
+      defaultValue: "process.env.WORKOS_CLIENT_ID"
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Custom name for the auth provider instance.",
+      isOptional: true,
+      defaultValue: '"workos"'
+    },
+    {
+      name: "authorizeUser",
+      type: "(user: WorkosUser) => Promise<boolean> | boolean",
+      description: "Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks if the user has an 'admin' role in any organization membership.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+<PropertiesTable
+  content={[
+    {
+      name: "WORKOS_API_KEY",
+      type: "string",
+      description: "Your WorkOS API key. Can be found in your WorkOS Dashboard under API Keys.",
+      isOptional: true,
+    },
+    {
+      name: "WORKOS_CLIENT_ID",
+      type: "string",
+      description: "Your WorkOS Client ID. Can be found in your WorkOS Dashboard under Applications.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Default Authorization Behavior
+
+By default, `MastraAuthWorkos` implements role-based authorization that checks for admin access:
+
+1. **Token Verification**: The access token is verified with WorkOS to ensure it's valid and not expired
+2. **User Retrieval**: User information is extracted from the verified token
+3. **Organization Membership Check**: The system queries WorkOS for all organization memberships associated with the user's ID
+4. **Role Extraction**: All roles from the user's organization memberships are collected
+5. **Admin Check**: The system checks if any role has the slug 'admin'
+6. **Authorization Decision**: Access is granted only if the user has an admin role in at least one organization
+
+This means that by default, only users with admin privileges in at least one organization will be authorized to access your Mastra endpoints.
+
+To implement custom authorization logic (e.g., allow all authenticated users, check for specific roles, or implement custom business logic), provide a custom `authorizeUser` function.
+
+## WorkOS User Type
+
+The `WorkosUser` type used in the `authorizeUser` function corresponds to the JWT token payload returned by WorkOS. WorkOS allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. Here's an example of what the user object might look like:
+
+```javascript
+{
+  'urn:myapp:full_name': 'John Doe',
+  'urn:myapp:email': 'john.doe@example.com',
+  'urn:myapp:organization_tier': 'bronze',
+  'urn:myapp:user_language': 'en',
+  'urn:myapp:organization_domain': 'example.com',
+  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
+  sub: 'user_01XYZ789ABC123DEF456GHI012',
+  sid: 'session_01PQR456STU789VWX012YZA345',
+  jti: '01MNO678PQR901STU234VWX567',
+  org_id: 'org_01DEF234GHI567JKL890MNO123',
+  role: 'member',
+  roles: [ 'member' ],
+  permissions: [],
+  exp: 1758290589,
+  iat: 1758290289
+}
+```
+
+The properties with `urn:myapp:` prefixes are custom claims configured in your WorkOS JWT template. Standard JWT claims include `sub` (user ID), `iss` (issuer), `exp` (expiration), and WorkOS-specific claims like `org_id`, `role`, and `roles`.
+
+## Related
+
+[MastraAuthWorkos Class](/docs/auth/workos)
+

package/.docs/raw/reference/memory/Memory.mdx

@@ -152,6 +152,47 @@ export const agent = new Agent({
 });
 ```
 
+## PostgreSQL with index configuration
+
+```typescript filename="src/mastra/agents/pg-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { PgStore, PgVector } from "@mastra/pg";
+
+export const agent = new Agent({
+  name: "pg-agent",
+  instructions: "You are an agent with optimized PostgreSQL memory.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new PgStore({
+      connectionString: process.env.DATABASE_URL
+    }),
+    vector: new PgVector({
+      connectionString: process.env.DATABASE_URL
+    }),
+    embedder: openai.embedding("text-embedding-3-small"),
+    options: {
+      lastMessages: 20,
+      semanticRecall: {
+        topK: 5,
+        messageRange: 3,
+        scope: 'resource',
+        indexConfig: {
+          type: 'hnsw',              // Use HNSW for better performance
+          metric: 'dotproduct',      // Optimal for OpenAI embeddings
+          m: 16,                     // Number of bi-directional links
+          efConstruction: 64         // Construction-time candidate list size
+        }
+      },
+      workingMemory: {
+        enabled: true
+      }
+    }
+  })
+});
+```
+
 ### Related
 
 - [Getting Started with Memory](/docs/memory/overview.mdx)

package/.docs/raw/reference/rag/pg.mdx

@@ -498,11 +498,38 @@ try {
 }
 ```
 
+## Index Configuration Guide
+
+### Performance Optimization
+
+#### IVFFlat Tuning
+- **lists parameter**: Set to `sqrt(n) * 2` where n is the number of vectors
+- More lists = better accuracy but slower build time
+- Fewer lists = faster build but potentially lower accuracy
+
+#### HNSW Tuning
+- **m parameter**: 
+  - 8-16: Moderate accuracy, lower memory
+  - 16-32: High accuracy, moderate memory
+  - 32-64: Very high accuracy, high memory
+- **efConstruction**: 
+  - 32-64: Fast build, good quality
+  - 64-128: Slower build, better quality
+  - 128-256: Slowest build, best quality
+
+### Index Recreation Behavior
+
+The system automatically detects configuration changes and only rebuilds indexes when necessary:
+- Same configuration: Index is kept (no recreation)
+- Changed configuration: Index is dropped and rebuilt
+- This prevents the performance issues from unnecessary index recreations
+
 ## Best Practices
 
 - Regularly evaluate your index configuration to ensure optimal performance.
 - Adjust parameters like `lists` and `m` based on dataset size and query requirements.
-- Rebuild indexes periodically to maintain efficiency, especially after significant data changes.
+- **Monitor index performance** using `describeIndex()` to track usage
+- Rebuild indexes periodically to maintain efficiency, especially after significant data changes
 
 ## Direct Pool Access
 

package/.docs/raw/reference/workflows/step.mdx

@@ -103,7 +103,7 @@ const step1 = createStep({
     },
     {
       name: "getStepResult",
-      type: "(stepId: string) => any",
+      type: "(step: Step | string) => any",
       description: "Function to access results from other steps",
     },
     {

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/mcp-docs-server
 
+## 0.13.24-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`4b339b8`](https://github.com/mastra-ai/mastra/commit/4b339b8141c20d6a6d80583c7e8c5c05d8c19492), [`c591dfc`](https://github.com/mastra-ai/mastra/commit/c591dfc1e600fae1dedffe239357d250e146378f), [`1920c5c`](https://github.com/mastra-ai/mastra/commit/1920c5c6d666f687785c73021196aa551e579e0d), [`b6a3b65`](https://github.com/mastra-ai/mastra/commit/b6a3b65d830fa0ca7754ad6481661d1f2c878f21), [`af3abb6`](https://github.com/mastra-ai/mastra/commit/af3abb6f7c7585d856e22d27f4e7d2ece2186b9a)]:
+  - @mastra/core@0.18.0-alpha.3
+
+## 0.13.24-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`cf34503`](https://github.com/mastra-ai/mastra/commit/cf345031de4e157f29087946449e60b965e9c8a9), [`6b4b1e4`](https://github.com/mastra-ai/mastra/commit/6b4b1e4235428d39e51cbda9832704c0ba70ab32), [`3469fca`](https://github.com/mastra-ai/mastra/commit/3469fca7bb7e5e19369ff9f7044716a5e4b02585), [`c4a8204`](https://github.com/mastra-ai/mastra/commit/c4a82046bfd241d6044e234bc5917d5a01fe6b55), [`5b1ee71`](https://github.com/mastra-ai/mastra/commit/5b1ee71dc3ac92383226dc1e375642ca5f9b4224)]:
+  - @mastra/core@0.18.0-alpha.2
+  - @mastra/mcp@0.13.1-alpha.0
+
+## 0.13.24-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`c45298a`](https://github.com/mastra-ai/mastra/commit/c45298a0a0791db35cf79f1199d77004da0704cb)]:
+  - @mastra/core@0.17.2-alpha.1
+
 ## 0.13.24-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.24-alpha.0",
+  "version": "0.13.24-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,11 +33,11 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@mastra/core": "0.17.2-alpha.0",
-    "@mastra/mcp": "^0.13.0"
+    "@mastra/core": "0.18.0-alpha.3",
+    "@mastra/mcp": "^0.13.1-alpha.0"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.3",
+    "@hono/node-server": "^1.19.4",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^20.19.0",
     "@types/turndown": "^5.0.5",
@@ -50,7 +50,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@internal/lint": "0.0.41",
-    "@mastra/core": "0.17.2-alpha.0"
+    "@mastra/core": "0.18.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {