@evantahler/mcpx 0.16.1 → 0.16.3

package/.claude/skills/mcpx.md

@@ -25,7 +25,8 @@ This shows parameters, types, required fields, and the full JSON Schema.
 ## 3. Execute the tool
 
 ```bash
-mcpx exec <server> <tool> '<json args>'
+mcpx exec <tool> '<json args>'                # server auto-resolved if unambiguous
+mcpx exec <server> <tool> '<json args>'       # explicit server (required if tool name exists on multiple servers)
 mcpx exec <server> <tool> -f params.json
 ```
 
@@ -52,7 +53,10 @@ mcpx search "send a message"
 # See what parameters Slack_SendMessage needs
 mcpx info arcade Slack_SendMessage
 
-# Send a message
+# Send a message (server optional if tool name is unique)
+mcpx exec Slack_SendMessage '{"channel":"#general","message":"hello"}'
+
+# Or explicitly specify the server
 mcpx exec arcade Slack_SendMessage '{"channel":"#general","message":"hello"}'
 
 # Chain commands — search repos and read the first result
@@ -118,7 +122,8 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx info <server>`                  | Server overview (version, capabilities, tools) |
 | `mcpx info <server> <tool>`           | Show tool schema                  |
 | `mcpx exec <server>`                  | List tools for a server           |
-| `mcpx exec <server> <tool> '<json>'`  | Execute a tool                    |
+| `mcpx exec <tool> '<json>'`           | Execute tool (server auto-resolved) |
+| `mcpx exec <server> <tool> '<json>'`  | Execute tool (explicit server)    |
 | `mcpx exec <server> <tool> -f file`   | Execute with args from file       |
 | `mcpx search "<query>"`               | Search tools (keyword + semantic) |
 | `mcpx search -k "<pattern>"`          | Keyword/glob search only          |

package/.cursor/rules/mcpx.mdc

@@ -25,7 +25,8 @@ This shows parameters, types, required fields, and the full JSON Schema.
 ## 3. Execute the tool
 
 ```bash
-mcpx exec <server> <tool> '<json args>'
+mcpx exec <tool> '<json args>'                # server auto-resolved if unambiguous
+mcpx exec <server> <tool> '<json args>'       # explicit server (required if tool name exists on multiple servers)
 mcpx exec <server> <tool> -f params.json
 ```
 
@@ -52,7 +53,10 @@ mcpx search "send a message"
 # See what parameters Slack_SendMessage needs
 mcpx info arcade Slack_SendMessage
 
-# Send a message
+# Send a message (server optional if tool name is unique)
+mcpx exec Slack_SendMessage '{"channel":"#general","message":"hello"}'
+
+# Or explicitly specify the server
 mcpx exec arcade Slack_SendMessage '{"channel":"#general","message":"hello"}'
 
 # Chain commands — search repos and read the first result
@@ -118,7 +122,8 @@ mcpx deauth <server>           # remove stored auth
 | `mcpx info <server>`                  | Server overview (version, capabilities, tools) |
 | `mcpx info <server> <tool>`           | Show tool schema                  |
 | `mcpx exec <server>`                  | List tools for a server           |
-| `mcpx exec <server> <tool> '<json>'`  | Execute a tool                    |
+| `mcpx exec <tool> '<json>'`           | Execute tool (server auto-resolved) |
+| `mcpx exec <server> <tool> '<json>'`  | Execute tool (explicit server)    |
 | `mcpx exec <server> <tool> -f file`   | Execute with args from file       |
 | `mcpx search "<query>"`               | Search tools (keyword + semantic) |
 | `mcpx search -k "<pattern>"`          | Keyword/glob search only          |

package/README.md

@@ -12,14 +12,19 @@ Two audiences:
 ## Install
 
 ```bash
-# Via bun
+# Via bun (all platforms)
 bun install -g @evantahler/mcpx
 
