@node9/proxy 1.2.0 → 1.3.1

package/README.md

@@ -15,6 +15,19 @@ While others try to _guess_ if a prompt is malicious (Semantic Security), Node9
 
 ---
 
+## Contents
+
+|                                                   |                                                    |
+| ------------------------------------------------- | -------------------------------------------------- |
+| [💎 The Aha Moment](#-the-aha-moment)             | [🌐 MCP Gateway](#-mcp-gateway)                    |
+| [⚡ Key Features](#-key-features)                 | [🔗 Config Precedence](#-configuration-precedence) |
+| [🎮 Try it Live](#-try-it-live)                   | [⚙️ Custom Rules](#️-custom-rules-advanced)         |
+| [🚀 Quick Start](#-quick-start)                   | [🖥️ CLI Reference](#️-cli-reference)                |
+| [🛡️ How Protection Works](#️-how-protection-works) | [🔧 Troubleshooting](#-troubleshooting)            |
+| [🛠 Protection Modes](#-protection-modes)         | [🗺️ Roadmap](#️-roadmap)                            |
+
+---
+
 ## 💎 The "Aha!" Moment
 
 **AIs are literal.** When you ask an agent to "Fix my disk space," it might decide to run `docker system prune -af`.
@@ -206,11 +219,117 @@ node9 shield status             # see what's currently active
 
 ## 🛠 Protection Modes
 
-| Mode            | Target                 | How it works                                            |
-| :-------------- | :--------------------- | :------------------------------------------------------ |
-| **Hook Mode**   | Claude, Gemini, Cursor | `node9 addto <agent>` wires native pre-execution hooks. |
-| **Proxy Mode**  | MCP Servers, Shell     | `node9 "npx <server>"` intercepts JSON-RPC traffic.     |
-| **Manual Mode** | You                    | `node9 rm -rf /` protects you from your own typos.      |
+| Mode            | Target                        | How it works                                                             |
+| :-------------- | :---------------------------- | :----------------------------------------------------------------------- |
+| **Hook Mode**   | Claude Code, Gemini, Cursor   | `node9 addto <agent>` wires native pre-execution hooks.                  |
+| **MCP Gateway** | Any MCP server, any AI client | `node9 mcp-gateway --upstream <cmd>` wraps any MCP server transparently. |
+| **Manual Mode** | You                           | `node9 rm -rf /` protects you from your own typos.                       |
+
+---
+
+## 🌐 MCP Gateway
+
+The MCP Gateway is a **transparent stdio proxy** that sits between any AI agent and any MCP server. The agent doesn't know Node9 is there — it just sees the same MCP server it always did.
+
+```
+AI Agent (Claude, Cursor, Gemini…)
+    ↓ stdio  (JSON-RPC)
+Node9 MCP Gateway  ← intercepts every tools/call
+    ↓ stdio  (JSON-RPC)
+Upstream MCP Server (filesystem, postgres, browser…)
+```
+
+**Every `tools/call` is intercepted.** Read-only tools pass through silently. Write/mutate tools are routed through the full approval engine — DLP scan, smart rules, shields, and human approval.
+
+### Setup
+
+**1. Register any MCP server through the gateway:**
+
+```bash
+# Filesystem server — protect all file writes
+claude mcp add filesystem -- node9 mcp-gateway --upstream \
+  "npx -y @modelcontextprotocol/server-filesystem /your/workspace"
+
+# Any other MCP server — same pattern
+claude mcp add myserver -- node9 mcp-gateway --upstream \
+  "npx -y @some/mcp-server"
+```
+
+**2. Add globally (all projects):**
+
+```bash
+claude mcp add --scope user filesystem -- node9 mcp-gateway --upstream \
+  "npx -y @modelcontextprotocol/server-filesystem /home/you"
+```
+
+**3. Share with your team via `.mcp.json` in the repo:**
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "node9",
+      "args": ["mcp-gateway", "--upstream", "npx -y @modelcontextprotocol/server-filesystem ."]
+    }
+  }
+}
+```
+
+> **Note:** `--upstream` takes a single command string. The gateway's tokenizer splits it on whitespace and handles double-quoted paths (e.g. `"npx \"/path with spaces/server.js\""`) — it does not run a shell.
+>
+> ⚠️ **Supply-chain warning:** `.mcp.json` files from untrusted repositories can specify any `--upstream` command. Always review `.mcp.json` before using it — treat it with the same caution as a `Makefile` or `package.json` `postinstall` script.
+
+### What gets protected
+
+The same `ignoredTools`, smart rules, shields, and DLP that protect hook-mode tools apply here — but matched against **MCP tool names** (e.g. `write_file`, `execute_query`) instead of Claude's built-in tools.
+
+**Tune your config for MCP tool names:**
+
+```json
+{
+  "policy": {
+    "ignoredTools": ["read_file", "read_text_file", "list_*", "search_*"],
+    "toolInspection": {
+      "write_file": "content",
+      "execute_query": "sql",
+      "run_command": "command"
+    }
+  }
+}
+```
+
+**Add MCP-specific smart rules:**
+
+```json
+{
+  "policy": {
+    "smartRules": [
+      {
+        "name": "block-write-production-config",
+        "tool": "write_file",
+        "conditions": [{ "field": "path", "op": "matches", "value": "/etc/|/prod/" }],
+        "verdict": "block",
+        "reason": "Writes to production config require a manual change process"
+      }
+    ]
+  }
+}
+```
+
+### How blocked calls look to the AI
+
+When Node9 blocks an MCP tool call, it returns a structured JSON-RPC error that tells the AI exactly what happened and instructs it to pivot:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 42,
+  "error": {
+    "code": -32000,
+    "message": "NODE9 SECURITY ALERT: Action blocked by DLP — credential detected in content field. Do NOT retry. Remove the hardcoded secret and use an environment variable instead."
+  }
+}
+```
 
 ---
 
@@ -327,18 +446,19 @@ Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which
 
 ## 🖥️ CLI Reference
 
-| Command                       | Description                                                                           |
-| :---------------------------- | :------------------------------------------------------------------------------------ |
-| `node9 setup`                 | Interactive menu — detects installed agents and wires hooks for you                   |
-| `node9 addto <agent>`         | Wire hooks for a specific agent (`claude`, `gemini`, `cursor`)                        |
-| `node9 init`                  | Create default `~/.node9/config.json`                                                 |
-| `node9 status`                | Show current protection status and active rules                                       |
-| `node9 doctor`                | Health check — verifies binaries, config, credentials, and all agent hooks            |
-| `node9 shield <cmd>`          | Manage shields (`enable`, `disable`, `list`, `status`)                                |
-| `node9 tail [--history]`      | Stream live agent activity to the terminal (auto-starts daemon if needed)             |
-| `node9 explain <tool> [args]` | Trace the policy waterfall for a given tool call (dry-run, no approval prompt)        |
-| `node9 undo [--steps N]`      | Revert the last N AI file edits using shadow Git snapshots                            |
-| `node9 check`                 | Called by agent hooks; evaluates a pending tool call and exits 0 (allow) or 1 (block) |
+| Command                              | Description                                                                           |
+| :----------------------------------- | :------------------------------------------------------------------------------------ |
+| `node9 setup`                        | Interactive menu — detects installed agents and wires hooks for you                   |
+| `node9 addto <agent>`                | Wire hooks for a specific agent (`claude`, `gemini`, `cursor`)                        |
+| `node9 init`                         | Create default `~/.node9/config.json`                                                 |
+| `node9 status`                       | Show current protection status and active rules                                       |
+| `node9 doctor`                       | Health check — verifies binaries, config, credentials, and all agent hooks            |
+| `node9 shield <cmd>`                 | Manage shields (`enable`, `disable`, `list`, `status`)                                |
+| `node9 tail [--history]`             | Stream live agent activity to the terminal (auto-starts daemon if needed)             |
+| `node9 explain <tool> [args]`        | Trace the policy waterfall for a given tool call (dry-run, no approval prompt)        |
+| `node9 undo [--steps N]`             | Revert the last N AI file edits using shadow Git snapshots                            |
+| `node9 mcp-gateway --upstream <cmd>` | Wrap an MCP server with Node9 security — intercepts every tool call                   |
+| `node9 check`                        | Called by agent hooks; evaluates a pending tool call and exits 0 (allow) or 1 (block) |
 
 ### `node9 doctor`
 
@@ -408,7 +528,7 @@ This can happen when the daemon's PID file (`~/.node9/daemon.pid`) is missing
 - [x] **Shield Templates** (`node9 shield enable <service>` — one-click protection for Postgres, GitHub, AWS)
 - [x] **Content Scanner / DLP** (Detect and block secrets like AWS keys and Bearer tokens in-flight)
 - [x] **Flight Recorder** (Real-time activity stream in browser dashboard and `node9 tail` terminal view)
-- [ ] **Universal MCP Gateway** (Standalone security tunnel for LangChain, CrewAI, and any agent without native hooks)
+- [x] **Universal MCP Gateway** (Transparent stdio proxy — wraps any MCP server for any AI agent: `node9 mcp-gateway --upstream <cmd>`)
 - [ ] **Cursor & Windsurf Hook** (Native hook support for AI-first IDEs)
 - [ ] **VS Code Extension** (Approval requests in a native sidebar — no more OS popups)
 - [ ] **Execution Sandboxing** (Simulate dangerous commands in a virtual FS before applying)