db-mcp 1.1.0 → 2.0.0

package/test-server/test-tool-groups/test-migration.md

@@ -0,0 +1,193 @@
+# db-mcp Tool Group Testing: [migration]
+
+> [!IMPORTANT]
+> **Do not track progress in this file.** Track your test progress, coverage matrix, and findings in your internal task tracking system (artifact). However, you SHOULD edit this file to fix any factual errors, broken code, or incorrect assertions in the test prompts.
+> If there is nothing to fix, don't update UNRELEASED.md.
+> We're currently testing Native mode.
+
+## WASM Mode
+
+> When testing against a **WASM backend** (`sqlite-wasm` / sql.js): All 6 migration tools are fully WASM-compatible. No items to skip or adjust.
+
+**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 **migration** tool group specified in the group-specific checklist below using live MCP server tool calls directly — not scripts/terminal.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+**Note** If temp tables are present from a previous test pass, it's because the database is locked. Ignore them.
+
+## 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**. Report the response size in KB and suggest a concrete optimization.
+
+## Test Database Schema
+
+| 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)                                                                        |
+
+> **Note:** When testing `sqlite_execute_code`, do **not** pass `readonly: true` unless specifically testing read-only filtering.
+
+## 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**.
+
+1. Use existing `test_*` tables for read operations
+2. Report all failures, unexpected behaviors, or unnecessarily large payloads
+3. Do not mention what already works well or issues documented in help resources
+4. **Error path testing**: For **every** tool, test (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}`.
+5. **Output schema testing**: For tools with `outputSchema`, confirm valid calls return structured JSON.
+6. **Deterministic checklist first**: Complete ALL items before freeform exploration.
+7. **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+## Structured Error Response Pattern
+
+```json
+{ "success": false, "error": "Human-readable error message" }
+```
+
+| 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, `isError: true` — no `success` field | Bug — report as ❌ |
+
+### Zod Validation Errors
+
+**Zod refinement leak pattern:** `.partial()` does NOT strip `.min(N)` / `.max(N)` refinements. **Fix:** Remove refinements from schema, validate inside handler.
+
+- Raw MCP error (no `success` field) → report as ❌
+- `{success: false, error: "..."}` → correct
+- Successful response for invalid input → report as ⚠️
+
+### Output Schema Validation Errors
+
+If valid inputs return raw MCP `-32602` mentioning "output schema", report as ❌.
+
+### Error Consistency Audit
+
+1. Raw error instead of `{success: false}` → ❌
+2. Must use `error` field name
+3. Orphaned/inline output schemas → ⚠️
+
+### Split Schema Pattern Verification
+
+Verify parameter visibility and alias acceptance.
+
+---
+
+## Group Focus: migration
+
+> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
+
+> **⚠️ After testing, run `Set-Location C:\Users\chris\Desktop\db-mcp\test-server; .\reset-database.ps1`** — migration testing creates the `_mcp_migrations` tracking table and modifies the database schema. Always reset the database after completing migration tests.
+
+### Built-in Tools (3)
+
+1. server_info
+2. server_health
+3. list_adapters
+
+### migration Group Tools (6)
+
+4. sqlite_migration_init
+5. sqlite_migration_record
+6. sqlite_migration_apply
+7. sqlite_migration_rollback
+8. sqlite_migration_history
+9. sqlite_migration_status
+10. sqlite_execute_code
+
+**Checklist — Initialization & Recording:**
+
+1. `sqlite_migration_init` → `{success: true}`, creates `_mcp_migrations` table (idempotent — safe to call multiple times)
+2. `sqlite_migration_init` → call again to verify idempotency (should succeed without error)
+3. `sqlite_migration_status` → verify empty state (no migrations applied yet)
+4. `sqlite_migration_record({version: "1.0.0", description: "Create temp table", sql: "CREATE TABLE temp_migration_test (id INTEGER PRIMARY KEY, name TEXT)"})` → recorded (not executed — only logged)
+5. `sqlite_migration_status` → verify migration count incremented
+6. `sqlite_migration_history` → verify migration 1.0.0 listed with status "recorded"
+
+**Checklist — Apply & Execute:**
+
+7. `sqlite_migration_apply({version: "1.0.1", description: "Create temp migration table", sql: "CREATE TABLE temp_migration_applied (id INTEGER PRIMARY KEY, value TEXT)"})` → applied (SQL executed AND recorded)
+8. Verify: `sqlite_read_query({query: "SELECT name FROM sqlite_master WHERE name = 'temp_migration_applied'"})` → table exists
+9. `sqlite_migration_history` → verify both 1.0.0 and 1.0.1 listed
+10. `sqlite_migration_status` → verify count shows 2 migrations
+
+**Checklist — SHA-256 Deduplication:**
+
+11. `sqlite_migration_record({version: "1.0.2", description: "Duplicate test", sql: "CREATE TABLE temp_migration_test (id INTEGER PRIMARY KEY, name TEXT)"})` → should fail (duplicate SQL detected via SHA-256 hash)
+
+**Checklist — Rollback:**
+
+12. `sqlite_migration_rollback({version: "1.0.1"})` → report behavior (rollback requires rollback SQL to have been recorded; if none was provided during apply, rollback should return an informative error)
+13. `sqlite_migration_apply({version: "1.0.3", description: "With rollback", sql: "CREATE TABLE temp_migration_rollback (id INTEGER PRIMARY KEY)", rollbackSql: "DROP TABLE IF EXISTS temp_migration_rollback"})` → applied with rollback SQL stored
+14. `sqlite_migration_rollback({version: "1.0.3"})` → should execute the rollback SQL
+15. Verify: `sqlite_read_query({query: "SELECT name FROM sqlite_master WHERE name = 'temp_migration_rollback'"})` → table should NOT exist
+16. `sqlite_migration_rollback({version: "1.0.3", dryRun: true})` → report behavior (preview mode)
+
+**Code mode testing:**
+
+17. `sqlite_execute_code({code: "const result = await sqlite.migration.migrationStatus(); return result;"})` → migration status summary
+18. `sqlite_execute_code({code: "const result = await sqlite.migration.migrationHistory(); return result;"})` → migration history list
+
+**Error path testing:**
+
+🔴 19. `sqlite_migration_apply({version: "bad version!", description: "Invalid", sql: "SELECT 1"})` → report behavior (invalid version format)
+🔴 20. `sqlite_migration_rollback({version: "nonexistent_version"})` → structured error
+
+**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
+
+🔴 21. `sqlite_migration_init({})` → handler error (or success if no required params)
+🔴 22. `sqlite_migration_record({})` → handler error
+🔴 23. `sqlite_migration_apply({})` → handler error
+🔴 24. `sqlite_migration_rollback({})` → handler error
+🔴 25. `sqlite_migration_history({})` → handler error (or success if no required params)
+🔴 26. `sqlite_migration_status({})` → handler error (or success if no required params)
+
+---
+
+## Post-Test Procedures
+
+### After Testing
+
+1. **⚠️ Reset database**: Run `Set-Location C:\Users\chris\Desktop\db-mcp\test-server; .\reset-database.ps1` to clean up migration artifacts (`_mcp_migrations` table and any `temp_migration_*` tables)
+2. **Triage findings**: Create implementation plan if issues found
+3. **Scope of fixes**: Handler code, server-instructions, test database, this prompt
+4. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+5. **Commit**: Stage and commit — do NOT push
+6. **Live re-test**: After server rebuild
+7. **Final summary**: After testing/re-testing
+
+---
+
+## Troubleshooting
+
+### Database is locked / file in use
+
+1. Check for Node.js processes: `Get-CimInstance Win32_Process -Filter "Name = 'node.exe'"`
+2. WAL/journal files are normal
+
+### Migration state is dirty
+
+If previous migration test left the database in a bad state:
+
+1. Run `Set-Location C:\Users\chris\Desktop\db-mcp\test-server; .\reset-database.ps1` to regenerate the test database from `test-database.sql`
+2. This drops and recreates all tables, including removing `_mcp_migrations`
+
+### Reset script fails
+
+1. Run with `-Verbose`: `.\reset-database.ps1 -Verbose`
+2. If `sqlite3` is not in PATH, the script falls back to Node.js with `better-sqlite3`

package/test-server/test-tool-groups/test-stats-advanced.md

@@ -0,0 +1,118 @@
+# db-mcp Tool Group Testing: [stats-advanced]
+
+> [!IMPORTANT]
+> **Do not track progress in this file.** Track your test progress, coverage matrix, and findings in your internal task tracking system (artifact). However, you SHOULD edit this file to fix any factual errors, broken code, or incorrect assertions in the test prompts.
+> If there is nothing to fix, don't update UNRELEASED.md.
+> We're currently testing Native mode.
+
+## WASM Mode
+
+> When testing against a **WASM backend** (`sqlite-wasm` / sql.js), apply these adjustments:
+>
+> - **Skip window function tools** (items 1-6: `sqlite_window_row_number`, `sqlite_window_rank`, `sqlite_window_lag_lead`, `sqlite_window_running_total`, `sqlite_window_moving_avg`, `sqlite_window_ntile`) — `[NATIVE ONLY]`. These tools are not registered in WASM.
+> - **Skip checklist items** 1-6.
+> - **Skip Zod items** 7-12.
+
+**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 **stats-advanced** tool group specified in the group-specific checklist below using live MCP server tool calls directly — not scripts/terminal.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+**Note** If temp tables are present from a previous test pass, it's because the database is locked. Ignore them.
+
+## 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.
+
+## Test Database Schema
+
+| 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)                                                                        |
+
+## 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**.
+
+1. Use existing `test_*` tables for read operations
+2. Report all failures, unexpected behaviors, improvement opportunities, or unnecessarily large payloads
+3. **Error path testing**: For **every** tool, test at least **two** invalid inputs: (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}` — NOT a raw MCP error frame.
+4. **Output schema testing**: For **every** tool with an `outputSchema`, confirm valid happy-path calls return structured JSON — NOT a raw MCP `-32602` error.
+
+## Structured Error Response Pattern
+
+```json
+{ "success": false, "error": "Human-readable error message" }
+```
+
+| 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, `isError: true` — no `success` field | Bug — report as ❌ |
+
+### Zod Validation Errors
+
+**Zod refinement leak pattern:** `.partial()` does NOT strip `.min(N)` / `.max(N)` refinements. **Fix:** Remove refinements from schema, validate inside handler.
+
+### Output Schema Validation Errors
+
+If valid inputs return raw MCP `-32602` mentioning "output schema", report as ❌.
+
+---
+
+## Group Focus: stats-advanced
+
+> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
+
+### stats-advanced Group Tools (6)
+
+1. sqlite_window_row_number `[NATIVE ONLY]`
+2. sqlite_window_rank `[NATIVE ONLY]`
+3. sqlite_window_lag_lead `[NATIVE ONLY]`
+4. sqlite_window_running_total `[NATIVE ONLY]`
+5. sqlite_window_moving_avg `[NATIVE ONLY]`
+6. sqlite_window_ntile `[NATIVE ONLY]`
+
+**Checklist:**
+
+**Window functions `[NATIVE ONLY]`:**
+
+1. `sqlite_window_row_number({table: "test_products", orderBy: "price DESC"})` → products ranked by price
+2. `sqlite_window_rank({table: "test_products", orderBy: "price DESC"})` → rank with ties
+3. `sqlite_window_running_total({table: "test_orders", column: "total_price", orderBy: "order_date"})` → cumulative totals
+4. `sqlite_window_moving_avg({table: "test_measurements", column: "temperature", windowSize: 5, orderBy: "measured_at"})` → moving averages
+5. `sqlite_window_lag_lead({table: "test_orders", column: "total_price", direction: "lag", orderBy: "order_date"})` → lag/lead values
+6. `sqlite_window_ntile({table: "test_products", buckets: 4, orderBy: "price"})` → quartile assignments
+
+**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
+
+🔴 7. `sqlite_window_row_number({})` `[NATIVE ONLY]` → handler error
+🔴 8. `sqlite_window_rank({})` `[NATIVE ONLY]` → handler error
+🔴 9. `sqlite_window_lag_lead({})` `[NATIVE ONLY]` → handler error
+🔴 10. `sqlite_window_running_total({})` `[NATIVE ONLY]` → handler error
+🔴 11. `sqlite_window_moving_avg({})` `[NATIVE ONLY]` → handler error
+🔴 12. `sqlite_window_ntile({})` `[NATIVE ONLY]` → handler error
+
+---
+
+## Post-Test Procedures
+
+1. **Triage findings**: Create implementation plan if issues found
+2. **Scope of fixes**: Handler code, server-instructions, test database, this prompt
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Live re-test**: After server rebuild
+6. **Final summary**: After testing/re-testing

