db-mcp 1.1.1 → 3.0.0

package/test-server/test-resources.md

@@ -1,245 +0,0 @@
-# db-mcp Resource Testing Plan
-
-Please test all db-mcp resources (8 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_insights     | memo://insights              | Static    | In-memory insights memo                    |
-
----
-
-## 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 (requires admin tools)
-3. Read memo://insights again — Should contain the new insight
-4. Verify timestamp, category, and finding text are present
-
-**Expected Output:**
-
-- Plain text (mimeType: text/plain)
-- Synthesized memo format from insightsManager
-
----
-
-### 9. 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    | 8                                            |
-| Help resources to test    | 1 (sqlite://help) + up to 8 group-specific   |
-| Static resources          | 7                                            |
-| 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.

package/test-server/test-tool-annotations.mjs

@@ -1,157 +0,0 @@
-/**
- * Integration Test: Tool Annotations
- *
- * Verifies that all tools returned by tools/list have annotations
- * with openWorldHint set. db-mcp tools are all local SQLite operations,
- * so all should have openWorldHint: false.
- *
- * Usage:
- *   npm run build
- *   node test-server/test-tool-annotations.mjs
- */
-
-import { spawn } from "child_process";
-
-const projectDir = "C:\\Users\\chris\\Desktop\\db-mcp";
-const proc = spawn(
-  "node",
-  [
-    "dist/cli.js",
-    "--instruction-level",
-    "essential",
-    "--sqlite",
-    "./test-server/test.db",
-    "--tool-filter",
-    "+all",
-  ],
-  {
-    cwd: projectDir,
-    stdio: ["pipe", "pipe", "pipe"],
-  },
-);
-
-let buffer = "";
-let finished = false;
-
-proc.stdout.on("data", (chunk) => {
-  buffer += chunk.toString();
-
-  // Try to parse complete JSON-RPC responses
-  const lines = buffer.split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      const msg = JSON.parse(trimmed);
-      if (msg.id === 1) {
-        // Initialize response — skip
-      } else if (msg.id === 2) {
-        // tools/list response
-        const tools = msg.result?.tools || [];
-        console.log(`Total tools: ${tools.length}`);
-
-        let withAnnotations = 0;
-        let openWorldTrue = 0;
-        let openWorldFalse = 0;
-        let missing = 0;
-        const trueNames = [];
-        const missingNames = [];
-
-        for (const tool of tools) {
-          if (tool.annotations) {
-            withAnnotations++;
-            if (tool.annotations.openWorldHint === true) {
-              openWorldTrue++;
-              trueNames.push(tool.name);
-            } else if (tool.annotations.openWorldHint === false) {
-              openWorldFalse++;
-            } else {
-              missing++;
-              missingNames.push(tool.name);
-            }
-          } else {
-            missing++;
-            missingNames.push(tool.name);
-          }
-        }
-
-        console.log(
-          `Tools with annotations: ${withAnnotations}/${tools.length}`,
-        );
-        console.log(`openWorldHint=false (local): ${openWorldFalse}`);
-        console.log(`openWorldHint=true: ${openWorldTrue}`);
-        console.log(`Missing openWorldHint: ${missing}`);
-
-        if (trueNames.length > 0) {
-          console.log(`\nopenWorldHint=true tools: ${trueNames.join(", ")}`);
-        }
-        if (missingNames.length > 0) {
-          console.log(`\nMISSING annotations: ${missingNames.join(", ")}`);
-        }
-
-        // Verification
-        const allHaveAnnotations = missing === 0;
-        const allAreFalse =
-          openWorldTrue === 0 && openWorldFalse === tools.length;
-
-        console.log(
-          `\n  All tools have annotations: ${allHaveAnnotations ? "✅" : "❌"}`,
-        );
-        console.log(
-          `  All openWorldHint=false: ${allAreFalse ? "✅" : "⚠️ (some are true)"}`,
-        );
-
-        finished = true;
-        proc.kill();
-        process.exit(allHaveAnnotations ? 0 : 1);
-      }
-    } catch {
-      // Not complete JSON yet
-    }
-  }
-});
-
-proc.stderr.on("data", () => {});
-
-// Send initialize
-proc.stdin.write(
-  JSON.stringify({
-    jsonrpc: "2.0",
-    id: 1,
-    method: "initialize",
-    params: {
-      protocolVersion: "2025-03-26",
-      capabilities: {},
-      clientInfo: { name: "test", version: "1.0" },
-    },
-  }) + "\n",
-);
-
-// Wait, then send initialized + tools/list
-setTimeout(() => {
-  proc.stdin.write(
-    JSON.stringify({
-      jsonrpc: "2.0",
-      method: "notifications/initialized",
-    }) + "\n",
-  );
-
-  setTimeout(() => {
-    proc.stdin.write(
-      JSON.stringify({
-        jsonrpc: "2.0",
-        id: 2,
-        method: "tools/list",
-        params: {},
-      }) + "\n",
-    );
-  }, 500);
-}, 1500);
-
-setTimeout(() => {
-  if (!finished) {
-    console.log("Timeout — killing process");
-    proc.kill();
-    process.exit(1);
-  }
-}, 15000);