db-mcp 1.1.1 → 3.0.0

package/test-server/test-help-resources.mjs

@@ -1,238 +0,0 @@
-/**
- * Integration Test: Help Resources + Slim Instructions
- *
- * Starts the server with various --tool-filter configs and verifies:
- * 1. Instructions are slim (~680 chars, within client limits)
- * 2. sqlite://help resources are registered based on tool filter
- * 3. Group-specific help resources are only registered for enabled groups
- *
- * Usage:
- *   npm run build
- *   node test-server/test-help-resources.mjs
- */
-
-import { spawn } from "child_process";
-
-const PROJECT_DIR = "C:\\Users\\chris\\Desktop\\db-mcp";
-
-/**
- * Start server, send initialize + resources/list, return results
- */
-function testServer(args) {
-  return new Promise((resolve, reject) => {
-    const proc = spawn("node", ["dist/cli.js", ...args], {
-      cwd: PROJECT_DIR,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-
-    let buffer = "";
-    let instructions = "";
-    let resourceUris = [];
-    let gotInitialize = false;
-
-    proc.stdout.on("data", (chunk) => {
-      buffer += chunk.toString();
-      const lines = buffer.split("\n");
-      buffer = lines.pop(); // Keep incomplete line
-
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        try {
-          const msg = JSON.parse(trimmed);
-
-          // Response to initialize (id=1)
-          if (msg.id === 1 && msg.result) {
-            instructions =
-              msg.result?.serverInfo?.instructions ||
-              msg.result?.instructions ||
-              msg.result?.capabilities?.instructions ||
-              "";
-            gotInitialize = true;
-
-            // Send resources/list
-            proc.stdin.write(
-              JSON.stringify({
-                jsonrpc: "2.0",
-                id: 2,
-                method: "resources/list",
-                params: {},
-              }) + "\n",
-            );
-          }
-
-          // Response to resources/list (id=2)
-          if (msg.id === 2 && msg.result) {
-            const resources = msg.result.resources || [];
-            resourceUris = resources.map((r) => r.uri);
-            proc.kill();
-            resolve({
-              instructions,
-              instructionChars: instructions.length,
-              resourceUris,
-            });
-          }
-        } catch {
-          // Not complete JSON yet
-        }
-      }
-    });
-
-    proc.stderr.on("data", () => {});
-
-    // Send initialize request
-    proc.stdin.write(
-      JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "initialize",
-        params: {
-          protocolVersion: "2025-03-26",
-          capabilities: {},
-          clientInfo: { name: "help-resource-test", version: "1.0" },
-        },
-      }) + "\n",
-    );
-
-    setTimeout(() => {
-      proc.kill();
-      reject(new Error(`Timeout for args: ${args.join(" ")}`));
-    }, 10000);
-  });
-}
-
-async function main() {
-  let allPassed = true;
-
-  // ── Test 1: Slim Instructions ──
-  console.log("=== Test 1: Slim Instructions ===\n");
-
-  const baseResult = await testServer([]);
-  console.log(`  Instruction chars: ${baseResult.instructionChars}`);
-  console.log(
-    `  Token estimate: ~${Math.round(baseResult.instructionChars / 4)}`,
-  );
-
-  const isSlim = baseResult.instructionChars < 1000;
-  console.log(`  Under 1000 chars: ${isSlim ? "✅" : "❌"}`);
-  if (!isSlim) allPassed = false;
-
-  const hasHelpPointer = baseResult.instructions.includes("sqlite://help");
-  console.log(
-    `  Contains sqlite://help pointer: ${hasHelpPointer ? "✅" : "❌"}`,
-  );
-  if (!hasHelpPointer) allPassed = false;
-
-  const noOldContent = !baseResult.instructions.includes("Critical Gotchas");
-  console.log(
-    `  No old gotchas in instructions: ${noOldContent ? "✅" : "❌"}`,
-  );
-  if (!noOldContent) allPassed = false;
-
-  // ── Test 2: Core-only Filter ──
-  console.log("\n=== Test 2: Core-only Filter (--tool-filter core) ===\n");
-
-  const coreResult = await testServer(["--tool-filter", "core"]);
-  const coreHelpUris = coreResult.resourceUris.filter((u) =>
-    u.startsWith("sqlite://help"),
-  );
-  console.log(`  Help resources: ${coreHelpUris.join(", ") || "(none)"}`);
-
-  const coreHasBaseHelp = coreHelpUris.includes("sqlite://help");
-  console.log(`  Has sqlite://help: ${coreHasBaseHelp ? "✅" : "❌"}`);
-  if (!coreHasBaseHelp) allPassed = false;
-
-  const coreNoGroupHelp = coreHelpUris.length === 1;
-  console.log(
-    `  No group-specific help: ${coreNoGroupHelp ? "✅" : "❌"} (count: ${coreHelpUris.length})`,
-  );
-  if (!coreNoGroupHelp) allPassed = false;
-
-  // ── Test 3: Stats Filter ──
-  console.log("\n=== Test 3: Stats Filter (--tool-filter stats) ===\n");
-
-  const statsResult = await testServer(["--tool-filter", "stats"]);
-  const statsHelpUris = statsResult.resourceUris.filter((u) =>
-    u.startsWith("sqlite://help"),
-  );
-  console.log(`  Help resources: ${statsHelpUris.join(", ")}`);
-
-  const statsHasBaseHelp = statsHelpUris.includes("sqlite://help");
-  const statsHasStatsHelp = statsHelpUris.includes("sqlite://help/stats");
-  console.log(`  Has sqlite://help: ${statsHasBaseHelp ? "✅" : "❌"}`);
-  console.log(`  Has sqlite://help/stats: ${statsHasStatsHelp ? "✅" : "❌"}`);
-  if (!statsHasBaseHelp || !statsHasStatsHelp) allPassed = false;
-
-  const statsNoJsonHelp = !statsHelpUris.includes("sqlite://help/json");
-  console.log(`  No sqlite://help/json: ${statsNoJsonHelp ? "✅" : "❌"}`);
-  if (!statsNoJsonHelp) allPassed = false;
-
-  // ── Test 4: Multi-group Filter ──
-  console.log(
-    "\n=== Test 4: Multi-group Filter (--tool-filter core,json,text,stats) ===\n",
-  );
-
-  const multiResult = await testServer([
-    "--tool-filter",
-    "core,json,text,stats",
-  ]);
-  const multiHelpUris = multiResult.resourceUris.filter((u) =>
-    u.startsWith("sqlite://help"),
-  );
-  console.log(`  Help resources: ${multiHelpUris.join(", ")}`);
-
-  const expectedMulti = [
-    "sqlite://help",
-    "sqlite://help/json",
-    "sqlite://help/text",
-    "sqlite://help/stats",
-  ];
-  for (const uri of expectedMulti) {
-    const found = multiHelpUris.includes(uri);
-    console.log(`  Has ${uri}: ${found ? "✅" : "❌"}`);
-    if (!found) allPassed = false;
-  }
-
-  const multiNoVector = !multiHelpUris.includes("sqlite://help/vector");
-  const multiNoGeo = !multiHelpUris.includes("sqlite://help/geo");
-  console.log(`  No sqlite://help/vector: ${multiNoVector ? "✅" : "❌"}`);
-  console.log(`  No sqlite://help/geo: ${multiNoGeo ? "✅" : "❌"}`);
-  if (!multiNoVector || !multiNoGeo) allPassed = false;
-
-  // ── Test 5: Full Filter ──
-  console.log("\n=== Test 5: Full Filter (--tool-filter full) ===\n");
-
-  const fullResult = await testServer(["--tool-filter", "full"]);
-  const fullHelpUris = fullResult.resourceUris.filter((u) =>
-    u.startsWith("sqlite://help"),
-  );
-  console.log(
-    `  Help resources (${fullHelpUris.length}): ${fullHelpUris.join(", ")}`,
-  );
-
-  const expectedFull = [
-    "sqlite://help",
-    "sqlite://help/json",
-    "sqlite://help/text",
-    "sqlite://help/stats",
-    "sqlite://help/vector",
-    "sqlite://help/geo",
-    "sqlite://help/admin",
-    "sqlite://help/introspection",
-    "sqlite://help/migration",
-  ];
-  const fullHasAll = expectedFull.every((u) => fullHelpUris.includes(u));
-  console.log(`  Has all 9 help resources: ${fullHasAll ? "✅" : "❌"}`);
-  if (!fullHasAll) allPassed = false;
-
-  // ── Summary ──
-  console.log(
-    `\n=== Overall: ${allPassed ? "✅ ALL PASSED" : "❌ FAILURES"} ===`,
-  );
-  process.exit(allPassed ? 0 : 1);
-}
-
-main().catch((err) => {
-  console.error("Fatal:", err.message);
-  process.exit(1);
-});

