@mastra/mcp-docs-server 1.2.14 → 1.2.15-alpha.10

package/.docs/reference/storage/oracledb.md

@@ -0,0 +1,239 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# OracleDB storage
+
+The OracleDB storage provider stores Mastra application state in Oracle Database. It implements Mastra's composite storage interface, so one `OracleStore` instance can back memory, workflow snapshots, observability, scores, scorer definitions, MCP client metadata, and agent registry data.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/oracledb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/oracledb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/oracledb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/oracledb@latest
+```
+
+## Usage
+
+```ts
+import { OracleStore } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+```
+
+Use it with Mastra:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+
+export const mastra = new Mastra({
+  storage,
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for this storage instance.
+
+**user** (`string`): Oracle Database user. Required unless using pool or externalAuth.
+
+**password** (`string`): Password for the Oracle Database user. Required unless using pool or externalAuth.
+
+**connectString** (`string`): Oracle connect string, service name, TNS alias, or Autonomous Database connect descriptor. Required unless using pool.
+
+**pool** (`oracledb.Pool`): Existing Oracle connection pool. When provided, Mastra uses the pool but doesn't close it when store.close() is called.
+
+**poolManager** (`OraclePoolManager`): Shared Oracle pool manager. Use this to share one Oracle pool between OracleStore and OracleVector.
+
+**schemaName** (`string`): Oracle schema name used to qualify storage tables.
+
+**poolMin** (`number`): Minimum number of Oracle pool connections. (Default: `0`)
+
+**poolMax** (`number`): Maximum number of Oracle pool connections. (Default: `4`)
+
+**poolIncrement** (`number`): Number of connections to add when the pool grows. (Default: `1`)
+
+**configDir** (`string`): Directory containing Oracle Network configuration files such as tnsnames.ora.
+
+**walletLocation** (`string`): Oracle wallet directory for mTLS connections such as Autonomous Database.
+
+**walletPassword** (`string`): Password for the Oracle wallet, when required by the wallet configuration.
+
+**externalAuth** (`boolean`): Use Oracle external authentication instead of username/password authentication.
+
+**disableInit** (`boolean`): When true, automatic schema initialization is disabled. Use this when schema changes are applied separately before the app starts. (Default: `false`)
+
+**messageBatchSize** (`number`): Number of messages sent per Oracle executeMany call when saving messages. The operation still commits once at the transaction boundary. (Default: `200`)
+
+**skipDefaultIndexes** (`boolean`): When true, default storage indexes aren't created during initialization.
+
+**indexes** (`OracleCreateIndexOptions[]`): Custom Oracle index definitions to create during initialization. Indexes are routed to the storage domain that owns the target table.
+
+**migrationTableName** (`string`): Oracle table used to track storage schema migrations. (Default: `'MASTRA_ORACLE_MIGRATIONS'`)
+
+**vectorRegistryTableName** (`string`): OracleVector registry table used to discover semantic-recall vector tables when threads or messages are deleted. Set this to match OracleVector's registryTableName when that option is customized.
+
+## Connection examples
+
+The basic username/password constructor is shown above. For Autonomous Database, add wallet options to the same constructor:
+
+```ts
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+  walletLocation: process.env.ORACLE_DATABASE_WALLET_DIR,
+  walletPassword: process.env.ORACLE_DATABASE_WALLET_PASSWORD,
+  configDir: process.env.ORACLE_DATABASE_CONFIG_DIR,
+})
+```
+
+For external authentication, set `externalAuth: true` and omit `password`. To reuse an existing `oracledb.Pool`, pass it as `pool`. Mastra uses it but doesn't close it.
+
+`OracleStore` backs memory, workflow snapshots, observability, scores, scorer definitions, MCP client metadata, and agent registry data. When using the store outside a `Mastra` instance, call `await storage.init()` and access a domain with `await storage.getStore('memory')`.
+
+## Initialization
+
+When you pass `OracleStore` to `Mastra`, `init()` is called automatically before storage operations run. If you use `OracleStore` directly, call `init()` before reading or writing:
+
+```ts
+await storage.init()
+```
+
+> **Warning:** If initialization is disabled or skipped, storage operations require the Oracle tables and indexes to already exist.
+
+`OracleStore.init()` runs repeatable migrations and records the result in the migration ledger table. The default ledger table is `MASTRA_ORACLE_MIGRATIONS`.
+
+```ts
+await storage.migrate()
+const history = await storage.listMigrations()
+```
+
+Repeatable migrations are idempotent. They reconcile the tables and indexes owned by each storage domain on startup, which lets new domain indexes or compatible schema additions apply without changing application code.
+
+Initialization also creates the provider's default indexes for common Mastra query paths. Use `skipDefaultIndexes` when indexes are managed separately, or pass `indexes` for custom Oracle indexes. Custom definitions support Oracle options such as `bitmap`, `online`, `invisible`, `parallel`, `compress`, `noLogging`, and `reverse`, as well as function-based expressions like `JSON_VALUE(...)`.
+
+Custom indexes are useful when your app repeatedly filters on JSON metadata or when database administrators (DBAs) want to test an index before the optimizer uses it:
+
+```ts
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user,
+  password,
+  connectString,
+  indexes: [
+    {
+      name: 'idx_messages_status',
+      table: 'mastra_messages',
+      columns: [
+        "JSON_VALUE(metadata, '$.status' RETURNING VARCHAR2(32) NULL ON ERROR)",
+        'thread_id',
+      ],
+      online: true,
+      invisible: true,
+    },
+  ],
+})
+```
+
+Use `invisible` for staged rollout, then remove it after validating query plans. Use `skipDefaultIndexes: true` only when a DBA-managed indexing strategy replaces the defaults.
+
+Use `disableInit: true` when schema changes are applied by a separate deployment step or by a database administrator.
+
+## Schema export
+
+Use `exportSchemas()` to generate Oracle DDL without connecting to a database. This is useful when schema changes are reviewed or applied outside application startup.
+
+```ts
+import { exportSchemas } from '@mastra/oracledb'
+
+const ddl = exportSchemas({
+  schemaName: 'MASTRA_APP',
+  domains: [
+    'memory',
+    'workflows',
+    'observability',
+    'scores',
+    'scorerDefinitions',
+    'mcpClients',
+    'agents',
+  ],
+})
+
+console.log(ddl)
+```
+
+`domains` defaults to every supported domain, including `vector`, when omitted.
+
+## Operational notes
+
+Use the same `OraclePoolManager` when `OracleStore` and `OracleVector` should share one Oracle connection lifecycle:
+
+```ts
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+```
+
+`OracleStore` exposes `storage.db` and `await storage.getPool()` for advanced use cases. When using these APIs directly, you're responsible for transaction boundaries and connection lifecycle.
+
+JSON metadata, payloads, and snapshots are stored in native Oracle JSON columns and encoded server-side, so the rows are readable directly with standard Oracle JDBC tools such as DBeaver and SQL Developer.
+
+## Usage example
+
+### Adding OracleDB memory to an agent
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { OracleStore } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+export const oracleAgent = new Agent({
+  id: 'oracle-agent',
+  name: 'Oracle Agent',
+  instructions: 'You are an assistant with persistent OracleDB-backed memory.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({ storage }),
+})
+```
+
+## Related
+
+- [OracleDB vector store](https://mastra.ai/reference/vectors/oracledb)
+- [Storage overview](https://mastra.ai/reference/storage/overview)
+- [Working memory](https://mastra.ai/docs/memory/working-memory)
+- [Workflow snapshots](https://mastra.ai/docs/workflows/snapshots)

package/.docs/reference/storage/overview.md

@@ -10,15 +10,15 @@ Mastra storage is organized into domains. Each domain owns a set of tables or co
 
 Not every storage adapter implements every domain. Composite storage lets you mix adapters per domain when the adapter packages export the corresponding domain classes.
 
-| Domain                | Description                                                                                                                            |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `memory`              | Conversation persistence: messages, threads, and resources (including working memory).                                                 |
-| `workflows`           | Workflow run snapshots used for suspend and resume.                                                                                    |
-| `workflowDefinitions` | Persisted [stored workflow](https://mastra.ai/docs/workflows/stored-workflows) definitions (beta). Loaded and live-registered on boot. |
-| `scores`              | Evaluation score records from eval runs.                                                                                               |
-| `observability`       | Traces and spans used by observability exporters and Studio.                                                                           |
-| `datasets`            | Dataset records, versioned items, and dataset versions used by experiments.                                                            |
-| `experiments`         | Experiment runs and per-item experiment results.                                                                                       |
+| Domain                | Description                                                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`              | Conversation persistence: messages, threads, and resources (including working memory).                                                   |
+| `workflows`           | Workflow run snapshots used for suspend and resume.                                                                                      |
+| `workflowDefinitions` | Persisted [dynamic workflow](https://mastra.ai/docs/workflows/dynamic-workflows) definitions (beta). Loaded and live-registered on boot. |
+| `scores`              | Evaluation score records from eval runs.                                                                                                 |
+| `observability`       | Traces and spans used by observability exporters and Studio.                                                                             |
+| `datasets`            | Dataset records, versioned items, and dataset versions used by experiments.                                                              |
+| `experiments`         | Experiment runs and per-item experiment results.                                                                                         |
 
 The schema definitions below cover the built-in database-backed tables documented for `memory`, `workflows`, `scores`, and `observability`. Other domains, and non-database adapters, use implementation-specific storage structures.
 

package/.docs/reference/storage/retention.md

@@ -92,7 +92,7 @@ Each domain declares which of its tables can be age-pruned and which timestamp c
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
-> - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
+> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`.
 > - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods

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

@@ -66,7 +66,7 @@ const stream = await agent.stream('message for agent')
 
 **options.delegation** (`DelegationConfig`): Configuration for subagent delegation. Use this to control and monitor when the agent delegates tasks to other agents, including the ability to modify, reject delegations, and provide feedback to guide the supervisor.
 
-**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters or reject the delegation entirely.
+**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters, reject the delegation entirely, or mutate context.requestContext to add entries to the subagent run's request context.
 
 **options.delegation.onDelegationComplete** (`(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>`): Called after a subagent delegation completes. The context includes a bail() method to stop further execution, and you can return { feedback } to guide the supervisor's next action. Feedback is saved to supervisor memory as an assistant message.
 

package/.docs/reference/tools/bedrock-kb-tool.md

@@ -0,0 +1,117 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# createBedrockKBTool()
+
+The `createBedrockKBTool()` function creates a tool that retrieves relevant documents from an Amazon Bedrock Knowledge Base. It supports both managed search configuration and agentic retrieval (query decomposition and managed reranking) with automatic fallback to standard retrieval.
+
+## Usage example
+
+```typescript
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+  region: 'us-west-2',
+  numberOfResults: 5,
+  useAgenticRetrieval: true,
+})
+```
+
+### With an Agent
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+})
+
+const agent = new Agent({
+  name: 'KnowledgeAssistant',
+  instructions: 'Use the knowledge base tool to answer questions.',
+  model: myModel,
+  tools: { kb: kbTool },
+})
+```
+
+## Parameters
+
+**knowledgeBaseId** (`string`): The ID of the Amazon Bedrock Knowledge Base to query.
+
+**region** (`string`): AWS region where the Knowledge Base is deployed. Defaults to AWS\_REGION environment variable or us-east-1.
+
+**numberOfResults** (`number`): Maximum number of results to return. Defaults to 5.
+
+**useAgenticRetrieval** (`boolean`): Use AgenticRetrieveStream for complex queries with query decomposition and managed reranking. Falls back to standard Retrieve on failure. Defaults to true (disable with USE\_AGENTIC\_RETRIEVAL=false env var).
+
+**userId** (`string`): Default AWS user ID for document-level access control. A userId in the Mastra request context takes precedence.
+
+## Input Schema
+
+The tool accepts the following input when called by an agent:
+
+**queryText** (`string`): The search query to find relevant documents in the knowledge base.
+
+## Output Schema
+
+The tool returns an object with:
+
+**results** (`BedrockKBResult[]`): Array of retrieval results. Standard retrieval includes source and score when Bedrock provides them; agentic retrieval may omit those fields.
+
+### BedrockKBResult
+
+| Field      | Type                      | Description                                                                                                                           |
+| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
+| `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
+
+## Retrieval Modes
+
+### Agentic Retrieval (default)
+
+When `useAgenticRetrieval` is `true` (default), the tool uses `AgenticRetrieveStreamCommand` which:
+
+- Decomposes complex queries into sub-queries
+- Retrieves across multiple passes
+- Applies managed reranking for better results
+
+If agentic retrieval fails (e.g., older SDK, permissions), it automatically falls back to standard managed retrieval.
+
+### Standard Managed Retrieval
+
+When `useAgenticRetrieval` is `false`, the tool uses `RetrieveCommand` with `managedSearchConfiguration` for direct single-pass retrieval.
+
+## User-based access control
+
+Set `userId` in the Mastra request context to forward it as the Bedrock `userContext.userId`. This supports knowledge bases that enforce document-level access control. The request context value overrides the default `userId` configured on the tool.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const requestContext = new RequestContext()
+requestContext.set('userId', 'user-123')
+
+await agent.generate('Find my private documents', { requestContext })
+```
+
+## Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["bedrock:Retrieve", "bedrock:AgenticRetrieveStream"],
+      "Resource": "arn:aws:bedrock:*:*:knowledge-base/*"
+    }
+  ]
+}
+```
+
+## SDK Requirements
+
+- `@aws-sdk/client-bedrock-agent-runtime` >= 3.1000 (AgenticRetrieveStreamCommand requires \~3.1000+)

package/.docs/reference/tools/mcp-client.md

@@ -37,6 +37,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **env** (`Record<string, string>`): For Stdio servers: Environment variables to set for the command.
 
+**inheritDefaultEnv** (`boolean`): For Stdio servers: Whether the subprocess environment starts from the MCP SDK's default inherited environment. The default is a curated whitelist, not the full process environment: on POSIX it inherits HOME, LOGNAME, PATH, SHELL, TERM, and USER; on Windows it inherits APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR\_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, and USERPROFILE. When set to false, only the variables explicitly listed in env are passed to the subprocess. Note that a subprocess without PATH may fail to spawn commands that are not absolute paths. (Default: `true`)
+
 **url** (`URL`): For HTTP servers (Streamable HTTP or SSE): The URL of the server.
 
 **requestInit** (`RequestInit`): For HTTP servers: Request configuration for the fetch API.
@@ -45,6 +47,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **fetch** (`MastraFetchLike`): For HTTP servers: Custom fetch implementation used for all network requests. Receives an optional third requestContext parameter containing request-scoped data (e.g., authentication cookies, bearer tokens) from the incoming request. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers, forward request-scoped credentials to the MCP server, customize request behavior per-request, or intercept and modify requests/responses. When fetch is provided, requestInit, eventSourceInit, and authProvider become optional, as you can handle these concerns within your custom fetch function.
 
+**allowedHosts** (`string[]`): For HTTP servers: Opt-in allowlist of hosts the client may contact on behalf of this server. Each entry is matched against the URL host (hostname plus port when the URL carries a non-default port), for example "api.example.com" or "localhost:8080". Matching is exact and case-insensitive on the hostname; wildcards are not supported and the URL scheme is not checked. An empty array denies all requests. When unset, no restriction is applied. See the Security section below for enforcement details.
+
 **logger** (`LogHandler`): Optional additional handler for logging.
 
 **timeout** (`number`): Server-specific timeout in milliseconds.
@@ -159,6 +163,56 @@ When `forwardInstructions` is omitted (the default), instructions are still cach
 
 > **Security note:** server instructions are forwarded verbatim (subject only to length truncation) into the agent's system prompt. A malicious or compromised MCP server can use them to inject instructions the agent will treat as trusted system guidance. Only enable `forwardInstructions` for servers you trust, and prefer reviewing instructions with `getServerInstructions()` before forwarding instructions from third-party servers.
 
+## Security
+
+### Subprocess environment for Stdio servers
+
+Stdio subprocesses don't inherit the full parent process environment. By default the subprocess environment starts from the MCP SDK's curated whitelist (POSIX: `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, `USER`; Windows: `APPDATA`, `HOMEDRIVE`, `HOMEPATH`, `LOCALAPPDATA`, `PATH`, `PROCESSOR_ARCHITECTURE`, `SYSTEMDRIVE`, `SYSTEMROOT`, `TEMP`, `USERNAME`, `USERPROFILE`), merged with any variables you set in `env`. Sensitive variables such as API keys aren't inherited unless you pass them explicitly.
+
+For stricter isolation, set `inheritDefaultEnv: false` so only your configured `env` entries reach the subprocess:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    myTool: {
+      command: '/usr/local/bin/my-mcp-server',
+      inheritDefaultEnv: false,
+      env: { MY_TOOL_API_KEY: process.env.MY_TOOL_API_KEY! },
+    },
+  },
+})
+```
+
+Variables you place in `env` are forwarded verbatim, so treat server configurations that come from untrusted sources (for example, user-supplied config files) as untrusted input.
+
+### Restricting outbound hosts with `allowedHosts`
+
+When HTTP server URLs come from untrusted configuration, an attacker-controlled URL can point the client at internal services (server-side request forgery). Set `allowedHosts` on such servers to restrict which hosts the client will contact:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    remote: {
+      url: new URL(untrustedConfig.serverUrl),
+      allowedHosts: ['api.example.com'],
+    },
+  },
+})
+```
+
+Enforcement details:
+
+- On the default fetch path, requests to disallowed hosts, including every redirect hop, are blocked **before** they're sent. Redirects are followed manually (up to 5 hops) so each hop is validated, and the `Authorization` header isn't carried across hops to a different origin (any scheme, host, or port change drops it, matching standard fetch behavior).
+- When you supply a custom `fetch` (or a custom `eventSourceInit.fetch`), the initial URL is still checked before the request, but redirect hops are validated **after the fact** using `response.url`: the outbound hop may occur, and the response is discarded when its final URL points at a disallowed host. A hand-built `Response` with an empty `response.url` skips this post-hoc check.
+- OAuth requests made through `authProvider` (authorization server metadata discovery, token exchange, refresh) are also validated. If your authorization server runs on a different host than the MCP server, add that host to `allowedHosts` too.
+- A blocked host fails the connection with a clear error and is never retried by the reconnect logic.
+
+`allowedHosts` is intentionally minimal: it matches exact hosts and doesn't support wildcards or scheme checks. If you need richer policy (scheme checks, IP-range rules), supply a custom `fetch` implementation, which is invoked for every request the client makes.
+
+### Treat tool responses as untrusted input
+
+Tool results returned by MCP servers flow into your agent's context as model input. A malicious or compromised server can use tool output for prompt injection. The transport client doesn't sanitize tool responses: sanitization policy belongs at the agent layer, where Mastra's [input and output processors](https://mastra.ai/docs/agents/processors) let you inspect, transform, or block content before and after it reaches the model. Combine this with `requireToolApproval` and the `forwardInstructions` security note above when working with third-party servers.
+
 ## Methods
 
 ### `listTools()`