@mastra/mcp-docs-server 1.1.25-alpha.1 → 1.1.25-alpha.3

package/.docs/docs/server/middleware.md

@@ -97,22 +97,62 @@ export const mastra = new Mastra({
 
 ### Authorization (User Isolation)
 
-Authentication verifies who the user is. Authorization controls what they can access. Without authorization middleware, an authenticated user could access other users' threads by guessing IDs or manipulating the `resourceId` parameter.
+Authentication verifies who the user is. Authorization controls what they can access. Without resource ID scoping, an authenticated user could access other users' threads by guessing IDs or manipulating the `resourceId` parameter.
 
-Mastra provides reserved context keys that, when set by middleware, take precedence over client-provided values. The server automatically enforces these keys across memory and agent endpoints:
+The simplest way to scope memory and threads to the authenticated user is the `mapUserToResourceId` callback in the auth config:
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
-import { getAuthenticatedUser } from '@mastra/server/auth'
 
 export const mastra = new Mastra({
   server: {
     auth: {
       authenticateToken: async token => {
-        // Your auth logic returns the user
-        return verifyToken(token) // { id: 'user-123', ... }
+        return verifyToken(token) // { id: 'user-123', orgId: 'org-456', ... }
       },
+      mapUserToResourceId: user => user.id,
+    },
+  },
+})
+```
+
+After successful authentication, `mapUserToResourceId` is called with the authenticated user object. The returned value is set as `MASTRA_RESOURCE_ID_KEY` on the request context, which works across all server adapters (Hono, Express, Next.js, etc.).
+
+The resource ID doesn't have to be `user.id`. Common patterns:
+
+```typescript
+// Org-scoped
+mapUserToResourceId: user => `${user.orgId}:${user.id}`
+
+// From a JWT claim
+mapUserToResourceId: user => user.tenantId
+
+// Composite key
+mapUserToResourceId: user => `${user.workspaceId}:${user.projectId}:${user.id}`
+```
+
+With a resource ID set, the server automatically:
+
+- **Filters thread listing** to only return threads owned by the user
+- **Validates thread access** and returns 403 if accessing another user's thread
+- **Forces thread creation** to use the authenticated user's ID
+- **Validates message operations** including deletion, ensuring messages belong to owned threads
+
+Even if a client passes `?resourceId=other-user-id`, the auth-set value takes precedence. Attempts to access threads or messages owned by other users will return a 403 error.
+
+#### Advanced: Setting resource ID in middleware
+
+For more complex scenarios (e.g., looking up the resource ID from a database), you can set `MASTRA_RESOURCE_ID_KEY` directly in middleware:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
+import { getAuthenticatedUser } from '@mastra/server/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: {
+      authenticateToken: async token => verifyToken(token),
     },
     middleware: [
       {
@@ -134,10 +174,7 @@ export const mastra = new Mastra({
             return c.json({ error: 'Unauthorized' }, 401)
           }
 
-          // Force all API operations to use this user's ID
-          // This takes precedence over any client-provided resourceId
           requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
-
           return next()
         },
       },
@@ -148,15 +185,6 @@ export const mastra = new Mastra({
 
 `server.middleware` runs before Mastra's per-route auth checks. When middleware needs the authenticated user, call `getAuthenticatedUser()` to resolve it from the configured auth provider without changing the default route auth flow.
 
-With this middleware, the server automatically:
-
-- **Filters thread listing** to only return threads owned by the user
-- **Validates thread access** and returns 403 if accessing another user's thread
-- **Forces thread creation** to use the authenticated user's ID
-- **Validates message operations** including deletion, ensuring messages belong to owned threads
-
-Even if a client passes `?resourceId=other-user-id`, the middleware-set value takes precedence. Attempts to access threads or messages owned by other users will return a 403 error.
-
 #### Using `MASTRA_THREAD_ID_KEY`
 
 You can also set `MASTRA_THREAD_ID_KEY` to override the client-provided thread ID:

package/.docs/docs/server/request-context.md

@@ -234,7 +234,18 @@ export const weatherTool = createTool({
 
 ## Reserved keys
 
-Mastra reserves special context keys for security purposes. When set by middleware, these keys take precedence over client-provided values. The server automatically validates ownership and returns 403 errors when users attempt to access resources they don't own.
+Mastra reserves special context keys for security purposes. When set, these keys take precedence over client-provided values. The server automatically validates ownership and returns 403 errors when users attempt to access resources they don't own.
+
+The easiest way to set `MASTRA_RESOURCE_ID_KEY` is via the `mapUserToResourceId` callback in auth config:
+
+```typescript
+auth: {
+  authenticateToken: async token => verifyToken(token),
+  mapUserToResourceId: user => user.id,
+}
+```
+
+You can also set these keys manually in middleware:
 
 ```typescript
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context'

package/.docs/reference/configuration.md

@@ -544,11 +544,14 @@ export const mastra = new Mastra({
   server: {
     auth: new MastraJwtAuth({
       secret: process.env.MASTRA_JWT_SECRET,
+      mapUserToResourceId: user => user.id,
     }),
   },
 })
 ```
 
+The `mapUserToResourceId` callback maps the authenticated user to a resource ID for memory/thread scoping. When provided, it's called after successful authentication and the returned value is set on the request context as `MASTRA_RESOURCE_ID_KEY`. See [Authorization (User Isolation)](https://mastra.ai/docs/server/middleware) for details.
+
 ### server.bodySizeLimit
 
 **Type:** `number`\

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.25-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`8fad147`](https://github.com/mastra-ai/mastra/commit/8fad14759804179c8e080ce4d9dec6ef1a808b31), [`582644c`](https://github.com/mastra-ai/mastra/commit/582644c4a87f83b4f245a84d72b9e8590585012e), [`5d84914`](https://github.com/mastra-ai/mastra/commit/5d84914e0e520c642a40329b210b413fcd139898), [`fd2f314`](https://github.com/mastra-ai/mastra/commit/fd2f31473d3449b6b97e837ef8641264377f41a7), [`e80fead`](https://github.com/mastra-ai/mastra/commit/e80fead1412cc0d1b2f7d6a1ce5017d9e0098ff7), [`0287b64`](https://github.com/mastra-ai/mastra/commit/0287b644a5c3272755cf3112e71338106664103b)]:
+  - @mastra/core@1.25.0-alpha.1
+
 ## 1.1.25-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.25-alpha.1",
+  "version": "1.1.25-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.24.2-alpha.0",
+    "@mastra/core": "1.25.0-alpha.1",
     "@mastra/mcp": "^1.4.2"
   },
   "devDependencies": {
@@ -47,8 +47,8 @@
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
     "@internal/types-builder": "0.0.57",
-    "@mastra/core": "1.24.2-alpha.0",
-    "@internal/lint": "0.0.82"
+    "@internal/lint": "0.0.82",
+    "@mastra/core": "1.25.0-alpha.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {