@vaultcompass/vault-guard-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vault & Compass LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+// src/server.ts
+var import_path2 = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
+var import_zod = require("zod");
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_vault_guard_core2 = require("@vaultcompass/vault-guard-core");
+var import_vault_guard_telemetry = require("@vaultcompass/vault-guard-telemetry");
+
+// src/workspace-scan.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var import_vault_guard_core = require("@vaultcompass/vault-guard-core");
+var MAX_FILE_SIZE = 10 * 1024 * 1024;
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".ico",
+  ".pdf",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".bin"
+]);
+function isBinaryFile(filePath) {
+  return BINARY_EXTENSIONS.has(import_path.default.extname(filePath).toLowerCase());
+}
+async function scanWorkspaceDirectory(root, scanner, concurrency = 10) {
+  const files = await (0, import_vault_guard_core.getFilesToScanAsync)(root, false);
+  const results = [];
+  let filesScanned = 0;
+  let bytesScanned = 0;
+  const scanOne = async (file) => {
+    try {
+      if (isBinaryFile(file)) return;
+      const st = await import_fs.default.promises.stat(file);
+      if (!st.isFile()) return;
+      filesScanned += 1;
+      bytesScanned += st.size;
+      const matches = await (0, import_vault_guard_core.scanTextFileAsync)(scanner, file, { maxFileBytes: MAX_FILE_SIZE });
+      if (matches.length > 0) {
+        results.push({ file, matches });
+      }
+    } catch {
+    }
+  };
+  for (let i = 0; i < files.length; i += concurrency) {
+    const batch = files.slice(i, i + concurrency);
+    await Promise.all(batch.map(scanOne));
+  }
+  return { results, filesScanned, bytesScanned };
+}
+
+// src/server.ts
+function makeScanner() {
+  const cwd = process.cwd();
+  let cfg;
+  try {
+    cfg = (0, import_vault_guard_core2.loadConfig)(cwd);
+  } catch (e) {
+    if (e instanceof import_vault_guard_core2.ConfigError) {
+      process.stderr.write(
+        `vault-guard MCP: ignoring broken config at ${e.filePath} \u2014 ${e.message}
+`
+      );
+      cfg = {};
+    } else {
+      throw e;
+    }
+  }
+  return new import_vault_guard_core2.SecretScanner(cfg);
+}
+function toolPayload(obj) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }]
+  };
+}
+function createMcpServer() {
+  const server = new import_mcp.McpServer(
+    { name: "vault-guard", version: "1.0.0" },
+    {
+      capabilities: {
+        tools: {}
+      },
+      instructions: "Vault Guard MCP: scan workspaces/files/text for secrets (SARIF-shaped JSON), report token estimates, and record opt-in session/usage events to local ~/.vault-guard/usage.sqlite."
+    }
+  );
+  const telemetry = new import_vault_guard_telemetry.TelemetryStore();
+  const tokenCounter = new import_vault_guard_core2.TokenCounter();
+  server.registerTool(
+    "scan_workspace",
+    {
+      title: "Scan workspace directory",
+      description: "Run the Vault Guard secret scanner on a directory (respects .gitignore). Returns JSON, SARIF string, and summary.",
+      inputSchema: {
+        root: import_zod.z.string().optional().describe("Directory to scan (default: process.cwd())")
+      }
+    },
+    async ({ root }) => {
+      const scanner = makeScanner();
+      const dir = import_path2.default.resolve(process.cwd(), root ?? ".");
+      const t0 = Date.now();
+      const { results, filesScanned, bytesScanned } = await scanWorkspaceDirectory(dir, scanner);
+      const run = {
+        duration_ms: Date.now() - t0,
+        files_scanned: filesScanned,
+        bytes_scanned: bytesScanned,
+        patterns_active: scanner.getActivePatternCount()
+      };
+      return toolPayload({
+        summary: {
+          files_with_secrets: results.length,
+          total_matches: results.reduce((n, r) => n + r.matches.length, 0)
+        },
+        json: JSON.parse((0, import_vault_guard_core2.formatJson)(results, { cwd: dir, run })),
+        sarif: (0, import_vault_guard_core2.formatSarif)(results, { cwd: dir, run }),
+        results
+      });
+    }
+  );
+  server.registerTool(
+    "scan_file",
+    {
+      title: "Scan a single file",
+      description: "Scan one file on disk for secrets. Returns JSON + SARIF.",
+      inputSchema: {
+        file_path: import_zod.z.string().describe("Absolute or relative path to a file")
+      }
+    },
+    async ({ file_path }) => {
+      const scanner = makeScanner();
+      const fp = import_path2.default.resolve(process.cwd(), file_path);
+      if (!import_fs2.default.existsSync(fp) || !import_fs2.default.statSync(fp).isFile()) {
+        return toolPayload({ error: "not_a_file", path: fp });
+      }
+      const t0 = Date.now();
+      const matches = scanner.scan(fp);
+      const st = import_fs2.default.statSync(fp);
+      const run = {
+        duration_ms: Date.now() - t0,
+        files_scanned: 1,
+        bytes_scanned: st.size,
+        patterns_active: scanner.getActivePatternCount()
+      };
+      const results = matches.length ? [{ file: fp, matches }] : [];
+      return toolPayload({
+        summary: { files_with_secrets: results.length, total_matches: matches.length },
+        json: JSON.parse((0, import_vault_guard_core2.formatJson)(results, { cwd: process.cwd(), run })),
+        sarif: (0, import_vault_guard_core2.formatSarif)(results, { cwd: process.cwd(), run })
+      });
+    }
+  );
+  server.registerTool(
+    "scan_text",
+    {
+      title: "Scan pasted text",
+      description: "Scan arbitrary UTF-8 text (e.g. proposed AI edit). Optional virtual_path for SARIF artifact URI only.",
+      inputSchema: {
+        text: import_zod.z.string().describe("UTF-8 content to scan"),
+        virtual_path: import_zod.z.string().optional().describe("Synthetic path label for SARIF (default: inline://snippet)")
+      }
+    },
+    async ({ text, virtual_path }) => {
+      const scanner = makeScanner();
+      const t0 = Date.now();
+      const matches = scanner.scanContent(text);
+      const label = virtual_path ?? "inline://snippet";
+      const results = matches.length ? [{ file: label, matches }] : [];
+      const bytes = Buffer.byteLength(text, "utf8");
+      const run = {
+        duration_ms: Date.now() - t0,
+        files_scanned: 1,
+        bytes_scanned: bytes,
+        patterns_active: scanner.getActivePatternCount()
+      };
+      return toolPayload({
+        summary: { total_matches: matches.length },
+        // virtual_path is a label, not a real path; skip relativization to preserve it verbatim.
+        json: JSON.parse((0, import_vault_guard_core2.formatJson)(results, { cwd: null, run })),
+        sarif: (0, import_vault_guard_core2.formatSarif)(results, { cwd: null, run })
+      });
+    }
+  );
+  server.registerTool(
+    "report_token_usage",
+    {
+      title: "Estimate token usage",
+      description: "Rough on-disk token estimate for paths (same heuristic as vault-guard tokens). Does not call cloud APIs.",
+      inputSchema: {
+        paths: import_zod.z.array(import_zod.z.string()).optional().describe("Files or directories to include (default: cwd)")
+      }
+    },
+    async ({ paths }) => {
+      const targets = paths && paths.length > 0 ? paths : [process.cwd()];
+      let total = 0;
+      const breakdown = {};
+      const walkFile = (file) => {
+        try {
+          if (!import_fs2.default.existsSync(file)) return;
+          const st = import_fs2.default.statSync(file);
+          if (st.isFile()) {
+            const n = tokenCounter.countTokensInFile(file);
+            total += n;
+            const ext = import_path2.default.extname(file) || "(no-ext)";
+            breakdown[ext] = (breakdown[ext] ?? 0) + n;
+          } else if (st.isDirectory()) {
+            const entries = import_fs2.default.readdirSync(file, { withFileTypes: true });
+            for (const e of entries) {
+              if (e.name === "node_modules" || e.name === ".git") continue;
+              walkFile(import_path2.default.join(file, e.name));
+            }
+          }
+        } catch {
+        }
+      };
+      for (const t of targets) {
+        walkFile(import_path2.default.resolve(process.cwd(), t));
+      }
+      const estCostAnthropic = tokenCounter.calculateCost("anthropic", total, 0);
+      return toolPayload({
+        total_tokens_estimated: total,
+        breakdown,
+        est_cost_usd_anthropic_input_only: Math.round(estCostAnthropic * 1e4) / 1e4
+      });
+    }
+  );
+  server.registerTool(
+    "record_session_event",
+    {
+      title: "Record session / accuracy event",
+      description: "Append an opt-in local telemetry row (e.g. accept/revert/secret_blocked). Stored under ~/.vault-guard/usage.sqlite only.",
+      inputSchema: {
+        event_type: import_zod.z.string().describe("e.g. accept | reject | revert | secret_blocked | completion"),
+        model: import_zod.z.string().optional(),
+        cwd: import_zod.z.string().optional(),
+        language: import_zod.z.string().optional(),
+        lines_accepted: import_zod.z.number().int().optional(),
+        lines_suggested: import_zod.z.number().int().optional(),
+        lines_reverted: import_zod.z.number().int().optional(),
+        extra: import_zod.z.record(import_zod.z.string(), import_zod.z.any()).optional()
+      }
+    },
+    async (args) => {
+      telemetry.recordSession({
+        eventType: args.event_type,
+        model: args.model,
+        cwd: args.cwd,
+        language: args.language,
+        linesAccepted: args.lines_accepted,
+        linesSuggested: args.lines_suggested,
+        linesReverted: args.lines_reverted,
+        extra: args.extra
+      });
+      return toolPayload({ ok: true });
+    }
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const server = createMcpServer();
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+}
+void main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@vaultcompass/vault-guard-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Vault Guard — scan tools + local telemetry hooks",
+  "main": "dist/index.js",
+  "bin": {
+    "vault-guard-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vaultcompasshq/vault-guard.git",
+    "directory": "packages/mcp"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=9.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3",
+    "@vaultcompass/vault-guard-core": "1.0.0",
+    "@vaultcompass/vault-guard-telemetry": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.1",
+    "esbuild": "^0.25.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "node scripts/build.cjs",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "start": "node dist/index.js"
+  }
+}