db-mcp 1.1.1 → 3.0.0

package/dist/codemode/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * db-mcp - Code Mode Types
+ *
+ * Type definitions for the sandboxed code execution environment.
+ */
+import type { ToolGroup } from "../types/index.js";
+/**
+ * Options for sandbox execution
+ */
+export interface SandboxOptions {
+    /** Memory limit in MB (default: 128) */
+    memoryLimitMb?: number;
+    /** Execution timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+    /** CPU time limit in milliseconds (default: 10000) */
+    cpuLimitMs?: number;
+}
+/**
+ * Options for the sandbox pool
+ */
+export interface PoolOptions {
+    /** Minimum instances to keep warm (default: 2) */
+    minInstances?: number;
+    /** Maximum instances in pool (default: 10) */
+    maxInstances?: number;
+    /** Idle timeout before disposing instance (default: 60000ms) */
+    idleTimeoutMs?: number;
+}
+/**
+ * Default sandbox configuration
+ */
+export declare const DEFAULT_SANDBOX_OPTIONS: Required<SandboxOptions>;
+/**
+ * Default pool configuration
+ */
+export declare const DEFAULT_POOL_OPTIONS: Required<PoolOptions>;
+/**
+ * Metrics collected during sandbox execution
+ */
+export interface ExecutionMetrics {
+    /** Wall clock time in milliseconds */
+    wallTimeMs: number;
+    /** CPU time consumed in milliseconds */
+    cpuTimeMs: number;
+    /** Peak memory usage in MB */
+    memoryUsedMb: number;
+}
+/**
+ * Result of sandbox code execution
+ */
+export interface SandboxResult {
+    /** Whether execution completed successfully */
+    success: boolean;
+    /** Return value from the code (if successful) */
+    result?: unknown;
+    /** Error message (if failed) */
+    error?: string | undefined;
+    /** Stack trace (if failed) */
+    stack?: string | undefined;
+    /** Execution logs */
+    logs?: string[];
+    /** Execution metrics */
+    metrics: ExecutionMetrics;
+}
+/**
+ * Security configuration for code validation
+ */
+export interface SecurityConfig {
+    /** Maximum code length in bytes (default: 50KB) */
+    maxCodeLength: number;
+    /** Maximum executions per minute per client (default: 60) */
+    maxExecutionsPerMinute: number;
+    /** Maximum result size in bytes (default: 10MB) */
+    maxResultSize: number;
+    /** Patterns to block in code */
+    blockedPatterns: RegExp[];
+}
+/**
+ * Default security configuration
+ */
+export declare const DEFAULT_SECURITY_CONFIG: SecurityConfig;
+/**
+ * Validation result from security checks
+ */
+export interface ValidationResult {
+    /** Whether the code passed validation */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: string[];
+}
+/**
+ * Execution record for audit logging
+ */
+export interface ExecutionRecord {
+    /** Unique execution ID */
+    id: string;
+    /** Client identifier (for rate limiting) */
+    clientId?: string | undefined;
+    /** Timestamp of execution start */
+    timestamp: Date;
+    /** Code that was executed (truncated for logging) */
+    codePreview: string;
+    /** Execution result */
+    result: SandboxResult;
+    /** Whether code was in readonly mode */
+    readonly: boolean;
+}
+/**
+ * Tool group API interface - each group exposes its tools as methods
+ */
+export interface GroupApi {
+    /** Tool group name */
+    readonly groupName: ToolGroup;
+}
+/**
+ * Options passed to sqlite_execute_code tool
+ */
+export interface ExecuteCodeOptions {
+    /** TypeScript code to execute */
+    code: string;
+    /** Timeout in milliseconds (max 30000) */
+    timeout?: number;
+    /** Restrict to read-only operations */
+    readonly?: boolean;
+}
+/**
+ * Result returned by sqlite_execute_code tool
+ */
+export interface ExecuteCodeResult {
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Return value from the code */
+    result?: unknown;
+    /** Error message (if failed) */
+    error?: string;
+    /** Execution logs */
+    logs?: string[];
+    /** Execution metrics */
+    metrics: ExecutionMetrics;
+}
+/**
+ * RPC request from worker thread to main thread.
+ * Sent over the MessagePort to invoke API methods on the main thread.
+ */
+export interface RpcRequest {
+    /** Unique request ID for correlating responses */
+    id: number;
+    /** API group name (e.g., "core", "json") */
+    group: string;
+    /** Method name within the group (e.g., "readQuery") */
+    method: string;
+    /** Arguments to pass to the method */
+    args: unknown[];
+}
+/**
+ * RPC response from main thread to worker thread.
+ * Sent back over the MessagePort with the result or error.
+ */
+export interface RpcResponse {
+    /** Matching request ID */
+    id: number;
+    /** Return value from the method (if successful) */
+    result?: unknown;
+    /** Error message (if failed) */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/codemode/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/codemode/types.ts"],"names":[],"mappings":"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"}

package/dist/constants/server-instructions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Server instructions for db-mcp (SQLite MCP Server).
+ *
+ * ⚠️  AUTO-GENERATED — DO NOT EDIT THIS FILE DIRECTLY
+ *     Edit src/constants/server-instructions/*.md instead,
+ *     then run: npm run generate:instructions
+ *
+ * Slim instructions are sent to MCP clients during initialization.
+ * Detailed help is available on-demand via sqlite://help resources.
+ */
+/**
+ * Slim instructions for the MCP instructions field (~600 chars).
+ * Points agents to sqlite://help resources for detailed reference.
+ */
+export declare const INSTRUCTIONS = "# db-mcp (SQLite MCP Server)\n\n## Quick Access\n\n| Purpose         | Action                     |\n| --------------- | -------------------------- |\n| Health check    | `server_health` tool       |\n| Server info     | `server_info` tool         |\n| Database schema | `sqlite://schema` resource |\n| Tool help       | `sqlite://help` resource   |\n\n## Built-in Tools\n\n`server_info`, `server_health`, `list_adapters`, `sqlite_execute_code` \u2014 injected into all configurations.\n\n## Help Resources\n\nRead `sqlite://help` for gotchas and critical usage patterns.\nRead `sqlite://help/{group}` for group-specific tool reference (core, json, text, stats, vector, geo, admin, transactions, introspection, migration).\nOnly help resources for your enabled tool groups are registered.";
+/**
+ * Help content keyed by group name.
+ * 'gotchas' is the always-available help (sqlite://help).
+ * Other keys are tool groups (sqlite://help/{group}).
+ */
+export declare const HELP_CONTENT: ReadonlyMap<string, string>;
+//# sourceMappingURL=server-instructions.d.ts.map

package/dist/constants/server-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/constants/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,yxBAmBwC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAm0BnD,CAAC"}

package/dist/filtering/tool-constants.d.ts

@@ -0,0 +1,45 @@
+/**
+ * db-mcp - Tool Constants
+ *
+ * Defines the tool groups and meta-groups used for filtering.
+ *
+ * GROUP TOOLS (adapter-registered, accessible via Code Mode sqlite.help()):
+ *   core: 21 tools (core/queries.ts, core/tables.ts, core/indexes.ts, core/convenience.ts, core/triggers.ts, core/constraints.ts, core/datetime.ts, core/alter-table.ts)
+ *   json: 25 tools (json-operations/crud+query+transform+security+diff.ts, json-helpers/read+write.ts)
+ *   text: 14 WASM / 19 Native (text/regex+formatting+search+validate+sentiment.ts, fts.ts)
+ *   stats: 17 WASM / 23 Native (stats/basic+advanced.ts, inference/, anomaly-detection.ts, schema-risks.ts, native: window.ts)
+ *   vector: 11 tools (vector/storage+search+metadata.ts)
+ *   admin: 31 WASM / 32 Native (admin/backup+verify+pragma+reindex+wal.ts, virtual/views+vtable+extensions+analysis.ts; dump.ts is NATIVE ONLY)
+ *   transactions: 8 Native (native: transactions.ts)
+ *   geo: 4 WASM / 11 Native (geo.ts, native: spatialite/tools+analysis.ts)
+ *   introspection: 10 tools (introspection/graph/tools.ts, analysis/constraints+risks+snapshot+diff.ts, diagnostics/storage+indexes+query-plan.ts)
+ *   migration: 6 tools (migration/tracking.ts) — opt-in
+ *   codemode: 1 tool (codemode.ts)
+ *   Subtotal: 139 WASM / 166 Native (excluding Code Mode)
+ *
+ * AUDIT TOOLS (server-level, MCP-only — NOT exposed in Code Mode):
+ *   5 tools (server/registration/audit-tools.ts)
+ *
+ * TOOL COUNT TAXONOMY:
+ *   Group tools:  166 Native / 139 WASM  (Code Mode sqlite.help() base total)
+ *   Audit tools:    5 Native /   5 WASM  (MCP-only)
+ *   Inventory:    171 Native / 144 WASM  (Group + Audit)
+ *   Built-in:       4 /   4              (server_info, health, adapters, + Code Mode injected)
+ *   MCP total:    175 Native / 148 WASM  (tools/list response)
+ */
+import type { ToolGroup, MetaGroup } from "../types/index.js";
+/**
+ * All valid tool groups
+ */
+export declare const ALL_TOOL_GROUPS: ToolGroup[];
+/**
+ * Tool groups - kept for backwards compatibility with scopes.ts
+ * The actual filtering uses the tool's 'group' property, not these lists.
+ */
+export declare const TOOL_GROUPS: Record<ToolGroup, string[]>;
+/**
+ * Meta-groups that expand to multiple tool groups.
+ * These provide shortcuts for common use cases.
+ */
+export declare const META_GROUPS: Record<MetaGroup, ToolGroup[]>;
+//# sourceMappingURL=tool-constants.d.ts.map

package/dist/filtering/tool-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-constants.d.ts","sourceRoot":"","sources":["../../src/filtering/tool-constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,EAYtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CA+MnD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,CAiCtD,CAAC"}

package/dist/filtering/tool-filter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * db-mcp - Tool Filtering System
+ *
+ * Parses and applies tool filter rules from environment variables.
+ * Compatible with postgres-mcp-server filtering syntax.
+ *
+ * Syntax:
+ *   groupName     → Enable only this group (whitelist mode)
+ *   shortcut      → Use a preset (starter, analytics, search, etc.)
+ *   -group        → Disable all tools in a group
+ *   +group        → Enable all tools in a group
+ *   -tool         → Disable a specific tool
+ *   +tool         → Enable a specific tool
+ *
+ * Mode Detection:
+ *   - If first token starts with '-', start with ALL groups enabled (exclusion mode)
+ *   - Otherwise, start with NO groups enabled (whitelist mode)
+ *
+ * Examples:
+ *   "core,json"           → Whitelist: only core and json groups
+ *   "starter"             → Preset: core + json + text groups
+ *   "starter,-fts5"       → Preset minus fts5 group
+ *   "-vector,-geo"        → Legacy: all groups except vector and geo
+ */
+import type { ToolGroup, MetaGroup, ToolFilterConfig, ToolDefinition } from "../types/index.js";
+export { META_GROUPS, TOOL_GROUPS, ALL_TOOL_GROUPS } from "./tool-constants.js";
+/**
+ * Get all tool names from all groups (cached)
+ */
+export declare function getAllToolNames(): string[];
+/**
+ * Get the group for a specific tool (O(1) lookup)
+ */
+export declare function getToolGroup(toolName: string): ToolGroup | undefined;
+/**
+ * Clear all caches - useful for testing
+ */
+export declare function clearToolFilterCaches(): void;
+/**
+ * Check if a name is a valid tool group
+ */
+export declare function isToolGroup(name: string): name is ToolGroup;
+/**
+ * Check if a name is a valid meta-group
+ */
+export declare function isMetaGroup(name: string): name is MetaGroup;
+/**
+ * Get tool groups from a meta-group
+ */
+export declare function getMetaGroupGroups(metaGroup: MetaGroup): ToolGroup[];
+/**
+ * Parse a tool filter string into structured rules
+ *
+ * @param filterString - The filter string (e.g., "starter" or "-vector,-geo")
+ * @returns Parsed filter configuration with enabled groups
+ */
+export declare function parseToolFilter(filterString: string | undefined): ToolFilterConfig;
+/**
+ * Check if a tool is enabled based on filter configuration
+ * Uses the tool's group property for matching
+ */
+export declare function isToolEnabled(tool: ToolDefinition, config: ToolFilterConfig): boolean;
+/**
+ * Filter a list of tool definitions based on filter configuration
+ */
+export declare function filterTools(tools: ToolDefinition[], config: ToolFilterConfig): ToolDefinition[];
+/**
+ * Get the tool filter from environment variable
+ */
+export declare function getToolFilterFromEnv(): ToolFilterConfig;
+/**
+ * Generate a summary of the current filter configuration
+ */
+export declare function getFilterSummary(config: ToolFilterConfig): string;
+/**
+ * Get a list of all meta-groups with their expanded groups
+ */
+export declare function getMetaGroupInfo(): {
+    metaGroup: MetaGroup;
+    groups: ToolGroup[];
+}[];
+//# sourceMappingURL=tool-filter.d.ts.map

package/dist/filtering/tool-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-filter.d.ts","sourceRoot":"","sources":["../../src/filtering/tool-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAchF;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAM1C;AAkBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,CAE3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,CAE3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,gBAAgB,CA+HlB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAoCT;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,gBAAgB,GACvB,cAAc,EAAE,CAElB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,CAIvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAiCjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB,EAAE,CAKF"}