package/test-server/test-tool-groups/test-stats-basic.md

@@ -0,0 +1,156 @@
+# db-mcp Tool Group Testing: [stats-basic]
+
+> [!IMPORTANT]
+> **Do not track progress in this file.** Track your test progress, coverage matrix, and findings in your internal task tracking system (artifact). However, you SHOULD edit this file to fix any factual errors, broken code, or incorrect assertions in the test prompts.
+> If there is nothing to fix, don't update UNRELEASED.md.
+> We're currently testing Native mode.
+
+## WASM Mode
+
+> When testing against a **WASM backend** (`sqlite-wasm` / sql.js): All 16 tools in this basic stats suite are fully WASM-compatible. No items to skip or adjust.
+
+**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 **stats-basic** tool group specified in the group-specific checklist below using live MCP server tool calls directly — not scripts/terminal.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+**Note** If temp tables are present from a previous test pass, it's because the database is locked. Ignore them.
+
+## 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**. Report the response size in KB and suggest a concrete optimization.
+
+## Test Database Schema
+
+| 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)                                                                        |
+
+## 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**.
+
+1. Use existing `test_*` tables for read operations
+2. Create temporary tables with `temp_*` prefix for write operations
+3. Report all failures, unexpected behaviors, improvement opportunities, or unnecessarily large payloads
+4. Do not mention what already works well or issues well documented in help resources
+5. **Error path testing**: For **every** tool, test at least **two** invalid inputs: (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}` — NOT a raw MCP error frame.
+6. **Output schema testing**: For **every** tool with an `outputSchema`, confirm valid happy-path calls return structured JSON — NOT a raw MCP `-32602` error.
+7. **Deterministic checklist first**: Complete ALL items before freeform exploration.
+8. **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+## Structured Error Response Pattern
+
+```json
+{ "success": false, "error": "Human-readable error message" }
+```
+
+| 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, `isError: true` — no `success` field | Bug — report as ❌ |
+
+### Zod Validation Errors
+
+**Zod refinement leak pattern:** `.partial()` does NOT strip `.min(N)` / `.max(N)` refinements. **Fix:** Remove refinements from schema, validate inside handler.
+
+### Output Schema Validation Errors
+
+If valid inputs return raw MCP `-32602` mentioning "output schema", report as ❌.
+
+---
+
+## Group Focus: stats-basic
+
+> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
+
+### stats-basic Group Tools (16)
+
+1. sqlite_stats_basic
+2. sqlite_stats_count
+3. sqlite_stats_group_by
+4. sqlite_stats_histogram
+5. sqlite_stats_percentile
+6. sqlite_stats_correlation
+7. sqlite_stats_top_n
+8. sqlite_stats_distinct
+9. sqlite_stats_summary
+10. sqlite_stats_frequency
+11. sqlite_stats_outliers
+12. sqlite_stats_regression
+13. sqlite_stats_hypothesis
+14. sqlite_stats_detect_anomalies
+15. sqlite_stats_detect_bloat
+16. sqlite_stats_detect_schema_risks
+17. sqlite_execute_code
+
+**Checklist:**
+
+1. `sqlite_stats_basic({table: "test_measurements", column: "temperature"})` → verify `count: 200`, `min`, `max`, `avg` present
+2. `sqlite_stats_count({table: "test_products"})` → `{count: 16}`
+3. `sqlite_stats_count({table: "test_products", column: "category", distinct: true})` → distinct category count (electronics, accessories, office = 3)
+4. `sqlite_stats_group_by({table: "test_measurements", groupByColumn: "sensor_id", valueColumn: "temperature", stat: "avg"})` → 5 groups (sensor_id 1-5) with average temperatures
+5. `sqlite_stats_histogram({table: "test_measurements", column: "temperature", buckets: 5})` → 5 buckets
+6. `sqlite_stats_percentile({table: "test_measurements", column: "temperature", percentiles: [25, 50, 75, 90]})` → 4 percentile values
+7. `sqlite_stats_correlation({table: "test_measurements", column1: "temperature", column2: "humidity"})` → correlation value between -1 and 1
+8. `sqlite_stats_top_n({table: "test_products", column: "price", n: 3, orderDirection: "desc"})` → top 3 most expensive products
+9. `sqlite_stats_distinct({table: "test_locations", column: "city"})` → distinct city count (6)
+10. `sqlite_stats_summary({table: "test_measurements", columns: ["temperature", "humidity", "pressure"]})` → summaries array with 3 entries
+11. `sqlite_stats_frequency({table: "test_events", column: "event_type"})` → distribution
+12. `sqlite_stats_outliers({table: "test_measurements", column: "temperature"})` → outlier detection result
+13. `sqlite_stats_regression({table: "test_measurements", xColumn: "temperature", yColumn: "humidity", degree: 1})` → regression coefficients
+14. `sqlite_stats_hypothesis({table: "test_measurements", column: "temperature", testType: "ttest_one", expectedMean: 25})` → verify `statistic` and `pValue` present
+
+**Code mode testing:**
+
+15. `sqlite_execute_code({code: "const result = await sqlite.stats.statsBasic({table: 'test_measurements', column: 'temperature'}); return result;"})` → verify `count: 200`, `min`, `max`, `avg` present
+16. `sqlite_execute_code({code: "const result = await sqlite.stats.statsPercentile({table: 'test_measurements', column: 'temperature', percentiles: [50]}); return result;"})` → median value
+
+**Error path testing:**
+
+🔴 17. `sqlite_stats_basic({table: "nonexistent_table_xyz", column: "x"})` → structured error
+🔴 18. `sqlite_stats_correlation({table: "test_products", column1: "name", column2: "description"})` → error about non-numeric columns
+
+**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
+
+🔴 19. `sqlite_stats_basic({})` → handler error
+🔴 20. `sqlite_stats_count({})` → handler error
+🔴 21. `sqlite_stats_group_by({})` → handler error
+🔴 22. `sqlite_stats_histogram({})` → handler error
+🔴 23. `sqlite_stats_percentile({})` → handler error
+🔴 24. `sqlite_stats_correlation({})` → handler error
+🔴 25. `sqlite_stats_top_n({})` → handler error
+🔴 26. `sqlite_stats_distinct({})` → handler error
+🔴 27. `sqlite_stats_summary({})` → handler error
+🔴 28. `sqlite_stats_frequency({})` → handler error
+🔴 29. `sqlite_stats_outliers({})` → handler error
+🔴 30. `sqlite_stats_regression({})` → handler error
+🔴 31. `sqlite_stats_hypothesis({})` → handler error
+🔴 32. `sqlite_stats_detect_anomalies({})` → handler error
+✅ 33. `sqlite_stats_detect_bloat({})` → success (no required params)
+✅ 34. `sqlite_stats_detect_schema_risks({})` → success (no required params)
+🔴 35. `sqlite_execute_code({})` → handler error
+
+---
+
+## Post-Test Procedures
+
+1. **Triage findings**: Create implementation plan if issues found
+2. **Scope of fixes**: Handler code, server-instructions, test database, this prompt
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Live re-test**: After server rebuild
+6. **Final summary**: After testing/re-testing

package/test-server/test-tool-groups/test-text-advanced.md

@@ -0,0 +1,169 @@
+# db-mcp Tool Group Testing: [text-advanced]
+
+> [!IMPORTANT]
+> **Do not track progress in this file.** Track your test progress, coverage matrix, and findings in your internal task tracking system (artifact). However, you SHOULD edit this file to fix any factual errors, broken code, or incorrect assertions in the test prompts.
+> If there is nothing to fix, don't update UNRELEASED.md.
+> We're currently testing Native mode.
+
+## WASM Mode
+
+> When testing against a **WASM backend** (`sqlite-wasm` / sql.js), apply these adjustments:
+>
+> - **Skip FTS5 tools** (items 5-9: `sqlite_fts_create`, `sqlite_fts_search`, `sqlite_fts_rebuild`, `sqlite_fts_match_info`, `sqlite_fts_headline`) — `[NATIVE ONLY]`. These tools are not registered in WASM and direct calls will fail with "unknown tool".
+> - **Skip FTS5 checklist items** 6-11 — all require FTS5 tools.
+> - **Skip error items** for FTS5 (item 14).
+> - **Skip Zod items** for FTS5 (items 20-24).
+
+**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 **text-advanced** tool group specified in the group-specific checklist below using live MCP server tool calls directly — not scripts/terminal.
+
+**Step 3:** The agent should update C:\Users\chris\Desktop\db-mcp\UNRELEASED.md with any/all changes/fixes.
+
+**Note** If temp tables are present from a previous test pass, it's because the database is locked. Ignore them.
+
+## 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.
+
+## 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)                                                                        |
+
+## 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.
+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. **Error path testing**: For **every** tool, test at least **two** invalid inputs: (a) a domain error and (b) a **Zod validation error** (call the tool with `{}` empty params). Both must return a **structured handler error** (`{success: false, error: "..."}`) — NOT a raw MCP error frame.
+6. **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 produce the same `-32602` code as input errors but are only caught with valid inputs.
+7. **Code Over Docs**: Fix the handler code if standards (Structured Errors/Zod) are violated. Do NOT change docs/prompts to accommodate broken code.
+
+## Structured Error Response Pattern
+
+All tools should return errors as structured objects instead of throwing. The expected pattern:
+
+```json
+{ "success": false, "error": "Human-readable error message" }
+```
+
+### Handler Error vs MCP Error — How to Distinguish
+
+| 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 ❌ |
+
+### 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.
+
+**Fix:** Remove ALL `.min(N)` / `.max(N)` refinements from the schema and validate inside the handler instead.
+
+### 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.
+
+**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", report as ❌ with both the tool name and the missing field(s).
+
+### Error Consistency Audit
+
+1. **Throw-vs-return**: If a tool throws a raw error instead of returning `{success: false}`, report as ❌.
+2. **Error field name**: All `{success: false}` responses should use `error` as the field name.
+3. **Zod validation leaks**: If calling a tool with 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", report as ❌.
+
+---
+
+## Group Focus: text-advanced
+
+> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
+
+> **FTS Testing Notes:** After `sqlite_fts_create`, always call `sqlite_fts_rebuild` before searching. `test_articles` searchable terms: `SQLite`, `database`, `JSON`, `FTS`, `vector`, `API`, `search`, `MCP`.
+
+### text-advanced Group Tools (9)
+
+1. sqlite_fuzzy_match
+2. sqlite_phonetic_match
+3. sqlite_advanced_search
+4. sqlite_text_sentiment
+5. sqlite_fts_create `[NATIVE ONLY]`
+6. sqlite_fts_search `[NATIVE ONLY]`
+7. sqlite_fts_rebuild `[NATIVE ONLY]`
+8. sqlite_fts_match_info `[NATIVE ONLY]`
+9. sqlite_fts_headline `[NATIVE ONLY]`
+
+**Checklist:**
+
+1. `sqlite_fuzzy_match({table: "test_products", column: "name", search: "Laptp", maxDistance: 3})` → results include `Laptop Pro 15`
+2. `sqlite_fuzzy_match({table: "test_products", column: "name", search: "Laptp", tokenize: false})` → verify behavior without tokenization
+3. `sqlite_phonetic_match({table: "test_products", column: "name", search: "Labtop"})` → should find `Laptop Pro 15` via Soundex (both produce L131)
+4. `sqlite_phonetic_match({table: "test_products", column: "name", search: "Labtop", algorithm: "metaphone"})` → test metaphone algorithm
+5. `sqlite_advanced_search({table: "test_products", column: "name", searchTerm: "keyboard", techniques: ["exact", "fuzzy", "phonetic"]})` → should find `Mechanical Keyboard`
+6. `sqlite_advanced_search({table: "test_products", column: "name", searchTerm: "Labtop", techniques: ["phonetic"]})` → test with single technique
+
+**FTS5 tools `[NATIVE ONLY]`:**
+
+7. `sqlite_fts_create({sourceTable: "test_users", columns: ["username", "bio"], ftsTable: "temp_users_fts"})` → FTS5 virtual table created
+8. `sqlite_fts_rebuild({table: "temp_users_fts"})` → rebuild index before searching
+9. `sqlite_fts_search({table: "temp_users_fts", query: "test*"})` → verify results from test_users data (prefix query needed since no standalone "test" token exists)
+10. Cleanup: `sqlite_drop_table({table: "temp_users_fts"})` (drop the temp FTS table using sqlite_write_query or core drop_table)
+11. `sqlite_fts_search({table: "test_articles_fts", query: "SQLite"})` → at least 1 result (article 1: "Introduction to SQLite")
+12. `sqlite_fts_search({table: "test_articles_fts", query: "MCP protocol"})` → matches article 3: "The Model Context Protocol Explained"
+13. `sqlite_fts_search({table: "test_articles_fts", query: "nonexistent_term_xyz"})` → 0 results
+14. `sqlite_fts_match_info({table: "test_articles_fts", query: "database"})` → match info with scoring data
+15. `sqlite_fts_rebuild({table: "test_articles_fts"})` → success
+
+**Error path testing:**
+
+🔴 16. `sqlite_fuzzy_match({table: "test_users", column: "nonexistent_col", search: "test"})` → structured error with code `COLUMN_NOT_FOUND`
+🔴 17. `sqlite_fts_search({table: "nonexistent_fts_xyz", query: "test"})` `[NATIVE ONLY]` → structured error
+
+**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
+
+🔴 18. `sqlite_fuzzy_match({})` → handler error
+🔴 19. `sqlite_phonetic_match({})` → handler error
+🔴 20. `sqlite_advanced_search({})` → handler error
+🔴 21. `sqlite_text_sentiment({})` → handler error
+🔴 22. `sqlite_fts_create({})` `[NATIVE ONLY]` → handler error
+🔴 23. `sqlite_fts_search({})` `[NATIVE ONLY]` → handler error
+🔴 24. `sqlite_fts_rebuild({})` `[NATIVE ONLY]` → handler error
+🔴 25. `sqlite_fts_match_info({})` `[NATIVE ONLY]` → handler error
+🔴 26. `sqlite_fts_headline({})` `[NATIVE ONLY]` → handler error
+
+---
+
+## 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. If the plan requires no user decisions, proceed directly to implementation
+2. **Scope of fixes** includes corrections to handler code, `src/constants/server-instructions/*.md`, test database, or this prompt
+3. **Validate**: Instruct the user to run the test suite (Vitest/Playwright), lint, and typecheck. Do NOT run them yourself.
+4. **Commit**: Stage and commit — do NOT push
+5. **Live re-test**: Test fixes with direct MCP tool calls after server rebuild
+6. **Final summary**: Provide summary after testing/re-testing confirms fixes