@luutuankiet/mcp-proxy-shim 1.0.8 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @luutuankiet/mcp-proxy-shim
 
-**Stdio MCP shim for [mcpproxy-go](https://github.com/smart-mcp-proxy/mcpproxy-go)** — eliminates `args_json` string escaping overhead for LLM clients.
+**MCP shim for [mcpproxy-go](https://github.com/smart-mcp-proxy/mcpproxy-go)** — eliminates `args_json` string escaping overhead for LLM clients. Supports **stdio** and **HTTP Streamable** transports.
 
 ## The Problem
 
@@ -21,7 +21,7 @@ mcpproxy-go's `/mcp/call` mode uses **generic dispatcher tools** (`call_tool_rea
 The LLM must escape every quote, every nested object, every bracket. For complex tool calls (file edits with match_text containing code), this becomes:
 
 ```json
-"args_json": "{\"files\":[{\"path\":\"src/app.ts\",\"edits\":[{\"match_text\":\"function hello() {\\n  return \\\"world\\\";\\n}\",\"new_string\":\"function hello() {\\n  return \\\"universe\\\";\\n}\"}]}]}"
+"args_json": "{\"files\":[{\"path\":\"src/app.ts\",\"edits\":[{\"match_text\":\"function hello() {\\n  return \\\\\"world\\\\\";\\n}\",\"new_string\":\"function hello() {\\n  return \\\\\"universe\\\\\";\\n}\"}]}]}"
 ```
 
 This is **~400 tokens of overhead per call**, and LLMs frequently produce malformed payloads (mismatched escaping, missing backslashes).
@@ -56,11 +56,11 @@ Native JSON. No escaping. ~50 tokens. Zero malformed payloads.
 ```mermaid
 sequenceDiagram
     participant Client as MCP Client<br/>Claude Code / Cursor / etc
-    participant Shim as mcp-proxy-shim<br/>stdio
+    participant Shim as mcp-proxy-shim<br/>stdio or HTTP
     participant Proxy as mcpproxy-go<br/>StreamableHTTP
 
     Note over Client,Proxy: Connection Setup
-    Client->>Shim: initialize (stdio)
+    Client->>Shim: initialize (stdio or HTTP)
     Shim->>Proxy: initialize (HTTP)
     Proxy-->>Shim: capabilities + session ID
     Shim-->>Client: capabilities
@@ -97,6 +97,8 @@ Only 3 tools are transformed. **Everything else passes through unchanged:**
 
 ## Quick Start
 
+### Option A: Stdio (local MCP client)
+
 Add to your `.mcp.json` — no install needed, `npx` fetches on first run:
 
 ```json
@@ -119,19 +121,227 @@ Or run directly from the CLI:
 MCP_URL="https://your-proxy/mcp/?apikey=KEY" npx @luutuankiet/mcp-proxy-shim
 ```
 
+### Option B: HTTP Streamable Server (remote agents)
+
+Run as an HTTP server that remote MCP clients connect to over the network:
+
+```bash
+MCP_URL="https://upstream-proxy/mcp/?apikey=KEY" \
+  MCP_APIKEY="my-secret" \
+  npx @luutuankiet/mcp-proxy-shim serve
+```
+
+Then point your remote MCP client at:
+```
+http://localhost:3000/mcp?apikey=my-secret
+```
+
+#### Production deployment with Docker
+
+```yaml
+# docker-compose.yml
+services:
+  mcp-shim:
+    image: node:22-slim
+    command: npx -y @luutuankiet/mcp-proxy-shim serve
+    environment:
+      - MCP_URL=http://mcpproxy:9997/mcp/?apikey=admin
+      - MCP_PORT=3000
+      - MCP_HOST=0.0.0.0
+      - MCP_APIKEY=your-secret-key
+    ports:
+      - "3000:3000"
+```
+
+Put a reverse proxy (Caddy/nginx/Traefik) in front for TLS:
+```
+https://shim.yourdomain.com/mcp?apikey=KEY  →  http://localhost:3000/mcp
+```
+
+#### HTTP Server Architecture
+
+```mermaid
+sequenceDiagram
+    participant Agent as Remote Agent
+    participant Shim as mcp-proxy-shim<br/>HTTP :3000
+    participant Proxy as mcpproxy-go<br/>upstream
+
+    Note over Agent,Shim: Authentication
+    Agent->>Shim: POST /mcp?apikey=KEY
+    alt apikey invalid or missing
+        Shim-->>Agent: 401 Unauthorized
+    else apikey valid
+        Note over Shim: Create session transport
+        Shim->>Proxy: initialize shared upstream
+        Proxy-->>Shim: session ID
+        Shim-->>Agent: MCP session + Mcp-Session-Id header
+    end
+
+    Note over Agent,Shim: Subsequent requests
+    Agent->>Shim: POST /mcp?apikey=KEY<br/>Mcp-Session-Id: abc-123
+    Shim->>Proxy: tool call shared session
+    Proxy-->>Shim: result
+    Shim-->>Agent: result
+
+    Note over Shim: Multiple agents share<br/>one upstream connection
+```
+
+Each downstream client gets its own MCP session, but all sessions **share a single upstream connection** to mcpproxy-go. This is efficient — one upstream session, many downstream clients.
+
+**Endpoints:**
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/mcp` | POST | `?apikey=` | MCP JSON-RPC (initialize, tool calls) |
+| `/mcp` | GET | `?apikey=` | SSE stream reconnection |
+| `/mcp` | DELETE | `?apikey=` | Session termination |
+| `/health` | GET | None | Health check (session count, uptime) |
+
+### Option C: Daemon Mode (multi-server MCP gateway)
+
+Run a standalone gateway that connects to **multiple** MCP servers (stdio or HTTP) and exposes all their tools through a single HTTP endpoint. Pure passthrough — no schema transformation.
+
+**Use case:** Cloud agents (claude.ai/code, Codespaces, etc.) that can't spawn MCP servers on the fly.
+
+```
+Cloud Agent ──HTTP──▶ daemon (:3456) ──┬── stdio ──▶ github MCP
+                                       ├── stdio ──▶ filesystem MCP
+                                       └── HTTP  ──▶ remote API (with auth headers)
+```
+
+#### Inline config
+
+```bash
+MCP_SERVERS='{
+  "github": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": { "GITHUB_TOKEN": "ghp_..." }
+  },
+  "my-api": {
+    "type": "streamableHttp",
+    "url": "https://api.example.com/mcp",
+    "headers": { "Authorization": "Bearer xxx", "X-Org-Id": "org_123" }
+  }
+}' npx @luutuankiet/mcp-proxy-shim daemon
+```
+
+#### Config file
+
+```bash
+MCP_CONFIG=./mcp-servers.json npx @luutuankiet/mcp-proxy-shim daemon
+```
+
+The config file supports three formats:
+- Flat: `{ "server-name": { "type": "stdio", ... } }`
+- Wrapped: `{ "servers": { "server-name": { ... } } }`
+- `.mcp.json` format: `{ "mcpServers": { "server-name": { ... } } }`
+
+#### How clients use it
+
+All upstream tools are **namespaced** with the server name as prefix:
+
+```
+github__get_file_contents    ← from the "github" server
+my-api__query                ← from the "my-api" server
+```
+
+A built-in `daemon_help` tool provides a full usage guide:
+
+```json
+{ "name": "daemon_help", "arguments": {} }
+```
+
+Returns connected servers, all tools with namespaced names, and calling examples. You can also filter to a specific server for full schemas:
+
+```json
+{ "name": "daemon_help", "arguments": { "server": "github" } }
+```
+
+The daemon also returns `instructions` in the MCP `initialize` response, so MCP clients that support server instructions will automatically know how to use it.
+
+#### Server config reference
+
+**Stdio servers** (spawn a local process):
+
+```json
+{
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": { "GITHUB_TOKEN": "ghp_..." },
+  "cwd": "/optional/working/directory"
+}
+```
+
+**HTTP Streamable servers** (connect to remote MCP):
+
+```json
+{
+  "type": "streamableHttp",
+  "url": "https://api.example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer your-token",
+    "X-Custom-Header": "value"
+  }
+}
+```
+
+The `headers` field supports any custom HTTP headers — useful for authentication, org routing, or API versioning.
+
+#### Daemon environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_SERVERS` | — | JSON string with server configs (inline) |
+| `MCP_CONFIG` | — | Path to JSON config file (alternative to MCP_SERVERS) |
+| `MCP_PORT` | `3456` | Port to listen on |
+| `MCP_HOST` | `0.0.0.0` | Host to bind to |
+| `MCP_APIKEY` | — (open) | Require `?apikey=KEY` on `/mcp` requests |
+| `https_proxy` | — | HTTPS proxy for HTTP upstream connections |
+
+#### Daemon endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/mcp` | POST | MCP JSON-RPC (initialize, tools/list, tools/call) |
+| `/mcp` | GET | SSE stream reconnection |
+| `/mcp` | DELETE | Session termination |
+| `/health` | GET | Per-server status, tool counts, uptime |
+
+#### Production deployment
+
+```yaml
+# docker-compose.yml
+services:
+  mcp-daemon:
+    image: node:22-slim
+    command: npx -y @luutuankiet/mcp-proxy-shim daemon
+    environment:
+      - MCP_CONFIG=/config/servers.json
+      - MCP_APIKEY=your-secret
+    ports:
+      - "3456:3456"
+    volumes:
+      - ./mcp-servers.json:/config/servers.json:ro
+```
+
+---
+
 ## Why Not `/mcp/all`?
 
 mcpproxy-go exposes two routing modes:
 
 ```mermaid
 flowchart LR
-    subgraph "/mcp/all (direct mode)"
+    subgraph direct["/mcp/all - direct mode"]
         A1[Client] --> B1[myserver__read_files<br/>native schema]
         A1 --> C1[myserver__edit_files<br/>native schema]
         A1 --> D1[github__get_user<br/>native schema]
     end
 
-    subgraph "/mcp/call (retrieve_tools mode)"
+    subgraph call["/mcp/call - retrieve_tools mode"]
         A2[Client] --> B2[retrieve_tools<br/>BM25 search]
         A2 --> C2[call_tool_read<br/>generic dispatcher]
         A2 --> D2[upstream_servers<br/>add/remove/patch]
@@ -150,41 +360,56 @@ We tested this live: added a YNAB financial tool mid-session → 43 new tools ap
 # 1. User adds YNAB server to mcpproxy-go (via UI or API)
 
 # 2. Client discovers new tools (no reconnect!)
-→ retrieve_tools("ynab accounts balance")
-← [ynab__getAccounts, ynab__getTransactions, ynab__getPlans, ...]
+# retrieve_tools("ynab accounts balance")
+# => [ynab__getAccounts, ynab__getTransactions, ynab__getPlans, ...]
 
 # 3. Client calls with native args (shim handles serialization)
-→ call_tool_read {
-    name: "utils:ynab__getAccounts",
-    args: { plan_id: "abc-123" }  // ← native object, not escaped string
-  }
-← [{ name: "Checking", balance: 1500000, ... }]
+# call_tool_read {
+#     name: "utils:ynab__getAccounts",
+#     args: { plan_id: "abc-123" }  // native object, not escaped string
+#   }
+# => [{ name: "Checking", balance: 1500000, ... }]
 ```
 
 ## Configuration
 
-| Environment variable | Default | Description |
-|---------------------|---------|-------------|
-| `MCP_URL` | **(required)** | mcpproxy-go StreamableHTTP endpoint |
-| `https_proxy` / `HTTPS_PROXY` | — | HTTPS proxy (auto-detected via undici ProxyAgent) |
+| Environment variable | Default | Transport | Description |
+|---------------------|---------|-----------|-------------|
+| `MCP_URL` | **(required)** | Both | mcpproxy-go StreamableHTTP endpoint |
+| `MCP_PORT` | `3000` | HTTP only | Port to listen on |
+| `MCP_HOST` | `0.0.0.0` | HTTP only | Host to bind to |
+| `MCP_APIKEY` | — (open) | HTTP only | API key for downstream clients. When set, requests must include `?apikey=KEY`. Unset = no auth. |
+| `https_proxy` / `HTTPS_PROXY` | — | Both | HTTPS proxy (auto-detected via undici ProxyAgent) |
 
 ## Architecture Details
 
+### Transport Modes
+
+| Feature | Stdio | HTTP Streamable (`serve`) | Daemon (`daemon`) |
+|---------|-------|--------------------------|-------------------|
+| Use case | Local MCP client (Claude Code, Cursor) | Remote agents, single upstream | Cloud agents, multi-server gateway |
+| Connection | stdin/stdout | HTTP on `/mcp` | HTTP on `/mcp` |
+| Upstreams | Single (mcpproxy-go) | Single (mcpproxy-go) | Multiple (stdio + HTTP) |
+| Schema transforms | `args_json` → `args` | `args_json` → `args` | None (pure passthrough) |
+| Auth | N/A (local process) | Optional `?apikey=` | Optional `?apikey=` |
+| Multi-client | Single | Multiple sessions | Multiple sessions |
+| Custom headers | N/A | N/A | Per-upstream `headers` config |
+
 ### Session Management
 
 - Initializes upstream MCP session on startup via `initialize` + `notifications/initialized`
 - Auto-reinitializes on session expiry (e.g., upstream restart, 405 responses)
 - Retries transient failures with exponential backoff (1s, 2s, max 2 retries)
 - Refreshes tool list on every `tools/list` request (upstream servers may have changed)
+- HTTP mode: each downstream client gets its own `Mcp-Session-Id`, all sharing one upstream session
 
 ### Backward Compatibility
 
 If a caller sends `args_json` directly (old style), the shim **passes it through unchanged**. You can migrate gradually — no breaking changes.
 
 ```json
-// Both work:
-{ "args": { "files": [...] } }         // ← new: native object (shim serializes)
-{ "args_json": "{\"files\":[...]}" }    // ← old: pre-serialized (shim passes through)
+{ "args": { "files": [...] } }         // new: native object (shim serializes)
+{ "args_json": "{\"files\":[...]}" }    // old: pre-serialized (shim passes through)
 ```
 
 ### HTTPS Proxy Support
@@ -206,19 +431,30 @@ StreamableHTTP responses may arrive as either `application/json` or `text/event-
 ## Development
 
 ```bash
-git clone https://github.com/luutuankiet/sandbox-cc
-cd sandbox-cc/mcp-shim
+git clone https://github.com/luutuankiet/mcp-proxy-shim
+cd mcp-proxy-shim
 npm install
 npm run build
-npm start       # starts the shim (connects upstream, waits for stdio)
+npm start             # stdio mode (connects upstream, waits for stdio)
+npm run start:http    # HTTP serve mode
+node dist/index.js daemon  # daemon mode (set MCP_SERVERS or MCP_CONFIG)
 ```
 
 ### Testing
 
 ```bash
-# Send MCP JSON-RPC over stdin:
+# Stdio mode — send MCP JSON-RPC over stdin:
 echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' \
   | MCP_URL="https://your-proxy/mcp/?apikey=KEY" node dist/index.js
+
+# HTTP mode — start server, then test with curl:
+MCP_URL="https://your-proxy/mcp/?apikey=KEY" MCP_APIKEY="test" node dist/index.js serve
+
+# In another terminal:
+curl http://localhost:3000/health
+curl -X POST http://localhost:3000/mcp?apikey=test \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
 ```
 
 Logs go to stderr (stdout is the stdio transport):

package/dist/core.js

@@ -189,7 +189,11 @@ function transformToolSchema(tool) {
     delete props.args_json;
     props.args = {
         type: "object",
-        description: "Tool arguments as a native JSON object. The shim serializes this to args_json before forwarding upstream.",
+        description: "The upstream tool's arguments as a native JSON object (not a string). " +
+            "Use describe_tools to get the upstream tool's inputSchema, then pass " +
+            "those fields here directly. Example: if the upstream tool expects " +
+            '{owner: string, repo: string}, pass args: {"owner": "foo", "repo": "bar"}. ' +
+            "Nested strings containing JSON are fine — only the top-level args must be an object.",
         additionalProperties: true,
     };
     let required = tool.inputSchema.required;
@@ -205,16 +209,91 @@ function transformToolSchema(tool) {
         },
     };
 }
+/**
+ * Validate and re-serialize a JSON string to canonical form.
+ * The upstream Go server expects args_json to unmarshal into map[string]interface{}.
+ *
+ * CRITICAL: Always re-serializes from the parsed object via JSON.stringify()
+ * rather than passing through the raw input string. This prevents failures when
+ * args arrives as a pre-serialized string from the LLM with non-canonical
+ * escaping, encoding quirks, or formatting that Go's json.Unmarshal rejects.
+ * See: https://github.com/luutuankiet/mcp-proxy-shim/issues/1
+ *
+ * Throws ArgsValidationError on invalid input — never silently drops data.
+ */
+class ArgsValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArgsValidationError";
+    }
+}
+function validateAndSerializeArgs(jsonStr) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch (err) {
+        throw new ArgsValidationError(`args is a string but not valid JSON. The "args" field must be a native JSON object, ` +
+            `not a pre-serialized string. Pass args as {"key": "value"}, not as '{"key": "value"}'. ` +
+            `Parse error: ${err.message}. Input (first 200 chars): ${jsonStr.slice(0, 200)}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        const actualType = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
+        throw new ArgsValidationError(`args must be a JSON object, got ${actualType}. ` +
+            `Pass args as {"key": "value"}, not as a primitive or array. ` +
+            `Input: ${jsonStr.slice(0, 200)}`);
+    }
+    // Re-serialize from parsed object for canonical JSON.
+    // Do NOT return jsonStr directly — the raw string from the LLM may have
+    // non-canonical escaping (e.g., \\/ vs /, unicode escapes, whitespace)
+    // that Go's json.Unmarshal handles differently than Node's JSON.parse.
+    return JSON.stringify(parsed);
+}
+/**
+ * Transform call_tool_* arguments: args:object → args_json:string.
+ * Returns the transformed args, or throws ArgsValidationError if
+ * the client sends malformed args.
+ */
 function transformToolCallArgs(toolName, args) {
     if (!CALL_TOOL_NAMES.has(toolName))
         return args;
-    if ("args_json" in args)
-        return args;
+    if ("args_json" in args) {
+        // Backward compat: if args_json is already present, ensure it's a string.
+        const existing = args.args_json;
+        if (typeof existing === "string") {
+            return { ...args, args_json: validateAndSerializeArgs(existing) };
+        }
+        // If it's an object, stringify it.
+        if (existing !== null && existing !== undefined && typeof existing === "object") {
+            return { ...args, args_json: JSON.stringify(existing) };
+        }
+        throw new ArgsValidationError(`args_json must be a JSON string or object, got ${existing === null ? "null" : typeof existing}. ` +
+            `Pass args_json as '{"key": "value"}' (string) or use the "args" field with a native object instead.`);
+    }
     if ("args" in args) {
         const { args: argsObj, ...rest } = args;
+        let argsJson;
+        if (argsObj === null || argsObj === undefined) {
+            // Nullish args — treat as empty object (common for tools with no required params)
+            argsJson = "{}";
+        }
+        else if (typeof argsObj === "string") {
+            // LLM sent args as a pre-serialized string — validate and re-serialize.
+            argsJson = validateAndSerializeArgs(argsObj);
+        }
+        else if (typeof argsObj === "object" && !Array.isArray(argsObj)) {
+            // Happy path: native object → serialize.
+            // Nested strings containing JSON are fine — JSON.stringify handles them correctly.
+            argsJson = JSON.stringify(argsObj);
+        }
+        else {
+            const actualType = Array.isArray(argsObj) ? "array" : typeof argsObj;
+            throw new ArgsValidationError(`args must be a JSON object, got ${actualType}. ` +
+                `Pass args as {"key": "value"}. Use describe_tools to get the upstream tool's inputSchema.`);
+        }
         return {
             ...rest,
-            args_json: JSON.stringify(argsObj),
+            args_json: argsJson,
         };
     }
     return args;
@@ -331,6 +410,45 @@ async function fetchUpstreamTools() {
     log(`Fetched ${tools.length} upstream tools`);
     return tools;
 }
+// ---------------------------------------------------------------------------
+// Tool name resolution helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a tool name against an index map, handling server prefixes and
+ * suffix matching for mount-path variations.
+ */
+function resolveToolFromIndex(name, index) {
+    // 1. Exact match
+    let tool = index.get(name);
+    if (tool)
+        return tool;
+    // 2. Try without server prefix (e.g., "utils:bi-platform__query" → "bi-platform__query")
+    if (name.includes(":")) {
+        const withoutPrefix = name.split(":").slice(1).join(":");
+        tool = index.get(withoutPrefix);
+        if (tool)
+            return tool;
+    }
+    // 3. Try suffix/prefix matching — check all indexed tools
+    for (const [key, candidate] of index) {
+        if (key.endsWith(name) || name.endsWith(key)) {
+            return candidate;
+        }
+    }
+    // 4. Fuzzy suffix match — handle mount-path variations
+    const nParts = name.includes(":") ? name.split(":").slice(1).join(":").split("__") : name.split("__");
+    const nSuffix = nParts[nParts.length - 1];
+    if (nSuffix) {
+        for (const [, candidate] of index) {
+            const cParts = candidate.name.split("__");
+            const cSuffix = cParts[cParts.length - 1];
+            if (cSuffix === nSuffix && candidate.name.includes(nParts[0])) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * Create and wire up an MCP Server with all shim handlers.
  * Caller connects their chosen transport (stdio or HTTP).
@@ -384,11 +502,32 @@ export async function createShimServer(options = {}) {
             }
             await ensureSession();
             const nameSet = new Set(names);
+            // Always query live BM25 — no caching. Generate multiple search
+            // queries per tool name for broader coverage:
+            // 1. Raw name as-is (exact match in BM25 — most targeted)
+            // 2. Full name with separators → spaces (e.g., "bi-platform query")
+            // 3. Last __ segment only (e.g., "query") as a broader fallback
+            // 4. First __ segment (e.g., "bi-platform") for server/mount prefix matching
             const queries = new Set();
             for (const n of nameSet) {
-                const parts = n.split("__");
-                const toolPart = parts[parts.length - 1] || n;
-                queries.add(toolPart.replace(/_/g, " "));
+                // Strip optional "server:" prefix for searching
+                const withoutServer = n.includes(":") ? n.split(":").slice(1).join(":") : n;
+                // Raw name as-is — BM25 often matches exact tool names better than transformed queries
+                queries.add(withoutServer);
+                // Full name → spaces (primary query, most specific)
+                queries.add(withoutServer.replace(/__/g, " ").replace(/[-_]/g, " "));
+                // Segment-based queries for compound names
+                const parts = withoutServer.split("__");
+                if (parts.length > 1) {
+                    // Last segment: tool action (e.g., "query", "edit_files")
+                    const toolPart = parts[parts.length - 1] || withoutServer;
+                    queries.add(toolPart.replace(/[-_]/g, " "));
+                    // First segment: server/mount prefix (e.g., "looker-da", "hetzner_at_slash")
+                    const prefixPart = parts[0];
+                    if (prefixPart && prefixPart !== toolPart) {
+                        queries.add(prefixPart.replace(/[-_]/g, " ") + " " + toolPart.replace(/[-_]/g, " "));
+                    }
+                }
             }
             const index = new Map();
             for (const query of queries) {
@@ -398,18 +537,13 @@ export async function createShimServer(options = {}) {
                         name: "retrieve_tools",
                         arguments: { query },
                     });
-                    log("describe_tools: resp exists:", !!resp, "resp.result exists:", !!resp?.result);
                     if (resp?.result) {
                         const unwrapped = deepUnwrapResult(resp.result);
-                        log("describe_tools: unwrapped type:", typeof unwrapped, "isArray:", Array.isArray(unwrapped));
-                        if (unwrapped && typeof unwrapped === "object" && !Array.isArray(unwrapped)) {
-                            log("describe_tools: unwrapped keys:", Object.keys(unwrapped).join(", "));
-                        }
                         const result = unwrapped;
                         const tools = Array.isArray(result)
                             ? result
                             : (result && Array.isArray(result.tools) ? result.tools : []);
-                        log("describe_tools: found", tools.length, "tools from query");
+                        log("describe_tools: found", tools.length, "tools from query:", query);
                         for (const t of tools) {
                             const tool = t;
                             if (tool.name && !index.has(tool.name)) {
@@ -424,16 +558,29 @@ export async function createShimServer(options = {}) {
             }
             log("describe_tools: index has", index.size, "tools, looking up:", names.join(", "));
             const results = names.map((n) => {
-                const tool = index.get(n);
-                if (!tool)
-                    return { name: n, error: "not found" };
-                return transformToolSchema(tool);
+                const tool = resolveToolFromIndex(n, index);
+                if (tool)
+                    return transformToolSchema(tool);
+                return { name: n, error: "not found" };
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(results) }],
             };
         }
-        const forwardArgs = transformToolCallArgs(name, args || {});
+        let forwardArgs;
+        try {
+            forwardArgs = transformToolCallArgs(name, args || {});
+        }
+        catch (err) {
+            if (err instanceof ArgsValidationError) {
+                log("Args validation rejected:", err.message);
+                return {
+                    content: [{ type: "text", text: err.message }],
+                    isError: true,
+                };
+            }
+            throw err;
+        }
         try {
             await ensureSession();
             const resp = await mcpRequest("tools/call", {