capybara-db-mcp 1.1.0 → 1.1.2

package/README.md

@@ -11,7 +11,7 @@ This project is intended for development, sandbox, or formally reviewed environm
 
 This project is designed to reduce the likelihood of exposing query results to LLMs, but it does not replace enterprise security controls and should not be used to bypass governance processes.
 
-**capybara-db-mcp** is a community fork of [DBHub](https://github.com/bytebase/dbhub) by [Bytebase](https://www.bytebase.com/). The key difference: **DBHub sends query results (rows, columns, counts) directly to the LLM**, which can expose sensitive data. capybara-db-mcp is designed to reduce the likelihood of exposing query results to LLMs by writing results to local files, opening them in the editor, and returning status-oriented metadata to the MCP client instead of result sets. It also implements SQL validation intended to restrict execution to read-only statements, keeps the same internal names (e.g. `dbhub.toml`) for easy merging from upstream, and adds **default-schema support** for PostgreSQL and multi-database setups.
+**capybara-db-mcp** is a community fork of [DBHub](https://github.com/bytebase/dbhub) by [Bytebase](https://www.bytebase.com/). The key difference: **DBHub sends query results (rows, columns, counts) directly to the LLM**, which can expose sensitive data. capybara-db-mcp is designed to reduce the likelihood of exposing query results to LLMs by writing results to local files, opening them in the editor, and returning status-oriented metadata to the MCP client instead of result sets. It uses connector-level read-only connections (PostgreSQL, SQLite), keeps the same internal names (e.g. `dbhub.toml`) for easy merging from upstream, and adds **default-schema support** for PostgreSQL and multi-database setups.
 
 - **Original project:** [github.com/bytebase/dbhub](https://github.com/bytebase/dbhub)
 - **This fork:** [github.com/ajgreyling/capybara-db-mcp](https://github.com/ajgreyling/capybara-db-mcp)
@@ -34,12 +34,12 @@ git remote set-url origin https://github.com/ajgreyling/capybara-db-mcp.git
 
 ```mermaid
 flowchart LR
-    subgraph clients["MCP Clients"]
+    subgraph clients["MCP Clients - Supported"]
         A[Claude Desktop]
         B[Claude Code]
         C[Cursor]
-        D[VS Code]
-        E[Copilot CLI]
+        D[Codex]
+        E[Gemini]
     end
 
     subgraph server["MCP Server"]
@@ -67,19 +67,27 @@ flowchart LR
     M --> Ma
 ```
 
+### Unsupported: VS Code / GitHub Copilot
+
+**VS Code and GitHub Copilot are not supported** for capybara-db-mcp for security reasons. There is no project-level ignore file (such as `.cursorignore` or `.aiexclude`) that Copilot consistently reads to exclude `.safe-sql-results/` from AI context. Query result files may therefore be exposed to the LLM when using VS Code/Copilot, undermining the PII isolation design.
+
+**Use of capybara-db-mcp in VS Code/Copilot is not recommended.** For PII-safe database workflows, use one of the supported editors that provide ignore mechanisms: **Cursor**, **Claude Code**, **Codex**, or **Gemini**.
+
 ## Security Model Overview
 
 capybara-db-mcp is designed to reduce the likelihood of transmitting query result data to an LLM by isolating result sets to the local filesystem and returning status-oriented metadata to the MCP client.
 
 - **1) LLM generates SQL**: The MCP client sends an `execute_sql` request containing SQL text.
-- **2) Server validates SQL**: The server performs SQL validation intended to restrict execution to read-only statements (e.g., SELECT, WITH, EXPLAIN, SHOW).
-- **3) Query executes against the database**: The validated query runs using the configured connector.
-- **4) Results are written locally**: Result sets are written to `.safe-sql-results/` and opened in the editor (configurable).
+- **2) Connector is read-only**: Database connections are opened in read-only mode (PostgreSQL: `default_transaction_read_only`; SQLite: readonly file mode). Write attempts fail at the database level.
+- **3) Query executes against the database**: The query runs using the configured connector.
+- **4) Results are written locally**: Result sets are written to `.safe-sql-results/` and opened in the editor when running in a supported AI editor (Cursor, Claude Code, Codex, Gemini).
 - **5) LLM receives metadata only**: The MCP tool response is formatted to avoid including raw query results in the response payload.
 - **6) Logging remains local**: Operational logs and diagnostic details are written locally.
 
 This design reduces the likelihood of transmitting result data to an LLM, but it does not eliminate operational, environment, or governance risks. Database-level controls (RBAC, network segmentation, auditing) and approved operating procedures remain required.
 
+For detailed PII safety mechanisms (result isolation, generic errors, log redaction, search_objects names-only, request telemetry redaction, HTTP hardening), see [ARCHITECTURE.md](ARCHITECTURE.md).
+
 ### Result handling and LLM exposure minimization
 
 Query results are written to local files and opened in the editor; the MCP tool response is formatted to return success/failure metadata rather than result sets:
