db-mcp 1.0.2 → 1.1.0

package/dist/chunk-DZQLDEQS.js

@@ -0,0 +1,879 @@
+import { READ_ONLY, SERVER_ICONS } from './chunk-S5IDDSSB.js';
+import { parseToolFilter, getToolFilterFromEnv, logger, getFilterSummary, DbMcpError } from './chunk-AOUL5SHS.js';
+import { createRequire } from 'module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+var _require = createRequire(import.meta.url);
+var pkg = _require("../package.json");
+var VERSION = pkg.version;
+var NAME = pkg.name;
+
+// src/constants/server-instructions.ts
+var INSTRUCTIONS = `# db-mcp (SQLite MCP Server)
+
+## Quick Access
+
+| Purpose         | Action                     |
+| --------------- | -------------------------- |
+| Health check    | \`server_health\` tool       |
+| Server info     | \`server_info\` tool         |
+| Database schema | \`sqlite://schema\` resource |
+| Tool help       | \`sqlite://help\` resource   |
+
+## Built-in Tools
+
+\`server_info\`, \`server_health\`, \`list_adapters\` \u2014 always available.
+
+## Help Resources
+
+Read \`sqlite://help\` for gotchas and critical usage patterns.
+Read \`sqlite://help/{group}\` for group-specific tool reference (json, text, stats, vector, geo, admin, introspection, migration).
+Only help resources for your enabled tool groups are registered.`;
+var HELP_CONTENT = /* @__PURE__ */ new Map([
+  [
+    "admin",
+    `# db-mcp Help \u2014 Database Administration (33 Native / 26 WASM)
+
+## Transactions (7 tools, Native only)
+
+\`\`\`javascript
+// Atomic multi-statement execution (preferred for simple cases)
+sqlite_transaction_execute({ statements: ["UPDATE a SET x=1", "UPDATE b SET y=2"] });
+
+// Manual transaction control
+sqlite_transaction_begin({ mode: "immediate" }); // or "deferred", "exclusive"
+sqlite_transaction_savepoint({ name: "checkpoint" });
+sqlite_transaction_rollback_to({ name: "checkpoint" });
+sqlite_transaction_release({ name: "checkpoint" });
+sqlite_transaction_commit();
+sqlite_transaction_rollback();
+\`\`\`
+
+## Maintenance
+
+\`\`\`javascript
+sqlite_integrity_check({ maxErrors: 10 }); // check for corruption
+sqlite_optimize({ analyze: true, reindex: true }); // optimize performance
+sqlite_vacuum(); // reclaim space
+sqlite_analyze({ table: "orders" }); // update statistics for query planner
+sqlite_dbstat({ summarize: true }); // storage stats (\u26A0\uFE0F summarize native-only; WASM returns counts only)
+\`\`\`
+
+## Backup/Restore (Native only)
+
+\`\`\`javascript
+sqlite_backup({ targetPath: "/path/to/backup.db" });
+sqlite_verify_backup({ backupPath: "/path/to/backup.db" }); // check integrity without restoring
+sqlite_restore({ sourcePath: "/path/to/backup.db" }); // \u26A0\uFE0F WARNING: Replaces current database
+\`\`\`
+
+## PRAGMA
+
+\`\`\`javascript
+sqlite_pragma_settings({ pragma: "journal_mode" }); // get value
+sqlite_pragma_settings({ pragma: "cache_size", value: 10000 }); // set value
+sqlite_pragma_table_info({ table: "users" }); // column details
+sqlite_pragma_compile_options({ filter: "FTS" }); // \u26A0\uFE0F WASM may show FTS3, not FTS5
+sqlite_pragma_database_list(); // list attached databases
+sqlite_pragma_optimize(); // run PRAGMA optimize
+\`\`\`
+
+## Index & Stats
+
+- \`sqlite_index_stats({ table: "orders" })\` \u2014 stats for explicit indexes
+
+## Views
+
+\`\`\`javascript
+sqlite_create_view({ viewName: "active_orders", selectQuery: "SELECT * FROM orders WHERE status = 'active'" });
+sqlite_create_view({ viewName: "v", selectQuery: "...", replace: true }); // CREATE OR REPLACE
+sqlite_list_views(); // list all views
+sqlite_drop_view({ viewName: "active_orders" });
+\`\`\`
+
+## Virtual Tables
+
+\`\`\`javascript
+sqlite_list_virtual_tables(); // list FTS5, R-Tree, CSV tables
+sqlite_virtual_table_info({ tableName: "articles_fts" }); // module and column info
+sqlite_drop_virtual_table({ tableName: "old_fts", ifExists: true });
+\`\`\`
+
+## Generate Series (pure JS)
+
+\`\`\`javascript
+sqlite_generate_series({ start: 1, stop: 100, step: 5 }); // returns array of values
+// \u26A0\uFE0F Creates a REGULAR table (not virtual) \u2014 use sqlite_drop_table to remove
+sqlite_create_series_table({ tableName: "numbers", start: 1, stop: 1000 });
+\`\`\`
+
+## R-Tree (Native only)
+
+\`\`\`javascript
+sqlite_create_rtree_table({ tableName: "locations_idx", dimensions: 2 }); // 2D: minX, maxX, minY, maxY
+// Returns graceful error with wasmLimitation: true in WASM
+\`\`\`
+
+## CSV Virtual Tables (Native only)
+
+\u26A0\uFE0F Requires ABSOLUTE file paths
+
+\`\`\`javascript
+sqlite_analyze_csv_schema({ filePath: "/absolute/path/to/data.csv" }); // analyze CSV structure
+sqlite_create_csv_table({ tableName: "csv_data", filePath: "/absolute/path/to/data.csv" });
+\`\`\`
+
+## Business Insights
+
+\`\`\`javascript
+sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }); // add to memo://insights
+\`\`\``
+  ],
+  [
+    "geo",
+    `# db-mcp Help \u2014 Geospatial Operations (4 basic + 7 SpatiaLite)
+
+## Basic Geo (always available \u2014 Haversine formula)
+
+\`\`\`javascript
+sqlite_geo_distance({ lat1: 40.7128, lon1: -74.006, lat2: 34.0522, lon2: -118.2437 }); // returns km
+sqlite_geo_bounding_box({
+  table: "stores", latColumn: "lat", lonColumn: "lon",
+  minLat: 40, maxLat: 41, minLon: -75, maxLon: -73,
+});
+sqlite_geo_nearby({
+  table: "stores", latColumn: "lat", lonColumn: "lon",
+  centerLat: 40.7, centerLon: -74, radius: 10, unit: "km",
+});
+sqlite_geo_cluster({ table: "customers", latColumn: "lat", lonColumn: "lon", gridSize: 0.1 });
+\`\`\`
+
+## SpatiaLite (7 tools, Native only)
+
+\`\`\`javascript
+// Load extension first
+sqlite_spatialite_load(); // \u26A0\uFE0F Required before using other spatial tools
+
+// Create spatial table with geometry column
+sqlite_spatialite_create_table({ tableName: "places", geometryColumn: "geom", geometryType: "POINT", srid: 4326 });
+
+// Import data (WKT or GeoJSON)
+sqlite_spatialite_import({ tableName: "places", format: "wkt", data: "POINT(-73.99 40.75)", additionalData: { name: "NYC" } });
+sqlite_spatialite_import({ tableName: "places", format: "geojson", data: '{"type":"Point","coordinates":[-73.99,40.75]}' });
+
+// Spatial queries (SELECT only)
+sqlite_spatialite_query({ query: "SELECT name, AsText(geom) FROM places WHERE ST_Within(geom, ...)" });
+
+// Spatial analysis
+// analysisType: "spatial_extent" | "point_in_polygon" | "nearest_neighbor" | "distance_matrix"
+// \u26A0\uFE0F nearest_neighbor/distance_matrix return CARTESIAN distance (degrees), not geodetic (km/miles)
+// For same source/target table, use excludeSelf: true to avoid self-matches
+sqlite_spatialite_analyze({ analysisType: "spatial_extent", sourceTable: "places", geometryColumn: "geom" });
+sqlite_spatialite_analyze({ analysisType: "nearest_neighbor", sourceTable: "pts", targetTable: "pts", excludeSelf: true });
+
+// Geometry transforms
+// buffer: 'distance' = radius; simplify: 'distance' = tolerance (0.0001 for lat/lon)
+// \u26A0\uFE0F Buffer auto-simplifies output by default (tolerance=0.0001). Use simplifyTolerance: 0 to disable
+sqlite_spatialite_transform({ operation: "buffer", geometry1: "POINT(-73.99 40.75)", distance: 0.01 });
+sqlite_spatialite_transform({ operation: "simplify", geometry1: "...", distance: 0.001 });
+
+// Spatial index (R-Tree)
+sqlite_spatialite_index({ tableName: "places", geometryColumn: "geom", action: "create" }); // create, drop, or check
+\`\`\``
+  ],
+  [
+    "gotchas",
+    `# db-mcp Help \u2014 Gotchas & Code Mode
+
+## \u26A0\uFE0F Critical Gotchas
+
+1. **sqlite_write_query**: \u26D4 Only INSERT/UPDATE/DELETE \u2014 use \`sqlite_read_query\` for SELECT
+2. **Regex patterns**: Double-escape backslashes (\`\\\\\\\\\`) when passing through JSON/MCP
+3. **FTS5 virtual tables**: \`*_fts\` and shadow tables \`*_fts_*\` are hidden from \`sqlite_list_tables\` for cleaner output
+4. **FTS5 boolean logic**: Uses AND by default \u2014 \`"machine learning"\` = rows with BOTH words. Use OR explicitly: \`"machine OR learning"\`
+5. **FTS5 rebuild**: After \`sqlite_fts_create\`, must call \`sqlite_fts_rebuild\` to populate index with existing data
+6. **json_each row multiplication**: Expands arrays to rows \u2014 use \`limit\` param for large arrays
+7. **json_group_object without groupByColumn**: Each row creates a key-value pair; duplicate keys result if key values aren't unique
+8. **allowExpressions**: For column extraction ONLY (e.g., \`json_extract\`), NOT aggregate functions \u2014 use \`aggregateFunction\` param instead
+9. **sqlite_json_normalize_column**: Defaults to \`preserve\` (maintains original format); use \`outputFormat: 'text'\` to force text
+10. **Fuzzy matching tokenization**: Matches WORD TOKENS by default \u2014 \`"laptop"\` matches \`"Laptop Pro 15"\` (distance 0 on first token). Use \`tokenize: false\` for full-string matching
+11. **SpatiaLite distances**: \`nearest_neighbor\`/\`distance_matrix\` return CARTESIAN distance (degrees), not geodetic (km/miles)
+12. **SpatiaLite buffer**: Auto-simplifies output by default (tolerance=0.0001). Use \`simplifyTolerance: 0\` to disable
+13. **sqlite_stats_top_n**: Auto-excludes long-content columns (description, body, notes, etc.) when \`selectColumns\` is omitted. Use \`selectColumns\` to override
+14. **CSV virtual tables**: Require ABSOLUTE file paths
+15. **sqlite_create_series_table**: Creates a REGULAR table (not virtual) \u2014 use \`sqlite_drop_table\` to remove
+16. **sqlite_dbstat**: \`summarize\` only works in native; WASM returns counts only
+17. **PRAGMA compile options**: WASM may show FTS3, not FTS5
+
+## WASM vs Native
+
+| Feature                                           | Native                | WASM        | Fallback         |
+| ------------------------------------------------- | --------------------- | ----------- | ---------------- |
+| FTS5 full-text search                             | \u2705                    | \u274C          | None             |
+| Transactions (7 tools)                            | \u2705                    | \u274C          | None             |
+| Window functions (6 tools in stats group)         | \u2705                    | \u274C          | None             |
+| SpatiaLite GIS (7 tools; 4 basic geo always work) | \u2705                    | \u274C          | None             |
+| Backup/Restore (3 tools)                          | \u2705                    | \u274C          | Graceful error   |
+| R-Tree spatial indexing                           | \u2705                    | \u274C          | Graceful error   |
+| CSV virtual tables                                | \u2705                    | \u274C          | Graceful error   |
+| generate_series                                   | JS fallback           | JS fallback | \u2014                |
+| dbstat                                            | \u2705 native (per-table) | \u274C          | JS (counts only) |
+| soundex()                                         | \u2705 native             | \u274C          | JS               |
+
+## Code Mode (1 tool)
+
+| Tool                  | Description                                                       |
+| --------------------- | ----------------------------------------------------------------- |
+| \`sqlite_execute_code\` | Execute JavaScript in a sandboxed environment with \`sqlite.*\` API |
+
+**Usage**: \`sqlite_execute_code({ code: "const tables = await sqlite.core.listTables(); return tables;" })\`
+**Discover**: \`sqlite.help()\` for all groups, \`sqlite.<group>.help()\` for methods.
+**Groups**: \`sqlite.core\`, \`sqlite.json\`, \`sqlite.text\`, \`sqlite.stats\`, \`sqlite.vector\`, \`sqlite.admin\`, \`sqlite.geo\`, \`sqlite.introspection\`, \`sqlite.migration\`
+
+## Code Mode API Mapping
+
+\`sqlite_group_action\` \u2192 \`sqlite.group.action()\` (group prefixes dropped: \`sqlite_json_insert\` \u2192 \`sqlite.json.insert()\`)
+
+**Positional args work**: \`sqlite.core.readQuery("SELECT...")\`, \`sqlite.json.insert("docs", "data", {...})\`
+
+**Discovery**: \`sqlite.help()\` returns all groups and methods. \`sqlite.core.help()\`, \`sqlite.json.help()\` for group-specific methods.`
+  ],
+  [
+    "introspection",
+    `# db-mcp Help \u2014 Schema Introspection (9 tools)
+
+All introspection tools are **read-only** \u2014 they query PRAGMAs and sqlite_master, never modify data.
+
+## Graph Analysis (3 tools)
+
+\`\`\`javascript
+// Build FK dependency graph \u2014 nodesOnly: true for lightweight response (nodes without edges)
+sqlite_dependency_graph({ includeRowCounts: true, excludeSystemTables: true });
+sqlite_dependency_graph({ nodesOnly: true }); // lighter payload
+
+// Safe DDL execution order \u2014 "create" = parents first (default), "drop" = children first
+sqlite_topological_sort({ direction: "create", excludeSystemTables: true });
+sqlite_topological_sort({ direction: "drop" }); // safe DROP order
+
+// Simulate DELETE/DROP/TRUNCATE impact \u2014 shows affected tables, cascade paths, severity scoring
+sqlite_cascade_simulator({ table: "users", operation: "delete" });
+sqlite_cascade_simulator({ table: "users", operation: "drop", compact: true }); // compact omits path arrays
+\`\`\`
+
+## Schema Analysis (3 tools)
+
+\`\`\`javascript
+// Full schema in one call \u2014 compact: true omits column details, sections limits scope
+sqlite_schema_snapshot({ sections: ["tables", "indexes"], excludeSystemTables: true });
+sqlite_schema_snapshot({ compact: true }); // lighter payload
+
+// Find constraint health issues \u2014 missing PKs, nullable FKs, unindexed FKs
+sqlite_constraint_analysis({ excludeSystemTables: true });
+sqlite_constraint_analysis({ table: "orders", checks: ["missing_pk", "unindexed_fk"] }); // limit scope
+
+// Analyze DDL for SQLite-specific risks \u2014 does NOT execute the statements
+sqlite_migration_risks({ statements: ["ALTER TABLE users ADD COLUMN email TEXT", "DROP TABLE old_logs"] });
+\`\`\`
+
+## Diagnostics (3 tools)
+
+\`\`\`javascript
+// Fragmentation, per-table size breakdown, optimization recommendations
+sqlite_storage_analysis({ includeTableDetails: true, excludeSystemTables: true });
+sqlite_storage_analysis({ limit: 10 }); // top 10 tables only
+
+// Audit index effectiveness \u2014 find redundant, missing FK, unindexed large tables
+sqlite_index_audit({ excludeSystemTables: true });
+sqlite_index_audit({ table: "orders", minSeverity: "warning" }); // reduce payload
+
+// EXPLAIN QUERY PLAN with scan-type classification and optimization suggestions (SELECT/WITH only)
+sqlite_query_plan({ sql: "SELECT * FROM orders WHERE status = 'active'" });
+\`\`\`
+
+## \u26A0\uFE0F Gotchas
+
+- \`excludeSystemTables\` defaults to \`true\` \u2014 SpatiaLite system tables are hidden for cleaner output. Pass \`false\` to include them
+- \`sqlite_migration_risks\` analyzes DDL text statically \u2014 it does NOT execute the statements`
+  ],
+  [
+    "json",
+    `# db-mcp Help \u2014 JSON Operations (23 tools)
+
+## Collection & CRUD
+
+- \`sqlite_create_json_collection({ tableName, indexes: [{ path: "$.type" }, { path: "$.author" }] })\` \u2014 creates table with JSON indexes
+- \`sqlite_json_insert({ table, column, data: { type: "article", title: "Hello", tags: ["news"] } })\` \u2014 insert JSON document
+- \`sqlite_json_select({ table, column, extractPaths? })\` \u2014 select rows, optionally extract specific JSON paths
+- \`sqlite_json_update({ table, column, path, value, whereClause })\` \u2014 update value at JSON path
+- \`sqlite_json_query({ table, column, filterPaths: { "$.type": "article" }, selectPaths: ["$.title"] })\` \u2014 query with path-based filters and projections
+
+## Path Operations
+
+- \`sqlite_json_extract({ table, column, path: "$.title" })\` \u2014 extract value at path. Returns null if path doesn't exist
+- \`sqlite_json_set({ table, column, path: "$.views", value: 100, whereClause: "id = 1" })\` \u2014 set value at path (creates if missing)
+- \`sqlite_json_merge({ table, column, mergeData: { featured: true }, whereClause: "id = 1" })\` \u2014 merge object into existing JSON
+- \`sqlite_json_remove({ table, column, path, whereClause })\` \u2014 remove key at path
+- \`sqlite_json_validate_path({ path: "$.store.books[0].title" })\` \u2014 validate JSON path syntax without executing a query
+- \`sqlite_json_type({ table, column, path })\` \u2014 get JSON type (null, true, false, integer, real, text, array, object)
+
+## Array Operations
+
+\u26A0\uFE0F \`json_each\` multiplies output rows \u2014 use \`limit\` param for large arrays
+
+- \`sqlite_json_array_append({ table, column, path: "$.tags", value: "featured", whereClause: "id = 1" })\` \u2014 append to array
+- \`sqlite_json_array_length({ table, column, path })\` \u2014 get array length
+- \`sqlite_json_each({ table, column, path: "$.tags", limit: 50 })\` \u2014 expand array to rows
+
+## Aggregation & Analysis
+
+\`\`\`javascript
+// Regular tables: use column names directly
+sqlite_json_group_array({ table: "events", valueColumn: "user_id", groupByColumn: "event_type" });
+
+// JSON collections: use allowExpressions with json_extract for both columns
+// \u26A0\uFE0F allowExpressions is for column extraction ONLY, NOT aggregate functions
+// \u26A0\uFE0F Without groupByColumn, each row creates a key-value pair; duplicate keys if values aren't unique
+sqlite_json_group_array({
+  table: "docs",
+  valueColumn: "json_extract(data, '$.author')",
+  groupByColumn: "json_extract(data, '$.type')",
+  allowExpressions: true,
+});
+
+// For aggregate values (COUNT, SUM, AVG), use aggregateFunction parameter instead
+sqlite_json_group_object({ table: "events", keyColumn: "event_type", aggregateFunction: "COUNT(*)" });
+sqlite_json_group_object({ table: "orders", keyColumn: "status", aggregateFunction: "SUM(total)" });
+\`\`\`
+
+- \`sqlite_json_keys({ table, column, path? })\` \u2014 get distinct keys of JSON objects
+- \`sqlite_json_pretty({ table, column, whereClause? })\` \u2014 format JSON with indentation
+- \`sqlite_json_valid({ table, column })\` \u2014 check if values are valid JSON
+- \`sqlite_json_analyze_schema({ table, column })\` \u2014 infer schema types
+
+## JSONB Optimization (SQLite 3.45+)
+
+- \`sqlite_json_storage_info({ table, column })\` \u2014 check text vs JSONB format
+- \`sqlite_jsonb_convert({ table, column })\` \u2014 convert to JSONB for faster queries
+- \`sqlite_json_normalize_column({ table, column, outputFormat? })\` \u2014 normalize JSON (sort keys, compact). \u26A0\uFE0F Defaults to \`"preserve"\` (maintains original format); use \`outputFormat: "text"\` to force text output`
+  ],
+  [
+    "migration",
+    `# db-mcp Help \u2014 Migration Tracking (6 tools)
+
+\u26A0\uFE0F Must call \`sqlite_migration_init()\` before using any other migration tool \u2014 it creates the tracking table.
+
+\`\`\`javascript
+// Initialize tracking table (idempotent \u2014 safe to call multiple times)
+sqlite_migration_init();
+
+// Apply migration: executes SQL and records atomically. If SQL fails, no record is created
+// SHA-256 dedup \u2014 submitting the same SQL twice is rejected as a duplicate
+sqlite_migration_apply({
+  version: "2024-01-15-add-users",
+  description: "Create users table",
+  migrationSql: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)",
+  rollbackSql: "DROP TABLE users",
+  sourceSystem: "agent",
+  appliedBy: "claude",
+});
+
+// Record externally-applied migration (does NOT execute the SQL)
+sqlite_migration_record({
+  version: "2024-01-10-initial",
+  description: "Initial schema (pre-existing)",
+  migrationSql: "CREATE TABLE orders (...)",
+  sourceSystem: "manual",
+});
+
+// Rollback by ID or version \u2014 requires rollbackSql to have been recorded
+sqlite_migration_rollback({ version: "2024-01-15-add-users" });
+sqlite_migration_rollback({ id: 3, dryRun: true }); // preview SQL without executing
+
+// Query history with filters and pagination
+sqlite_migration_history({ status: "applied", limit: 10 });
+sqlite_migration_history({ sourceSystem: "agent", compact: true }); // compact omits hash and source system
+
+// Summary: latest version, counts by status, unique source systems
+sqlite_migration_status();
+\`\`\`
+
+## \u26A0\uFE0F Gotchas
+
+- Rollback requires \`rollbackSql\` to have been provided when the migration was recorded/applied
+- Migration group is **opt-in** \u2014 not included in any shortcut except \`dev-schema\` and \`full\``
+  ],
+  [
+    "stats",
+    `# db-mcp Help \u2014 Statistical Analysis (13 core + 6 window)
+
+## Core Statistics (always available)
+
+\`\`\`javascript
+sqlite_stats_basic({ table: "employees", column: "salary" }); // count, sum, avg, min, max
+sqlite_stats_count({ table: "orders", column: "status", distinct: true }); // count rows, optionally distinct
+sqlite_stats_group_by({ table: "orders", column: "total", groupBy: "status" }); // aggregate by group
+sqlite_stats_percentile({ table: "sales", column: "revenue", percentiles: [25, 50, 75, 90] });
+sqlite_stats_histogram({ table: "products", column: "price", buckets: 10 });
+sqlite_stats_correlation({ table: "data", column1: "x", column2: "y" }); // Pearson coefficient
+sqlite_stats_distinct({ table: "orders", column: "status" }); // distinct values
+sqlite_stats_summary({ table: "data", columns: ["price", "quantity", "discount"] }); // multi-column summary
+sqlite_stats_frequency({ table: "orders", column: "status" }); // frequency distribution
+sqlite_stats_regression({ table: "data", xColumn: "year", yColumn: "revenue" }); // linear
+sqlite_stats_regression({ table: "data", xColumn: "year", yColumn: "revenue", degree: 2 }); // quadratic
+sqlite_stats_outliers({ table: "sales", column: "amount", method: "iqr" }); // or "zscore". Use maxOutliers to limit payload
+sqlite_stats_hypothesis({ table: "samples", column: "value", testType: "ttest_one", expectedMean: 100 });
+\`\`\`
+
+\u26A0\uFE0F \`sqlite_stats_top_n\` \u2014 always use \`selectColumns\` to avoid returning all columns (large payloads with text fields):
+
+\`\`\`javascript
+sqlite_stats_top_n({
+  table: "products",
+  column: "price",
+  n: 10,
+  selectColumns: ["id", "name", "price"],
+});
+\`\`\`
+
+## Window Functions (6 tools, Native only)
+
+\`\`\`javascript
+sqlite_window_row_number({ table: "employees", orderBy: "hire_date", partitionBy: "department" });
+sqlite_window_rank({ table: "sales", orderBy: "revenue DESC", partitionBy: "region", rankType: "dense_rank" });
+sqlite_window_lag_lead({ table: "sales", orderBy: "date", column: "revenue", partitionBy: "region" }); // access previous/next row values
+sqlite_window_running_total({ table: "transactions", column: "amount", orderBy: "date" });
+sqlite_window_moving_avg({ table: "stock_prices", column: "close_price", orderBy: "date", windowSize: 7 });
+sqlite_window_ntile({ table: "employees", orderBy: "salary DESC", buckets: 4, partitionBy: "department" }); // quartiles
+\`\`\``
+  ],
+  [
+    "text",
+    `# db-mcp Help \u2014 Text Processing & FTS5
+
+## Full-Text Search / FTS5 (4 tools, Native only)
+
+\`\`\`javascript
+// Create FTS5 table with triggers for auto-sync on future changes
+sqlite_fts_create({ tableName: "articles_fts", sourceTable: "articles", columns: ["title", "content"] });
+sqlite_fts_rebuild({ table: "articles_fts" }); // \u26A0\uFE0F Required: populate index with existing data
+
+// FTS5 uses AND by default: "machine learning" = rows containing BOTH words
+// Use OR explicitly: "machine OR learning" for rows containing EITHER word
+sqlite_fts_search({ table: "articles_fts", query: "machine learning", limit: 10 });
+sqlite_fts_match_info({ table: "articles_fts", query: "machine learning" }); // bm25 ranking info
+\`\`\`
+
+\u26A0\uFE0F FTS5 virtual tables (\`*_fts\`) and shadow tables (\`*_fts_*\`) are hidden from \`sqlite_list_tables\` for cleaner output
+
+## Text Processing (13 tools)
+
+\`\`\`javascript
+// Regex patterns: \u26A0\uFE0F Double-escape backslashes (\\\\) when passing through JSON/MCP
+sqlite_regex_match({ table: "logs", column: "message", pattern: "ERROR:\\\\\\\\s+(\\\\\\\\w+)" });
+sqlite_regex_extract({ table: "users", column: "email", pattern: "@([a-zA-Z0-9.-]+)", groupIndex: 1 });
+
+// Text manipulation
+sqlite_text_split({ table: "users", column: "email", delimiter: "@" }); // split into parts array
+sqlite_text_concat({ table: "users", columns: ["first_name", "last_name"], separator: " " });
+sqlite_text_replace({ table: "docs", column: "content", search: "old", replacement: "new" });
+sqlite_text_trim({ table: "users", column: "name" }); // trim whitespace
+sqlite_text_case({ table: "products", column: "name", mode: "upper" }); // or "lower"
+sqlite_text_substring({ table: "codes", column: "value", start: 1, length: 3 }); // extract substring
+sqlite_text_normalize({ table: "docs", column: "content", mode: "strip_accents" }); // or nfc, nfd, nfkc, nfkd
+
+// Validation patterns: email, phone, url, uuid, ipv4, custom
+sqlite_text_validate({ table: "users", column: "email", pattern: "email" });
+sqlite_text_validate({ table: "data", column: "field", pattern: "custom", customPattern: "^[A-Z]{2}[0-9]{4}$" });
+
+// Fuzzy matching \u2014 matches WORD TOKENS by default (not entire value)
+// "laptop" matches "Laptop Pro 15" (distance 0 on first token). Use tokenize: false for full-string matching.
+sqlite_fuzzy_match({ table: "products", column: "name", search: "laptop", maxDistance: 2 });
+sqlite_fuzzy_match({ table: "products", column: "name", search: "laptob", maxDistance: 2, tokenize: false }); // full value
+
+// Phonetic matching \u2014 finds words that sound alike (matches against any word in value)
+// Use includeRowData: false for lighter payloads when only matching values are needed
+sqlite_phonetic_match({ table: "products", column: "name", search: "laptop", algorithm: "soundex" });
+sqlite_phonetic_match({ table: "products", column: "name", search: "laptop", includeRowData: false }); // lighter
+
+// Advanced search \u2014 combines exact, fuzzy, and phonetic techniques
+// fuzzyThreshold: 0.3-0.4 = loose matching (more results), 0.6-0.8 = strict matching (fewer results)
+sqlite_advanced_search({
+  table: "products", column: "name", searchTerm: "laptop",
+  techniques: ["exact", "fuzzy", "phonetic"], fuzzyThreshold: 0.4,
+});
+\`\`\``
+  ],
+  [
+    "vector",
+    `# db-mcp Help \u2014 Vector/Semantic Search (11 tools)
+
+\`\`\`javascript
+// Create vector table with metadata columns
+sqlite_vector_create_table({ tableName: "docs", dimensions: 384, additionalColumns: [{ name: "content", type: "TEXT" }] });
+
+// Store vectors (single and batch)
+sqlite_vector_store({ table: "docs", idColumn: "id", vectorColumn: "emb", id: 1, vector: [...] });
+sqlite_vector_batch_store({ table: "docs", idColumn: "id", vectorColumn: "emb", items: [{ id: 1, vector: [...] }, { id: 2, vector: [...] }] });
+
+// Search vectors (returnColumns omits vector data from results for smaller payloads)
+sqlite_vector_search({ table: "docs", vectorColumn: "emb", queryVector: [...], limit: 10, returnColumns: ["id", "title"] });
+
+// Retrieve and delete vectors
+// Note: sqlite_vector_get returns parsed 'vector' array + raw JSON string in 'metadata' for flexibility
+sqlite_vector_get({ table: "docs", idColumn: "id", vectorColumn: "emb", id: 1 });
+sqlite_vector_delete({ table: "docs", idColumn: "id", ids: [1, 2, 3] });
+
+// Vector metadata
+sqlite_vector_count({ table: "docs" }); // or with dimensions filter: { table: "docs", dimensions: 384 }
+sqlite_vector_dimensions({ table: "docs", vectorColumn: "emb" });
+sqlite_vector_stats({ table: "docs", vectorColumn: "emb" }); // magnitude min/max/avg
+
+// Utility tools for preprocessing
+sqlite_vector_normalize({ vector: [3, 4, 0, 0] }); // returns unit vector [0.6, 0.8, 0, 0]
+sqlite_vector_distance({ vector1: [...], vector2: [...], metric: "cosine" }); // or "euclidean", "dot"
+\`\`\``
+  ]
+]);
+
+// src/server/mcp-server.ts
+var DbMcpServer = class {
+  server;
+  adapters = /* @__PURE__ */ new Map();
+  toolFilter;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.toolFilter = config.toolFilter ? parseToolFilter(config.toolFilter) : getToolFilterFromEnv();
+    this.server = new McpServer(
+      {
+        name: config.name,
+        version: config.version
+      },
+      {
+        capabilities: {
+          logging: {}
+        },
+        instructions: INSTRUCTIONS
+      }
+    );
+    logger.info(getFilterSummary(this.toolFilter), { module: "FILTER" });
+    logger.info("MCP Server initialized", {
+      module: "SERVER",
+      name: config.name,
+      version: config.version,
+      toolFilter: config.toolFilter ?? "none",
+      capabilities: ["logging"]
+    });
+    this.registerBuiltInTools();
+    this.registerHelpResources();
+  }
+  /**
+   * Register a database adapter
+   */
+  async registerAdapter(adapter, config) {
+    const adapterId = `${adapter.type}:${config.connectionString ?? "default"}`;
+    await adapter.connect(config);
+    this.adapters.set(adapterId, adapter);
+    adapter.registerTools(this.server, this.toolFilter);
+    adapter.registerResources(this.server);
+    adapter.registerPrompts(this.server);
+    logger.info(`Registered adapter: ${adapter.name} (${adapterId})`, {
+      module: "SERVER"
+    });
+  }
+  /**
+   * Get an adapter by ID
+   */
+  getAdapter(adapterId) {
+    return this.adapters.get(adapterId);
+  }
+  /**
+   * Get all registered adapters
+   */
+  getAdapters() {
+    return this.adapters;
+  }
+  /**
+   * Register built-in server tools (health, info, etc.)
+   */
+  registerBuiltInTools() {
+    const serverInfoOpts = {
+      title: "Server Info",
+      description: "Get information about the db-mcp server and registered adapters",
+      icons: SERVER_ICONS,
+      annotations: READ_ONLY
+    };
+    this.server.registerTool(
+      "server_info",
+      serverInfoOpts,
+      () => {
+        const adapterInfo = [];
+        for (const [id, adapter] of this.adapters) {
+          adapterInfo.push({
+            id,
+            ...adapter.getInfo()
+          });
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  name: this.config.name,
+                  version: this.config.version,
+                  transport: this.config.transport,
+                  adapters: adapterInfo,
+                  toolFilter: {
+                    raw: this.toolFilter.raw,
+                    enabledGroups: [...this.toolFilter.enabledGroups]
+                  }
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+    );
+    const healthOpts = {
+      title: "Server Health",
+      description: "Check health status of all database connections",
+      icons: SERVER_ICONS,
+      annotations: READ_ONLY
+    };
+    this.server.registerTool(
+      "server_health",
+      healthOpts,
+      async () => {
+        const health = {
+          server: "healthy",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          adapters: {}
+        };
+        for (const [id, adapter] of this.adapters) {
+          try {
+            const adapterHealth = await adapter.getHealth();
+            health["adapters"][id] = adapterHealth;
+          } catch (error) {
+            health["adapters"][id] = {
+              connected: false,
+              error: error instanceof Error ? error.message : "Unknown error"
+            };
+          }
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(health, null, 2)
+            }
+          ]
+        };
+      }
+    );
+    const listAdaptersOpts = {
+      title: "List Adapters",
+      description: "List all registered database adapters",
+      icons: SERVER_ICONS,
+      annotations: READ_ONLY
+    };
+    this.server.registerTool(
+      "list_adapters",
+      listAdaptersOpts,
+      () => {
+        const adapters = [];
+        for (const [id, adapter] of this.adapters) {
+          adapters.push({
+            id,
+            type: adapter.type,
+            name: adapter.name,
+            version: adapter.version,
+            connected: adapter.isConnected()
+          });
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(adapters, null, 2)
+            }
+          ]
+        };
+      }
+    );
+  }
+  /**
+   * Register sqlite://help resources for on-demand reference documentation.
+   * Always registers sqlite://help (gotchas). Group-specific help is filtered
+   * by the tool filter configuration.
+   */
+  registerHelpResources() {
+    const gotchasContent = HELP_CONTENT.get("gotchas");
+    if (gotchasContent) {
+      this.server.registerResource(
+        "sqlite_help",
+        "sqlite://help",
+        {
+          description: "Critical gotchas, WASM vs Native comparison, and Code Mode API reference",
+          mimeType: "text/markdown"
+        },
+        () => ({
+          contents: [
+            {
+              uri: "sqlite://help",
+              mimeType: "text/markdown",
+              text: gotchasContent
+            }
+          ]
+        })
+      );
+    }
+    const groupHelpKeys = [
+      { group: "json", key: "json" },
+      { group: "text", key: "text" },
+      { group: "stats", key: "stats" },
+      { group: "vector", key: "vector" },
+      { group: "geo", key: "geo" },
+      { group: "admin", key: "admin" },
+      { group: "introspection", key: "introspection" },
+      { group: "migration", key: "migration" }
+    ];
+    for (const { group, key } of groupHelpKeys) {
+      if (!this.toolFilter.enabledGroups.has(group)) continue;
+      const content = HELP_CONTENT.get(key);
+      if (!content) continue;
+      this.server.registerResource(
+        `sqlite_help_${key}`,
+        `sqlite://help/${key}`,
+        {
+          description: `Tool reference for the ${group} tool group`,
+          mimeType: "text/markdown"
+        },
+        () => ({
+          contents: [
+            {
+              uri: `sqlite://help/${key}`,
+              mimeType: "text/markdown",
+              text: content
+            }
+          ]
+        })
+      );
+    }
+    const registeredHelp = ["sqlite://help"];
+    for (const { group, key } of groupHelpKeys) {
+      if (this.toolFilter.enabledGroups.has(group)) {
+        registeredHelp.push(`sqlite://help/${key}`);
+      }
+    }
+    logger.info(`Help resources: ${registeredHelp.join(", ")}`, {
+      module: "SERVER"
+    });
+  }
+  /**
+   * Start the server with the configured transport
+   */
+  async start() {
+    switch (this.config.transport) {
+      case "stdio":
+        await this.startStdio();
+        break;
+      case "http":
+        await this.startHttp();
+        break;
+      default:
+        throw new DbMcpError(
+          `Unsupported transport: ${this.config.transport}`,
+          "SERVER_START_FAILED",
+          "config" /* CONFIGURATION */
+        );
+    }
+  }
+  /**
+   * Start server with stdio transport
+   */
+  async startStdio() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    logger.info(`db-mcp server started (stdio transport)`, {
+      module: "SERVER"
+    });
+  }
+  /**
+   * Start server with HTTP transport (Streamable HTTP with SSE support)
+   */
+  async startHttp() {
+    const { HttpTransport } = await import('./http-VSB7DBJR.js');
+    const oauthConfig = {
+      enabled: this.config.oauth?.enabled ?? false,
+      authorizationServerUrl: this.config.oauth?.authorizationServerUrl ?? "",
+      audience: this.config.oauth?.audience ?? this.config.name
+    };
+    if (this.config.oauth?.issuer !== void 0) {
+      oauthConfig.issuer = this.config.oauth.issuer;
+    }
+    if (this.config.oauth?.jwksUri !== void 0) {
+      oauthConfig.jwksUri = this.config.oauth.jwksUri;
+    }
+    if (this.config.oauth?.clockTolerance !== void 0) {
+      oauthConfig.clockTolerance = this.config.oauth.clockTolerance;
+    }
+    if (this.config.oauth?.publicPaths !== void 0) {
+      oauthConfig.publicPaths = this.config.oauth.publicPaths;
+    }
+    const transport = new HttpTransport({
+      port: this.config.port ?? 3e3,
+      ...this.config.host !== void 0 && { host: this.config.host },
+      ...this.config.authToken !== void 0 && {
+        authToken: this.config.authToken
+      },
+      ...this.config.enableHSTS !== void 0 && {
+        enableHSTS: this.config.enableHSTS
+      },
+      oauth: oauthConfig,
+      stateless: this.config.statelessHttp ?? false
+    });
+    await transport.initialize(this.server);
+    await transport.start();
+    const mode = this.config.statelessHttp ? "stateless" : "stateful";
+    const host = this.config.host ?? "0.0.0.0";
+    const port = String(this.config.port ?? 3e3);
+    logger.info(
+      `db-mcp server started (HTTP transport on ${host}:${port}, ${mode} mode)`,
+      { module: "TRANSPORT", mode }
+    );
+  }
+  /**
+   * Gracefully shut down the server
+   */
+  async shutdown() {
+    logger.info("Shutting down db-mcp server...", { module: "SERVER" });
+    for (const [id, adapter] of this.adapters) {
+      try {
+        await adapter.disconnect();
+        logger.info(`Disconnected adapter: ${id}`, { module: "SERVER" });
+      } catch (error) {
+        logger.error(`Error disconnecting adapter ${id}`, {
+          module: "SERVER",
+          error: error instanceof Error ? error : void 0
+        });
+      }
+    }
+    await this.server.close();
+    logger.info("Server shutdown complete", { module: "SERVER" });
+  }
+};
+function createServer(config) {
+  return new DbMcpServer(config);
+}
+var DEFAULT_CONFIG = {
+  name: NAME,
+  version: VERSION,
+  transport: "stdio",
+  databases: []
+};
+
+export { DEFAULT_CONFIG, DbMcpServer, NAME, VERSION, createServer };