hyperdb-mcp 0.7.3 → 1.0.0-rc.2

package/README.md

@@ -1,10 +1,10 @@
 # hyperdb-mcp
 
-> **Note:** This crate is AI-assisted but human-directed — much of the code was written by AI coding assistants under close review, with the design and engineering trade-offs decided by an experienced developer. The pre-1.0 (0.x) line may still undergo large breaking changes; the public API won't settle until the 1.0.0 release.
+> **Note:** This crate is AI-assisted but human-directed — much of the code was written by AI coding assistants under close review, with the design and engineering trade-offs decided by an experienced developer. As of 1.0.0 the public API is stable and follows [semantic versioning](https://semver.org/), so breaking changes require a major release.
 
 An MCP (Model Context Protocol) server that turns the Hyper columnar database into an instant SQL analytics engine. Data flows in from other MCP plugins or files, lands in Hyper automatically, and becomes queryable with SQL — no setup, no schema files, no database management.
 
-Built on the pure-Rust [`hyperdb-api`](../hyperdb-api/) crate for maximum performance: 22M+ rows/sec inserts, 18M+ rows/sec queries, constant memory for billion-row results.
+Built on the pure-Rust [`hyperdb-api`](../hyperdb-api/) crate for maximum performance. On a single connection that crate benchmarks at 68.9M rows/sec inserts with the async `AsyncArrowInserter`, 25.0M rows/sec with the sync `Inserter`, and 31.1M rows/sec full-scan queries, with constant memory for billion-row results — see [docs/BENCHMARK_GUIDE.md](../docs/BENCHMARK_GUIDE.md).
 
 ---
 
@@ -17,6 +17,7 @@ LLMs are powerful at reasoning but cannot natively crunch millions of rows. This
 Unlike flat-text memory systems that store blobs and retrieve by similarity search, HyperDB gives LLMs **structured, queryable long-term memory**. The persistent database survives across sessions — anything the LLM stores there can be JOINed, filtered, aggregated, and reasoned over with full SQL in any future conversation.
 
 This means an LLM can:
+
 - **Accumulate knowledge over time** — store reference tables, project decisions, user preferences, learned facts
 - **Cross-reference across sessions** — JOIN today's analysis against historical data from last week
 - **Answer complex recall questions** — "Which projects had budget overruns in Q1?" is a SQL query, not a fuzzy text search
@@ -76,6 +77,7 @@ The npm package bundles both the `hyperdb-mcp` binary and the `hyperd` database
 `nvm` (Node Version Manager) makes it easy to install and switch between Node.js versions.
 
 **macOS / Linux** ([nvm-sh/nvm](https://github.com/nvm-sh/nvm)):
+
 ```bash
 # install nvm if you don't have it
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
@@ -87,6 +89,7 @@ node --version    # should report v22.x.x or newer
 ```
 
 **Windows** ([coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows)): download the installer, then in a new shell:
+
 ```powershell
 nvm install lts
 nvm use lts
@@ -127,6 +130,7 @@ current directory for `.hyperd/current/hyperd`; it does not perform a general
 ### MCP Client Configuration
 
 Each AI tool reads MCP server config from a different file but uses the same JSON shape. The base config block using npx (recommended):
+
 ```json
 {
   "mcpServers": {
@@ -140,6 +144,7 @@ Each AI tool reads MCP server config from a different file but uses the same JSO
 ```
 
 Or if you built from source:
+
 ```json
 {
   "mcpServers": {
@@ -155,6 +160,7 @@ Or if you built from source:
 ```
 
 By default, persistent storage lives at the platform data dir (`~/Library/Application Support/hyperdb/workspace.hyper` on macOS, `~/.local/share/hyperdb/workspace.hyper` on Linux, `%APPDATA%\hyperdb\workspace.hyper` on Windows). To use a custom path:
+
 ```json
 "args": ["--persistent-db", "/path/to/my-project.hyper"]
 ```
@@ -171,6 +177,7 @@ process trying to attach the same file can instead receive contextual
 Create or edit `~/.claude/.mcp.json` (global) or `.mcp.json` in the project root (project-scoped). Use the base config block above.
 
 After adding the config:
+
 1. Start a new Claude Code session. You'll be prompted to approve the server on first use.
 2. **Auto-approve tools (optional):** Add `"mcp__HyperDB__*"` to the `permissions.allow` array in `~/.claude/settings.json`.
 
@@ -230,7 +237,14 @@ describe({ database: "persistent" })
 sample({ table: "customers", database: "persistent" })
 ```
 
-The `database` parameter is available on `query`, `execute`, `load_data`, `load_file`, `load_files`, `watch_directory`, `describe`, `sample`, `chart`, `export`, and `set_table_metadata`. The shorthand `persist: true` (sugar for `database: "persistent"`) is available on `load_data`, `load_file`, `load_files`, and `watch_directory`. Read tools generally accept a read-only user attachment; write tools require a writable one. The exception is the KV family: every `kv_*` call to a user attachment requires it to be writable because the backing table may need initialization.
+The `database` parameter is available on `query`, `execute`, `load_data`,
+`load_file`, `load_files`, `watch_directory`, `describe`, `sample`, `chart`,
+`export`, and `set_table_metadata`. The shorthand `persist: true` (sugar for
+`database: "persistent"`) is available on `load_data`, `load_file`,
+`load_files`, and `watch_directory`. Read tools generally accept a read-only
+user attachment; write tools require a writable one. The exception is the KV
+family: every `kv_*` call to a user attachment requires it to be writable
+because the backing table may need initialization.
 
 Every successful database-routed response includes the canonical
 `resolved_database`: `"local"`, `"persistent"`, or the lowercase attached
@@ -325,7 +339,7 @@ If hyperd repeatedly fails to start (3 attempts within 60 seconds — e.g., misc
 
 Ingest inline data and run a SQL query in a single call.
 
-```
+```text
 query_data(data: '[{"region":"West","revenue":1200},...]', sql: 'SELECT region, SUM(revenue) FROM data GROUP BY region')
 ```
 
@@ -341,7 +355,7 @@ query_data(data: '[{"region":"West","revenue":1200},...]', sql: 'SELECT region,
 
 Ingest a file and run a SQL query in a single call. Streams from disk — handles files of any size.
 
-```
+```text
 query_file(path: '/tmp/sales.parquet', sql: 'SELECT TOP 10 * FROM sales ORDER BY amount DESC')
 ```
 
@@ -358,7 +372,7 @@ query_file(path: '/tmp/sales.parquet', sql: 'SELECT TOP 10 * FROM sales ORDER BY
 
 Load inline data into a named local, persistent, or attached-database table.
 
-```
+```text
 load_data(table: 'customers', data: '[{"id":1,"name":"Alice"},...]')
 ```
 
@@ -374,7 +388,7 @@ load_data(table: 'customers', data: '[{"id":1,"name":"Alice"},...]')
 
 Load a file into a named local, persistent, or attached-database table.
 
-```
+```text
 load_file(table: 'orders', path: '/tmp/orders.csv')
 ```
 
@@ -386,7 +400,7 @@ load_file(table: 'orders', path: '/tmp/orders.csv')
 | `schema` | object | no | Partial column-name → type map (see [Schema Overrides](#schema-overrides)) |
 
 When you're unsure of the right types — or recovering from a previous
-`SCHEMA_MISMATCH` — call [`inspect_file`](#inspect-file) first. It reports the
+`SCHEMA_MISMATCH` — call [`inspect_file`](#inspect_file) first. It reports the
 exact schema `load_file` would use plus per-column `min` / `max` / `null_count`
 so you can build a minimal, correct override in one shot.
 
@@ -397,7 +411,7 @@ local table. Pass the absolute path to the Iceberg table root (the
 directory containing `metadata/` and `data/`); hyperd's native Iceberg
 reader derives the schema and resolves the snapshot.
 
-```
+```text
 load_iceberg(table: 'sales', path: '/lake/warehouse/db/sales')
 ```
 
@@ -416,7 +430,7 @@ Iceberg table metadata.
 
 Run a **read-only** SQL query against local (default), persistent, or an attached database. Accepts `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, `VALUES`. For DDL/DML use `execute`.
 
-```
+```text
 query(sql: 'SELECT c.name, SUM(o.amount) FROM orders o JOIN customers c ON o.customer_id = c.id GROUP BY c.name')
 ```
 
@@ -424,7 +438,7 @@ query(sql: 'SELECT c.name, SUM(o.amount) FROM orders o JOIN customers c ON o.cus
 
 Execute one or more **mutating** SQL statements as an atomic batch: `CREATE TABLE`, `INSERT`, `UPDATE`, `DELETE`, `DROP TABLE`, `ALTER`, `COPY`, etc. `sql` is an array of statements; multi-element batches run inside a transaction (all commit or all roll back). Single-element batches auto-commit, same as a one-off statement. Returns the per-statement affected row counts plus a total. Disabled in read-only mode.
 
-```
+```text
 // Single statement (auto-commit)
 execute(sql: ['CREATE TABLE archived_orders AS SELECT * FROM orders WHERE year < 2024'])
 
@@ -437,6 +451,7 @@ execute(sql: [
 ```
 
 Validation rules enforced before any SQL hits the server:
+
 - Array must be non-empty; no element may be empty / whitespace-only / comment-only.
 - No element may be read-only — use `query` for SELECT/WITH/EXPLAIN.
 - DDL and DML cannot be mixed in one batch (Hyper aborts mixed transactions with SQLSTATE 0A000).
@@ -451,7 +466,7 @@ List all tables in the selected database with their schemas, column types, and r
 
 Return the schema, total row count, and first N rows of a table in a single call.
 
-```
+```text
 sample(table: 'orders', n: 10)
 ```
 
@@ -475,7 +490,7 @@ Use it **before** `load_file` whenever you are unsure about types, or **after**
 reported `type` + `min` / `max` directly into a partial `schema` override on the
 subsequent `load_file` call.
 
-```
+```text
 inspect_file(path: '/tmp/owid-population.csv')
 ```
 
@@ -523,7 +538,7 @@ only for the lifetime of the server process.
 
 #### `save_query`
 
-```
+```text
 save_query(name: 'top_5_customers', sql: 'SELECT customer, SUM(amount) AS total FROM orders GROUP BY customer ORDER BY total DESC LIMIT 5', description: 'Biggest spenders this year')
 ```
 
@@ -539,7 +554,7 @@ first if you intend to overwrite. Non-read-only SQL is rejected with
 
 #### `delete_query`
 
-```
+```text
 delete_query(name: 'top_5_customers')
 ```
 
@@ -576,12 +591,13 @@ Nine tools cover the surface:
 | `kv_pop` | Destructively read-and-remove the lowest-keyed entry (atomic) | `store`, `database`, `persist` |
 | `kv_clear` | Delete all keys in a store (returns count removed) | `store`, `database`, `persist` |
 
-```
+```text
 kv_set(store: 'session', key: 'last_report', value: '{"rows": 4210}', database: 'persistent')
 kv_get(store: 'session', key: 'last_report')
 ```
 
 Key properties:
+
 - **Read-only mode** — the five mutators (`kv_set`, `kv_set_many`, `kv_delete`, `kv_pop`, `kv_clear`) are disabled and return `READ_ONLY_VIOLATION`; the global guard leaves the four readers (`kv_get`, `kv_list`, `kv_size`, `kv_list_stores`) available.
 - **Attached-database access** — every attached target must have been attached
   with `writable=true`, even for readers, because a KV call may need to
@@ -598,7 +614,7 @@ Key properties:
 
 Write query results or a table to a file.
 
-```
+```text
 export(table: 'orders', path: '~/Desktop/orders.parquet', format: 'parquet')
 export(sql: 'SELECT ...', path: '~/Desktop/analysis.hyper', format: 'hyper')
 ```
@@ -621,7 +637,7 @@ destination and materializes every user table from the selected source into it.
 Render a bounded quick diagnostic from a SQL query. This convenience tool is
 for inspecting or sharing one chart, not for dashboard/layout composition.
 
-```
+```text
 chart(sql: 'SELECT product, SUM(revenue) as total FROM sales GROUP BY product', chart_type: 'bar', x: 'product', y: 'total', title: 'Revenue by Product')
 ```
 
@@ -675,7 +691,7 @@ bound, never zero.
 
 Monitor a directory for data files and auto-append them to a target table.
 
-```
+```text
 watch_directory(path: '/tmp/inbox', table: 'events')
 unwatch_directory(path: '/tmp/inbox')
 ```
@@ -689,6 +705,7 @@ unwatch_directory(path: '/tmp/inbox')
 On success, both files are deleted. On failure, both are moved to `failed/` with a `.error` JSON file.
 
 Key properties:
+
 - **One directory, one table, append mode** — files must match the target schema.
 - **Initial sweep** — pre-existing `.ready` files are processed immediately.
 - **Read-only mode** — `watch_directory` is blocked; `unwatch_directory` is always allowed.
@@ -889,7 +906,7 @@ Hyper uses the Salesforce Data Cloud SQL dialect (PostgreSQL-compatible with ext
 
 Hyper does **not** support `ON CONFLICT` or `INSERT ... ON DUPLICATE KEY`. Use the `execute` tool's atomic batch shape instead:
 
-```
+```text
 execute(sql: [
   "UPDATE settings SET value = 'dark' WHERE key = 'theme'",
   "INSERT INTO settings (key, value) SELECT 'theme', 'dark' \
@@ -906,6 +923,7 @@ Both statements run inside a single Hyper transaction — they commit together o
 The Hyper Rust API supports `BEGIN` / `COMMIT` / `ROLLBACK` plus an RAII `Transaction` guard (see [`docs/TRANSACTIONS.md`](../docs/TRANSACTIONS.md)). The MCP `execute` tool surfaces this as the `sql` array shape: pass multiple statements and they run atomically.
 
 Hyper-specific limits worth remembering when batching:
+
 - **DDL after DML in the same transaction is rejected** with SQLSTATE 0A000. The `execute` tool catches this up front — mixing CREATE/DROP/ALTER with INSERT/UPDATE/DELETE in one batch is rejected with an actionable error.
 - **DDL is auto-committed** even inside a transaction. `execute` rejects multi-element all-DDL batches because the "atomic" promise can't be honored — issue each DDL call as its own one-element array.
 - **After any error inside a transaction**, the connection enters aborted state and only ROLLBACK is accepted next. The `execute` tool handles this for you — on any per-statement failure the wrapper issues ROLLBACK before surfacing the error.
@@ -916,7 +934,7 @@ Full reference: [Data Cloud SQL Reference](https://developer.salesforce.com/docs
 
 ## CLI Reference
 
-```
+```text
 hyperdb-mcp [OPTIONS] [COMMAND]
 
 Commands:

package/package.json

@@ -29,10 +29,10 @@
   "engines": {
     "node": ">= 21"
   },
-  "version": "0.7.3",
+  "version": "1.0.0-rc.2",
   "optionalDependencies": {
-    "hyperdb-mcp-darwin-arm64": "0.7.3",
-    "hyperdb-mcp-linux-x64-gnu": "0.7.3",
-    "hyperdb-mcp-win32-x64-msvc": "0.7.3"
+    "hyperdb-mcp-darwin-arm64": "1.0.0-rc.2",
+    "hyperdb-mcp-linux-x64-gnu": "1.0.0-rc.2",
+    "hyperdb-mcp-win32-x64-msvc": "1.0.0-rc.2"
   }
 }