-# Via curl
+# Via curl (macOS/Linux)
 curl -fsSL https://raw.githubusercontent.com/evantahler/mcpx/main/install.sh | bash
 ```
 
-The curl installer downloads a pre-built binary (macOS/Linux) — no runtime needed. The bun install method requires [Bun](https://bun.sh). Windows `.exe` binaries are available on the [GitHub Releases](https://github.com/evantahler/mcpx/releases) page.
+```powershell
+# Via PowerShell (Windows)
+irm https://raw.githubusercontent.com/evantahler/mcpx/main/install.ps1 | iex
+```
+
+The curl/PowerShell installers download a pre-built binary — no runtime needed. The bun install method requires [Bun](https://bun.sh). Binaries for all platforms are also available on the [GitHub Releases](https://github.com/evantahler/mcpx/releases) page.
 
 ## Quick Start
 
@@ -42,6 +47,9 @@ mcpx info github search_repositories
 # Execute a tool
 mcpx exec github search_repositories '{"query": "mcp server"}'
 
+# Execute a tool without specifying the server (auto-resolved)
+mcpx exec search_repositories '{"query": "mcp server"}'
+
 # Search tools — combines keyword and semantic matching
 mcpx search "post a ticket to linear"
 
@@ -70,6 +78,7 @@ mcpx search -n 5 "manage pull requests"
 | `mcpx index`                           | Build/rebuild the search index                         |
 | `mcpx index -i`                        | Show index status                                      |
 | `mcpx exec <server> <tool> [json]`     | Validate inputs locally, then execute tool             |
+| `mcpx exec <tool> [json]`              | Execute tool (server auto-resolved if unambiguous)     |
 | `mcpx exec <server> <tool> -f file`    | Read tool args from a JSON file                        |
 | `mcpx exec <server>`                   | List available tools for a server                      |
 | `mcpx auth <server>`                   | Authenticate with an HTTP MCP server (OAuth)           |
@@ -89,8 +98,8 @@ mcpx search -n 5 "manage pull requests"
 | `mcpx prompt`                          | List all prompts across all servers                    |
 | `mcpx prompt <server>`                 | List prompts for a server                              |
 | `mcpx prompt <server> <name> [json]`   | Get a specific prompt                                  |
-| `mcpx exec <server> <tool> --no-wait`  | Execute as async task, return task handle immediately  |
-| `mcpx exec <server> <tool> --ttl <ms>` | Set task TTL in milliseconds (default: 60000)          |
+| `mcpx exec [server] <tool> --no-wait`  | Execute as async task, return task handle immediately  |
+| `mcpx exec [server] <tool> --ttl <ms>` | Set task TTL in milliseconds (default: 60000)          |
 | `mcpx task list <server>`              | List tasks on a server                                 |
 | `mcpx task get <server> <taskId>`      | Get task status                                        |
 | `mcpx task result <server> <taskId>`   | Retrieve completed task result                         |
@@ -579,7 +588,7 @@ Then in any Claude Code session, the agent can use `/mcpx` or the skill triggers
 
 1. **Search first** — `mcpx search "<intent>"` to find relevant tools
 2. **Inspect** — `mcpx info <server> <tool>` to get the schema before calling
-3. **Execute** — `mcpx exec <server> <tool> '<json>'` to execute
+3. **Execute** — `mcpx exec <tool> '<json>'` to execute (or `mcpx exec <server> <tool> '<json>'` if the tool name is ambiguous)
 
 This keeps tool schemas out of the system prompt entirely. The agent discovers what it needs on-demand, saving tokens and context window space.
 
@@ -614,7 +623,8 @@ To discover tools:
   mcpx info <server> <tool>              # tool schema
 
 To execute tools:
-  mcpx exec <server> <tool> '<json args>'
+  mcpx exec <tool> '<json args>'              # server auto-resolved
+  mcpx exec <server> <tool> '<json args>'     # explicit server
   mcpx exec <server> <tool> -f params.json
 
 Always search before executing — don't assume tool names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evantahler/mcpx",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "A command-line interface for MCP servers. curl for MCP.",
   "type": "module",
   "bin": {

package/src/commands/exec.ts

@@ -11,27 +11,108 @@ import { logger } from "../output/logger.ts";
 import { validateToolInput } from "../validation/schema.ts";
 import { parseJsonArgs, readStdin } from "../lib/input.ts";
 import { DEFAULTS } from "../constants.ts";
+import type { ServerManager } from "../client/manager.ts";
+
+type ResolvedArgs =
+  | { mode: "list-tools"; server: string }
+  | { mode: "call-tool"; server: string; tool: string; argsStr: string | undefined };
+
+/**
+ * Resolve the positional args into either list-tools or call-tool mode.
+ * Supports both `exec <server> <tool> [args]` and `exec <tool> [args]`.
+ */
+async function resolveExecArgs(
+  manager: ServerManager,
+  first: string,
+  second: string | undefined,
+  third: string | undefined,
+): Promise<ResolvedArgs> {
+  const serverNames = manager.getServerNames();
+  const isServer = serverNames.includes(first);
+
+  if (isServer) {
+    // Traditional form: exec <server> [tool] [args]
+    if (!second) {
+      return { mode: "list-tools", server: first };
+    }
+
+    // Validate the tool exists on the specified server
+    const serverTools = await manager.listTools(first);
+    const toolExists = serverTools.some((t) => t.name === second);
+
+    if (!toolExists) {
+      const { tools } = await manager.getAllTools();
+      const matches = tools.filter((t) => t.tool.name === second);
+
+      if (matches.length === 1) {
+        throw new Error(
+          `Tool "${second}" not found on server "${first}". Did you mean:\n  mcpx exec ${matches[0]!.server} ${second}`,
+        );
+      } else if (matches.length > 1) {
+        const servers = matches.map((m) => m.server).join(", ");
+        throw new Error(
+          `Tool "${second}" not found on server "${first}". Found on: ${servers}\nUsage: mcpx exec <server> ${second} [args]`,
+        );
+      } else {
+        throw new Error(
+          `Tool "${second}" not found on server "${first}". Run "mcpx search ${second}" to find similar tools.`,
+        );
+      }
+    }
+
+    return { mode: "call-tool", server: first, tool: second, argsStr: third };
+  }
+
+  // Not a server name — treat first as a tool name
+  const toolName = first;
+  const { tools } = await manager.getAllTools();
+  const matches = tools.filter((t) => t.tool.name === toolName);
+
+  if (matches.length === 0) {
+    throw new Error(
+      `Unknown server or tool "${first}". Run "mcpx search ${first}" to find similar tools.`,
+    );
+  }
+
+  if (matches.length > 1) {
+    const servers = matches.map((m) => m.server).join(", ");
+    throw new Error(
+      `Ambiguous tool "${toolName}" — found on multiple servers: ${servers}\nSpecify the server: mcpx exec <server> ${toolName} [args]`,
+    );
+  }
+
+  return { mode: "call-tool", server: matches[0]!.server, tool: toolName, argsStr: second };
+}
 
 export function registerExecCommand(program: Command) {
   program
-    .command("exec <server> [tool] [args]")
-    .description("execute a tool (omit tool name to list available tools)")
+    .command("exec <first> [second] [third]")
+    .description("execute a tool (server is optional if tool name is unambiguous)")
     .option("-f, --file <path>", "read JSON args from a file")
     .option("--no-wait", "return task handle immediately without waiting for completion")
     .option("--ttl <ms>", "task TTL in milliseconds", String(DEFAULTS.TASK_TTL_MS))
     .action(
       async (
-        server: string,
-        tool: string | undefined,
-        argsStr: string | undefined,
+        first: string,
+        second: string | undefined,
+        third: string | undefined,
         options: { file?: string; wait: boolean; ttl: string },
       ) => {
         const { manager, formatOptions } = await getContext(program);
 
-        if (!tool) {
+        let resolved: ResolvedArgs;
+        try {
+          resolved = await resolveExecArgs(manager, first, second, third);
+        } catch (err) {
+          console.error(formatError(String(err), formatOptions));
+          await manager.close();
+          process.exit(1);
+        }
+
+        if (resolved.mode === "list-tools") {
           try {
-            const tools = await manager.listTools(server);
-            console.log(formatServerTools(server, tools, formatOptions));
+            const tools = await manager.listTools(resolved.server);
+            console.log(formatServerTools(resolved.server, tools, formatOptions));
           } catch (err) {
             console.error(formatError(String(err), formatOptions));
             process.exit(1);
@@ -40,6 +121,9 @@ export function registerExecCommand(program: Command) {
           }
           return;
         }
+
+        const { server, tool, argsStr } = resolved;
+
         try {
           // Error if both --file and positional arg provided
           if (options.file && argsStr) {