@mastra/mcp-docs-server 1.3.7 → 1.3.8-alpha.0

package/.docs/docs/harness/background-tasks.md

@@ -318,14 +318,14 @@ export const mastra = new Mastra({
 
 ### Subscribe to all task events
 
-Calling `stream()` with no filter returns a stream of every task event in the system. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
+Pass `allResources: true` to receive every task event in the system, across all resources. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
 
 ```typescript
 const bgManager = mastra.backgroundTaskManager;
 if (!bgManager) throw new Error('Background tasks are not enabled');
 
 const controller = new AbortController();
-const stream = bgManager.stream({ abortSignal: controller.signal });
+const stream = bgManager.stream({ allResources: true, abortSignal: controller.signal });
 
 for await (const chunk of stream) {
   switch (chunk.type) {
@@ -344,6 +344,8 @@ for await (const chunk of stream) {
 
 The stream stays open until the caller's `AbortSignal` fires. Always pass an `abortSignal` so you can disconnect cleanly.
 
+> **Warning:** `allResources: true` delivers task arguments and results for every user. Use it only in trusted server-side code, never to serve a single user's request. Without `resourceId` or `allResources`, `stream()` only delivers tasks that have no `resourceId`. Agent tasks dispatched with memory always have a `resourceId`, so they won't appear in that stream.
+
 ### Filter the stream
 
 Pass any combination of filter options to narrow the events you receive. Filters apply to both the initial snapshot and the live event subscription.
@@ -357,14 +359,15 @@ const stream = bgManager.stream({
 })
 ```
 
-| Filter        | Description                                         |
-| ------------- | --------------------------------------------------- |
-| `agentId`     | Only events from tasks dispatched by this agent     |
-| `runId`       | Only events from this specific agent run            |
-| `threadId`    | Only events from tasks scoped to this memory thread |
-| `resourceId`  | Only events from tasks scoped to this resource      |
-| `taskId`      | Only events for a single task                       |
-| `abortSignal` | Closes the stream when the signal aborts            |
+| Filter         | Description                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------- |
+| `agentId`      | Only events from tasks dispatched by this agent                                               |
+| `runId`        | Only events from this specific agent run                                                      |
+| `threadId`     | Only events from tasks scoped to this memory thread                                           |
+| `resourceId`   | Only events from tasks scoped to this resource                                                |
+| `taskId`       | Only events for a single task                                                                 |
+| `allResources` | Include tasks from every resource when `resourceId` is omitted. Trusted server-side code only |
+| `abortSignal`  | Closes the stream when the signal aborts                                                      |
 
 ### Look up task state directly
 

package/.docs/docs/memory/overview.md

@@ -151,6 +151,37 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 
 To list all threads for a resource, or retrieve a specific thread, [use the memory API directly](https://mastra.ai/docs/memory/message-history).
 
+### Identify memory with scopes
+
+Instead of a `memory` object, you can pass `scopes`: the addresses a run acts as, written as `<type>:<value>`. Memory reads the resource from a `resource:` scope and the thread from a `thread:` scope. Other scopes, such as `org:acme`, are passed to tools and processors.
+
+```typescript
+const response = await memoryAgent.generate('Remember my favorite color is blue.', {
+  scopes: ['org:acme', 'resource:user-123', 'thread:conversation-123'],
+})
+```
+
+Scopes can also come from the agent and from the request context. Mastra combines all three sources:
+
+```typescript
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  scopes: ({ requestContext }) => {
+    // Set by your auth middleware. Request bodies can fill unreserved keys.
+    const orgId = requestContext.get('org-id')
+    return orgId ? [`org:${orgId}`] : []
+  },
+  memory: new Memory(),
+})
+```
+
+The resolver's inputs must come from the server, not the client: a request body can set any request context key that isn't reserved. Trusted server middleware can also set scopes directly with the `MASTRA_SCOPES_KEY` request context key. Visit [Request Context](https://mastra.ai/docs/server/request-context) for details. Clients can't send scopes in a request body.
+
+You can mix scopes with `memory.resource`, `memory.thread`, or the resource and thread request context keys, as long as they agree. If a `resource:` or `thread:` scope names a different value than another source, the call throws an error.
+
+Tools, processors, and subagents receive the run's other scopes, but not its `resource:` and `thread:` scopes. Each nested agent call picks its own resource and thread.
+
 ## Observational Memory
 
 Long conversations can fill the context window with raw message history and reduce agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses background agents to compress older messages into observations. This reduces the context used by message history while retaining information for later turns.

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

@@ -284,11 +284,35 @@ requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
 requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
 ```
 
-| Key                         | Purpose                                                                                                                                                                                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MASTRA_RESOURCE_ID_KEY`    | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not.                                                                                                                          |
-| `MASTRA_THREAD_ID_KEY`      | Forces thread operations to use this thread ID, overriding client-provided values                                                                                                                                                                                         |
-| `MASTRA_MESSAGE_AUTHOR_KEY` | Names who sent a user message as `{ id, name?, avatarUrl? }`. Agent-controller sessions persist it at `content.metadata.signal.author` and mirror it to `providerMetadata.mastra.author` for compatibility, so a thread shared by several people can show who wrote what. |
+| Key                         | Purpose                                                                                                                                                                                                                                                                                        |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_RESOURCE_ID_KEY`    | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not.                                                                                                                                               |
+| `MASTRA_THREAD_ID_KEY`      | Forces thread operations to use this thread ID, overriding client-provided values                                                                                                                                                                                                              |
+| `MASTRA_SCOPES_KEY`         | Sets the [scopes](https://mastra.ai/docs/memory/overview) the agent run acts as, as an array of `<type>:<value>` strings. Combined with the agent's `scopes` and per-call `scopes`. A `resource:` or `thread:` scope that conflicts with another resource or thread value returns a 400 error. |
+| `MASTRA_MESSAGE_AUTHOR_KEY` | Names who sent a user message as `{ id, name?, avatarUrl? }`. Agent-controller sessions persist it at `content.metadata.signal.author` and mirror it to `providerMetadata.mastra.author` for compatibility, so a thread shared by several people can show who wrote what.                      |
+
+Server ownership checks read only `MASTRA_RESOURCE_ID_KEY` and `MASTRA_THREAD_ID_KEY`. If your middleware sets identity through `MASTRA_SCOPES_KEY` and you want those checks, set `MASTRA_RESOURCE_ID_KEY` too:
+
+```typescript
+import {
+  MASTRA_RESOURCE_ID_KEY,
+  MASTRA_THREAD_ID_KEY,
+  MASTRA_SCOPES_KEY,
+} from '@mastra/core/request-context'
+
+requestContext.set(MASTRA_SCOPES_KEY, [`org:${user.orgId}`, `resource:${user.id}`])
+requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
+```
+
+The same applies to a `thread:` scope: it sets the run's thread identity, but only `MASTRA_THREAD_ID_KEY` drives the server's thread checks, so set both when middleware pins the thread:
+
+```typescript
+requestContext.set(MASTRA_SCOPES_KEY, [`resource:${user.id}`, `thread:${threadId}`])
+requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
+requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
+```
+
+Scopes from the request context and per-call `scopes` need a `@mastra/server` release that reserves them. Older servers pass these values from request bodies through to the agent, so while one is registered, agents throw an `AGENT_SCOPES_SERVER_OUTDATED` error instead of using them. The agent's own `scopes` option still applies.
 
 These keys are used to implement user isolation in multi-tenant applications. See [Authorization middleware](https://mastra.ai/docs/server/middleware) for usage examples.
 

package/.docs/reference/agents/agent.md

@@ -587,6 +587,8 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **scorers** (`MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>`): Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.
 
+**scopes** (`string[] | ({ requestContext: RequestContext }) => string[] | Promise<string[]>`): Scopes every run of this agent acts as, written as \<type>:\<value>. Combined with per-call scopes and the mastra\_\_scopes request context key.
+
 **memory** (`MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>`): Memory module used for storing and retrieving stateful context.
 
 **notifications** (`object`): Notification delivery configuration for durable notification signals.

package/.docs/reference/agents/generate.md

@@ -128,6 +128,8 @@ const result = await agent.generate('message for agent')
 
 **options.output** (`Zod schema | JsonSchema7`): \*\*Deprecated.\*\* Use structuredOutput without a model to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
 
+**options.scopes** (`string[]`): Scopes the run acts as, written as \<type>:\<value> (for example org:acme, resource:user-123, thread:conversation-123). Memory reads its resource and thread from resource: and thread: scopes. Other scopes are passed to tools and processors. Combined with the agent's scopes and the mastra\_\_scopes request context key. Throws if a resource: or thread: scope conflicts with another resource or thread value.
+
 **options.memory** (`object`): Memory configuration for conversation persistence and retrieval.
 
 **options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title.

package/.docs/reference/streaming/agents/stream.md

@@ -122,6 +122,8 @@ const stream = await agent.stream('message for agent')
 
 **options.output** (`Zod schema | JsonSchema7`): \*\*Deprecated.\*\* Use structuredOutput without a model to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
 
+**options.scopes** (`string[]`): Scopes the run acts as, written as \<type>:\<value> (for example org:acme, resource:user-123, thread:conversation-123). Memory reads its resource and thread from resource: and thread: scopes. Other scopes are passed to tools and processors. Combined with the agent's scopes and the mastra\_\_scopes request context key. Throws if a resource: or thread: scope conflicts with another resource or thread value.
+
 **options.memory** (`object`): Configuration for memory. This is the preferred way to manage memory.
 
 **options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): The conversation thread, as a string ID or an object with an id and optional metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.3.7",
+  "version": "1.3.8-alpha.0",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,8 +26,8 @@
     "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/mcp": "^2.4.0",
-    "@mastra/core": "1.77.0"
+    "@mastra/core": "1.78.0-alpha.0",
+    "@mastra/mcp": "^2.4.0"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -43,9 +43,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
+    "@internal/types-builder": "0.0.118",
     "@internal/lint": "0.0.143",
-    "@mastra/core": "1.77.0",
-    "@internal/types-builder": "0.0.118"
+    "@mastra/core": "1.78.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {