db-mcp 1.0.2 → 1.1.0

package/test-server/test-tools.md

@@ -0,0 +1,176 @@
+# db-mcp (SQLite) Tool Testing
+
+**Ignore WASM content. Test Native Mode Only**
+
+**Step 1:** Confirm you read the server help content sourced from `C:\Users\chris\Desktop\db-mcp\src\constants\server-instructions\gotchas.md` using `view_file` (not grep or search) — to understand documented behaviors, edge cases, and response structures for this tool group.
+
+**Step 2:** Please conduct an exhaustive test of the tool group specified in the group-specific checklist (pasted after this document) using live MCP server tool calls directly — not scripts/terminal.
+
+**Note** If temp tables are present from a previous test pass, it's because the database is locked. Ignore them.
+
+## Test Database Schema
+
+The test database (test-server/test.db) contains these tables with JSON-relevant columns:
+
+| Table             | Rows | Columns                                                                       | JSON Columns                                                                              |
+| ----------------- | ---- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| test_products     | 16   | id, name, description, price, category, created_at                            | —                                                                                         |
+| test_orders       | 20   | id, product_id (FK), customer_name, quantity, total_price, order_date, status | —                                                                                         |
+| test_jsonb_docs   | 6    | id, doc, metadata, tags, created_at                                           | **doc**, **metadata** (nested), **tags** (array)                                          |
+| test_articles     | 8    | id, title, body, author, category, published_at                               | —                                                                                         |
+| test_users        | 9    | id, username, email, phone, bio, created_at                                   | —                                                                                         |
+| test_measurements | 200  | id, sensor_id, temperature, humidity, pressure, measured_at                   | —                                                                                         |
+| test_embeddings   | 20   | id, content, category, embedding                                              | **embedding** (8-dim float array); category values: database, fitness, food, tech, travel |
+| test_locations    | 15   | id, name, city, latitude, longitude, type                                     | —                                                                                         |
+| test_categories   | 17   | id, name, path, level                                                         | —                                                                                         |
+| test_events       | 100  | id, event_type, user_id (INT, 8 values), payload, event_date                  | **payload** (JSON)                                                                        |
+
+**Primary JSON test tables:**
+
+- `test_jsonb_docs.doc` — Row 1: `{"type":"article","title":"Getting Started with SQLite","author":"Alice","views":1250,"rating":4.5}`, Row 3: `{"type":"video",...,"duration":3600}`, Row 4 has `nested.level1.level2 = "deep value"`
+- `test_jsonb_docs.metadata` — Object with keys: source, language, version, quality, subscribers
+- `test_jsonb_docs.tags` — Array of strings like `["database","tutorial","beginner"]`
+- `test_events.payload` — Object with keys: page (values: home, products, cart, checkout), session (values: sess_1000+)
+
+> **Note:** String values in test data use **lowercase** (e.g., `category = 'electronics'`, not `'Electronics'`). Use case-sensitive matching in queries.
+
+> **Note:** `test_measurements.sensor_id` is an **INTEGER** column (values 1-5), not a string. Use `sensor_id = 1`, not `sensor_id = 'S001'`.
+
+> **Note:** When testing `sqlite_execute_code`, do **not** pass `readonly: true` unless specifically testing read-only filtering. The `readonly` flag makes write methods return structured errors (`{success: false, code: "CODEMODE_READONLY_VIOLATION"}`). Methods remain callable but reject write operations. Use `readonly: false` (or omit it) to get the full API surface.
+
+## Testing Requirements
+
+> [!CAUTION]
+> **Zero tolerance for raw MCP errors.** ANY response that is a raw MCP error (e.g., `-32602`, `isError: true`, no `success` field) is a **bug that must be reported and fixed** — never an acceptable design choice, SDK limitation, or expected behavior. If you see one, report it as ❌ immediately. Do not rationalize it as "the SDK rejecting at the boundary" or "by design for range-constrained params." The handler MUST catch it.
+
+1. Use existing `test_*` tables for read operations (SELECT, COUNT, queries)
+2. Create temporary tables with `temp_*` prefix for write operations
+3. Test each tool with realistic inputs based on the schema above
+4. Report all failures, unexpected behaviors, improvement opportunities, or unnecessarily large payloads
+5. Do not mention what already works well or issues well documented in help resources and runtime hints which are already optimal
+6. **Error path testing**: For **every** tool, test at least **two** invalid inputs: (a) a domain error (nonexistent table, invalid column, missing required parameter) and (b) a **Zod validation error** (call the tool with `{}` empty params if it has required parameters, or pass the wrong type). Both must return a **structured handler error** (`{success: false, error: "..."}`) — NOT a raw MCP error frame. See the "Structured Error Response Pattern" section below for how to distinguish the two. This is the most common deficiency found across tool groups.
+7. **Output schema testing**: For **every** tool that has an `outputSchema`, confirm that at least one valid happy-path call returns a structured JSON response — NOT a raw MCP `-32602` "output schema" error. Output schema mismatches (handler returns fields not declared in the schema) produce the same `-32602` code as input errors but are only caught with valid inputs. See "Output Schema Validation Errors" below. Also check for the inverse: if a schema is **defined** in `src/adapters/sqlite/output-schemas/` but **not wired** to the tool definition, report as ⚠️ — the schema exists but provides no enforcement.
+8. **Deterministic checklist first**: Complete ALL items in the group-specific checklist before moving to freeform exploration. The checklist uses exact inputs and expected outputs to ensure reproducible coverage every run.
+
+## Structured Error Response Pattern
+
+All tools should return errors as structured objects instead of throwing. A thrown error propagates as a raw MCP error, which is unhelpful to clients. The expected pattern:
+
+```json
+{ "success": false, "error": "Human-readable error message" }
+```
+
+### Handler Error vs MCP Error — How to Distinguish
+
+There are two kinds of error responses. Only one is correct:
+
+| Type                 | Source                                                             | What you see                                                                                                          | Verdict            |
+| -------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Handler error** ✅ | Handler catches error and returns `{success: false, error: "..."}` | Parseable JSON object with `success` and `error` fields                                                               | Correct            |
+| **MCP error** ❌     | Uncaught throw propagates to MCP framework                         | Raw text error string, often prefixed with `Error:`, wrapped in an `isError: true` content block — no `success` field | Bug — report as ❌ |
+
+**Concrete examples:**
+
+```
+✅ Handler error (correct):
+{"success": false, "error": "Table 'nonexistent_xyz' does not exist"}
+
+❌ MCP error (bug — handler threw instead of catching):
+content: [{type: "text", text: "Error: SQLITE_ERROR: no such table: nonexistent_xyz"}]
+isError: true
+```
+
+The MCP error case means the handler is missing a `try/catch` block. When testing, if you see a raw error string (especially one containing `SQLITE_ERROR` without a `success` field), report it as ❌.
+
+### Zod Validation Errors
+
+Calling a tool with wrong parameter types or missing required fields triggers a Zod validation error. If the handler has no outer `try/catch`, this surfaces as a raw MCP error (often `-32602`). Test every tool with `{}` (empty params) if it has required parameters — the response must be a handler error, not an MCP error.
+
+**Zod refinement leak pattern:** `DatabaseAdapter.registerTool()` uses `.partial()` on input schemas so the SDK accepts `{}`. But `.partial()` only makes keys **optional** — it does NOT strip refinements like `.min(1)`, `.max(90)`, or `.min(-90).max(90)`. This applies to **ALL types** — strings, arrays, AND numbers:
+
+- `z.string().min(1)` + empty `""` → SDK rejects with raw MCP `-32602`
+- `z.array().min(1)` + empty `[]` → SDK rejects with raw MCP `-32602`
+- `z.number().min(-90).max(90)` + value `91` → SDK rejects with raw MCP `-32602`
+
+**Fix:** Remove ALL `.min(N)` / `.max(N)` refinements from the schema and validate inside the handler instead (see `sqlite_query_plan` in `diagnostics.ts`, `sqlite_append_insight` in `pragma.ts`, and `validateCoordinates()` in `geo.ts` for examples). Optional fields with `.default()` are safe because the default satisfies the constraint.
+
+**Required enum coercion pattern:** For **optional** enum params with defaults, `z.preprocess(coercer, z.enum([...]).optional().default(...))` works — the coercer returns `undefined` for invalid values → the `.default()` kicks in. For **required** enum params (no `.optional().default(...)`), this pattern **fails**: the SDK's `.partial()` wraps the preprocess in `.optional()`, but the inner `z.enum()` still rejects `undefined` → raw MCP `-32602`. **Fix:** Use `z.string()` in the schema and validate the enum inside the handler's `try/catch`, returning a structured error (see `VALID_ANALYSIS_TYPES` / `VALID_OPERATIONS` / `VALID_FORMATS` in SpatiaLite `analysis.ts` for examples).
+
+**What to report:**
+
+- If a tool call returns a raw MCP error (no JSON body with `success` field), report it as ❌ with the tool name and the raw error message
+- If a tool returns `{success: false, error: "..."}`, that is the correct behavior — do not report it as a failure
+- If a tool returns a successful response for an obviously invalid input (e.g., nonexistent table returns `{success: true}`), report it as ⚠️
+
+### Wrong-Type Numeric Parameter Coercion
+
+For every tool with optional numeric parameters (e.g., `limit`, `buckets`, `windowSize`, `radius`, `sampleSize`), call the tool with `param: "abc"` (string instead of number). The tool must NOT return a raw MCP `-32602` error. Acceptable behaviors:
+
+- Handler returns `{success: false, error: "..."}` with a validation message
+- Handler silently applies the default value
+- Handler coerces to NaN and returns a descriptive error
+
+Unacceptable: Raw MCP error frame with `-32602` code.
+
+### Output Schema Validation Errors
+
+The MCP SDK enforces `additionalProperties: false` on **output** schemas. If a handler returns fields not declared in its output schema, the SDK rejects the response with a raw `-32602` error — even though the handler logic succeeded. This is a different failure mode from input validation:
+
+- **Input `-32602`**: Triggered by sending unrecognized/invalid parameters → caught by the Zod sweep (call with `{}` or `extraParam`)
+- **Output `-32602`**: Triggered by the handler **returning** undeclared fields → caught by a valid happy-path call that still produces a raw MCP error
+
+**How to detect:** If a tool call with **correct, valid inputs** returns a raw MCP `-32602` mentioning "does not match the tool's output schema" or "additional properties", the output schema in `src/adapters/sqlite/output-schemas/` is missing fields that the handler returns. Report as ❌ with both the tool name and the missing field(s).
+
+**Fix pattern:** Add the missing fields to the output schema (e.g., `durationMs: z.number().optional()`, `message: z.string().optional()`). Do NOT remove fields from the handler response — the schema must match reality.
+
+**Systematic check:** For every tool that has an `outputSchema`, make at least one valid happy-path call and confirm it returns a parseable JSON object with a `success` field — not a raw MCP error. This is separate from (and complementary to) the Zod validation sweep, which tests invalid inputs.
+
+### Error Consistency Audit
+
+During testing, check for these inconsistencies across tool groups:
+
+1. **Throw-vs-return**: If a tool throws a raw error instead of returning `{success: false}`, report as ❌. Document which tool groups have raw-error leakage.
+2. **Error field name**: All `{success: false}` responses should use `error` as the field name. The `reason` field is reserved for `{success: true, skipped: true}` informational responses.
+3. **Zod validation leaks**: If calling a tool with an invalid enum value or missing required field produces a raw MCP `-32602` error instead of a structured response, report as ❌.
+4. **Output schema leaks**: If calling a tool with valid inputs produces a raw MCP `-32602` mentioning "output schema" or "additional properties", report as ❌ (see "Output Schema Validation Errors" above).
+5. **Centralized error formatting**: db-mcp uses `DbMcpError`. If any tool group catches errors but formats them inconsistently (e.g., different message patterns for the same error type), report as ⚠️.
+6. **Orphaned output schemas**: If a schema is exported from `src/adapters/sqlite/output-schemas/` (e.g., `TransactionBeginOutputSchema`) but the corresponding tool definition does not reference it via `outputSchema`, report as ⚠️. Use `grep_search` to check whether the schema name appears in any tool file under `src/adapters/`. Defined-but-unwired schemas provide zero enforcement.
+7. **Inline output schemas**: If any tool defines `outputSchema: z.object({...})` inline in the handler file instead of importing a named schema from `output-schemas/`, report as ⚠️. All output schemas must live in `src/adapters/sqlite/output-schemas/` with named exports. Use `grep_search` with pattern `outputSchema: z.object` across `src/adapters/` to detect violations.
+
+### Split Schema Pattern Verification
+
+All tools use the Split Schema pattern: a plain `z.object()` Base schema for MCP parameter visibility, and a `z.preprocess()` wrapper for handler parsing. Verify:
+
+1. **Parameter visibility**: For tools with optional parameters (e.g., `limit`, `readonly`), make a direct MCP call using those parameters. If the tool ignores or rejects documented parameters, report as a Split Schema violation.
+2. **Alias acceptance**: For tools with documented parameter aliases (e.g., `table`/`tableName`, `query`/`sql`, `indexName`/`name`), verify that direct MCP tool calls correctly accept the aliases.
+
+## Reporting Format
+
+- ❌ Fail: Tool errors or produces incorrect results (include error message)
+- ⚠️ Issue: Unexpected behavior or improvement opportunity
+- 📦 Payload: Unnecessarily large response that should be optimized — **blocking, equally important as ❌ bugs**. Oversized payloads waste LLM context window tokens and degrade downstream tool-calling quality. Report the response size in KB and suggest a concrete optimization (e.g., filter system tables, add `compact` option, omit empty arrays).
+
+## Post-Test Procedures
+
+### Reporting Rules
+
+- Use ✅ only in inline notes during testing; omit from Final Summary
+- Do not mention what already works well or issues already documented in help resources and runtime hints
+
+### After Testing
+
+1. **Triage findings**: If issues were found, create an implementation plan, making sure they are consistent with working patterns in other tools/tool groups. If the plan requires no user decisions, proceed directly to implementation
+2. **Scope of fixes** includes corrections to any of:
+   - Handler code
+   - `src/constants/server-instructions/*.md` (per-group help files) — run `npm run generate:instructions` after editing to regenerate `server-instructions.ts`
+   - Test database (`test-server/test.db`)
+   - This prompt (`test-tools.md`) and group file (`test-group-tools.md`)
+
+### After Implementation
+
+3. **Validate**: Run test suite and fix broken tests, run lint + typecheck and fix issues, update changelog (no duplicate headers)
+4. **Commit**: Stage and commit all changes — do NOT push
+5. **Live re-test**: Test fixes with direct MCP tool calls. I will have already rebuilt and restarted the server.
+6. **Final summary**: If no issues found, provide the final summary after testing. If issues were fixed, provide the summary after live MCP re-testing confirms fixes are working. If the test prompt/database can be improved, make the improvements.
+
+---

