run-mcp 1.7.0 → 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
 

package/dist/index.js

@@ -11,7 +11,7 @@ import { spawn } from "child_process";
 
 // src/config-scanner.ts
 import { existsSync } from "fs";
-import { readFile } from "fs/promises";
+import { readFile, readdir } from "fs/promises";
 import { homedir } from "os";
 import path from "path";
 import process2 from "process";
@@ -57,10 +57,14 @@ function getConfigPaths() {
     { source: "Gemini CLI (Project)", file: path.join(cwd, ".gemini", "settings.json") },
     { source: "Claude Code (Global)", file: path.join(home, ".claude.json") },
     { source: "Claude Code (Project)", file: path.join(cwd, ".mcp.json") },
-    { source: "Antigravity", file: path.join(home, ".gemini", "antigravity", "mcp_config.json") }
+    { source: "Antigravity", file: path.join(home, ".gemini", "antigravity", "mcp_config.json") },
+    {
+      source: "Gemini App (Global)",
+      file: path.join(home, ".gemini", "config", "mcp_config.json")
+    }
   ];
 }
-async function discoverServers() {
+async function discoverServers(options) {
   const servers = [];
   const paths = getConfigPaths();
   for (const { source, file } of paths) {
@@ -86,10 +90,52 @@ async function discoverServers() {
     } catch {
     }
   }
+  if (options?.scan) {
+    try {
+      let currentDir = process2.cwd();
+      const visited = /* @__PURE__ */ new Set();
+      while (currentDir && !visited.has(currentDir)) {
+        visited.add(currentDir);
+        if (existsSync(currentDir)) {
+          const files = await readdir(currentDir, { withFileTypes: true });
+          for (const file of files) {
+            if (file.isFile() && file.name.endsWith(".json")) {
+              if (file.name === "package-lock.json" || file.name === "package.json" || file.name === "tsconfig.json") {
+                continue;
+              }
+              const filePath = path.join(currentDir, file.name);
+              try {
+                const content = await readFile(filePath, "utf8");
+                if (content.includes("mcpServers")) {
+                  const json = JSON.parse(content);
+                  if (json.mcpServers && typeof json.mcpServers === "object") {
+                    for (const [name, config] of Object.entries(json.mcpServers)) {
+                      if (config && typeof config === "object" && config.command) {
+                        servers.push({
+                          name,
+                          config,
+                          source: `Local Workspace (${file.name})`
+                        });
+                      }
+                    }
+                  }
+                }
+              } catch {
+              }
+            }
+          }
+        }
+        const parent = path.dirname(currentDir);
+        if (parent === currentDir) break;
+        currentDir = parent;
+      }
+    } catch {
+    }
+  }
   return servers;
 }
-async function pickDiscoveredServer() {
-  const servers = await discoverServers();
+async function pickDiscoveredServer(options) {
+  const servers = await discoverServers(options);
   if (servers.length === 0) {
     return null;
   }
@@ -99,7 +145,7 @@ async function pickDiscoveredServer() {
     if (!uniqueServers.has(key)) {
       uniqueServers.set(key, s);
     } else {
-      if (s.source.includes("Project")) {
+      if (s.source.includes("Project") || s.source.includes("Local Workspace")) {
         uniqueServers.set(key, s);
       }
     }
@@ -1430,7 +1476,7 @@ var TargetManager = class _TargetManager extends EventEmitter {
         this.transport = stdioTransport;
       }
       this.client = new Client(
-        { name: "run-mcp", version: "1.7.0" },
+        { name: "run-mcp", version: "1.7.1" },
         {
           capabilities: {
             roots: { listChanged: true },
@@ -4425,7 +4471,7 @@ async function startServer(opts) {
     mediaThresholdKb: opts.mediaThresholdKb
   });
   const mcpServer = new McpServer(
-    { name: "run-mcp", version: "1.7.0" },
+    { name: "run-mcp", version: "1.7.1" },
     {
       capabilities: {
         tools: {},
@@ -5020,7 +5066,7 @@ Available: ${available}`
     },
     async () => {
       try {
-        const servers = await discoverServers();
+        const servers = await discoverServers({ scan: opts.scan });
         if (servers.length === 0) {
           return {
             content: [
@@ -5454,7 +5500,7 @@ ${stderrLines.join("\n") || "(none)"}`
       const searchTypes = type ?? ["tools"];
       const lowerQuery = query.toLowerCase();
       try {
-        const servers = await discoverServers();
+        const servers = await discoverServers({ scan: opts.scan });
         if (servers.length === 0) {
           return {
             content: [{ type: "text", text: "No local MCP servers found to search." }]
@@ -5975,7 +6021,7 @@ program.command("close-session").argument("<session_name>", "Session name").desc
     }
   }
 });
-program.name("run-mcp").description("A smart interactive REPL and live test harness for MCP servers").version("1.7.0").passThroughOptions().allowUnknownOption().argument(
+program.name("run-mcp").description("A smart interactive REPL and live test harness for MCP servers").version("1.7.1").passThroughOptions().allowUnknownOption().argument(
   "[target_command...]",
   "Command to spawn the target MCP server (starts REPL if provided, Agent server otherwise)"
 ).option("-o, --out-dir <path>", "Directory to save intercepted images and audio").option(
@@ -5990,7 +6036,10 @@ program.name("run-mcp").description("A smart interactive REPL and live test harn
 ).option("--mcp", "Force start Agent Server mode even if run interactively without arguments").option("-s, --script <file>", "Read commands from a file instead of stdin (REPL Mode only)").option("--color <mode>", "Color output mode: always, never, auto (default: auto)").option(
   "--open-media",
   "Automatically open intercepted images and audio files using the host OS viewer"
-).option("--sandbox <mode>", "Sandbox execution mode: auto, docker, native, audit, none", "none").addHelpText(
+).option("--sandbox <mode>", "Sandbox execution mode: auto, docker, native, audit, none", "none").option(
+  "--scan",
+  "Scan the current workspace and parent directories for any JSON files containing mcpServers"
+).addHelpText(
   "after",
   `
 Examples:
@@ -6085,10 +6134,11 @@ Shortcuts: tl td tc ts rl rr rt rs ru pl pg (see help for details)`
           allowNet: opts.allowNet,
           denyRead: opts.denyRead,
           denyWrite: opts.denyWrite,
-          denyNet: opts.denyNet
+          denyNet: opts.denyNet,
+          scan: opts.scan
         });
       } else {
-        const selected = await pickDiscoveredServer();
+        const selected = await pickDiscoveredServer({ scan: opts.scan });
         if (!selected) {
           console.log("Run 'run-mcp --help' to see manual usage instructions.");
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-mcp",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "A smart proxy and interactive REPL for Model Context Protocol (MCP) servers",
   "homepage": "https://github.com/funkyfunc/run-mcp#readme",
   "bugs": {
@@ -29,7 +29,7 @@
     "run-mcp": "dist/index.js"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/update-readme-help.js",
     "build:fixtures": "tsup tests/fixtures/mock-server.ts tests/fixtures/vulnerable-stdio-server.ts --format esm --target node18 --out-dir tests/fixtures/dist",
     "dev": "tsup --watch",
     "start": "node dist/index.js",