run-mcp 1.6.3 → 1.7.1

package/README.md

@@ -60,14 +60,28 @@ You'll see an interactive prompt:
 
 run-mcp [options] [target_command...]
 
-Options:
--V, --version Show version number
--o, --out-dir <path> Directory to save intercepted images and audio
--t, --timeout <ms> Default tool call timeout in milliseconds (default: 300000) (Agent Mode only)
---max-text <chars> Max text response length before truncation (default: 50000) (Agent Mode only)
---mcp Force start Agent Server mode even if run interactively without arguments
--s, --script <file> Read commands from a file instead of stdin (REPL Mode only)
--h, --help Display help for command
+<!-- OPTIONS_START -->
+| Option | Description |
+| :--- | :--- |
+| `-V, --version` | output the version number |
+| `-o, --out-dir <path>` | Directory to save intercepted images and audio |
+| `-t, --timeout <ms>` | Default tool call timeout in milliseconds (default: 300000) (Agent Mode only) |
+| `--max-text <chars>` | Max text response length before truncation (default: 50000) (Agent Mode only) |
+| `-m, --media-threshold <kb>` | Media size threshold in KB to save to disk (0 to always save, -1 to keep inline) |
+| `--mcp` | Force start Agent Server mode even if run interactively without arguments |
+| `-s, --script <file>` | Read commands from a file instead of stdin (REPL Mode only) |
+| `--color <mode>` | Color output mode: always, never, auto (default: auto) |
+| `--open-media` | Automatically open intercepted images and audio files using the host OS viewer |
+| `--sandbox <mode>` | Sandbox execution mode: auto, docker, native, audit, none (default: "none") |
+| `--scan` | Scan the current workspace and parent directories for any JSON files containing mcpServers |
+| `--allow-read <paths...>` | Paths to allow reading under the sandbox |
+| `--allow-write <paths...>` | Paths to allow writing under the sandbox |
+| `--allow-net <domains...>` | Network domains to allow connecting to under the sandbox |
+| `--deny-read <paths...>` | Paths to deny reading under the sandbox |
+| `--deny-write <paths...>` | Paths to deny writing under the sandbox |
+| `--deny-net <domains...>` | Network domains to deny connecting to under the sandbox |
+| `-h, --help` | display help for command |
+<!-- OPTIONS_END -->
 
 Examples:
   $ run-mcp                                       # Test harness (agent mode)
@@ -81,12 +95,20 @@ Examples:
 
 For CI/CD pipelines, shell scripts, or parsing via `jq`, `run-mcp` exposes a suite of headless subcommands that pipe clean JSON to stdout and isolate standard errors and progress updates to stderr.
 
-### ⚠️ Strictly Required Double-Dash `--`
+### ⚠️ Double-Dash `--` Separator
 
-To prevent argument parsing conflicts between `run-mcp` and the target server, **you must always separate the target command with a double-dash `--`**. This applies to both default REPL launching and all headless subcommands.
+To prevent argument parsing conflicts between `run-mcp` and the target server, you should separate the target command with a double-dash `--` when the target command itself contains flags or options.
 
-- **Correct**: `run-mcp list-tools -- node my-server.js`
-- **Incorrect**: `run-mcp list-tools node my-server.js` (will exit with a coaching error)
+* **Required when the target command has options/flags:**
+  ```bash
+  run-mcp list-tools -- node my-server.js --verbose
+  ```
+  *(Must use `--` so `--verbose` is passed to your server, not parsed as an option for `run-mcp`.)*
+* **Optional when the target command has no options/flags:**
+  ```bash
+  run-mcp list-tools node my-server.js
+  ```
+  *(Runs successfully without `--`.)*
 
 ### ⚡ HTTPie-Style Shorthand Arguments
 
@@ -119,14 +141,17 @@ run-mcp close-session main
 
 ### Available Headless Subcommands
 
-- `call <tool> [json_or_shorthand_args]`
-- `list-tools`
-- `list-resources`
-- `list-prompts`
-- `read <uri>`
-- `describe <tool>`
-- `get-prompt <name> [json_or_shorthand_args]`
+<!-- SUBCOMMANDS_START -->
+- `call [options] <tool> [json_args] [target_command...]`
+- `list-tools [options] [target_command...]`
+- `list-resources [options] [target_command...]`
+- `list-prompts [options] [target_command...]`
+- `read [options] <uri> [target_command...]`
+- `describe [options] <tool> [target_command...]`
+- `get-prompt [options] <name> [json_args] [target_command...]`
+- `daemon [options] <session_name> [target_command...]`
 - `close-session <session_name>`
