capybara-db-mcp 1.1.1 → 1.1.2

package/README.md

@@ -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,6 +67,12 @@ 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.
@@ -74,7 +80,7 @@ capybara-db-mcp is designed to reduce the likelihood of transmitting query resul
 - **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).
+- **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.
 
@@ -119,14 +125,14 @@ capybara-db-mcp is a zero-dependency, token-efficient MCP server implementing th
 
 **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 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.
+**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**: 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.
+- **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?
@@ -187,7 +193,7 @@ Full DBHub docs (including TOML and command-line options) apply; see [dbhub.ai](
 
 ### 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` 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 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.
 

package/dist/index.js

@@ -2461,7 +2461,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import express from "express";
-import path4 from "path";
+import path5 from "path";
 import { readFileSync as readFileSync3 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -3972,8 +3972,10 @@ function getOutputFormat() {
 
 // src/config/editor-command.ts
 var DEFAULT_EDITOR = "cursor";
+var SUPPORTED_EDITORS = ["cursor", "claude", "codex", "gemini"];
 var editorCommand = DEFAULT_EDITOR;
 var explicitlySet = false;
+var openingResultsSupported = false;
 function setEditorCommand(cmd) {
   editorCommand = cmd;
 }
@@ -3986,17 +3988,82 @@ function setEditorExplicitly(value) {
 function isEditorExplicitlySet() {
   return explicitlySet;
 }
+function setOpeningResultsSupported(value) {
+  openingResultsSupported = value;
+}
+function isOpeningResultsSupported() {
+  return openingResultsSupported;
+}
+function isEditorSupportedForOpening(editor) {
+  return SUPPORTED_EDITORS.includes(editor.toLowerCase());
+}
 function detectEditorFromClientName(name) {
   const lower = name.toLowerCase();
   if (lower.includes("cursor")) {
     return "cursor";
   }
-  if (lower.includes("vscode") || lower.includes("vs code") || lower.includes("visual studio code")) {
-    return "code";
+  if (lower.includes("claude")) {
+    return "claude";
+  }
+  if (lower.includes("codex")) {
+    return "codex";
+  }
+  if (lower.includes("gemini")) {
+    return "gemini";
+  }
+  if (lower.includes("vscode") || lower.includes("vs code") || lower.includes("visual studio code") || lower.includes("copilot")) {
+    return null;
   }
   return null;
 }
 
+// src/utils/ignore-file-sync.ts
+import fs3 from "fs";
+import path3 from "path";
+var AI_IGNORE_FILES = [
+  ".cursorignore",
+  ".claudeignore",
+  ".codeiumignore",
+  ".geminiignore"
+];
+var ENTRY = ".safe-sql-results/";
+var ENTRY_COMMENT = "# Query result files \u2014 contains PII data (names, SSNs, emails, DOBs, etc.)\n# These files must never be indexed, read, or included in AI context.";
+var NEGATION_PATTERN = /^\s*!\.safe-sql-results(\/.*)?\s*$/gm;
+var ENTRY_PRESENT = /\.safe-sql-results\/?(\s|$)/m;
+function removeNegationOverrides(content) {
+  return content.replace(NEGATION_PATTERN, "").replace(/\n{3,}/g, "\n\n");
+}
+function hasEntry(content) {
+  return ENTRY_PRESENT.test(content);
+}
+function ensureSafeSqlResultsInIgnoreFiles(projectRoot) {
+  for (const fileName of AI_IGNORE_FILES) {
+    const filePath = path3.join(projectRoot, fileName);
+    const exists = fs3.existsSync(filePath);
+    if (exists) {
+      let content = fs3.readFileSync(filePath, "utf-8");
+      content = removeNegationOverrides(content);
+      if (!hasEntry(content)) {
+        const trimmed = content.trimEnd();
+        const appended = trimmed ? `${trimmed}
+
+${ENTRY}
+` : `${ENTRY_COMMENT}
+${ENTRY}
+`;
+        fs3.writeFileSync(filePath, appended, "utf-8");
+      } else {
+        fs3.writeFileSync(filePath, content, "utf-8");
+      }
+    } else {
+      const content = `${ENTRY_COMMENT}
+${ENTRY}
+`;
+      fs3.writeFileSync(filePath, content, "utf-8");
+    }
+  }
+}
+
 // src/tools/execute-sql.ts
 import { z } from "zod";
 
@@ -4065,13 +4132,13 @@ function createToolSuccessResponse(data, meta = {}) {
 
 // src/utils/result-writer.ts
 import { exec } from "child_process";
-import fs3 from "fs";
-import path3 from "path";
+import fs4 from "fs";
+import path4 from "path";
 var OUTPUT_DIR = ".safe-sql-results";
 function ensureOutputDir() {
-  const dir = path3.join(process.cwd(), OUTPUT_DIR);
-  if (!fs3.existsSync(dir)) {
-    fs3.mkdirSync(dir, { recursive: true });
+  const dir = path4.join(process.cwd(), OUTPUT_DIR);
+  if (!fs4.existsSync(dir)) {
+    fs4.mkdirSync(dir, { recursive: true });
   }
   return dir;
 }
@@ -4126,7 +4193,7 @@ function writeResultFile(rows, toolName, format) {
   const dir = ensureOutputDir();
   const ext = format === "markdown" ? "md" : format;
   const sanitizedName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const filePath = path3.join(dir, `${timestamp()}_${sanitizedName}.${ext}`);
+  const filePath = path4.join(dir, `${timestamp()}_${sanitizedName}.${ext}`);
   let content;
   switch (format) {
     case "csv":
@@ -4139,14 +4206,20 @@ function writeResultFile(rows, toolName, format) {
       content = toMarkdownTable(rows);
       break;
   }
-  fs3.writeFileSync(filePath, content, "utf-8");
-  const resolvedPath = path3.resolve(filePath);
-  const editorCmd = getEditorCommand();
-  exec(`${editorCmd} "${resolvedPath}"`, { timeout: 5e3 }, (error) => {
-    if (error) {
-      console.error(`[result-writer] Failed to open result file in editor: ${error.message}`);
-    }
-  });
+  fs4.writeFileSync(filePath, content, "utf-8");
+  const resolvedPath = path4.resolve(filePath);
+  if (isOpeningResultsSupported()) {
+    const editorCmd = getEditorCommand();
+    exec(`${editorCmd} "${resolvedPath}"`, { timeout: 5e3 }, (error) => {
+      if (error) {
+        console.error(`[result-writer] Failed to open result file in editor: ${error.message}`);
+      }
+    });
+  } else {
+    console.error(
+      "[result-writer] Result written to .safe-sql-results/ (not opened \u2014 client does not support secure result handling)"
+    );
+  }
   return resolvedPath;
 }
 
@@ -5062,10 +5135,10 @@ function buildSourceDisplayInfo(sourceConfigs, getToolsForSource2, isDemo) {
 
 // src/server.ts
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname2 = path4.dirname(__filename2);
+var __dirname2 = path5.dirname(__filename2);
 var SERVER_VERSION = "0.0.0";
 try {
-  const packageJsonPath = path4.join(__dirname2, "..", "package.json");
+  const packageJsonPath = path5.join(__dirname2, "..", "package.json");
   const packageJson = JSON.parse(readFileSync3(packageJsonPath, "utf8"));
   if (typeof packageJson.version === "string") {
     SERVER_VERSION = packageJson.version;
@@ -5127,11 +5200,19 @@ See documentation for more details on configuring database connections.
     });
     console.error("Tool registry initialized");
     setOutputFormat(resolveOutputFormat());
+    ensureSafeSqlResultsInIgnoreFiles(process.cwd());
     const editorResult = resolveEditorCommand();
     if (editorResult) {
       setEditorCommand(editorResult.editor);
       setEditorExplicitly(true);
-      console.error(`Editor for result files: ${editorResult.editor} (${editorResult.source})`);
+      setOpeningResultsSupported(isEditorSupportedForOpening(editorResult.editor));
+      if (!isEditorSupportedForOpening(editorResult.editor)) {
+        console.error(
+          `Editor ${editorResult.editor} does not support secure result opening; results will not be opened automatically (${editorResult.source})`
+        );
+      } else {
+        console.error(`Editor for result files: ${editorResult.editor} (${editorResult.source})`);
+      }
     }
     const createServer2 = () => {
       const mcpServer = new McpServer({
@@ -5146,7 +5227,13 @@ See documentation for more details on configuring database connections.
           const detected = detectEditorFromClientName(clientName);
           if (detected) {
             setEditorCommand(detected);
+            setOpeningResultsSupported(true);
             console.error(`Editor for result files: ${detected} (detected from MCP client: ${clientName})`);
+          } else if (clientName) {
+            setOpeningResultsSupported(false);
+            console.error(
+              `MCP client "${clientName}" does not support secure result opening; results will not be opened automatically`
+            );
           }
         }
       };
@@ -5196,7 +5283,7 @@ See documentation for more details on configuring database connections.
         }
         next();
       });
-      const frontendPath = path4.join(__dirname2, "public");
+      const frontendPath = path5.join(__dirname2, "public");
       app.use(express.static(frontendPath));
       app.get("/healthz", (req, res) => {
         res.status(200).send("OK");
@@ -5230,7 +5317,7 @@ See documentation for more details on configuring database connections.
       });
       if (process.env.NODE_ENV !== "development") {
         app.get("*", (req, res) => {
-          res.sendFile(path4.join(frontendPath, "index.html"));
+          res.sendFile(path5.join(frontendPath, "index.html"));
         });
       }
       app.listen(port, bindAddress.host, () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capybara-db-mcp",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "mcpName": "io.github.ajgreyling/capybara-db-mcp",
   "description": "Minimal, token-efficient Database Read-Only PPI-safe MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB. Fork of DBHub with default-schema support.",
   "repository": {