@vaultcompass/vault-guard-mcp 1.0.2 → 1.0.4

package/README.md

@@ -0,0 +1,89 @@
+# @vaultcompass/vault-guard-mcp
+
+[MCP](https://modelcontextprotocol.io/) server for [Vault Guard](https://github.com/vaultcompasshq/vault-guard). Gives Cursor and Claude the ability to scan a proposed edit before it lands, at edit time instead of commit time. One config line, fully local.
+
+## Install
+
+```bash
+npm install -g @vaultcompass/vault-guard-mcp
+```
+
+Requires **Node.js 22+**.
+
+## Quickstart (Cursor / Claude Desktop)
+
+Add to your MCP config (`~/.cursor/mcp.json`, `claude_desktop_config.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "vault-guard": {
+      "command": "npx",
+      "args": ["-y", "@vaultcompass/vault-guard-mcp"]
+    }
+  }
+}
+```
+
+Restart the editor. Vault Guard tools are now available to your AI agent.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `scan_workspace` | Scan a directory (`.gitignore`-aware). Returns JSON, SARIF, and summary. |
+| `scan_file` | Scan a single file on disk. |
+| `scan_text` | Scan arbitrary UTF-8 text (e.g. a proposed edit). Optional `virtual_path` for SARIF URIs. |
+| `report_token_usage` | Rough on-disk token estimate for paths (no network calls). |
+| `record_session_event` | Append an opt-in local row to `~/.vault-guard/usage.sqlite` (e.g. `secret_blocked`, `revert`). |
+
+## Example agent workflow
+
+1. Before applying an edit, the agent calls `scan_text` with the proposed content.
+2. If secrets are found, the agent warns the user or refuses to apply the change.
+3. For repo-wide checks, use `scan_workspace` on the project root.
+
+All scanning runs locally. No secrets or file contents are sent to external servers.
+
+## Development (from a clone)
+
+```bash
+git clone https://github.com/vaultcompasshq/vault-guard.git
+cd vault-guard
+pnpm install && pnpm --filter @vaultcompass/vault-guard-mcp build
+```
+
+Point MCP config at the local binary:
+
+```json
+{
+  "mcpServers": {
+    "vault-guard": {
+      "command": "pnpm",
+      "args": ["exec", "vault-guard-mcp"],
+      "cwd": "/path/to/vault-guard"
+    }
+  }
+}
+```
+
+## Privacy
+
+Telemetry written by `record_session_event` stays on disk under `~/.vault-guard/` only. See [docs/PRIVACY.md](https://github.com/vaultcompasshq/vault-guard/blob/main/docs/PRIVACY.md).
+
+## Related packages
+
+| Package | Purpose |
+|---------|---------|
+| [@vaultcompass/vault-guard](https://www.npmjs.com/package/@vaultcompass/vault-guard) | CLI (`vault-guard scan`, pre-commit hooks, proxy) |
+| [@vaultcompass/vault-guard-core](https://www.npmjs.com/package/@vaultcompass/vault-guard-core) | Scanning engine used by this server |
+
+## Documentation
+
+- [Full MCP reference](https://github.com/vaultcompasshq/vault-guard/blob/main/docs/MCP.md)
+- [GitHub repository](https://github.com/vaultcompasshq/vault-guard)
+- [Detection rules](https://github.com/vaultcompasshq/vault-guard/blob/main/docs/RULES.md)
+
+## License
+
+MIT. [Vault & Compass LLC](https://vaultcompass.io)

package/dist/index.js

@@ -86,6 +86,7 @@ async function scanWorkspaceDirectory(root, scanner, concurrency = 10) {
 }
 
 // src/server.ts
+var SERVER_VERSION = true ? "1.0.4" : "0.0.0-dev";
 function makeScanner() {
   const cwd = process.cwd();
   let cfg;
@@ -109,9 +110,9 @@ function toolPayload(obj) {
     content: [{ type: "text", text: JSON.stringify(obj, null, 2) }]
   };
 }
-function createMcpServer() {
+function createMcpServer(options = {}) {
   const server = new import_mcp.McpServer(
-    { name: "vault-guard", version: "1.0.0" },
+    { name: "vault-guard", version: SERVER_VERSION },
     {
       capabilities: {
         tools: {}
@@ -119,7 +120,27 @@ function createMcpServer() {
       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 telemetryFactory = options.telemetryFactory ?? (() => new import_vault_guard_telemetry.TelemetryStore());
+  let telemetry = null;
+  let telemetryUnavailable = false;
+  function getTelemetry() {
+    if (telemetry) return telemetry;
+    if (telemetryUnavailable) return null;
+    try {
+      telemetry = telemetryFactory();
+      return telemetry;
+    } catch (e) {
+      if (e instanceof import_vault_guard_telemetry.TelemetryUnavailableError) {
+        telemetryUnavailable = true;
+        process.stderr.write(
+          `vault-guard MCP: telemetry unavailable; session events will not be recorded: ${e.message}
+`
+        );
+        return null;
+      }
+      throw e;
+    }
+  }
   const tokenCounter = new import_vault_guard_core2.TokenCounter();
   server.registerTool(
     "scan_workspace",
@@ -275,7 +296,11 @@ function createMcpServer() {
       }
     },
     async (args) => {
-      telemetry.recordSession({
+      const store = getTelemetry();
+      if (!store) {
+        return toolPayload({ ok: false, telemetry: "unavailable" });
+      }
+      store.recordSession({
         eventType: args.event_type,
         model: args.model,
         cwd: args.cwd,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vaultcompass/vault-guard-mcp",
-  "version": "1.0.2",
-  "description": "MCP server for Vault Guard — scan tools + local telemetry hooks",
+  "version": "1.0.4",
+  "description": "Let Cursor and Claude scan AI-proposed edits for secrets before applying. Local MCP server.",
   "main": "dist/index.js",
   "bin": {
     "vault-guard-mcp": "./dist/index.js"
@@ -26,8 +26,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@vaultcompass/vault-guard-core": "1.0.2",
-    "@vaultcompass/vault-guard-telemetry": "1.0.2"
+    "@vaultcompass/vault-guard-core": "1.0.4",
+    "@vaultcompass/vault-guard-telemetry": "1.0.4"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",