db-mcp 3.0.2 → 4.0.0
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.
- package/README.md +89 -57
- package/dist/.tsbuildinfo +1 -1
- package/dist/adapters/database-adapter.d.ts +2 -1
- package/dist/adapters/database-adapter.d.ts.map +1 -1
- package/dist/adapters/registration/resources.d.ts.map +1 -1
- package/dist/adapters/registration/tools.d.ts.map +1 -1
- package/dist/adapters/sqlite/prompts/analysis.d.ts.map +1 -1
- package/dist/adapters/sqlite/resources.d.ts +1 -1
- package/dist/adapters/sqlite/resources.d.ts.map +1 -1
- package/dist/adapters/sqlite/schemas/admin.d.ts +29 -15
- package/dist/adapters/sqlite/schemas/admin.d.ts.map +1 -1
- package/dist/adapters/sqlite/schemas/core.d.ts +2 -0
- package/dist/adapters/sqlite/schemas/core.d.ts.map +1 -1
- package/dist/adapters/sqlite/schemas/fts.d.ts +4 -0
- package/dist/adapters/sqlite/schemas/fts.d.ts.map +1 -1
- package/dist/adapters/sqlite/schemas/introspection.d.ts +20 -11
- package/dist/adapters/sqlite/schemas/introspection.d.ts.map +1 -1
- package/dist/adapters/sqlite/schemas/spatialite.d.ts +1 -0
- package/dist/adapters/sqlite/schemas/spatialite.d.ts.map +1 -1
- package/dist/adapters/sqlite/schemas/text.d.ts +36 -0
- package/dist/adapters/sqlite/schemas/text.d.ts.map +1 -1
- package/dist/adapters/sqlite/sqlite-adapter.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/admin/index.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/admin/pragma.d.ts +0 -4
- package/dist/adapters/sqlite/tools/admin/pragma.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/core/queries.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/core/tables.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/fts.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/introspection/diagnostics/indexes.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/json-helpers/read.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/json-operations/crud.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/json-operations/query.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/text/helpers.d.ts +9 -0
- package/dist/adapters/sqlite/tools/text/helpers.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/text/index.d.ts.map +1 -1
- package/dist/adapters/sqlite/tools/text/search.d.ts +4 -0
- package/dist/adapters/sqlite/tools/text/search.d.ts.map +1 -1
- package/dist/adapters/sqlite/types.d.ts +4 -0
- package/dist/adapters/sqlite/types.d.ts.map +1 -1
- package/dist/adapters/sqlite-native/native-sqlite-adapter.d.ts.map +1 -1
- package/dist/adapters/sqlite-native/tools/spatialite/tools.d.ts.map +1 -1
- package/dist/audit/interceptor.d.ts.map +1 -1
- package/dist/audit/logger.d.ts +26 -25
- package/dist/audit/logger.d.ts.map +1 -1
- package/dist/{chunk-W5WQVNVX.js → chunk-EQF3WZHX.js} +10 -17
- package/dist/{chunk-37G4DLL6.js → chunk-NIC5Z2CA.js} +732 -138
- package/dist/chunk-R5M4WKDM.js +987 -0
- package/dist/{chunk-NV34JSQM.js → chunk-TGE7LFAR.js} +708 -996
- package/dist/{chunk-L552U3QS.js → chunk-Y57WFKAP.js} +227 -9
- package/dist/cli.js +103 -10
- package/dist/codemode/sandbox.d.ts.map +1 -1
- package/dist/constants/server-instructions.d.ts +1 -1
- package/dist/constants/server-instructions.d.ts.map +1 -1
- package/dist/filtering/tool-constants.d.ts +9 -9
- package/dist/{http-HWTUVFIA.js → http-2WGR3E5K.js} +13 -1
- package/dist/index.js +4 -4
- package/dist/observability/metrics.d.ts +36 -0
- package/dist/observability/metrics.d.ts.map +1 -0
- package/dist/observability/system-db.d.ts +13 -0
- package/dist/observability/system-db.d.ts.map +1 -0
- package/dist/server/mcp-server.d.ts +3 -0
- package/dist/server/mcp-server.d.ts.map +1 -1
- package/dist/server/registration/admin-tools.d.ts +6 -0
- package/dist/server/registration/admin-tools.d.ts.map +1 -0
- package/dist/server/registration/audit-tools.d.ts +4 -0
- package/dist/server/registration/audit-tools.d.ts.map +1 -1
- package/dist/server/registration/help-resources.d.ts.map +1 -1
- package/dist/server/registration/index.d.ts +3 -1
- package/dist/server/registration/index.d.ts.map +1 -1
- package/dist/server/registration/observability-resources.d.ts +11 -0
- package/dist/server/registration/observability-resources.d.ts.map +1 -0
- package/dist/server/subscription-manager.d.ts +35 -0
- package/dist/server/subscription-manager.d.ts.map +1 -0
- package/dist/{sqlite-TB56Z7G3.js → sqlite-D4WCNPU4.js} +8 -5
- package/dist/{sqlite-native-IF75BB3O.js → sqlite-native-DLVS2T52.js} +159 -34
- package/dist/transports/http/sessions/legacy-sse.d.ts.map +1 -1
- package/dist/transports/http/sessions/stateful.d.ts.map +1 -1
- package/dist/transports/http/transport.d.ts.map +1 -1
- package/dist/transports/http/types.d.ts +2 -0
- package/dist/transports/http/types.d.ts.map +1 -1
- package/dist/types/server.d.ts +2 -0
- package/dist/types/server.d.ts.map +1 -1
- package/dist/utils/index.d.ts +1 -0
- package/dist/utils/index.d.ts.map +1 -1
- package/dist/utils/logger/types.d.ts +1 -1
- package/dist/utils/logger/types.d.ts.map +1 -1
- package/dist/utils/tokens.d.ts +15 -0
- package/dist/utils/tokens.d.ts.map +1 -0
- package/package.json +9 -7
- package/dist/chunk-E5IESRTK.js +0 -489
- package/dist/utils/insights-manager.d.ts +0 -39
- package/dist/utils/insights-manager.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- mcp-name: io.github.neverinfamous/db-mcp -->
|
|
4
4
|
|
|
5
|
-
**SQLite MCP Server** with 170+ specialized tools, 11 data resources +
|
|
5
|
+
**SQLite MCP Server** with 170+ specialized tools, 11 data resources + 11 help resources, and 10 prompts, audit logging with DDL backup snapshots, HTTP/SSE Transport, OAuth 2.1 authentication, tool filtering, granular access control, and structured error handling with categorized, actionable responses. Available in WASM and better-sqlite3 variants.
|
|
6
6
|
|
|
7
7
|
[](https://github.com/neverinfamous/db-mcp)
|
|
8
8
|
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
[](https://github.com/neverinfamous/db-mcp)
|
|
16
16
|
[](https://github.com/neverinfamous/db-mcp/actions/workflows/e2e.yml)
|
|
17
17
|
[](https://github.com/neverinfamous/db-mcp)
|
|
18
|
-
[](https://github.com/neverinfamous/db-mcp)
|
|
19
19
|
|
|
20
20
|
**[Wiki](https://github.com/neverinfamous/db-mcp/wiki)** • **[Changelog](CHANGELOG.md)**
|
|
21
21
|
|
|
@@ -23,21 +23,27 @@
|
|
|
23
23
|
|
|
24
24
|
## 🎯 What Sets Us Apart
|
|
25
25
|
|
|
26
|
-
| Feature | Description
|
|
27
|
-
| -------------------------------- |
|
|
28
|
-
| **
|
|
29
|
-
| **
|
|
30
|
-
| **
|
|
31
|
-
| **
|
|
32
|
-
| **
|
|
33
|
-
| **
|
|
34
|
-
| **
|
|
35
|
-
| **
|
|
36
|
-
| **
|
|
37
|
-
| **
|
|
38
|
-
| **
|
|
39
|
-
| **
|
|
40
|
-
| **
|
|
26
|
+
| Feature | Description |
|
|
27
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| **177+ Specialized Tools** | The most comprehensive SQLite MCP server available — core CRUD, JSON/JSONB, FTS5 full-text search, statistical analysis, vector search, geospatial/SpatiaLite, introspection, migration, and admin |
|
|
29
|
+
| **Deep Observability** | Built-in Prometheus `/metrics` export, real-time `sqlite://metrics` MCP resource, historical persistence to a `SystemDb` sidecar, and a granular `sqlite_audit_search` tool for compliance and investigation |
|
|
30
|
+
| **Dynamic Configuration** | Full YAML/JSON config file support (`--config`) with precedence rules, plus a `sqlite_server_config` tool for live runtime config updates (e.g., log levels) without server restarts |
|
|
31
|
+
| **Advanced Query & Search** | O(1) cursor-based keyset pagination, faceted search aggregation, and `sqlite_hybrid_search` orchestrating FTS5 + Vector similarity with Reciprocal Rank Fusion (RRF) in a single tool call |
|
|
32
|
+
| **AI Index Recommendations** | `sqlite_index_audit` automatically analyzes `EXPLAIN QUERY PLAN` responses to suggest optimized composite and partial indexes based on workload patterns |
|
|
33
|
+
| **Real-time Subscriptions** | Native `resources/subscribe` support pushing event-driven notifications for `sqlite://schema` DDL changes and periodic `sqlite://health` updates directly to clients |
|
|
34
|
+
| **22 Resources** | 11 data resources (schema, tables, table_schema, indexes, views, health, meta, audit, metrics, compile_options, pragma) + 11 help resources (`sqlite://help` + per-group reference) — filtered by `--tool-filter` |
|
|
35
|
+
| **10 AI-Powered Prompts** | Guided workflows for schema exploration, query building, data analysis, optimization, migration, debugging, and hybrid FTS5 + vector search |
|
|
36
|
+
| **Code Mode** | **Massive Token Savings:** Execute complex, multi-step operations inside a **V8 isolate sandbox** with process-level isolation and hard timeouts. Instead of spending thousands of tokens on back-and-forth tool calls, Code Mode exposes all 177+ capabilities locally, reducing token overhead by 70–90% and supercharging AI agent reasoning |
|
|
37
|
+
| **Token-Optimized Payloads** | Every tool response is designed for minimal token footprint with `_meta.tokenEstimate` on every response so agents know their token cost. Tools include `compact`, `nodesOnly`, `maxOutliers`, `minSeverity`, and `maxInvalid` parameters where applicable — letting agents control response size without losing data access |
|
|
38
|
+
| **Dual SQLite Backends** | WASM (sql.js) for zero-compilation portability, Native (better-sqlite3) for high-performance concurrent execution with full features including transactions, window functions, and SpatiaLite GIS |
|
|
39
|
+
| **OAuth 2.1 + Access Control** | Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`full`, `read`, `write`, `admin`, `db:*`, `table:*:*`), and Keycloak integration |
|
|
40
|
+
| **Smart Tool Filtering** | 10 tool groups + 7 shortcuts let you stay within IDE limits while exposing exactly what you need |
|
|
41
|
+
| **HTTP Streaming Transport** | Streamable HTTP (`/mcp`) for modern clients + legacy SSE (`/sse`) for backward compatibility — both protocols supported simultaneously with security headers, rate limiting, health check, and stateless mode for serverless |
|
|
42
|
+
| **Production-Ready Security** | SQL injection protection (parameterized queries + Unicode-normalized WHERE clause validation), sandboxed code execution (V8 `codeGeneration` restrictions, frozen prototypes, 29 blocked patterns, Proxy nullified, RPC allowlist), CORS deny-all default, fail-closed scope enforcement, JWT claims sanitization, 7 security headers, body size limits, rate limiting with Retry-After, slowloris timeouts, `trustedProxyIps`, opt-in HSTS, non-root Docker, and build provenance |
|
|
43
|
+
| **Encryption at Rest** | Native SQLCipher support via `--encryption-key` or `DB_ENCRYPTION_KEY`. Dynamically loads `better-sqlite3-multiple-ciphers` and automatically encrypts the sidecar `SystemDb` audit logs to prevent sensitive queries from leaking |
|
|
44
|
+
| **Strict TypeScript** | 100% type-safe codebase with strict mode, no `any` types, 1911 unit tests + 1136 E2E tests and 90% coverage |
|
|
45
|
+
| **Deterministic Error Handling** | Every tool returns structured `{success, error, code, category, suggestion, recoverable}` responses — no raw exceptions, no silent failures. Agents get enriched error context with actionable suggestions instead of cryptic SQLite codes |
|
|
46
|
+
| **MCP 2025-03-26 Compliant** | Full protocol support with tool safety hints (`sensitiveHint`, `readOnlyHint`), resource priorities, and progress notifications |
|
|
41
47
|
|
|
42
48
|
## 🚀 Quick Start
|
|
43
49
|
|
|
@@ -96,7 +102,7 @@ Or with **WASM backend** (sql.js — cross-platform, no compilation required):
|
|
|
96
102
|
node dist/cli.js --transport stdio --sqlite ./database.db
|
|
97
103
|
```
|
|
98
104
|
|
|
99
|
-
> **Backend Choice:** Use `--sqlite-native` for full features (166 group tools, transactions, window functions, SpatiaLite). Use `--sqlite` for WASM mode (139 tools, no native dependencies).
|
|
105
|
+
> **Backend Choice:** Use `--sqlite-native` for full features (177 MCP tools / 166 group tools, transactions, window functions, SpatiaLite). Use `--sqlite` for WASM mode (150 MCP tools / 139 group tools, no native dependencies).
|
|
100
106
|
|
|
101
107
|
### Verify It Works
|
|
102
108
|
|
|
@@ -203,9 +209,9 @@ Specify exactly the groups you need:
|
|
|
203
209
|
|
|
204
210
|
| Shortcut | WASM | Native | + Built-in | What's Included |
|
|
205
211
|
| ------------ | ------ | ------ | ---------- | ------------------------------ |
|
|
206
|
-
| `starter` | **
|
|
212
|
+
| `starter` | **61** | **66** | +4 | Core, JSON, Text |
|
|
207
213
|
| `analytics` | 63 | 69 | +4 | Core, JSON, Stats |
|
|
208
|
-
| `search` |
|
|
214
|
+
| `search` | 47 | 52 | +4 | Core, Text, Vector |
|
|
209
215
|
| `spatial` | 36 | 43 | +4 | Core, Geo, Vector |
|
|
210
216
|
| `dev-schema` | 37 | 37 | +4 | Core, Introspection, Migration |
|
|
211
217
|
| `minimal` | 21 | 21 | +4 | Core only |
|
|
@@ -217,13 +223,12 @@ Specify exactly the groups you need:
|
|
|
217
223
|
|
|
218
224
|
| Group | WASM | Native | + Built-in | Description |
|
|
219
225
|
| --------------- | ---- | ------ | ---------- | ------------------------------------------ |
|
|
220
|
-
| `codemode` | 1 | 1 | +4 | Code Mode (sandboxed code execution) 🧠 |
|
|
221
226
|
| `core` | 21 | 21 | +4 | Basic CRUD, schema, tables |
|
|
222
227
|
| `json` | 25 | 25 | +4 | JSON/JSONB operations, analysis |
|
|
223
|
-
| `text` |
|
|
228
|
+
| `text` | 15 | 20 | +4 | Text processing + FTS5 + advanced search |
|
|
224
229
|
| `stats` | 17 | 23 | +4 | Descriptive, inference, window functions |
|
|
225
230
|
| `vector` | 11 | 11 | +4 | Vector storage, similarity search |
|
|
226
|
-
| `admin` |
|
|
231
|
+
| `admin` | 30 | 31 | +4 | DB maintenance, backup, virtual tables |
|
|
227
232
|
| `transactions` | 0 | 8 | +4 | Commit, rollback, savepoints (Native only) |
|
|
228
233
|
| `geo` | 4 | 11 | +4 | Geospatial + SpatiaLite (Native only) |
|
|
229
234
|
| `introspection` | 10 | 10 | +4 | Schema mapping, FK graph, analysis |
|
|
@@ -363,16 +368,17 @@ MCP resources provide read-only access to database metadata:
|
|
|
363
368
|
| `sqlite_meta` | `sqlite://meta` | Database metadata and PRAGMAs | `core,admin` |
|
|
364
369
|
| `sqlite_compile_options` | `sqlite://compile_options` | SQLite compile-time build options | _(read-only)_ |
|
|
365
370
|
| `sqlite_pragma` | `sqlite://pragma` | Runtime PRAGMA config snapshot | _(read-only)_ |
|
|
366
|
-
| `sqlite_insights` | `memo://insights` | Business insights memo (analysis) | `core,admin` |
|
|
367
371
|
| `sqlite_audit` | `sqlite://audit` | Recent audit log + backup stats | `--audit-log` |
|
|
372
|
+
| `sqlite_metrics` | `sqlite://metrics` | Internal server metrics | _(read-only)_ |
|
|
368
373
|
|
|
369
|
-
### Help Resources (1 + up to
|
|
374
|
+
### Help Resources (1 + up to 10)
|
|
370
375
|
|
|
371
376
|
On-demand tool reference documentation, filtered by `--tool-filter`:
|
|
372
377
|
|
|
373
378
|
| Resource | URI | Description | When Registered |
|
|
374
379
|
| --------------------------- | ----------------------------- | ----------------------------------------------------- | --------------------------- |
|
|
375
380
|
| `sqlite_help` | `sqlite://help` | Gotchas, WASM vs Native, Code Mode API | Always |
|
|
381
|
+
| `sqlite_help_core` | `sqlite://help/core` | Core CRUD and table operations reference | When core group on |
|
|
376
382
|
| `sqlite_help_json` | `sqlite://help/json` | JSON/JSONB operations reference | When json group on |
|
|
377
383
|
| `sqlite_help_text` | `sqlite://help/text` | Text processing + FTS5 reference | When text group on |
|
|
378
384
|
| `sqlite_help_stats` | `sqlite://help/stats` | Statistical analysis + window functions reference | When stats group on |
|
|
@@ -406,28 +412,33 @@ MCP prompts provide AI-assisted database workflows:
|
|
|
406
412
|
|
|
407
413
|
### Environment Variables
|
|
408
414
|
|
|
409
|
-
| Variable | Default
|
|
410
|
-
| --------------------------- |
|
|
411
|
-
| `MCP_HOST` | `
|
|
412
|
-
| `SQLITE_DATABASE` | —
|
|
413
|
-
| `
|
|
414
|
-
| `
|
|
415
|
-
| `
|
|
416
|
-
| `
|
|
417
|
-
| `
|
|
418
|
-
| `
|
|
419
|
-
| `
|
|
420
|
-
| `
|
|
421
|
-
| `
|
|
422
|
-
| `
|
|
423
|
-
| `
|
|
424
|
-
| `
|
|
425
|
-
| `
|
|
426
|
-
| `
|
|
427
|
-
| `
|
|
428
|
-
| `
|
|
429
|
-
| `
|
|
430
|
-
| `
|
|
415
|
+
| Variable | Default | Description |
|
|
416
|
+
| --------------------------- | ----------- | ------------------------------------------------------------------------------ |
|
|
417
|
+
| `MCP_HOST` | `127.0.0.1` | Host/IP to bind to (`0.0.0.0` in Docker) (CLI: `--server-host`) |
|
|
418
|
+
| `SQLITE_DATABASE` | — | SQLite database path (CLI: `--sqlite` / `--sqlite-native`) |
|
|
419
|
+
| `DB_ENCRYPTION_KEY` | — | SQLCipher encryption key (Native only) (CLI: `--encryption-key`) |
|
|
420
|
+
| `DB_MCP_TOOL_FILTER` | — | Tool filter string (CLI: `--tool-filter`) |
|
|
421
|
+
| `METRICS_EXPORT` | — | Export metrics at HTTP /metrics (e.g., `prometheus`) (CLI: `--metrics-export`) |
|
|
422
|
+
| `OAUTH_ENABLED` | `false` | Enable OAuth 2.1 (CLI: `--oauth-enabled`) |
|
|
423
|
+
| `OAUTH_ISSUER` | — | Authorization server URL (CLI: `--oauth-issuer`) |
|
|
424
|
+
| `OAUTH_AUDIENCE` | — | Expected token audience (CLI: `--oauth-audience`) |
|
|
425
|
+
| `OAUTH_JWKS_URI` | — | JWKS URI, auto-discovered if omitted (CLI: `--oauth-jwks-uri`) |
|
|
426
|
+
| `OAUTH_CLOCK_TOLERANCE` | `60` | Clock tolerance in seconds (CLI: `--oauth-clock-tolerance`) |
|
|
427
|
+
| `MCP_ENABLE_HSTS` | `false` | Enable HSTS header (CLI: `--enable-hsts`) |
|
|
428
|
+
| `NO_AUTH_ENFORCEMENT` | `false` | Explicitly bypass auth enforcement for HTTP (CLI: `--no-auth-enforcement`) |
|
|
429
|
+
| `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warning`, `error` |
|
|
430
|
+
| `METADATA_CACHE_TTL_MS` | `5000` | Schema cache TTL in ms (auto-invalidated on DDL operations) |
|
|
431
|
+
| `CODEMODE_ISOLATION` | `isolate` | Code Mode sandbox: `isolate` (isolated-vm native) or `worker` |
|
|
432
|
+
| `CODE_MODE_MAX_RESULT_SIZE` | `102400` | Maximum Code Mode result payload in bytes (default 100KB, cap 50MB) |
|
|
433
|
+
| `MCP_RATE_LIMIT_MAX` | `100` | Max requests/minute per IP (HTTP transport) |
|
|
434
|
+
| `CSV_EXTENSION_PATH` | — | Custom path to CSV extension binary (native only) |
|
|
435
|
+
| `SPATIALITE_PATH` | — | Custom path to SpatiaLite extension binary (native only) |
|
|
436
|
+
| `MCP_AUTH_TOKEN` | — | Simple bearer token for HTTP auth (CLI: `--auth-token`) |
|
|
437
|
+
| `AUDIT_LOG` | — | Audit log file path, or `stderr` (CLI: `--audit-log`) |
|
|
438
|
+
| `AUDIT_REDACT` | `true` | Redact tool arguments from audit entries (CLI: `--audit-no-redact` to disable) |
|
|
439
|
+
| `AUDIT_READS` | `false` | Also log read-scoped tool invocations (CLI: `--audit-reads`) |
|
|
440
|
+
| `AUDIT_BACKUP` | `false` | Enable pre-mutation DDL snapshots (CLI: `--audit-backup`) |
|
|
441
|
+
| `AUDIT_BACKUP_DATA` | `false` | Include sample data rows in snapshots (CLI: `--audit-backup-data`) |
|
|
431
442
|
|
|
432
443
|
> **Tip:** Lower `METADATA_CACHE_TTL_MS` for development (e.g., `1000`), or increase it for production with stable schemas (e.g., `60000` = 1 min). Schema cache is automatically invalidated on DDL operations (CREATE/ALTER/DROP).
|
|
433
444
|
|
|
@@ -438,10 +449,10 @@ db-mcp [options]
|
|
|
438
449
|
|
|
439
450
|
Transport: --transport <stdio|http|sse> --port <N> --server-host <host> --stateless
|
|
440
451
|
Auth: --oauth-enabled --oauth-issuer <url> --oauth-audience <aud>
|
|
441
|
-
Database: --sqlite <path> | --sqlite-native <path>
|
|
452
|
+
Database: --sqlite <path> | --sqlite-native <path> [--encryption-key <key>]
|
|
442
453
|
Extensions: --csv --spatialite (native only)
|
|
443
454
|
Audit: --audit-log <path> --audit-no-redact --audit-reads --audit-backup --audit-backup-data
|
|
444
|
-
Server: --name <name> --version <ver> --tool-filter <filter>
|
|
455
|
+
Server: --name <name> --version <ver> --metrics-export <type> --tool-filter <filter>
|
|
445
456
|
```
|
|
446
457
|
|
|
447
458
|
> CLI flags override environment variables. Run `node dist/cli.js --help` for full details.
|
|
@@ -470,7 +481,7 @@ Add to your `~/.cursor/mcp.json`, Claude Desktop config, or equivalent:
|
|
|
470
481
|
```
|
|
471
482
|
|
|
472
483
|
> [!TIP]
|
|
473
|
-
> **Switching backends:** The config above uses the **Native** backend (better-sqlite3,
|
|
484
|
+
> **Switching backends:** The config above uses the **Native** backend (better-sqlite3, 177 MCP tools). To use the **WASM** backend (sql.js, 150 MCP tools, zero native dependencies), change `--sqlite-native` to `--sqlite` in the args array. See the [Backend Options table in DOCKER_README](DOCKER_README.md#backend-options) for feature differences.
|
|
474
485
|
|
|
475
486
|
**Variants** (modify the `args` array above):
|
|
476
487
|
|
|
@@ -598,17 +609,38 @@ The server exposes metadata at `/.well-known/oauth-protected-resource`.
|
|
|
598
609
|
> [!WARNING]
|
|
599
610
|
> **HTTP without authentication:** When using `--transport http` without enabling OAuth, all clients have full unrestricted access. Always enable authentication for production HTTP deployments. See [SECURITY.md](SECURITY.md) for details.
|
|
600
611
|
|
|
612
|
+
## 🔐 Encryption at Rest (Native Only)
|
|
613
|
+
|
|
614
|
+
db-mcp supports transparent database encryption using SQLCipher via the `better-sqlite3-multiple-ciphers` driver. When encryption is enabled, the server automatically encrypts both your target database (if newly created) and the sidecar `SystemDb` audit log, ensuring your schema, queries, and results are protected at rest.
|
|
615
|
+
|
|
616
|
+
**Important WASM Limitation**: The WASM backend (`sql.js`) **does not** support encryption. If you supply an encryption key to the WASM backend, it will gracefully ignore it for the target database. However, this can cause conflicts if both a Native and WASM backend share the same `--audit-log` file (since the Native backend will encrypt the shared audit log, causing the WASM backend to crash when reading it). To avoid this in dual-backend setups, assign a separate audit log (e.g., `--audit-log mcp-audit-wasm.db`) for your WASM instance.
|
|
617
|
+
|
|
618
|
+
**Configuring the Key**:
|
|
619
|
+
You can provide the key via the `--encryption-key` CLI flag or the `DB_ENCRYPTION_KEY` environment variable.
|
|
620
|
+
|
|
621
|
+
1. **Strong Passphrase**: A standard string. SQLCipher will automatically use PBKDF2 key derivation.
|
|
622
|
+
```bash
|
|
623
|
+
DB_ENCRYPTION_KEY="your-strong-passphrase-here"
|
|
624
|
+
```
|
|
625
|
+
2. **Raw Hex Key (Best Performance)**: To skip PBKDF2 derivation overhead, provide an exact 256-bit raw hex key prefixed with `x` and wrapped in single quotes:
|
|
626
|
+
```bash
|
|
627
|
+
DB_ENCRYPTION_KEY="x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'"
|
|
628
|
+
```
|
|
629
|
+
|
|
630
|
+
> [!WARNING]
|
|
631
|
+
> **Audit Log Compatibility**: The `DB_ENCRYPTION_KEY` environment variable applies globally and will cause the internal `SystemDb` to attempt to decrypt your audit log (`--audit-log`). If you have an existing unencrypted audit log, the server will fail to start with `file is not a database`. To encrypt ONLY your target database (leaving the audit log unencrypted), use the `--encryption-key` CLI flag instead of the global environment variable.
|
|
632
|
+
|
|
601
633
|
## 📊 Benchmarks
|
|
602
634
|
|
|
603
635
|
Performance benchmarks measure framework overhead on critical hot paths using [Vitest bench](https://vitest.dev/guide/features.html#benchmarking) (tinybench). The suite validates that framework plumbing stays negligible relative to actual database I/O:
|
|
604
636
|
|
|
605
|
-
- **Tool dispatch:**
|
|
606
|
-
- **Auth scope checks:**
|
|
607
|
-
- **Identifier validation:**
|
|
608
|
-
- **Schema cache hits:**
|
|
609
|
-
- **Debug log (filtered):**
|
|
610
|
-
- **Code Mode security:**
|
|
611
|
-
- **Sandbox execution:** ~
|
|
637
|
+
- **Tool dispatch:** 6–14M ops/sec — Map-based lookup is effectively zero-cost
|
|
638
|
+
- **Auth scope checks:** 4–8M ops/sec — OAuth middleware adds no measurable latency
|
|
639
|
+
- **Identifier validation:** 4–7M ops/sec — SQL sanitization is near-instant
|
|
640
|
+
- **Schema cache hits:** 3–6M ops/sec — metadata lookups avoid redundant queries
|
|
641
|
+
- **Debug log (filtered):** 5–11M ops/sec — disabled log levels are true no-ops
|
|
642
|
+
- **Code Mode security:** ~0.2–1.3M validations/sec for typical code, blocked patterns rejected in 1-2 µs
|
|
643
|
+
- **Sandbox execution:** ~0.5–4.9K executions/sec — trivial code round-trips through V8 isolate in 0.2-1.5 ms
|
|
612
644
|
|
|
613
645
|
```bash
|
|
614
646
|
npm run bench # Run all benchmarks
|