package/test-server/test-preflight.md

@@ -1,53 +0,0 @@
-# MCP Server Pre-Flight Check — db-mcp (SQLite)
-
-> **Purpose:** Validate that slim instructions, help resources, and data resources are working correctly before running full test passes. Run this in a fresh conversation with the server enabled.
-
-Do NOT read any files from disk. Answer using ONLY what you received via MCP initialization and resource reads.
-
-## Step 1: Instructions Audit
-
-Report exactly what you received in the MCP server instructions during initialization:
-
-- Paste the FULL raw text you received (use a code block)
-- Character count of the instructions
-- Does it mention help resources? If so, what URIs?
-- Does it contain detailed tool parameter tables or response structure docs? (It should NOT)
-
-## Step 2: Help Resource Access
-
-Read the main help resource `sqlite://help`. Report:
-
-- Did it succeed?
-- Approximate character count of the content
-- First 3 lines of content
-
-Then read ONE group-specific help resource (e.g., `sqlite://help/core`, `sqlite://help/json`, or whichever is available). Report:
-
-- Which URI did you read?
-- Did it succeed?
-- Does it contain tool-specific parameter details and response structures?
-
-## Step 3: Data Resource Access
-
-Read the schema resource `sqlite://schema`. Report:
-
-- Did it succeed?
-- How many tables are listed?
-
-## Step 4: Tool Inventory
-
-List the tool groups you see and count of tools per group. Do NOT call any tools — just report what's in your tool list.
-
-## Step 5: Verdict
-
-Based on steps 1-4, answer:
-
-| #   | Check                                                      | Result   |
-| --- | ---------------------------------------------------------- | -------- |
-| 1   | Instructions are slim (<1000 chars), not monolithic        | ✅ or ❌ |
-| 2   | Instructions reference help resources (`sqlite://help`)    | ✅ or ❌ |
-| 3   | Main help resource is readable                             | ✅ or ❌ |
-| 4   | Group-specific help resource is readable                   | ✅ or ❌ |
-| 5   | Data resources are readable                                | ✅ or ❌ |
-| 6   | Tool count matches expected for configured `--tool-filter` | ✅ or ❌ |
-| 7   | No detailed parameter tables leaked into instructions      | ✅ or ❌ |

package/test-server/test-prompts.md

@@ -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`)                         |