@mastra/mcp-docs-server 1.1.31-alpha.1 → 1.1.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/.docs/reference/index.md +1 -0
  2. package/.docs/reference/observability/metrics/automatic-metrics.md +2 -2
  3. package/.docs/reference/storage/clickhouse.md +24 -18
  4. package/.docs/reference/storage/duckdb.md +150 -0
  5. package/CHANGELOG.md +14 -0
  6. package/package.json +5 -5
package/.docs/reference/index.md CHANGED
@@ -199,6 +199,7 @@ The Reference section provides documentation of Mastra's API, including paramete
199
199
  - [Cloudflare KV Storage](https://mastra.ai/reference/storage/cloudflare)
200
200
  - [Composite Storage](https://mastra.ai/reference/storage/composite)
201
201
  - [Convex Storage](https://mastra.ai/reference/storage/convex)
202
+ - [DuckDB Storage](https://mastra.ai/reference/storage/duckdb)
202
203
  - [DynamoDB Storage](https://mastra.ai/reference/storage/dynamodb)
203
204
  - [LanceDB Storage](https://mastra.ai/reference/storage/lance)
204
205
  - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
package/.docs/reference/observability/metrics/automatic-metrics.md CHANGED
@@ -15,7 +15,7 @@ Metrics are routed through an internal event bus to the `DefaultExporter`, which
15
15
  Two conditions must be true for a metric to reach storage:
16
16
 
17
17
  1. `DefaultExporter` is configured as an exporter.
18
- 2. The storage backend supports metrics (ClickHouse, DuckDB, or in-memory).
18
+ 2. The storage backend supports metrics (ClickHouse or DuckDB).
19
19
 
20
20
  If metrics aren't appearing, see [troubleshooting](#troubleshooting).
21
21
 
@@ -118,7 +118,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
118
118
 
119
119
  - **Observability is configured**: Verify that your `Mastra` instance has an `observability` config with at least one exporter.
120
120
  - **`DefaultExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't persist metrics to Mastra storage. `DefaultExporter` is required for the Studio dashboard.
121
- - **Storage supports metrics**: Metrics require a separate OLAP store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
121
+ - **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) are not supported for metrics.
122
122
  - **Sampling isn't 0%**: If sampling probability is `0` or strategy is `never`, all spans become no-ops and no metrics are extracted.
123
123
 
124
124
  ### Duration metrics are missing
package/.docs/reference/storage/clickhouse.md CHANGED
@@ -2,15 +2,13 @@
2
2
 
3
3
  [ClickHouse](https://clickhouse.com/) is a columnar database designed for analytical workloads. The `@mastra/clickhouse` package provides storage adapters for several Mastra storage domains and is the recommended backend for production observability.
4
4
 
5
- ClickHouse is most commonly used as the dedicated observability backend in a [composite storage](https://mastra.ai/reference/storage/composite) setup, with another database serving the remaining domains. It can also back the supported domains on its own through `ClickhouseStore`.
5
+ ClickHouse is most commonly used as the dedicated observability backend in a [composite storage](https://mastra.ai/reference/storage/composite) setup, with another database serving the remaining domains.
6
6
 
7
7
  ## When to use ClickHouse
8
8
 
9
- - Production observability for traces, logs, metrics, scores, and feedback.
10
- - Append-heavy workloads where columnar storage and compression help keep costs down.
11
- - Deployment platforms with ephemeral filesystems (such as [Railway](#deploying-with-railway-and-similar-platforms), Fly.io, Render, Heroku, or container schedulers) where embedded backends like DuckDB cannot persist data.
9
+ Production observability for traces, logs, metrics, scores, and feedback.
12
10
 
13
- For local development, [LibSQL](https://mastra.ai/reference/storage/libsql) or `@mastra/duckdb` are usually a better fit because they need no external service.
11
+ For local development, use a composite store that combines [LibSQL](https://mastra.ai/reference/storage/libsql) (for memory and workflows) and `@mastra/duckdb` (for observability). Neither alone covers a development setup: LibSQL does not implement the observability domain, and DuckDB does not implement the other domains. See the [observability overview](https://mastra.ai/docs/observability/overview) for an example.
14
12
 
15
13
  ## Installation
16
14
 
@@ -51,7 +49,7 @@ Compose it with another storage adapter so observability writes do not contend w
51
49
  ```typescript
52
50
  import { Mastra } from '@mastra/core'
53
51
  import { MastraCompositeStore } from '@mastra/core/storage'
54
- import { LibSQLStore } from '@mastra/libsql'
52
+ import { PostgresStore } from '@mastra/pg'
55
53
  import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
56
54
  import { Observability, DefaultExporter } from '@mastra/observability'
57
55
 
@@ -64,9 +62,9 @@ const observabilityStore = new ObservabilityStorageClickhouseVNext({
64
62
  export const mastra = new Mastra({
65
63
  storage: new MastraCompositeStore({
66
64
  id: 'composite-storage',
67
- default: new LibSQLStore({
68
- id: 'mastra-storage',
69
- url: 'file:./mastra.db',
65
+ default: new PostgresStore({
66
+ id: 'pg',
67
+ connectionString: process.env.DATABASE_URL!,
70
68
  }),
71
69
  domains: {
72
70
  observability: observabilityStore,
@@ -101,20 +99,28 @@ const observabilityStore = new ObservabilityStorageClickhouse({
101
99
 
102
100
  New projects should use `ObservabilityStorageClickhouseVNext` instead.
103
101
 
104
- ### Full storage with `ClickhouseStore`
102
+ ### ClickHouse for every domain
105
103
 
106
- `ClickhouseStore` implements the `memory`, `workflows`, `scores`, and `observability` domains. Use it when you want a single backend for the supported domains. For most observability deployments, the composite setup above is preferable because it isolates observability writes from primary application data.
104
+ `ClickhouseStore` implements the `memory`, `workflows`, and `observability` domains, and is suitable when you want ClickHouse to back the entire application. Its built-in observability domain uses the legacy adapter, so wrap it in a composite store that overrides the `observability` domain with `ObservabilityStorageClickhouseVNext`:
107
105
 
108
106
  ```typescript
109
107
  import { Mastra } from '@mastra/core'
110
- import { ClickhouseStore } from '@mastra/clickhouse'
108
+ import { MastraCompositeStore } from '@mastra/core/storage'
109
+ import { ClickhouseStore, ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
110
+
111
+ const credentials = {
112
+ url: process.env.CLICKHOUSE_URL!,
113
+ username: process.env.CLICKHOUSE_USERNAME!,
114
+ password: process.env.CLICKHOUSE_PASSWORD!,
115
+ }
111
116
 
112
117
  export const mastra = new Mastra({
113
- storage: new ClickhouseStore({
114
- id: 'clickhouse-storage',
115
- url: process.env.CLICKHOUSE_URL!,
116
- username: process.env.CLICKHOUSE_USERNAME!,
117
- password: process.env.CLICKHOUSE_PASSWORD!,
118
+ storage: new MastraCompositeStore({
119
+ id: 'composite-storage',
120
+ default: new ClickhouseStore({ id: 'clickhouse-storage', ...credentials }),
121
+ domains: {
122
+ observability: new ObservabilityStorageClickhouseVNext(credentials),
123
+ },
118
124
  }),
119
125
  })
120
126
  ```
@@ -150,7 +156,7 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
150
156
 
151
157
  **username** (`string`): ClickHouse username. Required when not passing a pre-configured \`client\`.
152
158
 
153
- **password** (`string`): ClickHouse password. Required when not passing a pre-configured \`client\`. Can be an empty string for the default user on a local instance.
159
+ **password** (`string`): ClickHouse password. Required when not passing a pre-configured \`client\`. It can be an empty string for the default user on a local instance.
154
160
 
155
161
  **client** (`ClickHouseClient`): Pre-configured ClickHouse client from \`@clickhouse/client\`. Use this when you need custom request settings. Mutually exclusive with the credential fields above.
156
162
 
package/.docs/reference/storage/duckdb.md ADDED
@@ -0,0 +1,150 @@
1
+ # DuckDB storage
2
+
3
+ [DuckDB](https://duckdb.org/) is an embedded, in-process analytical database. The `@mastra/duckdb` package provides an OLAP-backed observability store for local development, suitable for traces, logs, metrics, scores, and feedback without running an external service.
4
+
5
+ For vector search, see the [DuckDB vector store reference](https://mastra.ai/reference/vectors/duckdb), which is a separate API in the same package.
6
+
7
+ ## When to use DuckDB
8
+
9
+ Local development of observability features. DuckDB is embedded and file-based, so it does not require a server and starts instantly. It supports the same observability signals as ClickHouse, which makes it useful for testing dashboards and trace exploration before deploying to a production backend.
10
+
11
+ DuckDB currently implements only the `observability` domain. Pair it with another storage adapter (such as [LibSQL](https://mastra.ai/reference/storage/libsql)) for `memory` and `workflows` in a [composite storage](https://mastra.ai/reference/storage/composite) setup.
12
+
13
+ > **Warning:** DuckDB is for development and not recommended for production. It runs in-process, persists to a single local file, and does not work on platforms with ephemeral filesystems (such as Railway, Fly.io, Render, Heroku, or serverless containers). For production observability, use [ClickHouse](https://mastra.ai/reference/storage/clickhouse).
14
+
15
+ ## Installation
16
+
17
+ **npm**:
18
+
19
+ ```bash
20
+ npm install @mastra/duckdb@latest
21
+ ```
22
+
23
+ **pnpm**:
24
+
25
+ ```bash
26
+ pnpm add @mastra/duckdb@latest
27
+ ```
28
+
29
+ **Yarn**:
30
+
31
+ ```bash
32
+ yarn add @mastra/duckdb@latest
33
+ ```
34
+
35
+ **Bun**:
36
+
37
+ ```bash
38
+ bun add @mastra/duckdb@latest
39
+ ```
40
+
41
+ ## Usage
42
+
43
+ ### As the observability domain in a composite store
44
+
45
+ This is the standard local-development setup. LibSQL handles the other domains, and DuckDB handles observability.
46
+
47
+ ```typescript
48
+ import { Mastra } from '@mastra/core'
49
+ import { MastraCompositeStore } from '@mastra/core/storage'
50
+ import { LibSQLStore } from '@mastra/libsql'
51
+ import { DuckDBStore } from '@mastra/duckdb'
52
+ import { Observability, DefaultExporter } from '@mastra/observability'
53
+
54
+ export const mastra = new Mastra({
55
+ storage: new MastraCompositeStore({
56
+ id: 'composite-storage',
57
+ default: new LibSQLStore({
58
+ id: 'mastra-storage',
59
+ url: 'file:./mastra.db',
60
+ }),
61
+ domains: {
62
+ observability: new DuckDBStore().observability,
63
+ },
64
+ }),
65
+ observability: new Observability({
66
+ configs: {
67
+ default: {
68
+ serviceName: 'mastra',
69
+ exporters: [new DefaultExporter()],
70
+ },
71
+ },
72
+ }),
73
+ })
74
+ ```
75
+
76
+ The `.observability` accessor returns the observability domain store directly. The equivalent generic form uses `getStore()`, which works for any composite-style storage adapter:
77
+
78
+ ```typescript
79
+ const observability = await new DuckDBStore().getStore('observability')
80
+ ```
81
+
82
+ ### Standalone
83
+
84
+ When you need only observability storage outside the `Mastra` composite, instantiate `DuckDBStore` directly and access the observability domain:
85
+
86
+ ```typescript
87
+ import { DuckDBStore } from '@mastra/duckdb'
88
+
89
+ const duckdb = new DuckDBStore({ path: './traces.duckdb' })
90
+ const observability = duckdb.observability
91
+
92
+ await observability.init()
93
+ ```
94
+
95
+ ### In-memory database
96
+
97
+ Pass `:memory:` to use an ephemeral DuckDB instance. Data is lost when the process exits, which is appropriate for unit tests and short-lived scripts.
98
+
99
+ ```typescript
100
+ const duckdb = new DuckDBStore({ path: ':memory:' })
101
+ ```
102
+
103
+ ## Configuration
104
+
105
+ ### `DuckDBStore` options
106
+
107
+ **id** (`string`): Unique identifier for this storage instance. (Default: `'duckdb'`)
108
+
109
+ **path** (`string`): Path to the DuckDB database file. Use \`:memory:\` for an ephemeral in-memory database. (Default: `'mastra.duckdb'`)
110
+
111
+ ### Lower-level types
112
+
113
+ `@mastra/duckdb` also exports `DuckDBConnection` for sharing a single underlying database across multiple Mastra storage instances, and the corresponding `DuckDBStorageConfig` type. Most applications will not need these directly.
114
+
115
+ ## Supported domains
116
+
117
+ DuckDB currently implements one storage domain:
118
+
119
+ | Domain | Supported |
120
+ | --------------- | --------- |
121
+ | `observability` | Yes |
122
+ | `memory` | No |
123
+ | `workflows` | No |
124
+ | `scores` | No |
125
+ | `agents` | No |
126
+
127
+ For a full storage solution, compose `DuckDBStore` with an adapter that covers the missing domains (most commonly [LibSQL](https://mastra.ai/reference/storage/libsql) for local development).
128
+
129
+ ## Initialization
130
+
131
+ When passed to `Mastra` through `MastraCompositeStore`, the observability domain initializes itself on first use. To run initialization explicitly outside of `Mastra`, call `init()` on the observability store:
132
+
133
+ ```typescript
134
+ import { DuckDBStore } from '@mastra/duckdb'
135
+
136
+ const duckdb = new DuckDBStore({ path: './traces.duckdb' })
137
+ await duckdb.observability.init()
138
+ ```
139
+
140
+ ## Observability strategy
141
+
142
+ DuckDB supports the `event-sourced` strategy used by `DefaultExporter`, which buffers spans in memory and writes completed events in batches. This is appropriate for development-scale traffic. For high-volume production workloads, see [`DefaultExporter` storage provider support](https://mastra.ai/docs/observability/tracing/exporters/default).
143
+
144
+ ## Related
145
+
146
+ - [Storage overview](https://mastra.ai/reference/storage/overview)
147
+ - [Composite storage](https://mastra.ai/reference/storage/composite)
148
+ - [ClickHouse storage](https://mastra.ai/reference/storage/clickhouse): Production observability backend
149
+ - [DuckDB vector store](https://mastra.ai/reference/vectors/duckdb): Vector search using the same package
150
+ - [Observability overview](https://mastra.ai/docs/observability/overview)
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.1.31
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`920c757`](https://github.com/mastra-ai/mastra/commit/920c75799c6bd71787d86deaf654a35af4c839ca), [`d587199`](https://github.com/mastra-ai/mastra/commit/d5871993c0371bde2b0717d6b47194755baa1443), [`1fe2533`](https://github.com/mastra-ai/mastra/commit/1fe2533c4382ca6858aac7c4b63e888c2eac6541), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
8
+ - @mastra/core@1.30.0
9
+
10
+ ## 1.1.31-alpha.2
11
+
12
+ ### Patch Changes
13
+
14
+ - Updated dependencies [[`920c757`](https://github.com/mastra-ai/mastra/commit/920c75799c6bd71787d86deaf654a35af4c839ca), [`1fe2533`](https://github.com/mastra-ai/mastra/commit/1fe2533c4382ca6858aac7c4b63e888c2eac6541), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
15
+ - @mastra/core@1.30.0-alpha.1
16
+
3
17
  ## 1.1.31-alpha.0
4
18
 
5
19
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.1.31-alpha.1",
3
+ "version": "1.1.31",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -29,7 +29,7 @@
29
29
  "jsdom": "^26.1.0",
30
30
  "local-pkg": "^1.1.2",
31
31
  "zod": "^4.3.6",
32
- "@mastra/core": "1.29.2-alpha.0",
32
+ "@mastra/core": "1.30.0",
33
33
  "@mastra/mcp": "^1.6.0"
34
34
  },
35
35
  "devDependencies": {
@@ -46,9 +46,9 @@
46
46
  "tsx": "^4.21.0",
47
47
  "typescript": "^6.0.3",
48
48
  "vitest": "4.1.5",
49
- "@internal/types-builder": "0.0.63",
50
- "@mastra/core": "1.29.2-alpha.0",
51
- "@internal/lint": "0.0.88"
49
+ "@internal/lint": "0.0.89",
50
+ "@internal/types-builder": "0.0.64",
51
+ "@mastra/core": "1.30.0"
52
52
  },
53
53
  "homepage": "https://mastra.ai",
54
54
  "repository": {