@@ -115,16 +123,16 @@ flowchart TB
 
 capybara-db-mcp is a zero-dependency, token-efficient MCP server implementing the Model Context Protocol (MCP). It supports the same features as DBHub, plus a default schema.
 
-**Read-only enforcement**: The server implements SQL validation intended to restrict execution to read-only statements (e.g., SELECT, WITH, EXPLAIN, SHOW). This enforcement reduces the risk of accidental writes, but it does not replace database-level RBAC or permissions configuration.
+**Read-only enforcement**: Database connections are opened in read-only mode (PostgreSQL: `default_transaction_read_only`; SQLite: readonly file mode). UPDATE, DELETE, INSERT, and other write operations fail at the connection level. This reduces the risk of accidental writes but does not replace database-level RBAC or permissions configuration.
 
-**Output isolation controls**: By default, query results are written to local files (`.safe-sql-results/`) and opened in the editor; tool responses are formatted to avoid returning result sets. Error payloads are formatted to avoid including SQL statements and parameter values; diagnostic details are logged locally, and database error messages are truncated. These mechanisms are designed to reduce LLM data exposure risk when used appropriately, and do not constitute regulatory compliance or replace enterprise data governance and DLP controls.
+**Output isolation controls**: By default, query results are written to local files (`.safe-sql-results/`) and opened in the editor when running in a supported client (Cursor, Claude Code, Codex, Gemini); tool responses are formatted to avoid returning result sets. Error responses return generic messages only (e.g. "Execution failed. See server logs for details."); no SQL, parameter values, or database error text are returned. Logs never include SQL or parameter values. These mechanisms are designed to reduce LLM data exposure risk when used appropriately, and do not constitute regulatory compliance or replace enterprise data governance and DLP controls.
 
 - **Local Development First**: Zero dependency, token efficient with just two MCP tools to maximize context window
 - **Multi-Database**: PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite through a single interface
 - **Multi-Connection**: Connect to multiple databases simultaneously with TOML configuration
 - **Default schema**: Use `--schema` (or TOML `schema = "..."`) so PostgreSQL uses that schema for `execute_sql` and `search_objects` is restricted to it (see below)
-- **Guardrails**: SQL read-only validation, row limiting, and a 60-second query timeout default (overridable per source via `query_timeout` in `dbhub.toml`) to reduce runaway operations
-- **Designed to reduce LLM data exposure**: Results are written to `.safe-sql-results/` and opened in the editor; tool responses are formatted to avoid returning result sets (including file path, row data, row counts, or column names). Error responses are formatted to avoid including SQL text and parameter values; database error text is truncated and detailed diagnostics are logged locally.
+- **Guardrails**: Connector-level read-only connections, row limiting, and a 60-second query timeout default (overridable per source via `query_timeout` in `dbhub.toml`) to reduce runaway operations
+- **Designed to reduce LLM data exposure**: Results are written to `.safe-sql-results/` and opened only in supported editors (Cursor, Claude Code, Codex, Gemini); tool responses return only success/failure metadata (no file path, row data, row counts, or column names). Error responses use generic messages only; no SQL, parameter values, or database error text reach the client. Logs are redacted to avoid SQL and parameter values.
 - **Secure Access**: SSH tunneling and SSL/TLS encryption
 
 ## Why Capybara?
