npm - db-mcp - Versions diffs - 2.0.0 → 3.0.1 - Mend

db-mcp 2.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (553) hide show

package/test-server/test-prompts.md DELETED Viewed

@@ -1,354 +0,0 @@
-# db-mcp Prompt Testing Plan (Cursor)
-This plan documents how to test all 10 MCP prompts in Cursor, since prompts aren't supported in AntiGravity.
-## Prerequisites
-1. Open Cursor and connect to the SQLite MCP server
-2. Test database must be loaded: `test-server/test.db`
-3. Server command: `node dist/cli.js --transport stdio --sqlite-native "test-server/test.db"`
----
-## Prompt Categories
-Prompts fall into two categories:
-### Data-Fetching Prompts (Work Without Tools)
-These prompts call adapter methods directly and provide real database information to the LLM. They work regardless of tool filter settings.
-| Prompt                  | Data Source                                                           |
-| ----------------------- | --------------------------------------------------------------------- |
-| `sqlite_explain_schema` | `adapter.getSchema()`, `adapter.listTables()`                         |
-| `sqlite_optimization`   | `adapter.getSchema()`, `adapter.listTables()`, `adapter.getIndexes()` |
-| `sqlite_documentation`  | `adapter.getSchema()`                                                 |
-### Template Prompts (Need Tools for Execution)
-These prompts format a structured request but require database tools to execute queries. The LLM can provide SQL guidance without tools, but running queries requires tools.
-| Prompt                          | Purpose                                          |
-| ------------------------------- | ------------------------------------------------ |
-| `sqlite_query_builder`          | Helps construct SQL (running it needs tools)     |
-| `sqlite_data_analysis`          | Guides analysis workflow (execution needs tools) |
-| `sqlite_migration`              | Helps write migration scripts                    |
-| `sqlite_debug_query`            | Helps fix SQL queries                            |
-| `sqlite_summarize_table`        | Guides table analysis (execution needs tools)    |
-| `sqlite_hybrid_search_workflow` | Provides hybrid search template                  |
-| `sqlite_demo`                   | Interactive demo (full execution needs tools)    |
----
-## Prompts Summary
-| #   | Prompt                          | Arguments              | Category      |
-| --- | ------------------------------- | ---------------------- | ------------- |
-| 1   | `sqlite_explain_schema`         | None                   | Data-fetching |
-| 2   | `sqlite_query_builder`          | 3 required             | Template      |
-| 3   | `sqlite_data_analysis`          | 1 required, 1 optional | Template      |
-| 4   | `sqlite_optimization`           | None                   | Data-fetching |
-| 5   | `sqlite_migration`              | 1 required, 1 optional | Template      |
-| 6   | `sqlite_debug_query`            | 1 required, 2 optional | Template      |
-| 7   | `sqlite_documentation`          | 1 optional             | Data-fetching |
-| 8   | `sqlite_summarize_table`        | 1 required, 1 optional | Template      |
-| 9   | `sqlite_hybrid_search_workflow` | 1 required             | Template      |
-| 10  | `sqlite_demo`                   | 1 required             | Template      |
----
-## Detailed Test Procedures
-### 1. sqlite_explain_schema
-**Slash Command:** `/sqlite_explain_schema`
-**Arguments:** None
-**What to Enter:** Just invoke the slash command, no additional input needed.
-**Expected Behavior:**
-- LLM receives schema and table list from test database
-- Should explain purpose of all 11 test tables
-- Should identify relationships (e.g., `test_orders.product_id` → `test_products.id`)
----
-### 2. sqlite_query_builder
-**Slash Command:** `/sqlite_query_builder`
-**Arguments (pop-up prompts):**
-| Argument      | Value to Enter                                                |
-| ------------- | ------------------------------------------------------------- |
-| `operation`   | `aggregate`                                                   |
-| `tables`      | `test_orders, test_products`                                  |
-| `description` | `Calculate total sales by product category with order counts` |
-**Expected Behavior:**
-- LLM builds a JOIN query with GROUP BY aggregations
-- Should provide SQL with explanation
-**Alternative Test Case:**
-| Argument      | Value to Enter                                  |
-| ------------- | ----------------------------------------------- |
-| `operation`   | `select`                                        |
-| `tables`      | `test_users`                                    |
-| `description` | `Find all users with gmail.com email addresses` |
----
-### 3. sqlite_data_analysis
-**Slash Command:** `/sqlite_data_analysis`
-**Arguments (pop-up prompts):**
-| Argument           | Value to Enter      |
-| ------------------ | ------------------- |
-| `table`            | `test_measurements` |
-| `focus` (optional) | `distribution`      |
-**Expected Behavior:**
-- LLM uses SQLite tools to analyze the 200-row measurements table
-- Should provide statistics for temperature, humidity, pressure columns
-- Should detect patterns across 5 sensor_ids
-**Alternative Test Case:**
-| Argument           | Value to Enter |
-| ------------------ | -------------- |
-| `table`            | `test_orders`  |
-| `focus` (optional) | `trends`       |
----
-### 4. sqlite_optimization
-**Slash Command:** `/sqlite_optimization`
-**Arguments:** None
-**What to Enter:** Just invoke the slash command, no additional input needed.
-**Expected Behavior:**
-- LLM receives full schema and index information
-- Should identify existing indexes (`idx_orders_status`, `idx_orders_date`, `idx_products_category`)
-- May suggest additional indexes or optimizations
-- Should check for VACUUM recommendations
----
-### 5. sqlite_migration
-**Slash Command:** `/sqlite_migration`
-**Arguments (pop-up prompts):**
-| Argument                | Value to Enter                                                                |
-| ----------------------- | ----------------------------------------------------------------------------- |
-| `change`                | `Add a 'discount_percent' column to test_products table with default value 0` |
-| `reversible` (optional) | `true`                                                                        |
-**Expected Behavior:**
-- LLM provides UP migration: `ALTER TABLE test_products ADD COLUMN discount_percent REAL DEFAULT 0`
-- LLM provides DOWN migration (if reversible=true)
-- Should include data migration steps if needed
-- Should include testing/verification steps
-**Alternative Test Case:**
-| Argument                | Value to Enter                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `change`                | `Create a new index on test_events(event_type, user_id) for dashboard queries` |
-| `reversible` (optional) | `false`                                                                        |
----
-### 6. sqlite_debug_query
-**Slash Command:** `/sqlite_debug_query`
-**Arguments (pop-up prompts):**
-| Argument              | Value to Enter                                       |
-| --------------------- | ---------------------------------------------------- |
-| `query`               | `SELECT * FROM test_orders WHERE status = completed` |
-| `error` (optional)    | `SQLITE_ERROR: no such column: completed`            |
-| `expected` (optional) | `All orders with completed status`                   |
-**Expected Behavior:**
-- LLM identifies the bug: `completed` should be `'completed'` (quoted string)
-- Provides corrected query: `SELECT * FROM test_orders WHERE status = 'completed'`
-- Explains that unquoted text is treated as column name
-**Alternative Test Case:**
-| Argument              | Value to Enter                                            |
-| --------------------- | --------------------------------------------------------- |
-| `query`               | `SELECT customer_name, SUM(total_price) FROM test_orders` |
-| `error` (optional)    | `Returns only one row instead of per-customer totals`     |
-| `expected` (optional) | `Sum of total_price grouped by each customer`             |
----
-### 7. sqlite_documentation
-**Slash Command:** `/sqlite_documentation`
-**Arguments (pop-up prompts):**
-| Argument            | Value to Enter |
-| ------------------- | -------------- |
-| `format` (optional) | `markdown`     |
-**What to Enter:** Optionally specify format, or leave blank for default `markdown`.
-**Expected Behavior:**
-- LLM generates comprehensive schema documentation
-- Should include overview, ERD description, table docs
-- Should provide common query examples
-**Alternative Test Case:**
-| Argument            | Value to Enter |
-| ------------------- | -------------- |
-| `format` (optional) | `json`         |
----
-### 8. sqlite_summarize_table
-**Slash Command:** `/sqlite_summarize_table`
-**Arguments (pop-up prompts):**
-| Argument                    | Value to Enter  |
-| --------------------------- | --------------- |
-| `table_name`                | `test_products` |
-| `analysis_depth` (optional) | `detailed`      |
-**Expected Behavior:**
-- LLM uses `sqlite_describe_table` to get schema
-- Runs statistics queries on 16 products
-- Performs NULL analysis, unique value analysis
-- Provides data quality assessment
-**Alternative Test Case:**
-| Argument                    | Value to Enter    |
-| --------------------------- | ----------------- |
-| `table_name`                | `test_embeddings` |
-| `analysis_depth` (optional) | `comprehensive`   |
----
-### 9. sqlite_hybrid_search_workflow
-**Slash Command:** `/sqlite_hybrid_search_workflow`
-**Arguments (pop-up prompts):**
-| Argument   | Value to Enter   |
-| ---------- | ---------------- |
-| `use_case` | `article_search` |
-**Expected Behavior:**
-- LLM provides template for FTS5 + vector hybrid search
-- Should create `article_search_fts` virtual table example
-- Should create `article_search_embeddings` table example
-- Provides weighted scoring template (keyword + semantic)
-**Alternative Test Case:**
-| Argument   | Value to Enter    |
-| ---------- | ----------------- |
-| `use_case` | `product_catalog` |
----
-### 10. sqlite_demo
-**Slash Command:** `/sqlite_demo`
-**Arguments (pop-up prompts):**
-| Argument | Value to Enter |
-| -------- | -------------- |
-| `topic`  | `retail sales` |
-**Expected Behavior:**
-- LLM creates interactive business narrative scenario
-- May create demo tables with synthetic data
-- Presents query options to user
-- Uses `sqlite_append_insight` to capture findings in `memo://insights`
-- Demonstrates prompts + tools + resources workflow
-**Alternative Test Case:**
-| Argument | Value to Enter          |
-| -------- | ----------------------- |
-| `topic`  | `IoT sensor monitoring` |
----
-## Pass/Fail Criteria
-| Symbol | Meaning                                                                    |
-| ------ | -------------------------------------------------------------------------- |
-| ✅     | Prompt invoked successfully, arguments collected, LLM response appropriate |
-| ❌     | Prompt fails to invoke or arguments not collected properly                 |
-| ⚠️     | Prompt works but unexpected behavior or improvement opportunity            |
-| 📝     | Documentation issue or unclear prompt description                          |
----
-## Test Artifacts
-| File                      | Description                              |
-| ------------------------- | ---------------------------------------- |
-| `test-prompts-plan.md`    | This testing plan                        |
-| `test-prompts-results.md` | Summary report after testing (to create) |
----
-## Test Database Reference
-The test database contains 11 tables (417 total rows):
-| Table               | Rows | Best for Testing             |
-| ------------------- | ---- | ---------------------------- |
-| `test_products`     | 16   | Query builder, documentation |
-| `test_orders`       | 20   | Query builder, data analysis |
-| `test_jsonb_docs`   | 6    | JSON-related prompts         |
-| `test_articles`     | 8    | Text/FTS prompts             |
-| `test_users`        | 9    | Debug query scenarios        |
-| `test_measurements` | 200  | Data analysis, stats         |
-| `test_embeddings`   | 20   | Hybrid search workflow       |
-| `test_locations`    | 15   | Geo-related analysis         |
-| `test_categories`   | 17   | Hierarchical data            |
-| `test_events`       | 100  | Time-series analysis         |
-| `temp_text_test`    | 5    | Quick tests                  |
----
-## Summary
-| Metric                               | Value                                              |
-| ------------------------------------ | -------------------------------------------------- |
-| Total prompts to test                | 10                                                 |
-| Prompts with no arguments            | 2 (`sqlite_explain_schema`, `sqlite_optimization`) |
-| Prompts with required arguments      | 8                                                  |
-| Prompts with optional-only arguments | 1 (`sqlite_documentation`)                         |