package/test-server/tool-reference.md

@@ -0,0 +1,236 @@
+# Tool Reference
+
+Complete reference of all **139 Native / 115 WASM tools** organized by 9 tool groups + codemode. Each group automatically includes Code Mode (`sqlite_execute_code`) for token-efficient operations.
+
+> **3 built-in tools** (`server_info`, `server_health`, `list_adapters`) are always available regardless of filter settings.
+>
+> Use [Tool Filtering](#️-tool-filtering) to select the groups you need. See [Code Mode](#-recommended-code-mode-maximum-token-savings) for the `sqlite.*` API that exposes every tool below through sandboxed JavaScript.
+
+---
+
+## codemode (1 tool)
+
+Sandboxed JavaScript execution that exposes all 9 tool groups through the `sqlite.*` API.
+
+| Tool                  | Description                                                                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sqlite_execute_code` | Execute JavaScript in a sandboxed environment with access to all SQLite tools via the `sqlite.*` API. Enables complex multi-step operations in a single call with 70–90% token savings. |
+
+---
+
+## core (9 tools + Code Mode)
+
+Read/write queries, table and index management, and schema discovery.
+
+| Tool                    | Description                                                                                               |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `sqlite_read_query`     | Execute a SELECT query on the SQLite database. Returns rows as JSON. Use parameter binding for safety.    |
+| `sqlite_write_query`    | Execute an INSERT, UPDATE, or DELETE query. Returns affected row count. Use parameter binding for safety. |
+| `sqlite_list_tables`    | List all tables and views in the database with their column counts.                                       |
+| `sqlite_describe_table` | Get detailed schema information for a table including columns, types, and constraints.                    |
+| `sqlite_create_table`   | Create a new table in the database with specified columns and constraints.                                |
+| `sqlite_drop_table`     | Drop (delete) a table from the database. This is irreversible!                                            |
+| `sqlite_get_indexes`    | List all indexes in the database, optionally filtered by table.                                           |
+| `sqlite_create_index`   | Create an index on one or more columns to improve query performance.                                      |
+| `sqlite_drop_index`     | Drop (delete) an index from the database.                                                                 |
+
+---
+
+## json (23 tools + Code Mode)
+
+Comprehensive JSON manipulation — read, write, transform, validate, and analyze JSON documents stored in SQLite.
+
+| Tool                            | Description                                                                                                          |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `sqlite_json_insert`            | Insert a row with JSON data. Automatically normalizes JSON for consistent storage.                                   |
+| `sqlite_json_update`            | Update a value at a specific JSON path using `json_set()`.                                                           |
+| `sqlite_json_select`            | Select rows and optionally extract specific JSON paths.                                                              |
+| `sqlite_json_query`             | Query JSON data with path-based filters and projections.                                                             |
+| `sqlite_json_validate_path`     | Validate a JSON path syntax without executing a query.                                                               |
+| `sqlite_json_merge`             | Merge JSON object into existing JSON column using `json_patch()`.                                                    |
+| `sqlite_json_analyze_schema`    | Analyze JSON data in a column to infer its schema (types, nullability, counts).                                      |
+| `sqlite_create_json_collection` | Create an optimized JSON document collection table with ID, data column, optional timestamps, and JSON path indexes. |
+| `sqlite_json_valid`             | Check if a string is valid JSON.                                                                                     |
+| `sqlite_json_extract`           | Extract a value from a JSON column at the specified path using `json_extract()`.                                     |
+| `sqlite_json_set`               | Set a value at a JSON path using `json_set()`. Creates path if it does not exist.                                    |
+| `sqlite_json_remove`            | Remove a value at a JSON path using `json_remove()`.                                                                 |
+| `sqlite_json_type`              | Get the JSON type (null, true, false, integer, real, text, array, object) at a path.                                 |
+| `sqlite_json_array_length`      | Get the length of a JSON array at the specified path.                                                                |
+| `sqlite_json_array_append`      | Append a value to a JSON array using `json_insert()`.                                                                |
+| `sqlite_json_keys`              | Get the distinct keys of JSON objects at the specified path (returns unique keys across all matching rows).          |
+| `sqlite_json_each`              | Expand a JSON array or object into rows using `json_each()`.                                                         |
+| `sqlite_json_group_array`       | Aggregate column values into a JSON array using `json_group_array()`.                                                |
+| `sqlite_json_group_object`      | Aggregate key-value pairs into a JSON object using `json_group_object()`.                                            |
+| `sqlite_json_pretty`            | Format JSON string with indentation for readability.                                                                 |
+| `sqlite_jsonb_convert`          | Convert a text JSON column to JSONB binary format for faster processing. Requires SQLite 3.45+.                      |
+| `sqlite_json_storage_info`      | Analyze storage format of a JSON column (text vs JSONB) and report statistics.                                       |
+| `sqlite_json_normalize_column`  | Normalize JSON data in a column (sort keys, compact format) for consistent storage and comparison.                   |
+
+---
+
+## text (17 Native / 13 WASM tools + Code Mode)
+
+Text processing, regex, fuzzy matching, phonetic search, and FTS5 full-text search.
+
+| Tool                     | Description                                                                                                                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sqlite_regex_extract`   | Extract text matching a regex pattern. Processed in JavaScript after fetching data.                                                                                              |
+| `sqlite_regex_match`     | Find rows where column matches a regex pattern. Processed in JavaScript.                                                                                                         |
+| `sqlite_text_split`      | Split a text column by delimiter into array results.                                                                                                                             |
+| `sqlite_text_concat`     | Concatenate multiple columns with optional separator.                                                                                                                            |
+| `sqlite_text_replace`    | Replace text in a column using SQLite `replace()` function.                                                                                                                      |
+| `sqlite_text_trim`       | Trim whitespace from text column values.                                                                                                                                         |
+| `sqlite_text_case`       | Convert text to uppercase or lowercase.                                                                                                                                          |
+| `sqlite_text_substring`  | Extract a substring from text column using `substr()`.                                                                                                                           |
+| `sqlite_fuzzy_match`     | Find fuzzy matches using Levenshtein distance. Splits values into tokens by default (`tokenize: false` to match entire value). Use `maxDistance` 1–3 for similar-length strings. |
+| `sqlite_phonetic_match`  | Find phonetically similar values using Soundex (SQLite native) or Metaphone algorithm.                                                                                           |
+| `sqlite_text_normalize`  | Normalize text using Unicode normalization (NFC, NFD, NFKC, NFKD) or strip accents.                                                                                              |
+| `sqlite_text_validate`   | Validate text values against patterns: email, phone, URL, UUID, IPv4, or custom regex.                                                                                           |
+| `sqlite_advanced_search` | Advanced search combining exact, fuzzy (Levenshtein), and phonetic (Soundex) matching.                                                                                           |
+| `sqlite_fts_create`      | Create an FTS5 full-text search virtual table. `[NATIVE ONLY]`                                                                                                                   |
+| `sqlite_fts_search`      | Search an FTS5 table using full-text query syntax. `[NATIVE ONLY]`                                                                                                               |
+| `sqlite_fts_rebuild`     | Rebuild an FTS5 index to optimize search performance. `[NATIVE ONLY]`                                                                                                            |
+| `sqlite_fts_match_info`  | Get FTS5 match ranking information using bm25. `[NATIVE ONLY]`                                                                                                                   |
+
+---
+
+## stats (19 Native / 13 WASM tools + Code Mode)
+
+Statistical analysis — descriptive stats, percentiles, correlation, regression, distributions, and window functions.
+
+| Tool                          | Description                                                                                                             |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `sqlite_stats_basic`          | Get basic statistics (count, sum, avg, min, max) for a numeric column.                                                  |
+| `sqlite_stats_count`          | Count rows, optionally distinct values in a column.                                                                     |
+| `sqlite_stats_group_by`       | Aggregate statistics grouped by a column.                                                                               |
+| `sqlite_stats_histogram`      | Create a histogram with specified number of buckets.                                                                    |
+| `sqlite_stats_percentile`     | Calculate percentiles (median, quartiles, etc.) for a column.                                                           |
+| `sqlite_stats_correlation`    | Calculate Pearson correlation coefficient between two numeric columns.                                                  |
+| `sqlite_stats_top_n`          | Get top N values from a column.                                                                                         |
+| `sqlite_stats_distinct`       | Get distinct values from a column.                                                                                      |
+| `sqlite_stats_summary`        | Get summary statistics for multiple columns at once.                                                                    |
+| `sqlite_stats_frequency`      | Get frequency distribution of values in a column.                                                                       |
+| `sqlite_stats_outliers`       | Detect outliers using IQR (Interquartile Range) or Z-score method.                                                      |
+| `sqlite_stats_regression`     | Perform linear or polynomial regression analysis between two columns.                                                   |
+| `sqlite_stats_hypothesis`     | Perform statistical hypothesis tests: one-sample t-test, two-sample t-test, or chi-square test.                         |
+| `sqlite_window_row_number`    | Assign sequential row numbers based on ordering. Useful for pagination and ranking. `[NATIVE ONLY]`                     |
+| `sqlite_window_rank`          | Calculate rank of rows. RANK leaves gaps after ties, DENSE_RANK does not, PERCENT_RANK gives 0–1 range. `[NATIVE ONLY]` |
+| `sqlite_window_lag_lead`      | Access previous (LAG) or next (LEAD) row values. Useful for comparing consecutive rows. `[NATIVE ONLY]`                 |
+| `sqlite_window_running_total` | Calculate running (cumulative) total. Useful for balance tracking, cumulative metrics. `[NATIVE ONLY]`                  |
+| `sqlite_window_moving_avg`    | Calculate moving (rolling) average. Useful for smoothing time series data. `[NATIVE ONLY]`                              |
+| `sqlite_window_ntile`         | Divide rows into N buckets. E.g., 4 buckets = quartiles, 10 = deciles, 100 = percentiles. `[NATIVE ONLY]`               |
+
+---
+
+## vector (11 tools + Code Mode)
+
+Vector storage, similarity search, and distance calculations for embeddings and AI/ML operations.
+
+| Tool                         | Description                                                              |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `sqlite_vector_create_table` | Create a table optimized for vector storage with JSON vector column.     |
+| `sqlite_vector_store`        | Store or update a vector in the database.                                |
+| `sqlite_vector_batch_store`  | Store multiple vectors in a batch operation.                             |
+| `sqlite_vector_search`       | Find similar vectors using cosine, euclidean, or dot product similarity. |
+| `sqlite_vector_get`          | Retrieve a vector by its ID.                                             |
+| `sqlite_vector_delete`       | Delete vectors by their IDs.                                             |
+| `sqlite_vector_count`        | Count vectors in a table.                                                |
+| `sqlite_vector_stats`        | Get statistics about vectors in a table.                                 |
+| `sqlite_vector_dimensions`   | Get the dimensions of vectors in a table.                                |
+| `sqlite_vector_normalize`    | Normalize a vector to unit length.                                       |
+| `sqlite_vector_distance`     | Calculate distance or similarity between two vectors.                    |
+
+---
+
+## admin (33 Native / 26 WASM tools + Code Mode)
+
+Database maintenance — backup/restore, PRAGMA, views, virtual tables, and transaction control.
+
+| Tool                             | Description                                                                                                                       |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `sqlite_backup`                  | Create a backup of the database to a file.                                                                                        |
+| `sqlite_analyze`                 | Analyze table statistics to improve query performance.                                                                            |
+| `sqlite_integrity_check`         | Check database integrity for corruption or errors.                                                                                |
+| `sqlite_optimize`                | Optimize database by reindexing and/or analyzing.                                                                                 |
+| `sqlite_restore`                 | Restore database from a backup file. WARNING: This replaces the current database.                                                 |
+| `sqlite_verify_backup`           | Verify a backup file's integrity without restoring it.                                                                            |
+| `sqlite_index_stats`             | Get detailed statistics for database indexes.                                                                                     |
+| `sqlite_pragma_compile_options`  | Get the compile-time options used to build SQLite. Use the `filter` parameter to reduce output (~50+ options by default).         |
+| `sqlite_pragma_database_list`    | List all attached databases.                                                                                                      |
+| `sqlite_pragma_optimize`         | Run `PRAGMA optimize` to improve query performance based on usage patterns.                                                       |
+| `sqlite_pragma_settings`         | Get or set a PRAGMA value.                                                                                                        |
+| `sqlite_pragma_table_info`       | Get detailed column information for a table.                                                                                      |
+| `sqlite_append_insight`          | Add a business insight to the `memo://insights` resource. Use this to capture key findings during data analysis.                  |
+| `sqlite_generate_series`         | Generate a series of numbers using `generate_series()` virtual table.                                                             |
+| `sqlite_create_view`             | Create a view based on a SELECT query.                                                                                            |
+| `sqlite_list_views`              | List all views in the database.                                                                                                   |
+| `sqlite_drop_view`               | Drop (delete) a view from the database.                                                                                           |
+| `sqlite_dbstat`                  | Get database storage statistics using dbstat virtual table.                                                                       |
+| `sqlite_vacuum`                  | Rebuild the database to reclaim space and optimize structure.                                                                     |
+| `sqlite_list_virtual_tables`     | List all virtual tables in the database.                                                                                          |
+| `sqlite_virtual_table_info`      | Get metadata about a specific virtual table.                                                                                      |
+| `sqlite_drop_virtual_table`      | Drop a virtual table.                                                                                                             |
+| `sqlite_create_csv_table`        | Create a virtual table from a CSV file. Requires the csv extension.                                                               |
+| `sqlite_analyze_csv_schema`      | Analyze a CSV file structure and infer column types. Uses a temporary virtual table.                                              |
+| `sqlite_create_rtree_table`      | Create an R-Tree virtual table for spatial indexing. Supports 2–5 dimensions.                                                     |
+| `sqlite_create_series_table`     | Create a table populated with a series of numbers. Unlike `generate_series`, this creates a persistent table.                     |
+| `sqlite_transaction_begin`       | Begin a new transaction. Use immediate or exclusive mode for write-heavy operations. `[NATIVE ONLY]`                              |
+| `sqlite_transaction_commit`      | Commit the current transaction, making all changes permanent. `[NATIVE ONLY]`                                                     |
+| `sqlite_transaction_rollback`    | Rollback the current transaction, discarding all changes. `[NATIVE ONLY]`                                                         |
+| `sqlite_transaction_savepoint`   | Create a savepoint within the current transaction for partial rollback. `[NATIVE ONLY]`                                           |
+| `sqlite_transaction_release`     | Release a savepoint, keeping the changes made since it was created. `[NATIVE ONLY]`                                               |
+| `sqlite_transaction_rollback_to` | Rollback to a savepoint, discarding changes made after it was created. `[NATIVE ONLY]`                                            |
+| `sqlite_transaction_execute`     | Execute multiple SQL statements in a single transaction. Automatically commits on success or rolls back on error. `[NATIVE ONLY]` |
+
+---
+
+## geo (11 Native / 4 WASM tools + Code Mode)
+
+Geospatial operations — Haversine distance/radius queries and SpatiaLite advanced GIS.
+
+| Tool                             | Description                                                                                                       |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `sqlite_geo_distance`            | Calculate the distance between two geographic points using Haversine formula.                                     |
+| `sqlite_geo_nearby`              | Find points within a radius of a center point.                                                                    |
+| `sqlite_geo_bounding_box`        | Find points within a rectangular bounding box.                                                                    |
+| `sqlite_geo_cluster`             | Cluster geographic points into grid cells.                                                                        |
+| `sqlite_spatialite_load`         | Load SpatiaLite extension for geospatial capabilities. Required before using other spatial tools. `[NATIVE ONLY]` |
+| `sqlite_spatialite_create_table` | Create a spatial table with geometry column using SpatiaLite. `[NATIVE ONLY]`                                     |
+| `sqlite_spatialite_query`        | Execute spatial SQL queries using SpatiaLite functions (`ST_Distance`, `ST_Within`, etc.). `[NATIVE ONLY]`        |
+| `sqlite_spatialite_analyze`      | Perform spatial analysis: nearest neighbor, point in polygon, distance matrix. `[NATIVE ONLY]`                    |
+| `sqlite_spatialite_index`        | Create, drop, or check spatial R-Tree index on geometry column. `[NATIVE ONLY]`                                   |
+| `sqlite_spatialite_transform`    | Perform geometry operations: buffer, intersection, union, centroid, simplify. `[NATIVE ONLY]`                     |
+| `sqlite_spatialite_import`       | Import geometry data from WKT or GeoJSON into a spatial table. `[NATIVE ONLY]`                                    |
+
+---
+
+## introspection (9 tools + Code Mode)
+
+Read-only schema analysis — dependency graphs, cascade simulation, diagnostics, and migration risk assessment.
+
+| Tool                         | Description                                                                                                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sqlite_dependency_graph`    | Build a foreign key dependency graph showing relationships between all tables. Returns nodes (tables), edges (FK references), circular dependency detection, and root/leaf table identification. |
+| `sqlite_topological_sort`    | Generate a safe DDL execution order for tables based on foreign key dependencies. `create` direction lists parent tables first; `drop` direction lists child tables first.                       |
+| `sqlite_cascade_simulator`   | Simulate the impact of a DELETE, DROP, or TRUNCATE on a table. Shows which tables would be affected through cascading foreign key actions, with severity scoring.                                |
+| `sqlite_schema_snapshot`     | Generate a comprehensive snapshot of the database schema — tables, views, indexes, and triggers — in a single call.                                                                              |
+| `sqlite_constraint_analysis` | Analyze database schema for constraint health issues: missing primary keys, columns that should be NOT NULL, foreign keys without indexes, and tables that could benefit from FK relationships.  |
+| `sqlite_migration_risks`     | Analyze DDL statements for SQLite-specific migration risks. Detects ALTER TABLE limitations, large table operations, column type changes, destructive operations, and FTS5 rebuild requirements. |
+| `sqlite_storage_analysis`    | Analyze database storage health: fragmentation, size breakdown per table, and optimization recommendations.                                                                                      |
+| `sqlite_index_audit`         | Audit index effectiveness: find redundant indexes (prefix duplicates), missing foreign key indexes, and large tables without secondary indexes. Returns actionable suggestions.                  |
+| `sqlite_query_plan`          | Analyze a SQL query's execution plan. Returns structured EXPLAIN QUERY PLAN output with scan-type classification and optimization suggestions.                                                   |
+
+---
+
+## migration (6 tools + Code Mode)
+
+Schema migration tracking — initialize, record, apply, rollback, and audit migrations with SHA-256 deduplication.
+
+| Tool                        | Description                                                                                                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sqlite_migration_init`     | Initialize the migration tracking system by creating the `_mcp_migrations` table. Safe to call multiple times — idempotent.                                              |
+| `sqlite_migration_record`   | Record a migration that was applied externally (not executed by this tool). Uses SHA-256 hashing for dedup — duplicate SQL blocks are rejected.                          |
+| `sqlite_migration_apply`    | Execute migration SQL and record it atomically. If the SQL fails, no record is created. Uses SHA-256 hashing for dedup.                                                  |
+| `sqlite_migration_rollback` | Roll back a migration by ID or version. Requires that rollback SQL was recorded with the migration. Supports dry-run mode to preview the rollback SQL without executing. |
+| `sqlite_migration_history`  | Query migration history with optional filters by status and source system. Supports pagination.                                                                          |
+| `sqlite_migration_status`   | Get a summary of migration tracking state — latest version, counts by status, and unique source systems.                                                                 |

package/tsconfig.test.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["src/**/*.ts", "src/**/*.test.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/adapters/DatabaseAdapter.d.ts

@@ -1,141 +0,0 @@
-/**
- * db-mcp - Database Adapter Interface
- *
- * Abstract base class for SQLite database adapters.
- * Provides a consistent interface for SQLite database operations
- * across WASM and native backend variants.
- */
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { DatabaseConfig, DatabaseType, HealthStatus, QueryResult, SchemaInfo, TableInfo, AdapterCapabilities, ToolDefinition, ResourceDefinition, PromptDefinition, RequestContext, ToolGroup, ToolFilterConfig } from "../types/index.js";
-/**
- * Abstract base class for database adapters
- */
-export declare abstract class DatabaseAdapter {
-    /** Database type identifier */
-    abstract readonly type: DatabaseType;
-    /** Human-readable adapter name */
-    abstract readonly name: string;
-    /** Adapter version */
-    abstract readonly version: string;
-    /** Connection status */
-    protected connected: boolean;
-    /** Database configuration */
-    protected config: DatabaseConfig | null;
-    /**
-     * Connect to the database
-     * @param config - Database connection configuration
-     */
-    abstract connect(config: DatabaseConfig): Promise<void>;
-    /**
-     * Disconnect from the database
-     */
-    abstract disconnect(): Promise<void>;
-    /**
-     * Check if connected to the database
-     */
-    isConnected(): boolean;
-    /**
-     * Get health status of the database connection
-     */
-    abstract getHealth(): Promise<HealthStatus>;
-    /**
-     * Execute a read-only query (SELECT)
-     * @param sql - SQL query string
-     * @param params - Query parameters for prepared statements
-     */
-    abstract executeReadQuery(sql: string, params?: unknown[]): Promise<QueryResult>;
-    /**
-     * Execute a write query (INSERT, UPDATE, DELETE)
-     * @param sql - SQL query string
-     * @param params - Query parameters for prepared statements
-     * @param skipValidation - Skip security validation (for trusted internal operations)
-     */
-    abstract executeWriteQuery(sql: string, params?: unknown[], skipValidation?: boolean): Promise<QueryResult>;
-    /**
-     * Execute any query (for admin operations)
-     * @param sql - SQL query string
-     * @param params - Query parameters for prepared statements
-     */
-    abstract executeQuery(sql: string, params?: unknown[]): Promise<QueryResult>;
-    /**
-     * Get full database schema information
-     */
-    abstract getSchema(): Promise<SchemaInfo>;
-    /**
-     * List all tables in the database
-     */
-    abstract listTables(): Promise<TableInfo[]>;
-    /**
-     * Describe a specific table's structure
-     * @param tableName - Name of the table
-     */
-    abstract describeTable(tableName: string): Promise<TableInfo>;
-    /**
-     * List available schemas/databases
-     */
-    abstract listSchemas(): Promise<string[]>;
-    /**
-     * Get adapter capabilities
-     */
-    abstract getCapabilities(): AdapterCapabilities;
-    /**
-     * Get supported tool groups for this adapter
-     */
-    abstract getSupportedToolGroups(): ToolGroup[];
-    /**
-     * Get all tool definitions for this adapter
-     */
-    abstract getToolDefinitions(): ToolDefinition[];
-    /**
-     * Get all resource definitions for this adapter
-     */
-    abstract getResourceDefinitions(): ResourceDefinition[];
-    /**
-     * Get all prompt definitions for this adapter
-     */
-    abstract getPromptDefinitions(): PromptDefinition[];
-    /**
-     * Register tools with the MCP server
-     * @param server - MCP server instance
-     * @param filterConfig - Tool filter configuration
-     */
-    registerTools(server: McpServer, filterConfig: ToolFilterConfig): void;
-    /**
-     * Register a single tool with the MCP server
-     */
-    protected abstract registerTool(server: McpServer, tool: ToolDefinition): void;
-    /**
-     * Register resources with the MCP server
-     */
-    registerResources(server: McpServer): void;
-    /**
-     * Register a single resource with the MCP server
-     */
-    protected abstract registerResource(server: McpServer, resource: ResourceDefinition): void;
-    /**
-     * Register prompts with the MCP server
-     */
-    registerPrompts(server: McpServer): void;
-    /**
-     * Register a single prompt with the MCP server
-     */
-    protected abstract registerPrompt(server: McpServer, prompt: PromptDefinition): void;
-    /**
-     * Validate query for safety (SQL injection prevention)
-     * @param sql - SQL query to validate
-     * @param isReadOnly - Whether to enforce read-only restrictions
-     */
-    protected validateQuery(sql: string, isReadOnly: boolean): void;
-    /**
-     * Create a request context for tool execution
-     * @param requestId Optional request ID for tracing
-     * @param server Optional MCP Server instance for progress notifications
-     * @param progressToken Optional progress token from client request _meta
-     */
-    protected createContext(requestId?: string, server?: unknown, progressToken?: string | number): RequestContext;
-    /**
-     * Get adapter info for logging/debugging
-     */
-    getInfo(): Record<string, unknown>;
-}
-//# sourceMappingURL=DatabaseAdapter.d.ts.map

package/dist/adapters/DatabaseAdapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DatabaseAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/DatabaseAdapter.ts"],"names":[],"mappings":"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"}