@@ -138,8 +146,7 @@ PostgreSQL, MySQL, SQL Server, MariaDB, and SQLite.
 ## MCP Tools
 
 - **[execute_sql](https://dbhub.ai/tools/execute-sql)**: Execute SQL queries with transaction support and safety controls
-- **[search_objects](https://dbhub.ai/tools/search-objects)**: Search and explore database schemas, tables, columns, indexes, and procedures with progressive disclosure
-- **[Custom Tools](https://dbhub.ai/tools/custom-tools)**: Define reusable, parameterized SQL operations in your `dbhub.toml` configuration file
+- **[search_objects](https://dbhub.ai/tools/search-objects)**: Search and explore database schemas, tables, columns, indexes, and procedures (names only; summary/full metadata disabled for PII safety)
 
 ## Default schema (`--schema`)
 
@@ -186,13 +193,13 @@ Full DBHub docs (including TOML and command-line options) apply; see [dbhub.ai](
 
 ### Output isolation (designed to reduce LLM exposure)
 
-By default, `execute_sql` and custom tools write query results to `.safe-sql-results/` in your project directory and open them in the editor. The MCP tool response sent back to the MCP client is formatted to return success/failure metadata rather than result sets. This reduces the likelihood of transmitting result data to an LLM, but it does not eliminate data handling risk and does not by itself satisfy regulatory or compliance requirements.
+By default, `execute_sql` writes query results to `.safe-sql-results/` in your project directory and opens them in the editor when running in a supported AI editor (Cursor, Claude Code, Codex, Gemini). The MCP tool response sent back to the MCP client is formatted to return success/failure metadata rather than result sets. This reduces the likelihood of transmitting result data to an LLM, but it does not eliminate data handling risk and does not by itself satisfy regulatory or compliance requirements.
 
-To reduce exfiltration risk via dynamic SQL (e.g. `SELECT secret AS "password_is_hunter2"`), tool responses are formatted to avoid including file paths, row data, row counts, or column names. Error responses are formatted to avoid including SQL statements or parameter values; those details are logged locally for debugging. Database error messages are truncated before being returned.
+To reduce exfiltration risk via dynamic SQL (e.g. `SELECT secret AS "password_is_hunter2"`), tool responses are formatted to avoid including file paths, row data, row counts, or column names. Error responses return generic messages only (e.g. "Execution failed. See server logs for details."); no SQL, parameter values, or database error text are returned. Logs never include SQL or parameter values.
 
 ### Read-only enforcement
 
-The server implements SQL validation intended to restrict execution to read-only statements (e.g., SELECT, WITH, EXPLAIN, SHOW, DESCRIBE). This enforcement is a guardrail and does not substitute for database-level RBAC, permissions, or audit controls.
+Database connections are opened in read-only mode (PostgreSQL: `default_transaction_read_only`; SQLite: readonly file mode). UPDATE, DELETE, INSERT, and other write operations fail at the connection level. This is a guardrail and does not substitute for database-level RBAC, permissions, or audit controls.
 
 ## Workbench
 

package/dist/chunk-POWQBIVO.js

@@ -0,0 +1,118 @@
+// src/tools/builtin-tools.ts
+var BUILTIN_TOOL_EXECUTE_SQL = "execute_sql";
+var BUILTIN_TOOL_SEARCH_OBJECTS = "search_objects";
+var BUILTIN_TOOLS = [
+  BUILTIN_TOOL_EXECUTE_SQL,
+  BUILTIN_TOOL_SEARCH_OBJECTS
+];
+
+// src/tools/registry.ts
+var ToolRegistry = class {
+  constructor(config) {
+    this.toolsBySource = this.buildRegistry(config);
+  }
+  /**
+   * Check if a tool name is a built-in tool
+   */
+  isBuiltinTool(toolName) {
+    return BUILTIN_TOOLS.includes(toolName);
+  }
+  /**
+   * Build the internal registry mapping sources to their enabled tools
+   */
+  buildRegistry(config) {
+    const registry = /* @__PURE__ */ new Map();
+    for (const tool of config.tools || []) {
+      if (!this.isBuiltinTool(tool.name)) {
+        throw new Error(
+          `Unknown tool '${tool.name}'. Valid tools: ${BUILTIN_TOOLS.join(", ")}. Custom tools are not supported.`
+        );
+      }
+      const existing = registry.get(tool.source) || [];
+      existing.push(tool);
+      registry.set(tool.source, existing);
+    }
+    for (const source of config.sources) {
+      if (!registry.has(source.id)) {
+        const defaultTools = BUILTIN_TOOLS.map((name) => {
+          if (name === "execute_sql") {
+            return { name: "execute_sql", source: source.id };
+          } else {
+            return { name: "search_objects", source: source.id };
+          }
+        });
+        registry.set(source.id, defaultTools);
+      }
+    }
+    return registry;
+  }
+  /**
+   * Get all enabled tool configs for a specific source
+   */
+  getEnabledToolConfigs(sourceId) {
+    return this.toolsBySource.get(sourceId) || [];
+  }
+  /**
+   * Get built-in tool configuration for a specific source
+   * Returns undefined if tool is not enabled or not a built-in
+   */
+  getBuiltinToolConfig(toolName, sourceId) {
+    if (!this.isBuiltinTool(toolName)) {
+      return void 0;
+    }
+    const tools = this.getEnabledToolConfigs(sourceId);
+    return tools.find((t) => t.name === toolName);
+  }
+  /**
+   * Get all unique tools across all sources (for tools/list response)
+   * Returns the union of all enabled tools
+   */
+  getAllTools() {
+    const seen = /* @__PURE__ */ new Set();
+    const result = [];
+    for (const tools of this.toolsBySource.values()) {
+      for (const tool of tools) {
+        if (!seen.has(tool.name)) {
+          seen.add(tool.name);
+          result.push(tool);
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Get all built-in tool names that are enabled across any source
+   */
+  getEnabledBuiltinToolNames() {
+    const enabledBuiltins = /* @__PURE__ */ new Set();
+    for (const tools of this.toolsBySource.values()) {
+      for (const tool of tools) {
+        if (this.isBuiltinTool(tool.name)) {
+          enabledBuiltins.add(tool.name);
+        }
+      }
+    }
+    return Array.from(enabledBuiltins);
+  }
+};
+var globalRegistry = null;
+function initializeToolRegistry(config) {
+  globalRegistry = new ToolRegistry(config);
+}
+function getToolRegistry() {
+  if (!globalRegistry) {
+    throw new Error(
+      "Tool registry not initialized. Call initializeToolRegistry first."
+    );
+  }
+  return globalRegistry;
+}
+
+export {
+  BUILTIN_TOOL_EXECUTE_SQL,
+  BUILTIN_TOOL_SEARCH_OBJECTS,
+  BUILTIN_TOOLS,
+  ToolRegistry,
+  initializeToolRegistry,
+  getToolRegistry
+};