@mastra/mcp-docs-server 1.3.7-alpha.9 → 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/harness/durable-agents.md

@@ -374,10 +374,13 @@ Enforcement of the claim depends on the workflows store. When the store supports
 - `@mastra/convex`
 - `@mastra/mongodb`, on a replica set or sharded cluster
 - `@mastra/dynamodb`
+- `@mastra/redis`
+- `@mastra/upstash`
+- `@mastra/valkey`
 
 On Convex, run fencing runs in the Mastra server functions you deploy. Redeploy your Convex functions after upgrading `@mastra/convex`. Until you do, durable agent runs fail with an error asking you to redeploy, while other writes keep working.
 
-Stores that support run fencing keep one claim record per run, plus one memory fence record per run with memory. Stores with retention support prune them with the `workflows.runOwnership` and `memory.runFences` [retention keys](https://mastra.ai/reference/storage/retention). A run's first generation comes from the store's clock, so a run that reuses a `runId` after its records were pruned still outranks the fences and stream events of its earlier executions.
+Stores that support run fencing keep one claim record per run, plus one memory fence record per run with memory. Stores with retention support prune them with the `workflows.runOwnership` and `memory.runFences` [retention keys](https://mastra.ai/reference/storage/retention). Redis, Upstash, and Valkey expire them on their own instead: a claim 7 days after its last claim, renewal, or release, and a fence 7 days after it's retired. A run's first generation comes from the store's clock, so a run that reuses a `runId` after its records were pruned still outranks the fences and stream events of its earlier executions.
 
 With any other workflows store, the claim is a lease on the [PubSub](https://mastra.ai/docs/server/pubsub) backend. The lease keeps two executions from claiming the run at once, but writes from an execution that lost the run aren't rejected. A run taken over while its previous execution was still live can end with that execution's output. When an execution loses its lease and no other execution has taken the run, the run stays held for up to 15 more seconds. Until then, `recover()` without `force` throws `DURABLE_AGENT_RUN_ACTIVE` with `retryAt` set to when the hold is sure to have ended. Mastra logs a warning when it recovers runs against a workflows or memory store without run fencing.
 

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/integrations/databases/redis.md

@@ -4,7 +4,7 @@
 
 # Redis
 
-The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [`node-redis`](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.
+The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [`node-redis`](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis and, through a custom client, Redis Sentinel. Redis Cluster isn't supported.
 
 ## Installation
 
@@ -45,7 +45,7 @@ await storage.init()
 
 ### Using Pre-configured Client
 
-For advanced configurations like Sentinel or Cluster, you can pass a pre-configured Redis client:
+For advanced configurations such as Sentinel, you can pass a pre-configured Redis client:
 
 ```typescript
 import { RedisStore } from '@mastra/redis'
@@ -122,27 +122,7 @@ const storage = new RedisStore({
 
 ### Redis Cluster
 
-For Redis Cluster deployments, use the cluster client:
-
-```typescript
-import { RedisStore } from '@mastra/redis'
-import { createCluster } from 'redis'
-
-const cluster = createCluster({
-  rootNodes: [
-    { url: 'redis://node-1:6379' },
-    { url: 'redis://node-2:6379' },
-    { url: 'redis://node-3:6379' },
-  ],
-})
-
-await cluster.connect()
-
-const storage = new RedisStore({
-  id: 'redis-cluster-storage',
-  client: cluster,
-})
-```
+Redis Cluster isn't supported. `RedisStore` accepts only a standalone client from `createClient()`, and several operations read or write keys that hash to different slots, which Redis Cluster rejects with a `CROSSSLOT` error.
 
 ### Accessing the Underlying Client
 

package/.docs/integrations/databases/valkey.md

@@ -66,6 +66,8 @@ const storage = new ValkeyStore({
 
 For an existing `GlideClient`, connect it before passing it to `ValkeyStore`. The caller remains responsible for closing injected clients.
 
+`ValkeyStore` needs a standalone Valkey server. Valkey Cluster and `GlideClusterClient` aren't supported.
+
 ## Constructor parameters
 
 **id** (`string`): Unique identifier for the storage instance.

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/cli/mastra.md

@@ -2006,15 +2006,24 @@ Prints help message and exits.
 
 ## Telemetry
 
-By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
+By default, Mastra collects telemetry about your project, including your OS, Mastra version, and Node.js version. Server events also include the project identifiers described below. You can read the [CLI telemetry source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected by the CLI.
 
-When a server started with `mastra dev` or `mastra start` has observability metrics enabled, Mastra also sends anonymous, aggregated model usage at startup: input and output token counts per provider and model, plus the command (`dev` or `start`) and `NODE_ENV`. No prompts, responses, or other message content is ever sent. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts) to check what's collected.
+When a server started with `mastra dev` or `mastra start` has observability metrics enabled, Mastra sends aggregated model usage at startup: input and output token counts per provider and model, plus the command (`dev` or `start`) and `NODE_ENV`. No prompts, responses, or other message content is sent. You can read the [model usage telemetry source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts) to check what's collected.
 
-At server startup, Mastra also sends an anonymous project-surface snapshot: counts of registered agents, agent controllers, workflows, tools, processors, vector stores, scorers, workspaces, MCP servers, gateways, and channels, plus booleans for memory, voice, editor, and observability usage and the coarse storage backend category. It doesn't send names or identifiers. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts) to check what's collected.
+At server startup, Mastra sends a project-surface snapshot with component counts, feature flags, and the coarse storage backend category, but no component names or component identifiers. You can read the [feature telemetry source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts) to check what's collected.
+
+The server events `mastra_feature_usage` and `mastra_model_token_usage` include:
+
+- `project_id`: The first 16 hexadecimal characters of the SHA-256 hash of `MASTRA_PROJECT_ROOT`, or the current working directory when unset. This identifier also keys the local model-usage cursor.
+- `project_id2`: An optional identifier for correlation across machines and deployments. If the trimmed `MASTRA_PROJECT_ID` value has UUID format, the value is sent **unhashed**, prefixed with `mp_`. Search for `mp_<platform-project-id>` to find that project's telemetry. Names, slugs, and other non-UUID values aren't sent as Platform identifiers.
+
+When no UUID-shaped Platform ID is available, `project_id2` uses the first 16 hexadecimal characters of the SHA-256 hash of the normalized Git `origin` remote. Normalization keeps the lowercase host and repository path, excluding the scheme, credentials, port, query, fragment, trailing slashes, and `.git` suffix. Equivalent SSH and HTTPS remotes produce the same identifier. Remotes with the same host and path share an identifier even if different ports or SSH users refer to different repositories. Local filesystem remotes aren't used. Git discovery runs asynchronously and is cached for the process, including when unavailable. If neither source is available, `project_id2` is omitted.
+
+These server events aren't anonymous: a Platform ID links them to that project, and a known repository URL can be normalized and hashed to match Git-derived events. Hashing the Git identity avoids sending the raw repository URL or credentials, but doesn't prevent correlation with public or otherwise known repositories.
 
 The Studio UI also collects anonymous browser-side usage analytics, such as page views and UI interactions. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/playground/src/lib/analytics.tsx) to check what's collected. Setting `MASTRA_TELEMETRY_DISABLED` disables this too: the value is injected into the served page, so it applies to `mastra dev` and self-hosted builds alike.
 
-You can opt out of all CLI and usage analytics by setting an environment variable:
+You can opt out of CLI, server, and Studio usage analytics by setting this environment variable before starting Mastra. When disabled, server telemetry doesn't look up the Git remote or send either project identifier:
 
 ```bash
 MASTRA_TELEMETRY_DISABLED=1

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-alpha.9",
+  "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-alpha.0",
-    "@mastra/core": "1.77.0-alpha.4"
+    "@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/lint": "0.0.142",
-    "@internal/types-builder": "0.0.117",
-    "@mastra/core": "1.77.0-alpha.4"
+    "@internal/types-builder": "0.0.118",
+    "@internal/lint": "0.0.143",
+    "@mastra/core": "1.78.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {