capybara-db-mcp 1.0.6 → 1.1.1

package/README.md

@@ -1,8 +1,17 @@
 # capybara-db-mcp
 
-> **Your data is safe with Capybara.** Just like capybaras are famously safe and peaceful to be around, **capybara-db-mcp keeps your database data safe—your query results are never shared with an LLM.** Data stays on your machine; the model receives only success/failure.
+## ⚠️ Production & Governance Notice
 
-**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 PII-safe**: it writes results to local files, opens them in the editor, and returns only success/failure to the LLM—no data or file path ever reaches the model. It also enforces read-only SQL, 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.
+This project is intended for development, sandbox, or formally reviewed environments. Before connecting to any production system:
+
+- Conduct a security review
+- Validate data classification and handling requirements
+- Ensure compliance with internal AI and data governance policies
+- Confirm logging, auditing, and DLP controls are in place
+
+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 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)
@@ -58,9 +67,24 @@ flowchart LR
     M --> Ma
 ```
 
-### PII-safe data flow
+## 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) 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 (configurable).
+- **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.
 
-SQL results never reach the LLM. They are written to local files and opened in the editor; only a success/failure status is returned:
+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:
 
 ```mermaid
 flowchart TB
@@ -93,29 +117,21 @@ 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.
 
-**This fork is unconditionally read-only.** Only read-only SQL (SELECT, WITH, EXPLAIN, SHOW, etc.) is allowed. Write operations (UPDATE, DELETE, INSERT, MERGE, etc.) are never permitted.
+**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.
 
-**Your data is safe with Capybara.** Capybaras are famously safe and peaceful—and so is your data. Query results are **never shared with an LLM**. Raw data is written to local files (`.safe-sql-results/`) and opened in the editor; the LLM receives only success/failure. No file path, row count, or column names are returned (to prevent exfiltration via dynamic SQL). Error responses are also PII-safe: SQL statements and parameter values are never sent to the LLM; they are logged to stderr for local debugging, and database error messages are truncated. This prevents personally identifiable information (PII) from ever reaching the model. There is a default timeout of 60 seconds to ensure queries are not tying up the server. 
+**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 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**: Unconditionally read-only, row limiting, and a safe 60-second query timeout default (overridable per source via `query_timeout` in `dbhub.toml`) to prevent runaway operations
-- **PII-safe**: Query results are written to `.safe-sql-results/` and opened in the editor; only success/failure is sent to the LLM—no file path, row data, count, or column names (prevents exfiltration via dynamic column aliasing). Error responses are hardened: SQL and parameter values are logged locally, not returned to the LLM; database error text is truncated.
+- **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 in the editor; 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?
 
-The capybara is the spirit animal of capybara-db-mcp: calm, social, and famously safe to be around. **Just as capybaras are safe, your database data stays safe—never shared with an LLM**. It reflects the project's philosophy of peaceful coexistence, predictable behavior, and built-in guardrails.
-
-### The Capybara: A Paragon of Peaceful Coexistence
-
-- **Docile temperament**: Capybaras are known for gentle, non-aggressive behavior and are often seen peacefully sharing space with many species.
-- **Herbivorous nature**: As herbivores, they pose no predatory threat to humans or other animals.
-- **Social harmony**: They live in cooperative groups, reinforcing a "safe by default" ecosystem.
-- **Adaptability**: They thrive in different environments, reducing conflict and stress.
-- **Confident calm**: Other animals prefer their company, and capybaras are rarely rattled by neighbors around them.
+Capybara branding reflects a calm, predictable design philosophy: minimal surface area, conservative defaults, and straightforward operational behavior. Branding is not a security or compliance claim; apply your organization’s governance and review standards before production use.
 
 ## Supported Databases
 
@@ -124,8 +140,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`)
 
@@ -170,13 +185,15 @@ schema = "my_app_schema"
 
 Full DBHub docs (including TOML and command-line options) apply; see [dbhub.ai](https://dbhub.ai) and [Command-Line Options](https://dbhub.ai/config/command-line).
 
-### PII-safe output
+### Output isolation (designed to reduce LLM exposure)
+
+By default, `execute_sql` writes query results to `.safe-sql-results/` in your project directory and opens 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` 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 to the LLM contains only success/failure. **No file path, row data, row count, or column names** are returned—preventing both direct PII leakage and exfiltration via dynamic SQL (e.g. `SELECT secret AS "password_is_hunter2"`). Error responses are likewise hardened: SQL statements and parameter values are never included in tool error text sent to the LLM; they are logged to stderr for debugging. Database error messages are truncated before being returned. The user inspects results in the editor. Output format is configurable via `--output-format=csv|json|markdown` (default: `csv`).
+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 (unconditional)
+### Read-only enforcement
 
-This fork is unconditionally read-only. Write operations (UPDATE, DELETE, INSERT, MERGE, DROP, CREATE, ALTER, TRUNCATE, etc.) are never allowed. Only read-only SQL (SELECT, WITH, EXPLAIN, SHOW, DESCRIBE, etc.) is permitted.
+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
+};