+<!-- SUBCOMMANDS_END -->
 
 Use `run-mcp <subcommand> --help` for specific command options.
 
@@ -154,30 +179,49 @@ Add `run-mcp` to your agent's MCP configuration using `npx`:
 
 Then use these tools from your agent:
 
-| Tool                         | Description                                                                                                                       |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `connect_to_mcp`             | Spawn and connect to a local MCP server. Use `include` to get tools/resources/prompts inline. Shows a diff on reconnect.          |
-| `disconnect_from_mcp`        | Tear down the connection                                                                                                          |
-| `mcp_server_status`          | Check connection status                                                                                                           |
-| `call_mcp_primitive`         | Call a tool, read a resource, or get a prompt. Auto-connects if not already connected. Use `disconnect_after` for one-shot tests. |
-| `list_mcp_primitives`        | List tools, resources, and/or prompts on the connected server                                                                     |
-| `get_mcp_server_stderr`      | View target server stderr output                                                                                                  |
-| `list_available_mcp_servers` | Discover other local MCP servers configured on the host machine                                                                   |
+<!-- AGENT_TOOLS_START -->
+| Tool | Description |
+| :--- | :--- |
+| `connect_to_mcp` | Spawn and connect (use include to get tools/resources/prompts) |
+| `call_mcp_primitive` | Call a tool, read a resource, or get a prompt (auto-connects) |
+| `list_mcp_primitives` | List tools, resources, and/or prompts |
+| `disconnect_from_mcp` | Tear down and reconnect after changes |
+| `mcp_server_status` | Check connection status |
+| `get_mcp_server_stderr` | View target server stderr output |
+| `validate_mcp_server` | Validate an MCP server command and collect diagnostics |
+| `search_all_local_mcp_servers` | Scan and search all local MCP servers for a query |
+<!-- AGENT_TOOLS_END -->
 
 ## REPL Mode Commands
 
 Once connected via `run-mcp <command>`, the following shorthand commands are available:
 
-| Command                              | Description                                                                                               |
-| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `explore`                            | Open interactive fuzzy-search selector for tools, resources, and prompts                                  |
-| `tools/list`                         | List all tools exposed by the target server                                                               |
-| `tools/describe <name>`              | Show a tool's full input schema                                                                           |
-| `tools/call <name> [json] [--clear]` | Call a tool. Launch interactive wizard if no JSON provided. Use `--clear` to ignore remembered arguments. |
-| `tools/forget [name]`                | Clear remembered interactive arguments for a tool, or all tools if no name provided.                      |
-| `status`                             | Show target server status (PID, uptime, connection)                                                       |
-| `help`                               | Show available commands                                                                                   |
-| `exit` / `quit`                      | Disconnect and exit                                                                                       |
+<!-- REPL_COMMANDS_START -->
+| Command | Description |
+| :--- | :--- |
+| `tools/list` | List all available tools |
+| `tools/describe <name>` | Show a tool's input schema |
+| `tools/call <name> [json] [opts]` | Call a tool (interactive if no json) |
+| `tools/scaffold <name>` | Generate argument template for a tool |
+| `resources/list` | List all available resources |
+| `resources/read <uri>` | Read a resource by URI |
+| `resources/templates` | List resource templates |
+| `resources/subscribe <uri>` | Subscribe to resource changes |
+| `resources/unsubscribe <uri>` | Unsubscribe from resource changes |
+| `prompts/list` | List all available prompts |
+| `prompts/get <name> [json_args]` | Get a prompt with arguments |
+| `ping` | Verify connection, show round-trip time |
+| `log-level <level>` | Set server logging verbosity |
+| `history [count|clear]` | Show request/response history |
+| `notifications [count|clear]` | Show server notifications |
+| `roots/list` | Show configured client roots |
+| `roots/add <uri> [name]` | Add a root directory |
+| `roots/remove <uri>` | Remove a root directory |
+| `!! / last` | Re-run the last command |
+| `reconnect` | Disconnect and reconnect |
+| `timing` | Show tool call performance stats |
+| `status` | Show target server status |
+<!-- REPL_COMMANDS_END -->
 
 ### Examples
 
