@mastra/mcp-docs-server 1.2.19-alpha.0 → 1.2.19-alpha.14

package/.docs/integrations/databases/elasticsearch.md

@@ -0,0 +1,156 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Elasticsearch
+
+The Elasticsearch storage implementation provides agent memory, workflow snapshot, and score storage on top of an Elasticsearch cluster using the official [`@elastic/elasticsearch`](https://github.com/elastic/elasticsearch-js) client. It shares the same connection configuration as `ElasticSearchVector`, so a single cluster (and even a single client instance) can serve both agent memory and semantic recall.
+
+`ElasticSearchStore` currently implements the `memory`, `workflows`, and `scores` storage domains.
+
+## Installation
+
+```bash
+npm install @mastra/elasticsearch
+```
+
+## Usage
+
+### Using a URL
+
+```typescript
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'elasticsearch-storage',
+  url: 'http://localhost:9200',
+})
+
+await storage.init()
+```
+
+### Using authentication
+
+```typescript
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'elasticsearch-storage',
+  url: 'https://my-cluster.example.com:9200',
+  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
+})
+```
+
+`auth` also accepts `{ username, password }` or `{ bearer }`.
+
+### Using a pre-configured client
+
+For advanced configurations (cloud IDs, TLS options, custom transport), pass a pre-configured client. The same client can be shared with `ElasticSearchVector`:
+
+```typescript
+import { Client } from '@elastic/elasticsearch'
+import { ElasticSearchStore, ElasticSearchVector } from '@mastra/elasticsearch'
+
+const client = new Client({
+  node: 'https://my-cluster.example.com:9200',
+  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
+})
+
+const storage = new ElasticSearchStore({ id: 'elasticsearch-storage', client })
+const vector = new ElasticSearchVector({ id: 'elasticsearch-vector', client })
+```
+
+When you provide your own client, `storage.close()` does not close it — you remain responsible for its lifecycle.
+
+## Parameters
+
+**id** (`string`): Unique identifier for the storage instance
+
+**url** (`string`): Elasticsearch node URL (e.g., http\://localhost:9200)
+
+**auth** (`ElasticSearchAuth`): Authentication options: { apiKey }, { username, password }, or { bearer }
+
+**client** (`Client`): Pre-configured Elasticsearch client (from @elastic/elasticsearch) for advanced setups
+
+**disableInit** (`boolean`): Disable automatic initialization; call storage.init() explicitly before use
+
+> **Note:** You must provide either `url` or `client`. These options are mutually exclusive.
+
+## Additional Notes
+
+### Index Structure
+
+Each Mastra storage table maps to one Elasticsearch index of the same name (for example `mastra_threads`, `mastra_messages`, `mastra_workflow_snapshot`, `mastra_scorers`). Records are stored as opaque JSON documents with a keyword `key` field, so no index mappings need to be managed manually — indexes are created on first use.
+
+### Consistency
+
+Elasticsearch search is near-real-time. All writes are performed with an immediate refresh so subsequent reads and searches observe them, and point reads use real-time get-by-ID lookups.
+
+### Closing Connections
+
+When shutting down your application, close the connection:
+
+```typescript
+await storage.close()
+```
+
+This only closes clients created by `ElasticSearchStore` from a `url`; user-provided clients are left open.
+
+## Usage Example
+
+### Adding memory to an agent
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+export const elasticsearchAgent = new Agent({
+  id: 'elasticsearch-agent',
+  name: 'Elasticsearch Agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage: new ElasticSearchStore({
+      id: 'elasticsearch-agent-storage',
+      url: process.env.ELASTICSEARCH_URL!,
+      auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
+    }),
+    options: {
+      lastMessages: 10,
+    },
+  }),
+})
+```
+
+### Using with Mastra instance
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'mastra-storage',
+  url: 'http://localhost:9200',
+})
+
+const mastra = new Mastra({
+  storage, // init() called automatically
+})
+```
+
+If using storage directly without Mastra, call `init()` explicitly:
+
+```typescript
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'elasticsearch-storage',
+  url: 'http://localhost:9200',
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```

package/.docs/integrations/databases/libsql.md

