db-mcp 2.0.0 → 3.0.1

package/test-server/test-tool-groups/test-geo-haversine.md

@@ -1,130 +0,0 @@
-# db-mcp Tool Group Testing: [geo-haversine]
-
-> [!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 4 Haversine 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 **geo-haversine** 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. Create temporary tables with `temp_*` prefix for write operations
-3. **Error path testing**: For **every** tool, test (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}`.
-4. **Output schema testing**: For tools with `outputSchema`, confirm valid calls return structured JSON.
-
-## 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. This is **especially important for geo tools** with coordinate params like `.min(-90).max(90)`. **Fix:** Remove refinements from schema, validate inside handler (see `validateCoordinates()` in `geo.ts`).
-
-### Output Schema Validation Errors
-
-If valid inputs return raw MCP `-32602` mentioning "output schema", report as ❌.
-
----
-
-## Group Focus: geo-haversine
-
-> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
-
-### geo-haversine Group Tools (5)
-
-1. sqlite_geo_distance
-2. sqlite_geo_nearby
-3. sqlite_geo_bounding_box
-4. sqlite_geo_cluster
-5. sqlite_execute_code
-
-**Test data:** `test_locations` (15 rows). Key coordinates:
-
-| Name               | City          | Lat      | Lng       |
-| ------------------ | ------------- | -------- | --------- |
-| Central Park       | New York      | 40.7829  | -73.9654  |
-| Eiffel Tower       | Paris         | 48.8584  | 2.2945    |
-| Big Ben            | London        | 51.5007  | -0.1246   |
-| Tokyo Tower        | Tokyo         | 35.6586  | 139.7454  |
-| Sydney Opera House | Sydney        | -33.8568 | 151.2153  |
-| Golden Gate Bridge | San Francisco | 37.8199  | -122.4783 |
-
-**Checklist:**
-
-1. `sqlite_geo_distance({lat1: 40.7829, lon1: -73.9654, lat2: 48.8584, lon2: 2.2945})` → NYC to Paris ≈ 5,837 km (verify within ±50 km)
-2. `sqlite_geo_distance({lat1: 40.7829, lon1: -73.9654, lat2: 37.8199, lon2: -122.4783})` → NYC to SF ≈ 4,130 km
-3. `sqlite_geo_nearby({table: "test_locations", latColumn: "latitude", lonColumn: "longitude", centerLat: 40.7580, centerLon: -73.9855, radius: 10})` → should find NYC locations (Central Park, Empire State Building, Times Square) — 3 results
-4. `sqlite_geo_nearby({table: "test_locations", latColumn: "latitude", lonColumn: "longitude", centerLat: 48.8584, centerLon: 2.2945, radius: 10})` → should find Paris locations (Eiffel Tower, Louvre, Notre-Dame) — 3 results
-5. `sqlite_geo_bounding_box({table: "test_locations", latColumn: "latitude", lonColumn: "longitude", minLat: 35, maxLat: 55, minLon: -130, maxLon: -70})` → US locations (NYC 3 + SF 1 = 4)
-6. `sqlite_geo_cluster({table: "test_locations", latColumn: "latitude", lonColumn: "longitude", gridSize: 5})` → ~5 clusters grouping by city proximity
-
-**Code mode testing:**
-
-7. `sqlite_execute_code({code: "const result = await sqlite.geo.distance({lat1: 40.7829, lon1: -73.9654, lat2: 48.8584, lon2: 2.2945}); return result;"})` → NYC to Paris ≈ 5,837 km
-8. `sqlite_execute_code({code: "const result = await sqlite.geo.nearby({table: 'test_locations', latColumn: 'latitude', lonColumn: 'longitude', centerLat: 40.758, centerLon: -73.9855, radius: 10}); return result;"})` → NYC locations
-
-**Error path testing:**
-
-🔴 9. `sqlite_geo_nearby({table: "nonexistent_table_xyz", latColumn: "lat", lonColumn: "lng", centerLat: 0, centerLon: 0, radius: 100})` → structured error
-🔴 10. `sqlite_geo_distance({lat1: 91, lon1: 0, lat2: 0, lon2: 0})` → must return `{success: false, error: "Invalid lat1: 91. Must be between -90 and 90."}` — structured handler error, NOT a raw MCP error. If this returns a raw MCP `-32602`, it is a Zod `.min()/.max()` refinement leak bug (see Zod refinement leak pattern above).
-
-**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
-
-🔴 11. `sqlite_geo_distance({})` → handler error
-🔴 12. `sqlite_geo_nearby({})` → handler error
-🔴 13. `sqlite_geo_bounding_box({})` → handler error
-🔴 14. `sqlite_geo_cluster({})` → 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-geo-spatialite.md

@@ -1,110 +0,0 @@
-# db-mcp Tool Group Testing: [geo-spatialite]
-
-> [!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 SpatiaLite tools** (items 1-7: `sqlite_spatialite_load`, `sqlite_spatialite_create_table`, `sqlite_spatialite_query`, `sqlite_spatialite_analyze`, `sqlite_spatialite_index`, `sqlite_spatialite_transform`, `sqlite_spatialite_import`) — `[NATIVE ONLY]`. These tools are not registered in WASM.
-> - **Skip all checklist items** — all require SpatiaLite.
-> - **Skip all Zod items** (SpatiaLite tools) — `[NATIVE 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 **geo-spatialite** 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.
-
-## 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. **Error path testing**: For **every** tool, test (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}`.
-4. **Output schema testing**: For tools with `outputSchema`, confirm valid calls return structured JSON.
-
-## 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: geo-spatialite
-
-> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
-
-### geo-spatialite Group Tools (7)
-
-1. sqlite_spatialite_load `[NATIVE ONLY]`
-2. sqlite_spatialite_create_table `[NATIVE ONLY]`
-3. sqlite_spatialite_query `[NATIVE ONLY]`
-4. sqlite_spatialite_analyze `[NATIVE ONLY]`
-5. sqlite_spatialite_index `[NATIVE ONLY]`
-6. sqlite_spatialite_transform `[NATIVE ONLY]`
-7. sqlite_spatialite_import `[NATIVE ONLY]`
-
-**Checklist:**
-
-**SpatiaLite tools `[NATIVE ONLY]`:**
-
-1. `sqlite_spatialite_load` → load SpatiaLite extension, verify version
-2. `sqlite_spatialite_create_table({tableName: "temp_spatial_test", geometryColumn: "geom", geometryType: "POINT", srid: 4326, additionalColumns: [{name: "name", type: "TEXT"}]})` → success
-3. `sqlite_spatialite_import({tableName: "temp_spatial_test", format: "wkt", data: "POINT(-73.9654 40.7829)", additionalData: {name: "Test Point"}})` → success
-4. `sqlite_spatialite_query({query: "SELECT name, AsText(geom) as geom_text FROM temp_spatial_test"})` → WKT geometry returned
-5. `sqlite_spatialite_transform({operation: "buffer", geometry1: "POINT(-73.9654 40.7829)", distance: 0.01, srid: 4326})` → buffered polygon
-6. `sqlite_spatialite_index({tableName: "temp_spatial_test", geometryColumn: "geom", action: "create"})` → R-Tree index created
-7. `sqlite_spatialite_analyze({analysisType: "spatial_extent", sourceTable: "temp_spatial_test", geometryColumn: "geom"})` → spatial extent
-8. Cleanup: drop R-Tree index (`sqlite_spatialite_index` with `action: "drop"`), then drop `temp_spatial_test`
-
-**Error path testing:**
-
-🔴 9. `sqlite_spatialite_query({query: "SELECT name FROM nonexistent_table_xyz"})` `[NATIVE ONLY]` → structured error
-
-**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
-
-🔴 10. `sqlite_spatialite_create_table({})` `[NATIVE ONLY]` → handler error
-🔴 11. `sqlite_spatialite_query({})` `[NATIVE ONLY]` → handler error
-🔴 12. `sqlite_spatialite_analyze({})` `[NATIVE ONLY]` → handler error
-🔴 13. `sqlite_spatialite_index({})` `[NATIVE ONLY]` → handler error
-🔴 14. `sqlite_spatialite_transform({})` `[NATIVE ONLY]` → handler error
-🔴 15. `sqlite_spatialite_import({})` `[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-introspection-diagnostics.md

@@ -1,123 +0,0 @@
-# db-mcp Tool Group Testing: [introspection-diagnostics]
-
-> [!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 3 diagnostics tools are fully WASM-compatible. No items to skip.
-
-**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 **introspection-diagnostics** 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)                                                                        |
-
-**Redundant index (intentional):** `idx_orders_status` is a prefix of `idx_orders_status_date` — used to test index audit tools.
-
-## 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. **Error path testing**: For **every** tool, test (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}`.
-3. **Output schema testing**: For tools with `outputSchema`, confirm valid calls return structured JSON.
-
-## 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: introspection-diagnostics
-
-> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
-
-### introspection-diagnostics Group Tools (4)
-
-1. sqlite_storage_analysis
-2. sqlite_index_audit
-3. sqlite_query_plan
-4. sqlite_execute_code
-
-**Checklist:**
-
-**Diagnostics:**
-
-1. `sqlite_storage_analysis({})` → database.pageSize > 0, database.totalPages > 0, database.totalSizeBytes = pageSize × totalPages; recommendations array present
-2. `sqlite_storage_analysis({})` → tables array contains "test_measurements" (largest by row count); verify each entry has name, sizeBytes, rowCount
-3. `sqlite_storage_analysis({includeTableDetails: false})` → tables array should be missing or empty
-4. `sqlite_index_audit({})` → findings array present; summary has redundant, missingFk, total fields
-5. `sqlite_index_audit({})` → findings includes type="redundant" for `idx_orders_status` (prefix of `idx_orders_status_date`)
-6. `sqlite_index_audit({table: "test_orders"})` → findings restricted to `test_orders`
-7. `sqlite_query_plan({sql: "SELECT * FROM test_products WHERE category = 'electronics'"})` → plan array non-empty; analysis.fullScans may or may not include test_products (idx_products_category exists)
-8. `sqlite_query_plan({sql: "SELECT * FROM test_orders WHERE status = 'completed'"})` → analysis.indexScans present (idx_orders_status exists)
-9. `sqlite_query_plan({sql: "SELECT * FROM test_products WHERE name = 'Laptop Pro 15'"})` → analysis.fullScans includes test_products (no index on name); suggestions non-empty
-10. `sqlite_query_plan({sql: "WITH recent AS (SELECT * FROM test_orders ORDER BY order_date DESC LIMIT 5) SELECT * FROM recent"})` → plan contains CTE-related entries
-
-**Code mode testing:**
-
-11. `sqlite_execute_code({code: "const result = await sqlite.introspection.queryPlan({sql: 'SELECT * FROM test_products WHERE category = \\u0027electronics\\u0027'}); return result;"})` → plan array present
-
-**Error path testing:**
-
-🔴 12. `sqlite_query_plan({sql: "DELETE FROM test_products WHERE id = 1"})` → `{success: false, error: "...only SELECT..."}` (non-SELECT rejected)
-🔴 13. `sqlite_query_plan({})` → Zod validation error (missing required `sql`). Must be handler error, NOT raw MCP error.
-🔴 14. `sqlite_storage_analysis({limit: 0})` → Call via direct tool or code mode to verify Zod validation error (min: 1). Must be handler error.
-
-**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
-
-🔴 15. `sqlite_storage_analysis({})` → handler error (or success if no required params)
-🔴 16. `sqlite_index_audit({})` → handler error (or success if no required params)
-
----
-
-## 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-introspection-schema.md

@@ -1,133 +0,0 @@
-# db-mcp Tool Group Testing: [introspection-schema]
-
-> [!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 schema introspection tools are fully WASM-compatible. No items to skip.
->
-> **Minor difference**: `sqlite_schema_snapshot` may report `test_articles_fts` in the `tables` array but it is not queryable (FTS5 is unavailable in WASM). Treat its presence as expected but non-functional.
-
-**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 **introspection-schema** 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)                                                                        |
-
-**Key FK:** `test_orders.product_id → test_products.id`
-
-## 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. **Error path testing**: For **every** tool, test (a) domain error and (b) Zod validation error (`{}`). Both must return `{success: false, error: "..."}`.
-3. **Output schema testing**: For tools with `outputSchema`, confirm valid calls return structured JSON.
-
-## 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: introspection-schema
-
-> **Instructions**: Execute every numbered checklist item with the exact inputs shown. Compare responses against the expected results. Report any deviation.
-
-### introspection-schema Group Tools (6)
-
-1. sqlite_dependency_graph
-2. sqlite_topological_sort
-3. sqlite_cascade_simulator
-4. sqlite_schema_snapshot
-5. sqlite_constraint_analysis
-6. sqlite_migration_risks
-
-**Checklist:**
-
-**Graph Analysis:**
-
-1. `sqlite_dependency_graph({})` → nodes ≥ 2, edges includes `test_orders → test_products` (FK); stats.totalRelationships ≥ 1
-2. `sqlite_topological_sort({})` → order array with `test_products` before `test_orders` (FK dependency); hasCycles = false
-3. `sqlite_topological_sort({direction: "drop"})` → order array with `test_orders` before `test_products` (reverse topo sort)
-4. `sqlite_cascade_simulator({table: "test_products"})` → affectedTables includes `test_orders` (FK dependent)
-5. `sqlite_cascade_simulator({table: "test_measurements"})` → affectedTables is empty (no tables reference it via FK)
-6. `sqlite_cascade_simulator({table: "nonexistent_table_xyz"})` → `{success: false, error: "..."}`
-
-**Schema Analysis:**
-
-7. `sqlite_schema_snapshot({})` → snapshot.tables ≥ 11 (10 test\_ tables + FTS virtual); stats.indexes ≥ 4; generatedAt present
-8. `sqlite_schema_snapshot({sections: ["tables"]})` → snapshot.tables is populated, but views/indexes should be missing or empty
-9. `sqlite_schema_snapshot({compact: true})` → columns array should be omitted or minimal
-10. `sqlite_constraint_analysis({})` → findings array; summary.totalFindings ≥ 0; summary.byType and bySeverity objects present
-11. `sqlite_constraint_analysis({table: "test_orders"})` → findings restricted to `test_orders`
-12. `sqlite_constraint_analysis({checks: ["unindexed_fk"]})` → findings restricted to `unindexed_fk`
-13. `sqlite_migration_risks({statements: ["DROP TABLE test_products"]})` → risks array non-empty; risk category includes data_loss or destructive
-14. `sqlite_migration_risks({statements: ["ALTER TABLE test_users ADD COLUMN age INTEGER"]})` → low risk
-15. `sqlite_migration_risks({statements: ["CREATE TABLE new_table (id INTEGER PRIMARY KEY)", "DROP TABLE test_products"]})` → summary.totalStatements = 2; summary.highestRisk ≥ "high"
-
-**Error path testing:**
-
-🔴 16. `sqlite_cascade_simulator({})` → Zod validation error (missing required `table`). Must be handler error, NOT raw MCP error.
-🔴 17. `sqlite_migration_risks({statements: []})` → report behavior for empty array
-
-**Zod validation sweep** — call each tool with `{}` (empty params). Must return handler error, NOT raw MCP error:
-
-🔴 18. `sqlite_dependency_graph({})` → handler error (or success if no required params)
-🔴 19. `sqlite_topological_sort({})` → handler error (or success if no required params)
-🔴 20. `sqlite_schema_snapshot({})` → handler error (or success if no required params)
-🔴 21. `sqlite_constraint_analysis({})` → handler error (or success if no required params)
-🔴 22. `sqlite_migration_risks({})` → 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