@@ -282,6 +326,81 @@ Tool call responses are processed through the interceptor pipeline. All other pr
 | **Timeouts**         | Tool calls are wrapped in a configurable timeout (default 60s, use `--timeout` to change)                                |
 | **Truncation**       | Text responses exceeding the limit (default 50K chars, use `--max-text` to change) are truncated                         |
 
+## Sandboxing & Outbound Data Exfiltration Protection
+
+`run-mcp` features a comprehensive multi-layered sandboxing engine designed to protect local systems and credentials from malicious or buggy MCP servers.
+
+### 🛡️ Sandboxing Modes
+
+You can restrict a target server's execution footprint using the `--sandbox` flag:
+
+- **`none`** (Default): No sandboxing. The target server runs with full user privileges.
+- **`auto`**: Automatically selects the most restrictive sandboxing system available on the host OS.
+- **`native`**: Uses OS-level native isolation:
+  - **macOS**: Utilizes the Seatbelt (App Sandbox) framework (`sandbox-exec`).
+  - **Linux**: Utilizes `bubblewrap` (`bwrap`) containerization.
+  - **Windows**: Utilizes `@microsoft/mxc-sdk` App Container sandboxing (requires the package to be present).
+- **`docker`**: Spawns the target command inside a fresh, network-disabled ephemeral Docker container (`node:20` or `python:3` depending on the command).
+- **`audit`**: Runs the server under a special non-enforcing native sandbox mode that permits operations but logs all network activity to the console.
+
+### 🌐 Outbound Network Proxy Auditing
+
+When a sandboxed server is granted outbound network access (e.g., using `--allow-net`), `run-mcp` automatically spawns a zero-dependency local **Network Audit Proxy**.
+- All outbound HTTP/HTTPS traffic is forced through the proxy using environment variables.
+- Target endpoints and protocols (including HTTPS `CONNECT` tunnels) are transparently logged to stderr in distinct cyan color:
+  ```
+  🌐 [NETWORK AUDIT] HTTP request to: http://example.com/api/v1/data
+  🌐 [NETWORK AUDIT] HTTPS connection established to: github.com
+  ```
+- Permits outbound traffic while providing complete visibility into where the server is sending data.
+
+### 🔑 Automatic Credential Protection (Deny-Wins)
+
+When outbound network capability is enabled, `run-mcp` automatically safeguards your local configuration files and private keys from exfiltration. 
+By default, the sandbox denies access to the following directories:
+- `~/.ssh` (SSH private keys and configs)
+- `~/.aws` (AWS credentials)
+- `~/.kube` (Kubernetes configurations)
+- `~/.config/gcloud` (Google Cloud SDK credentials)
+- `~/.netrc` and `~/.npmrc` (Authentication files)
+
+Access is strictly blocked using **Deny-Wins** precedence unless a folder is explicitly whitelisted.
+
+### ⚙️ Capabilities & Configuration
+
+You can configure sandbox rules on the command line or using structured JSON settings files.
+
+#### CLI Overrides
+
+Pass these flags after `run-mcp` and before the target command:
+- `--sandbox <mode>`: Set sandbox execution mode (`auto`, `native`, `docker`, `audit`, `none`).
+- `--allow-read <paths...>`: Allow reading specific host directories.
+- `--allow-write <paths...>`: Allow writing to specific host directories.
+- `--allow-net <domains...>`: Allow outbound network access to specific domains.
+- `--deny-read <paths...>`: Deny reading specific host directories.
+- `--deny-write <paths...>`: Deny writing to specific host directories.
+- `--deny-net <domains...>`: Deny outbound network access to specific domains.
+
+#### Configuration Scopes
+
+`run-mcp` resolves settings hierarchically, allowing both administrator enforcement and developer configuration:
+1. **Managed (Enterprise)**: System-wide read-only overrides (`/Library/Application Support/run-mcp/settings.json`, `C:\Program Files\run-mcp\settings.json`, `/etc/run-mcp/settings.json`).
+2. **User (Global)**: Personal defaults (`~/.gemini/antigravity-ide/settings.json` or equivalent).
+3. **Project**: Shared settings within a repository (`<workspace>/.run-mcp.json`).
+4. **Local**: Developer-specific project settings (`<workspace>/.run-mcp.local.json`).
+
+*Example Settings File (`.run-mcp.json`):*
+```json
+{
+  "sandbox": {
+    "mode": "native",
+    "allowRead": ["/usr/local/bin"],
+    "allowNet": ["*.api.github.com"],
+    "denyRead": ["~/.ssh"]
+  }
+}
+```
+
 ## Architecture
 
 ```