package/test-server/test-resources.md DELETED Viewed

@@ -1,272 +0,0 @@
-# db-mcp Resource Testing Plan
-Please test all db-mcp resources (11 data + up to 9 help) using the test database (test-server/test.db) and concisely report any issues.
-## Resources to Test
-| #   | Resource Name          | URI                          | Type      | Expected Data Source                       |
-| --- | ---------------------- | ---------------------------- | --------- | ------------------------------------------ |
-| 1   | sqlite_schema          | sqlite://schema              | Static    | Full schema via adapter.getSchema()        |
-| 2   | sqlite_tables          | sqlite://tables              | Static    | Table list via adapter.listTables()        |
-| 3   | sqlite_table_schema    | sqlite://table/{name}/schema | Templated | Specific table via adapter.describeTable() |
-| 4   | sqlite_indexes         | sqlite://indexes             | Static    | All indexes via adapter.getAllIndexes()    |
-| 5   | sqlite_views           | sqlite://views               | Static    | Views from sqlite_master                   |
-| 6   | sqlite_health          | sqlite://health              | Static    | Connection health via adapter.getHealth()  |
-| 7   | sqlite_meta            | sqlite://meta                | Static    | PRAGMA values + adapter info               |
-| 8   | sqlite_compile_options | sqlite://compile_options     | Static    | SQLite compile-time build options          |
-| 9   | sqlite_pragma          | sqlite://pragma              | Static    | Runtime PRAGMA config snapshot             |
-| 10  | sqlite_insights        | memo://insights              | Static    | In-memory insights memo                    |
-| 11  | sqlite_audit           | sqlite://audit               | Static    | Audit log access (if enabled)              |
----
-## Test Procedures
-### 1. sqlite_schema — Full Database Schema
-**URI:** `sqlite://schema`
-**Test:** Read the schema resource and verify it contains all 11 test tables.
-**Expected Output:**
-- JSON with table definitions including columns, types, and constraints
-- Should include: test_products, test_orders, test_jsonb_docs, test_articles, test_users, test_measurements, test_embeddings, test_locations, test_categories, test_events, temp_text_test
-- **Note:** FTS5 virtual tables (test_articles_fts and shadow tables) are intentionally filtered out
----
-### 2. sqlite_tables — List All Tables
-**URI:** `sqlite://tables`
-**Test:** Read the tables resource and count entries.
-**Expected Output:**
-- JSON array of table objects
-- Should list **11 tables** (FTS5 virtual tables are intentionally filtered for cleaner output)
-- Each entry should have: name, type, columns (array with full column definitions)
----
-### 3. sqlite_table_schema — Table-Specific Schema (Templated)
-**URI Template:** `sqlite://table/{tableName}/schema`
-**Tests:** Multiple table names to verify URI parsing.
-**Test Cases:**
-| URI                                       | Expected Result                           |
-| ----------------------------------------- | ----------------------------------------- |
-| `sqlite://table/test_products/schema`     | ✅ Returns 6 columns                      |
-| `sqlite://table/test_orders/schema`       | ✅ Returns 7 columns                      |
-| `sqlite://table/test_embeddings/schema`   | ✅ Returns 4 columns                      |
-| `sqlite://table/nonexistent_table/schema` | ✅ Graceful error: "Table does not exist" |
-**Expected Output per table:**
-- Column definitions with names, types, nullability, default values
-- Primary key information
----
-### 4. sqlite_indexes — All Database Indexes
-**URI:** `sqlite://indexes`
-**Test:** Read indexes resource.
-**Expected Output:**
-- JSON grouped by table name
-- Should include at minimum:
-  - idx_orders_status on test_orders(status)
-  - idx_orders_date on test_orders(order_date)
-  - idx_products_category on test_products(category)
-- Each index should have: name, tableName, columns, unique flag
----
-### 5. sqlite_views — All Views
-**URI:** `sqlite://views`
-**Test:** Read views resource.
-**Expected Output:**
-- JSON array of view objects
-- Test database has no views by default, so expect empty array `[]`
-- Optionally: Create a test view, verify it appears, then clean up
-**Optional Setup/Cleanup:**
-```sql
--- Setup (if testing view detection)
-CREATE VIEW test_view_order_summary AS
-SELECT product_id, SUM(total_price) as total FROM test_orders GROUP BY product_id;
--- Cleanup
-DROP VIEW IF EXISTS test_view_order_summary;
-```
----
-### 6. sqlite_health — Database Health
-**URI:** `sqlite://health`
-**Test:** Read health resource.
-**Expected Output:**
-- JSON with connection status information
-- Should indicate: connected/healthy status
-- May include: database path, backend type (sql.js for WASM, better-sqlite3 for native), version info
----
-### 7. sqlite_meta — Database Metadata
-**URI:** `sqlite://meta`
-**Test:** Read meta resource.
-**Expected Output:**
-- JSON with PRAGMA values for:
-  - database_list — Attached databases
-  - page_count — Total database pages
-  - page_size — Page size in bytes
-  - journal_mode — Should be wal or delete
-  - synchronous — Sync mode setting
-  - foreign_keys — FK enforcement status
-  - wal_autocheckpoint — WAL checkpoint threshold
-- Adapter info with backend type and capabilities
----
-### 8. sqlite_insights — Business Insights Memo
-**URI:** `memo://insights`
-**Test:** Read insights resource (may be empty initially), then add an insight and verify.
-> **Prerequisite:** The `sqlite_append_insight` tool requires the `admin` tool group to be enabled.
-**Test Sequence:**
-1. Read memo://insights — May be empty or have default content ("No business insights have been discovered yet.")
-2. Call sqlite_append_insight tool with a test insight `{"insight": "Test insight"}` (requires admin tools)
-3. Read memo://insights again — Should contain the new insight
-4. Verify the exact insight text is present
-**Expected Output:**
-- Plain text (mimeType: text/plain)
-- Synthesized memo format from insightsManager
----
-### 9. sqlite_compile_options — Compile-Time Options
-**URI:** `sqlite://compile_options`
-**Test:** Read the compile options resource.
-**Expected Output:**
-- JSON with an `options` array, `count`, and `highlights` array.
-- Should contain fundamental build options (e.g., `THREADSAFE`).
----
-### 10. sqlite_pragma — Runtime Configuration Snapshot
-**URI:** `sqlite://pragma`
-**Test:** Read the pragma configuration resource.
-**Expected Output:**
-- JSON with a `settings` object grouping configuration into categories (storage, performance, safety, behavior).
-- Each setting should include `value`, `category`, and `description`.
----
-### 11. Help Resources — On-Demand Reference Documentation
-**Test A — sqlite://help (always registered):**
-Read `sqlite://help` and verify it contains critical reference content:
-| Check                       | Expected                                       |
-| --------------------------- | ---------------------------------------------- |
-| Resource exists             | ✅ Always registered regardless of tool filter |
-| Contains "Critical Gotchas" | ✅ Section header present                      |
-| Contains "Code Mode API"    | ✅ Section header present                      |
-| Contains "WASM vs Native"   | ✅ Comparison section present                  |
-| Content is markdown         | ✅ mimeType: text/markdown                     |
-**Test B — Group-specific help resources:**
-Verify that group-specific help resources are only registered when the corresponding group is enabled. These tests depend on the `--tool-filter` configuration:
-| Resource                    | URI                           | Registered When             |
-| --------------------------- | ----------------------------- | --------------------------- |
-| `sqlite_help_json`          | `sqlite://help/json`          | json group enabled          |
-| `sqlite_help_text`          | `sqlite://help/text`          | text group enabled          |
-| `sqlite_help_stats`         | `sqlite://help/stats`         | stats group enabled         |
-| `sqlite_help_vector`        | `sqlite://help/vector`        | vector group enabled        |
-| `sqlite_help_geo`           | `sqlite://help/geo`           | geo group enabled           |
-| `sqlite_help_admin`         | `sqlite://help/admin`         | admin group enabled         |
-| `sqlite_help_introspection` | `sqlite://help/introspection` | introspection group enabled |
-| `sqlite_help_migration`     | `sqlite://help/migration`     | migration group enabled     |
-If a group-specific help resource is available, read it and verify it contains relevant tool reference content (tool names, parameters, usage notes).
-> **Note:** Help resources are tested more thoroughly by the `test-help-resources.mjs` integration script, which spins up separate server instances with different `--tool-filter` values.
-**Test C — Tool Annotations (`openWorldHint`):**
-Call `tools/list` and verify that **all** tools have `openWorldHint: false` in their annotations. db-mcp tools are local database operations — none require external network access.
-| Check                               | Expected                 |
-| ----------------------------------- | ------------------------ |
-| All tools have `annotations` object | ✅ Present on every tool |
-| All `openWorldHint` values          | `false`                  |
----
-## Verification Plan
-### Execution Method
-Use live MCP resource reads via the `read_resource` tool against the running sqlite MCP server.
-### Test Commands
-```
-# Resources being tested use the read_resource tool with:
-# ServerName: "sqlite"
-# Uri: "<resource-uri>"
-```
-### Pass/Fail Criteria
-| Symbol | Meaning                                        |
-| ------ | ---------------------------------------------- |
-| ✅     | Resource returns expected data structure       |
-| ❌     | Resource errors or returns unexpected format   |
-| ⚠️     | Unexpected behavior or improvement opportunity |
-| 📦     | Response payload is larger than necessary      |
----
-## Summary
-| Metric                    | Value                                        |
-| ------------------------- | -------------------------------------------- |
-| Data resources to test    | 10                                           |
-| Help resources to test    | 1 (sqlite://help) + up to 8 group-specific   |
-| Static resources          | 9                                            |
-| Templated resources       | 1 (sqlite_table_schema with URI parameter)   |
-| Protocol validation tests | 2 (help resource content + tool annotations) |
-| Error cases to test       | 1 (nonexistent table in template)            |
----
-## Design Notes
-- **FTS5 Table Filtering:** FTS5 virtual tables (`*_fts`) and shadow tables (`*_fts_*`) are intentionally hidden from `sqlite_schema` and `sqlite_tables` resources. This keeps table listings clean since shadow tables are internal implementation details. FTS5 tables are still fully accessible via `sqlite_fts_*` tools.