@@ -89,12 +89,28 @@ storage: new LibSQLStore({
 
 > **Warning:** In-memory storage resets when the process changes. Only suitable for development.
 
+Embedded replica synced with a remote primary (for example Turso):
+
+```typescript
+storage: new LibSQLStore({
+  id: 'libsql-storage',
+  url: 'file:./replica.db',
+  syncUrl: 'libsql://your-db-name.aws-ap-northeast-1.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+  syncInterval: 60,
+})
+```
+
 ## Options
 
 **url** (`string`): Database URL. Use :memory: for in-memory database, file:filename.db for a file database, or a libSQL connection string (e.g., libsql://your-database.turso.io) for remote storage.
 
 **authToken** (`string`): Authentication token for remote libSQL databases.
 
+**syncUrl** (`string`): URL of the remote primary database to sync from, enabling an embedded replica. Requires a local file: url.
+
+**syncInterval** (`number`): Interval in seconds for automatic sync with the remote primary. Only applies when syncUrl is set.
+
 ## Managed tables
 
 The storage implementation creates the core storage tables automatically, including `mastra_notifications` for notification inbox records and delivery metadata.

package/.docs/integrations/databases/mongodb.md

@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
 
 ## Usage
 
-Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with MongoDB Search enabled. MongoDB 7.0+ is recommended.
 
 ```typescript
 import { MongoDBStore } from '@mastra/mongodb'

package/.docs/integrations/databases/postgresql.md

@@ -146,6 +146,32 @@ PostgreSQL supports observability and can handle low trace volumes. Throughput c
 - Setting up table partitioning for efficient data retention
 - Migrating observability to [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite) if you need to scale further
 
+`PostgresStoreVNext` uses the `event-sourced` [tracing strategy](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) instead. It writes one row when a span starts and another when it ends, never updating a row in place, and collapses those rows when a trace is read. Writes stay append-only, and traces appear in Studio while the run is still executing.
+
+#### Filter suggestions
+
+Studio's Traces, Logs, and Metrics pages offer filter values (tags, service names, environments, entity names, metric names and labels) discovered from your observability data. Those values are cached in the database and recomputed in the background when the cache goes stale.
+
+To keep the refresh cheap on large datasets, it only scans events from the last 30 days. Values that appear exclusively in older events won't be suggested, though filtering by them still works. Use `discovery` to change the window or how often it refreshes:
+
+```typescript
+import { PostgresStoreVNext } from '@mastra/pg'
+
+const storage = new PostgresStoreVNext({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+  observability: {
+    connectionString: process.env.OBSERVABILITY_DATABASE_URL,
+    discovery: {
+      lookbackSeconds: 7 * 24 * 60 * 60, // scan the last 7 days; 0 scans all history
+      ttlSeconds: 15 * 60, // refresh at most every 15 minutes
+    },
+  },
+})
+```
+
+Lower `lookbackSeconds` if refreshes are slow, and raise `ttlSeconds` if they run more often than your filter values change. Only one process refreshes a given cache entry at a time, so adding server instances doesn't multiply the work.
+
 ### Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:

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

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Valkey
+
+The Valkey storage implementation provides persistent storage and server-side caching through the [Valkey GLIDE](https://github.com/valkey-io/valkey-glide) client. Use it when your deployment runs Valkey or needs GLIDE features such as native Valkey configuration and authentication.
+
+Use [`@mastra/redis`](https://mastra.ai/integrations/databases/redis) for Redis deployments that use the official `redis` client. The packages are tested independently against their respective servers.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/valkey
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/valkey
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/valkey
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/valkey
+```
+
+## Usage
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ValkeyStore } from '@mastra/valkey'
+
+export const mastra = new Mastra({
+  storage: new ValkeyStore({
+    id: 'valkey-storage',
+    host: 'localhost',
+    port: 6379,
+    password: process.env.VALKEY_PASSWORD,
+  }),
+})
+```
+
+You can also provide a native GLIDE configuration:
+
+```typescript
+import { ValkeyStore } from '@mastra/valkey'
+
+const storage = new ValkeyStore({
+  id: 'valkey-storage',
+  config: {
+    addresses: [{ host: 'localhost', port: 6379 }],
+    useTLS: true,
+  },
+})
+```
+
+For an existing `GlideClient`, connect it before passing it to `ValkeyStore`. The caller remains responsible for closing injected clients.
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the storage instance.
+
+**host** (`string`): Valkey host address. Use with the direct connection fields.
+
+**port** (`number`): Valkey port. (Default: `6379`)
+
+**username** (`string`): Valkey authentication username. (Default: `default`)
+
+**password** (`string`): Valkey authentication password.
+
+**db** (`number`): Valkey database number. (Default: `0`)
+
+**useTLS** (`boolean`): Enables TLS for direct connections.
+
+**config** (`GlideClientConfiguration`): Native GLIDE standalone client configuration.
+
+**client** (`GlideClient`): Preconfigured GLIDE standalone client.
+
+**disableInit** (`boolean`): Disables automatic storage initialization.
+
+Provide exactly one connection form: `client`, `config`, or `host` with its optional direct connection fields.
+
+## Closing connections
+
+Close clients created by `ValkeyStore` during graceful shutdown:
+
+```typescript
+await storage.close()
+```
+
+`close()` doesn't close an injected `GlideClient`.

package/.docs/integrations/deploy/render.md

@@ -12,7 +12,7 @@ Choose the deployment path that fits your application:
 
 This guide builds an editorial pipeline that reviews a draft from three perspectives in parallel, then passes the feedback to an editor agent. Use the links above if you want to deploy a Mastra API or execute an entire Mastra workflow as one task.
 
-## How Render Workflows works with Mastra
+## How Render Workflows integrate with Mastra
 
 Mastra supplies the agents and application logic, while Render Workflows defines the execution boundaries. A typical pipeline has three layers:
 
@@ -93,8 +93,6 @@ yarn add @renderinc/sdk tsx
 bun add @renderinc/sdk tsx
 ```
 
-> **Note:** Render Workflows requires `@renderinc/sdk@^0.5.0` or later.
-
 Set the API key for your model provider. This example uses OpenAI:
 
 ```text
@@ -103,9 +101,9 @@ OPENAI_API_KEY=your_openai_api_key
 
 Any supported [Mastra model provider](https://mastra.ai/models) works.
 
-## Building a distributed agent pipeline
+## Build a distributed agent pipeline
 
-### Creating the agents
+### Create the agents
 
 In `src/mastra`, create an `agents` directory with `reviewer-agent.ts` and `editor-agent.ts`. Define both agents:
 
@@ -139,7 +137,7 @@ export const editorAgent = new Agent({
 })
 ```
 
-### Configuring the Mastra instance
+### Configure the Mastra instance
 
 Add both agents to the Mastra instance in `src/mastra/index.ts`:
 
@@ -158,7 +156,7 @@ export const mastra = new Mastra({
 
 Retrieving agents from the Mastra instance gives them access to shared application services such as logging, storage, and observability.
 
-### Creating the review task
+### Create the review task
 
 In `src`, create a `tasks` directory. The reviewer agent handles one area of focus. Its compute plan, five-minute timeout, and retry policy apply only to that analysis. A temporary model-provider failure can trigger another attempt without restarting the other reviewers.
 
@@ -199,7 +197,7 @@ export const reviewDraft = task(
 )
 ```
 
-### Creating the revision task
+### Create the revision task
 
 This task combines the feedback and produces a revised draft. It uses a larger compute plan and a longer timeout than each reviewer.
 
@@ -240,7 +238,7 @@ export const reviseDraft = task(
 )
 ```
 
-### Creating the orchestration task
+### Create the orchestration task
 
 The parent dispatches three reviews in parallel with `Promise.all()`, then sends their combined feedback to the revision step. Retries are disabled at this level because each child defines its own policy. If you enable orchestration retries, ensure that another attempt cannot duplicate external side effects or other non-idempotent work.
 
@@ -268,7 +266,7 @@ export const editorialPipeline = task(
 )
 ```
 
-### Registering the tasks
+### Register the tasks
 
 Create `src/index.ts` and import the editorial task:
 
@@ -278,7 +276,7 @@ import './tasks/editorial-task.js'
 
 Running the entry point loads the module and registers every task defined with `task()`.
 
-`create mastra` already wrote `tsconfig.json` and `package.json`. Keep those files. For the workflow start command, `tsc` must emit JavaScript into `dist`, so set these compiler options (do not leave `noEmit: true`):
+Change your `tsconfig.json`:
 
 ```json
 {
@@ -292,7 +290,7 @@ Running the entry point loads the module and registers every task defined with `
 }
 ```
 
-Add these scripts next to the ones `create mastra` already added. `create mastra` already sets `"type": "module"`:
+Add these scripts to `package.json`:
 
 ```json
 {
@@ -304,13 +302,11 @@ Add these scripts next to the ones `create mastra` already added. `create mastra
 }
 ```
 
-Relative imports in the examples above end in `.js` because Node resolves the compiled output as ES modules. Keep those extensions so the built entry point resolves its imports.
-
-Those files are the complete pipeline. [render-examples/render-workflows-mastra](https://github.com/render-examples/render-workflows-mastra) mirrors this `src/` layout and adds a web UI that starts the parent task. Its agents use the provider-specific model ID `openai/gpt-5.6-sol`. In this page's source, that value is represented by a documentation token that is replaced during the docs build. Clone it to skip copying the snippets before you run it.
+Those files are the complete pipeline. [render-examples/render-workflows-mastra](https://github.com/render-examples/render-workflows-mastra) mirrors this `src/` layout and adds a web UI that starts the parent task.
 
-## Running the pipeline
+## Run the pipeline
 
-### Running locally
+### Local
 
 Start the local Render Workflows development server:
 
@@ -334,56 +330,56 @@ render workflows tasks start editorial_pipeline \
 
 The local server keeps runs and their logs in memory, so you can inspect them after they finish with `render workflows runs list <task-name> --local`.
 
-### Running in production
+### Production
 
 Running the pipeline on Render requires a _workflow service_. This is the Render service that holds your task definitions: it builds your repository, registers every task it finds, and provisions an instance for each run.
 
-#### 1. Push the project to a Git repository
+1. #### Push the project to a Git repository
 
-Render builds workflow services from a repository on GitHub, GitLab, or Bitbucket, so push your project to one of those providers. The first time you use a provider, Render asks for permission to access your repositories.
+   Render builds workflow services from a repository on GitHub, GitLab, or Bitbucket, so push your project to one of those providers. The first time you use a provider, Render asks for permission to access your repositories.
 
-#### 2. Create the workflow service
+2. #### Create the workflow service
 
-In the [Render Dashboard](https://dashboard.render.com), click **New > Workflow** and link the repository from the previous step. Then complete the creation form:
+   In the [Render Dashboard](https://dashboard.render.com), click **New > Workflow** and link the repository from the previous step. Then complete the creation form:
 
-| Field             | Value                                                         |
-| ----------------- | ------------------------------------------------------------- |
-| **Language**      | Node                                                          |
-| **Region**        | The region of any other Render services your tasks connect to |
-| **Build Command** | `npm install && npm run build`                                |
-| **Start Command** | `npm run start:workflows`                                     |
+   | Field             | Value                                                         |
+   | ----------------- | ------------------------------------------------------------- |
+   | **Language**      | Node                                                          |
+   | **Region**        | The region of any other Render services your tasks connect to |
+   | **Build Command** | `npm install && npm run build`                                |
+   | **Start Command** | `npm run start:workflows`                                     |
 
-Click **Deploy Workflow**. Render builds the project and registers `review_draft`, `revise_draft`, and `editorial_pipeline`, which then appear on the workflow's **Tasks** page.
+   Click **Deploy Workflow**. Render builds the project and registers `review_draft`, `revise_draft`, and `editorial_pipeline`, which then appear on the workflow's **Tasks** page.
 
-The Render CLI creates the same service without leaving your terminal:
+   The Render CLI creates the same service without leaving your terminal:
 
-```bash
-render workflows create \
-  --name mastra-workflows \
-  --repo . \
-  --runtime node \
-  --build-command "npm install && npm run build" \
-  --run-command "npm run start:workflows"
-```
+   ```bash
+   render workflows create \
+     --name mastra-workflows \
+     --repo . \
+     --runtime node \
+     --build-command "npm install && npm run build" \
+     --run-command "npm run start:workflows"
+   ```
 
-`--repo .` reads the `origin` remote of your local repository, so the project must already be pushed.
+   `--repo .` reads the `origin` remote of your local repository, so the project must already be pushed.
 
-#### 3. Set the workflow's environment variables
+3. #### Set the workflow's environment variables
 
-Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the workflow service in the Dashboard before the first run.
+   Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the workflow service in the Dashboard before the first run.
 
-#### 4. Start a run
+4. #### Start a run
 
-```bash
-render workflows tasks start mastra-workflows/editorial_pipeline \
-  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
-```
+   ```bash
+   render workflows tasks start mastra-workflows/editorial_pipeline \
+     --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+   ```
 
-The first part of that identifier is your workflow's slug and the second is the task name. Both appear on the task's page in the Render Dashboard, so use the slug shown there if your workflow has a different name.
+   The first part of that identifier is your workflow's slug and the second is the task name. Both appear on the task's page in the Render Dashboard, so use the slug shown there if your workflow has a different name.
 
-Open the workflow in the Render Dashboard to inspect each task run, attempt, result, and log stream.
+   Open the workflow in the Render Dashboard to inspect each task run, attempt, result, and log stream.
 
-## Triggering from your application
+## Trigger from your application
 
 You can trigger the pipeline asynchronously from a Mastra application, web service, or script with the Render SDK.
 
@@ -415,17 +411,6 @@ The task continues running after `startTask()` returns. Call `await run.get()` w
 
 Returning the task run ID from a request handler lets the application respond without keeping the request open for the full pipeline.
 
-## Constraints
-
-These limits live in Render's docs and can change. Prefer those pages over this list:
-
-- Task arguments and return values must be JSON serializable. Arguments to a single run cannot exceed 4 MB. See [defining tasks](https://render.com/docs/workflows-defining#task-arguments) and [Workflows limits](https://render.com/docs/workflows-limits).
-- A task can run for up to 24 hours. The default timeout is two hours. See [timeouts](https://render.com/docs/workflows-defining#timeout).
-- A workflow service can register up to 500 task definitions. See [Workflows limits](https://render.com/docs/workflows-limits).
-- Render Workflows currently supports TypeScript and Python task definitions. See [defining tasks](https://render.com/docs/workflows-defining).
-
-To run the pipeline on a schedule, create a [Render cron job](https://render.com/docs/cronjobs) whose command calls `render workflows tasks start` or `startTask()`.
-
 ## Related
 
 - [Live demo](https://render-workflows-mastra.onrender.com)
@@ -433,4 +418,5 @@ To run the pipeline on a schedule, create a [Render cron job](https://render.com
 - [Defining Render workflow tasks](https://render.com/docs/workflows-defining)
 - [Triggering task runs](https://render.com/docs/workflows-running)
 - [Render Workflows TypeScript SDK](https://render.com/docs/workflows-sdk-typescript)
-- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)
+- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)
+- [Render cron jobs](https://render.com/docs/cronjobs)

package/.docs/integrations/sandboxes/e2b.md

@@ -60,6 +60,8 @@ const agent = new Agent({
 
 **timeout** (`number`): Execution timeout in milliseconds (Default: `300000 (5 minutes)`)
 
+**lifecycle** (`SandboxLifecycle`): Controls what happens when the sandbox timeout is reached. Defaults to pausing the sandbox so the next start resumes it. Pass { onTimeout: 'kill' } to destroy idle sandboxes instead, which suits stateless workspaces whose data is persisted outside the sandbox. An explicit stop() always pauses, regardless of this setting. (Default: `{ onTimeout: 'pause' }`)
+
 **template** (`string | TemplateBuilder | function`): Sandbox template specification. Can be a template ID string, a TemplateBuilder, or a function that customizes the default template.
 
 **env** (`Record<string, string>`): Environment variables to set in the sandbox