openclaw-mcp-router 1.0.1 → 1.2.0

package/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+- 
+
+## Why
+- 
+
+## Validation
+- [ ] `npm test` passes locally
+
+## Documentation Checklist
+- [ ] README updated (if behavior/config/user workflow changed)
+- [ ] docs/ updated to match README and implementation
+- [ ] No README/docs drift introduced
+- [ ] skills/ content updated to match behavior/config changes (if applicable)

package/.github/topics.txt

@@ -0,0 +1,10 @@
+openclaw
+model-context-protocol
+mcp
+mcp-router
+ai-agents
+semantic-search
+tool-discovery
+lancedb
+ollama
+agent-tools

package/README.md

@@ -1,129 +1,180 @@
 # OpenClaw MCP Router 🚀
 
-**OpenClaw MCP Router** is a dynamic tool discovery layer for [OpenClaw](https://openclaw.ai). It uses semantic vector search to eliminate **Context Bloat** by routing only the necessary Model Context Protocol (MCP) tool schemas to your agent on-demand.
+**OpenClaw MCP Router** is a dynamic **MCP (Model Context Protocol) tool router** for OpenClaw. It uses semantic search to discover the right MCP tools at runtime, so agents avoid loading huge tool catalogs into the system prompt.
 
-## ⚡ The Problem: Context Window Exhaustion
 
-Modern MCP catalogs are growing. Loading every tool schema upfront is expensive and inefficient:
+Instead of injecting every MCP schema up front, it provides two lightweight meta-tools:
 
-* **Token Waste:** 5 MCP servers with 50+ tools can burn **55k–134k tokens** before your agent even says "Hello."
-* **Performance Hit:** Massive system prompts degrade reasoning accuracy (the "lost in the middle" phenomenon).
-* **Cost:** High token usage leads to higher API costs for every turn of the conversation.
+- `mcp_search` → discover the right tool at runtime
+- `mcp_call` → execute as JSON fallback
 
-## 🛠️ The Solution: Semantic Tool Routing
+This cuts context bloat, improves tool selection quality, and reduces token cost on large MCP server inventories.
 
-Instead of a full schema dump, this plugin registers two lightweight "Meta-Tools":
+---
 
-1. **`mcp_search(query)`**: Uses **Ollama** and **LanceDB** to perform a semantic search. It returns only the top-N most relevant tool definitions (reducing overhead by ~95%).
-2. **`mcp_call(tool_name, params)`**: Dynamically resolves the owning MCP server and executes the call.
+## Keywords
 
-> **Result:** Your agent "asks" for the tools it needs, keeping the context window clean and the reasoning sharp.
+OpenClaw plugin, MCP router, Model Context Protocol, tool discovery, semantic tool search, AI agent tooling, LanceDB, Ollama embeddings.
 
----
+## Why this exists
 
-## 🚀 Quick Start
+Large MCP catalogs are expensive in prompt space.
 
-### 1. Prerequisites
+- **Token waste:** tens of thousands of tokens before first user turn
+- **Reasoning quality loss:** "lost in the middle" on oversized prompts
+- **Higher cost:** more prompt tokens every turn
 
-Ensure you have **Ollama** running locally with an embedding model:
+MCP Router applies Anthropic's tool-search pattern so only relevant tools are surfaced when needed.
 
-```bash
-ollama pull embeddinggemma
+Refs:
+- Tool search / advanced tool use: <https://www.anthropic.com/engineering/advanced-tool-use>
+- Code execution with MCP: <https://www.anthropic.com/engineering/code-execution-with-mcp>
 
-```
+---
 
-### 2. Installation
+## Core model
 
-```bash
-openclaw plugins install openclaw-mcp-router
+### 1) Index time (`reindex`)
+- Connect to configured MCP servers
+- List tools
+- Embed tool text
+- Store vectors in LanceDB
+- Register tool→server ownership
+- *(Optional)* generate CLI artifacts via `mcporter generate-cli`
 
-```
+### 2) Runtime (`mcp_search`)
+- Semantic search over indexed tools
+- Default schema verbosity is adaptive:
+  - if `mcporter` is available: compact cards by default
+  - if `mcporter` is not available: include JSON params by default
+- Full JSON schema can always be forced with `include_schema=true`
 
-### 3. Setup & Indexing
+### 3) Execute (`mcp_call`)
+- JSON-based execution path (classic MCP params flow)
 
-Run the interactive wizard to configure your servers and automatically update your `alsoAllow` permissions:
+---
 
-```bash
-openclaw openclaw-mcp-router setup
-openclaw openclaw-mcp-router reindex
+## CLI-first behavior (new)
 
-```
+Router is now optimized for a CLI-first workflow:
+
+- Prefer: `mcporter call <server>.<tool> ...`
+- Fallback: `mcp_call(tool_name, params_json)`
+
+`mcp_search` adapts to environment: compact when mcporter is present, schema-forward when it is not (so agents can drive `mcp_call` reliably).
 
 ---
 
-## ⚙️ Configuration
+## Use cases
 
-The plugin is highly configurable via `~/.openclaw/openclaw.json`.
+- Route large MCP tool catalogs without prompt bloat
+- Improve tool selection for coding and automation agents
+- Keep system prompts small while preserving broad MCP capability
+- Enable CLI-first MCP execution with JSON fallback
 
-### Server Management
+## Quick start
 
-You can manage servers via the **Interactive TUI**:
+### Prerequisites
 
 ```bash
-openclaw openclaw-mcp-router control
+ollama pull embeddinggemma
+```
+
+### Install
 
+```bash
+openclaw plugins install openclaw-mcp-router
 ```
 
-### Manual Schema Example
+### Setup + index
 
-For power users, add servers directly to your `plugins.entries`:
+```bash
+openclaw openclaw-mcp-router setup
+openclaw openclaw-mcp-router reindex
+```
+
+The setup wizard auto-detects whether `mcporter` is installed and suggests a sensible default for `mcp_search` schema verbosity.
 
-| Key | Description | Default |
-| --- | --- | --- |
-| `topK` | Number of tools returned per search | `5` |
-| `minScore` | Similarity threshold (0.0 - 1.0) | `0.3` |
-| `maxRetries` | Connection attempts for slow servers | `3` |
+---
+
+## Key configuration
+
+In `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-mcp-router.config`:
 
 ```json5
-// ~/.openclaw/openclaw.json
 {
-  "plugins": {
-    "entries": {
-      "openclaw-mcp-router": {
-        "enabled": true,
-        "config": {
-          "servers": [{ "name": "filesystem", "transport": "stdio", "command": "npx", "args": ["..."] }],
-          "embedding": { "provider": "ollama", "model": "embeddinggemma" }
-        }
-      }
-    }
+  "search": {
+    "topK": 5,
+    "minScore": 0.3
+    // includeParametersDefault optional:
+    // true  -> always include params
+    // false -> always compact
+    // unset -> auto (based on mcporter availability)
+  },
+  "indexer": {
+    "connectTimeout": 60000,
+    "maxRetries": 3,
+    "initialRetryDelay": 2000,
+    "maxRetryDelay": 30000,
+    "maxChunkChars": 500,
+    "overlapChars": 100,
+    "generateCliArtifacts": false
   }
 }
-
 ```
 
----
+### Notes
 
-## 🧠 How It Works: Under the Hood
+- `search.includeParametersDefault` is optional; if omitted, router auto-decides based on mcporter availability.
+- `indexer.generateCliArtifacts=true` enables best-effort per-server `mcporter generate-cli` during reindex.
+- `mcp_call` stays the classic JSON meta-tool (no backend mode flag).
 
-1. **Indexing:** During `reindex`, the router connects to all configured MCP servers, fetches their manifests, and generates vector embeddings for every tool description.
-2. **Storage:** These embeddings are stored in a local **LanceDB** instance for sub-millisecond retrieval.
-3. **Runtime Discovery:** * Agent detects a task (e.g., "Analyze this CSV").
-* Agent calls `mcp_search("read or analyze csv files")`.
-* Router returns the `filesystem` tool schema.
-* Agent executes the tool via `mcp_call`.
+---
 
+## Server management
 
+```bash
+openclaw openclaw-mcp-router control
+openclaw openclaw-mcp-router list
+openclaw openclaw-mcp-router add <name> <command-or-url> [...]
+openclaw openclaw-mcp-router reindex
+```
 
 ---
 
-## 📈 Performance & Benchmarks
+## MCPorter inspiration
+
+Huge thanks to **@steipete** and [mcporter](https://github.com/steipete/mcporter) for the CLI-first MCP execution model inspiration.
 
-Based on the [Anthropic Tool Search](https://www.anthropic.com/engineering/advanced-tool-use) pattern, dynamic routing can improve tool selection accuracy significantly:
+---
+
+## Documentation
 
-* **Standard Loading:** ~49% Accuracy (Large catalogs)
-* **Dynamic Routing:** **~88% Accuracy** (Opus 4.5 benchmarks)
+- Architecture + flow details: `docs/CLI_FIRST_WORKFLOW.md`
+- Plugin config schema: `openclaw.plugin.json`
+- Skill usage examples: `skills/mcp-router/`
 
 ---
 
-## 🤝 Contributing
+## Contributing
+
+PRs welcome — especially around:
+- better reranking
+- hybrid retrieval (vector + lexical)
+
+PR hygiene:
+- keep README + docs in sync for every behavior/config/workflow change
+- keep `skills/` guidance in sync when user-facing behavior changes
+- run test suite before opening PR
+
+## License
 
-We are looking to implement **Hybrid Search (BM25)** and **LLM-based Reranking**. If you're interested in improving LLM orchestration efficiency, we'd love your help!
+MIT
 
-1. Fork the repo.
-2. Create your feature branch.
-3. Submit a PR.
 
-## 📄 License
+## GitHub SEO checklist
 
-Released under the [MIT License](https://www.google.com/search?q=LICENSE).
+- Set repo description to include: `OpenClaw`, `MCP`, `Model Context Protocol`, `semantic search`
+- Add GitHub topics (see `.github/topics.txt`)
+- Pin this repository on your profile if it's a flagship plugin
+- Link this repo from related blog posts, docs, and demos

package/docs/CLI_FIRST_WORKFLOW.md

@@ -0,0 +1,76 @@
+# CLI-First Workflow (MCP Router + MCPorter)
+
+This document explains the intended execution model:
+
+1. Reindex tools + metadata
+2. Search tools with adaptive schema verbosity
+3. Prefer CLI calls when available
+4. Use `mcp_call` as classic JSON fallback
+
+## Reindex behavior
+
+During `openclaw openclaw-mcp-router reindex`:
+
+- Router connects to enabled MCP servers
+- Lists tools
+- Chunks/embeds descriptions
+- Stores vectors + metadata in LanceDB
+
+Optional:
+- If `indexer.generateCliArtifacts=true`, router runs best-effort `mcporter generate-cli` per server.
+- Generation failures do **not** block indexing.
+
+## `mcp_search` behavior
+
+`mcp_search` supports adaptive defaults:
+
+- If `mcporter` is installed: default to compact cards (save tokens)
+- If `mcporter` is not installed: include JSON params by default (so agents can call `mcp_call` reliably)
+
+Overrides:
+- request-level: `include_schema=true|false`
+- config-level: `search.includeParametersDefault=true|false`
+  - if unset, auto mode is used
+
+## `mcp_call` behavior
+
+`mcp_call` remains the original JSON meta-tool path:
+
+- resolve tool owner by registry
+- open MCP connection
+- call tool with `params_json`
+- return content/errors
+
+No backend mode flag is required.
+
+## Recommended config
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "openclaw-mcp-router": {
+        "enabled": true,
+        "config": {
+          "search": {
+            "topK": 5,
+            "minScore": 0.3
+            // includeParametersDefault optional (true|false)
+          },
+          "indexer": {
+            "generateCliArtifacts": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Acknowledgement
+
+Special thanks to **@steipete** and **MCPorter**:
+<https://github.com/steipete/mcporter>
+
+Anthropic reference:
+<https://www.anthropic.com/engineering/code-execution-with-mcp>

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-mcp-router",
   "name": "MCP Router",
-  "description": "Semantic search across MCP tool catalogs. Reduces context bloat from ~77k→8.7k tokens by dynamically surfacing only relevant tools.",
+  "description": "Semantic search across MCP tool catalogs. Reduces context bloat from ~77k\u21928.7k tokens by dynamically surfacing only relevant tools.",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -12,14 +12,45 @@
         "additionalProperties": {
           "type": "object",
           "properties": {
-            "command":   { "type": "string" },
-            "args":      { "type": "array", "items": { "type": "string" } },
-            "env":       { "type": "object", "additionalProperties": { "type": "string" } },
-            "url":       { "type": "string" },
-            "serverUrl": { "type": "string" },
-            "type":      { "type": "string", "enum": ["stdio", "sse", "http"] },
-            "headers":   { "type": "object", "additionalProperties": { "type": "string" } },
-            "timeout":   { "type": "number", "description": "Per-server connect timeout in ms; overrides indexer.connectTimeout" }
+            "command": {
+              "type": "string"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "env": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "url": {
+              "type": "string"
+            },
+            "serverUrl": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "stdio",
+                "sse",
+                "http"
+              ]
+            },
+            "headers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "timeout": {
+              "type": "number",
+              "description": "Per-server connect timeout in ms; overrides indexer.connectTimeout"
+            }
           }
         }
       },
@@ -32,16 +63,50 @@
         "description": "Legacy server array format. Prefer mcpServers dict.",
         "items": {
           "type": "object",
-          "required": ["name", "transport"],
+          "required": [
+            "name",
+            "transport"
+          ],
           "properties": {
-            "name":      { "type": "string" },
-            "transport": { "type": "string", "enum": ["stdio", "sse", "http"] },
-            "command":   { "type": "string" },
-            "args":      { "type": "array", "items": { "type": "string" } },
-            "env":       { "type": "object", "additionalProperties": { "type": "string" } },
-            "url":       { "type": "string" },
-            "headers":   { "type": "object", "additionalProperties": { "type": "string" } },
-            "timeout":   { "type": "number", "description": "Per-server connect timeout in ms; overrides indexer.connectTimeout" }
+            "name": {
+              "type": "string"
+            },
+            "transport": {
+              "type": "string",
+              "enum": [
+                "stdio",
+                "sse",
+                "http"
+              ]
+            },
+            "command": {
+              "type": "string"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "env": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "url": {
+              "type": "string"
+            },
+            "headers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "timeout": {
+              "type": "number",
+              "description": "Per-server connect timeout in ms; overrides indexer.connectTimeout"
+            }
           }
         }
       },
@@ -49,34 +114,98 @@
         "type": "object",
         "description": "Indexer retry and timeout settings",
         "properties": {
-          "connectTimeout":    { "type": "number", "description": "Per-server default connect timeout in ms (default: 60000)" },
-          "maxRetries":        { "type": "number", "minimum": 0, "description": "Retry attempts per server, 0 = no retry (default: 3)" },
-          "initialRetryDelay": { "type": "number", "description": "Initial backoff delay in ms (default: 2000)" },
-          "maxRetryDelay":     { "type": "number", "description": "Max backoff cap in ms (default: 30000)" },
-          "maxChunkChars":     { "type": "number", "minimum": 0, "description": "Max chars per chunk for long tool descriptions. 0 = disable chunking (default: 500)" },
-          "overlapChars":      { "type": "number", "minimum": 0, "description": "Overlap chars between adjacent chunks (default: 100)" }
+          "connectTimeout": {
+            "type": "number",
+            "description": "Per-server default connect timeout in ms (default: 60000)"
+          },
+          "maxRetries": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Retry attempts per server, 0 = no retry (default: 3)"
+          },
+          "initialRetryDelay": {
+            "type": "number",
+            "description": "Initial backoff delay in ms (default: 2000)"
+          },
+          "maxRetryDelay": {
+            "type": "number",
+            "description": "Max backoff cap in ms (default: 30000)"
+          },
+          "maxChunkChars": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Max chars per chunk for long tool descriptions. 0 = disable chunking (default: 500)"
+          },
+          "overlapChars": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Overlap chars between adjacent chunks (default: 100)"
+          },
+          "generateCliArtifacts": {
+            "type": "boolean",
+            "description": "Generate mcporter CLI artifacts during reindex (default: false)"
+          }
         }
       },
       "embedding": {
         "type": "object",
         "properties": {
-          "provider": { "type": "string", "enum": ["openai", "gemini", "voyage", "mistral", "ollama"] },
-          "model":    { "type": "string" },
-          "baseUrl":  { "type": "string" },
-          "url":      { "type": "string", "description": "Deprecated: use baseUrl. Old Ollama URL (gets /v1 appended)." },
-          "apiKey":   { "type": "string" },
-          "headers":  { "type": "object", "additionalProperties": { "type": "string" } }
+          "provider": {
+            "type": "string",
+            "enum": [
+              "openai",
+              "gemini",
+              "voyage",
+              "mistral",
+              "ollama"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "baseUrl": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string",
+            "description": "Deprecated: use baseUrl. Old Ollama URL (gets /v1 appended)."
+          },
+          "apiKey": {
+            "type": "string"
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
         }
       },
       "vectorDb": {
         "type": "object",
-        "properties": { "path": { "type": "string" } }
+        "properties": {
+          "path": {
+            "type": "string"
+          }
+        }
       },
       "search": {
         "type": "object",
         "properties": {
-          "topK":     { "type": "number", "minimum": 1, "maximum": 20 },
-          "minScore": { "type": "number", "minimum": 0, "maximum": 1 }
+          "topK": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 20
+          },
+          "minScore": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "includeParametersDefault": {
+            "type": "boolean",
+            "description": "Include full input schema by default in mcp_search results. If omitted, defaults automatically based on mcporter availability."
+          }
         }
       }
     }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "openclaw-mcp-router",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "private": false,
-  "description": "Dynamic MCP tool router for OpenClaw — semantic search over large MCP catalogs to eliminate context bloat",
+  "description": "OpenClaw MCP router plugin for Model Context Protocol (MCP): semantic tool search and dynamic tool calling to reduce prompt bloat",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -11,9 +11,13 @@
   },
   "keywords": [
     "openclaw",
+    "openclaw-plugin",
     "mcp",
-    "plugin",
-    "vector-search",
+    "model-context-protocol",
+    "mcp-router",
+    "tool-discovery",
+    "semantic-search",
+    "ai-agents",
     "lancedb",
     "ollama"
   ],
@@ -44,5 +48,9 @@
     "skills": [
       "./skills"
     ]
+  },
+  "homepage": "https://github.com/lunarmoon26/openclaw-mcp-router#readme",
+  "bugs": {
+    "url": "https://github.com/lunarmoon26/openclaw-mcp-router/issues"
   }
 }

package/skills/mcp-router/SKILL.md

@@ -21,13 +21,23 @@ If a relevant tool exists, use it with `mcp_call`.
    - Use an action-oriented query: `"create github pull request"`, `"query postgres"`, `"send slack message"`.
 2. **Select tool**
    - Prefer best intent match + feasible required params.
-3. **Read schema**
-   - Identify required fields, types, enums, nested structure.
-4. **Call tool**
-   - `mcp_call("exact_tool_name", "{...valid JSON...}")`
+3. **Decide execution path**
+   - If `mcporter` is available, prefer CLI invocation style shown in search hints.
+   - Otherwise, use `mcp_call` with JSON params.
+4. **Read schema when needed**
+   - Use `include_schema=true` on `mcp_search` when full parameter detail is required.
 5. **Recover on failure**
    - Fix schema/type mismatch or re-search with rewritten query.
 
+## Adaptive `mcp_search` Defaults
+
+- Default schema verbosity can be auto-configured by environment:
+  - `mcporter` installed → compact search cards by default
+  - `mcporter` not installed → include parameter schema by default
+- Overrides:
+  - Per call: `include_schema=true|false`
+  - Config: `search.includeParametersDefault=true|false`
+
 ## Query Rewrite Ladder (Deterministic)
 
 If search quality is poor, retry in this order:
@@ -50,7 +60,7 @@ When multiple tools match, rank by:
 
 ## `mcp_call` Parameter Checklist
 
-`params_json` must be a **JSON string**.
+`mcp_call` is the classic MCP JSON meta-tool. `params_json` must be a **JSON string**.
 
 - Include all required fields.
 - Match exact types (`42` vs `"42"`, `true` vs `"true"`).

package/skills/mcp-server-manager/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: mcp-server-manager
+description: Manage MCP servers for openclaw-mcp-router (add/list/enable/disable/remove/reindex/setup/control), including choosing openclaw.json vs ~/.openclaw/openclaw-mcp-router/.mcp.json and validating server state after changes. Use when the user asks to add new MCP capabilities, troubleshoot missing tools, rotate credentials/env vars, or maintain MCP server inventory.
+---
+
+# MCP Server Manager
+
+Manage MCP server lifecycle through `openclaw-mcp-router` commands first; edit config files directly only when CLI paths cannot express the change.
+
+## Command Surface
+
+Use these exact commands:
+
+- `openclaw openclaw-mcp-router setup`
+- `openclaw openclaw-mcp-router control`
+- `openclaw openclaw-mcp-router add <name> <command-or-url> [args...] [--transport stdio|sse|http] [--env KEY=VALUE ...] [--timeout <ms>] [--file]`
+- `openclaw openclaw-mcp-router list`
+- `openclaw openclaw-mcp-router enable <name>`
+- `openclaw openclaw-mcp-router disable <name>`
+- `openclaw openclaw-mcp-router remove <name>`
+- `openclaw openclaw-mcp-router reindex [--server <name>]`
+
+## Source of Truth and Precedence
+
+Server definitions can come from two places:
+
+1. inline plugin config (`plugins.entries.openclaw-mcp-router.config.mcpServers` in `~/.openclaw/openclaw.json`)
+2. file-based config (`~/.openclaw/openclaw-mcp-router/.mcp.json` by default, or configured `mcpServersFile`)
+
+Resolution rules:
+
+- Both sources are merged.
+- Name collisions are resolved with inline `mcpServers` winning over file-based entries.
+- Disabled servers (`disabled: true`) are skipped during indexing.
+
+## Standard Workflow
+
+1. Inspect current state:
+   - `openclaw openclaw-mcp-router list`
+2. Apply change (add/enable/disable/remove).
+3. Reindex:
+   - Full: `openclaw openclaw-mcp-router reindex`
+   - Single server: `openclaw openclaw-mcp-router reindex --server <name>`
+4. Verify:
+   - `openclaw openclaw-mcp-router list`
+   - confirm status is `ok` and tool count is non-zero when expected.
+
+## Add Server Patterns
+
+### Stdio server (default transport)
+
+```bash
+openclaw openclaw-mcp-router add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/root
+```
+
+### HTTP/SSE server
+
+```bash
+openclaw openclaw-mcp-router add notion https://mcp.example.com --transport http
+```
+
+### Store in `.mcp.json` instead of `openclaw.json`
+
+```bash
+openclaw openclaw-mcp-router add github npx -y @modelcontextprotocol/server-github --env GITHUB_TOKEN=${GITHUB_TOKEN} --file
+```
+
+## Operational Notes
+
+- Always run `reindex` after add/remove and after most enable/disable changes.
+- If a server fails to connect, retry with larger timeout (for slow startup servers):
+  - `--timeout 120000`
+- For env updates, re-run `add` with the same name (entry is replaced), then reindex.
+- Prefer `--file` when keeping credentials and frequently changing servers outside `openclaw.json`.
+
+## Troubleshooting Quick Checks
+
+- No results in `mcp_search`: verify server is enabled and indexed.
+- `list` shows `failed`: inspect endpoint/command/env and rerun reindex.
+- Server missing: check whether it exists in inline config vs `.mcp.json` and whether an inline entry with same name is overriding it.
+
+
+## Setup Behavior (mcporter-aware)
+
+- During `openclaw openclaw-mcp-router setup`, detect whether `mcporter` is installed and suggest `mcp_search` schema defaults accordingly.
+- First-install guidance:
+  - no `mcporter`: keep params visible by default (`search.includeParametersDefault=true`)
+  - with `mcporter`: prefer compact cards by default (`search.includeParametersDefault=false`)
+- This can still be overridden by users later in plugin config.

package/src/config.ts

@@ -41,13 +41,16 @@ export type IndexerConfig = {
   maxChunkChars: number;
   /** Overlap characters between adjacent chunks (default: 100) */
   overlapChars: number;
+  /** Generate mcporter CLI artifacts during reindex (default: false). */
+  generateCliArtifacts: boolean;
 };
 
+
 export type McpRouterConfig = {
   servers: McpServerConfig[];
   embedding: EmbeddingConfig;
   vectorDb: { path: string };
-  search: { topK: number; minScore: number };
+  search: { topK: number; minScore: number; includeParametersDefault?: boolean };
   indexer: IndexerConfig;
 };
 
@@ -356,6 +359,7 @@ export function parseConfig(raw: unknown, opts?: ParseConfigOpts): McpRouterConf
   const search = {
     topK: typeof srchRaw.topK === "number" ? Math.min(20, Math.max(1, srchRaw.topK)) : 5,
     minScore: typeof srchRaw.minScore === "number" ? srchRaw.minScore : 0.3,
+    includeParametersDefault: typeof srchRaw.includeParametersDefault === "boolean" ? srchRaw.includeParametersDefault : undefined,
   };
 
   // ── indexer defaults ──
@@ -367,6 +371,7 @@ export function parseConfig(raw: unknown, opts?: ParseConfigOpts): McpRouterConf
     maxRetryDelay: typeof idxRaw.maxRetryDelay === "number" ? idxRaw.maxRetryDelay : 30_000,
     maxChunkChars: typeof idxRaw.maxChunkChars === "number" ? Math.max(0, idxRaw.maxChunkChars) : 500,
     overlapChars: typeof idxRaw.overlapChars === "number" ? Math.max(0, idxRaw.overlapChars) : 100,
+    generateCliArtifacts: typeof idxRaw.generateCliArtifacts === "boolean" ? idxRaw.generateCliArtifacts : false,
   };
 
   return { servers, embedding, vectorDb, search, indexer };

package/src/index.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { parseConfig } from "./config.js";
@@ -10,6 +11,16 @@ import { createMcpCallTool } from "./tools/mcp-call-tool.js";
 import { createMcpSearchTool } from "./tools/mcp-search-tool.js";
 import { McpToolVectorStore } from "./vector-store.js";
 
+
+function detectMcporterInstalled(): boolean {
+  try {
+    const r = spawnSync("mcporter", ["--version"], { stdio: "ignore" });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
 const mcpRouterPlugin = {
   id: EXTENSION_ID,
   name: "OpenClaw MCP Router",
@@ -179,12 +190,14 @@ const mcpRouterPlugin = {
     }
 
     // Register tools as optional so the agent only sees them when alsoAllow is set
+    const hasMcporter = detectMcporterInstalled();
+
     api.registerTool(
-      createMcpSearchTool({ store, embeddings, cfg: cfg.search }),
+      createMcpSearchTool({ store, embeddings, cfg: cfg.search, hasMcporter }) as never,
       { optional: true },
     );
     api.registerTool(
-      createMcpCallTool({ registry, logger: api.logger }),
+      createMcpCallTool({ registry, logger: api.logger }) as never,
       { optional: true },
     );
 

package/src/indexer.ts

@@ -1,3 +1,6 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 import type { Embeddings } from "./embeddings.js";
 import type { McpRegistry } from "./mcp-registry.js";
 import { McpClient } from "./mcp-client.js";
@@ -48,6 +51,49 @@ export function abortableDelay(ms: number, signal?: AbortSignal): Promise<void>
   });
 }
 
+
+async function generateCliForServer(params: {
+  serverCfg: McpServerConfig;
+  cfg: McpRouterConfig;
+  logger: IndexerLogger;
+}): Promise<void> {
+  const { serverCfg, cfg, logger } = params;
+  // Best-effort CLI artifact generation inspired by mcporter.
+  // Stores generated artifacts alongside router state.
+  const outDir = path.join(path.dirname(cfg.vectorDb.path), "generated-clis");
+  const outFile = path.join(outDir, `${serverCfg.name}.ts`);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const args = ["-y", "mcporter", "generate-cli"];
+  if (serverCfg.transport === "stdio") {
+    if (!serverCfg.command) return;
+    const cmd = [serverCfg.command, ...(serverCfg.args ?? [])].join(" ");
+    args.push("--command", cmd);
+  } else if (serverCfg.url) {
+    args.push("--server", serverCfg.url);
+  } else {
+    return;
+  }
+
+  args.push("--name", serverCfg.name, "--output", outFile);
+
+  await new Promise<void>((resolve) => {
+    const child = spawn("npx", args, { stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    let stderr = "";
+    child.stderr.on("data", (d) => (stderr += String(d)));
+    child.on("close", (code) => {
+      if (code === 0) {
+        logger.info(`${EXTENSION_ID}: generated CLI artifact for server "${serverCfg.name}" at ${outFile}`);
+      } else {
+        logger.warn(
+          `${EXTENSION_ID}: failed to generate CLI artifact for "${serverCfg.name}" (best-effort): ${stderr.trim() || `exit ${String(code)}`}`,
+        );
+      }
+      resolve();
+    });
+  });
+}
+
 /**
  * Connect to all configured MCP servers in parallel, list their tools,
  * embed each tool description, and upsert into the vector store.
@@ -131,6 +177,17 @@ async function indexServer(params: {
       await client.connect({ signal, timeout: connectTimeout });
       const tools = await client.listTools();
 
+      // Clear all existing rows for this server before re-adding the fresh tool list.
+      // This prevents stale entries when tools are removed, renamed, or change between
+      // single-chunk and multi-chunk representations across reindexes.
+      await store.deleteServer(serverCfg.name);
+
+      // Optional: best-effort generation of per-server CLI wrapper via mcporter.
+      // Indexing continues even if generation fails.
+      if (cfg.indexer.generateCliArtifacts) {
+        await generateCliForServer({ serverCfg, cfg, logger });
+      }
+
       let indexed = 0;
       let failed = 0;
 

package/src/setup/setup-command.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { cancel, confirm, intro, isCancel, outro, select, text } from "@clack/prompts";
 import { parseConfig, type McpServerConfig, type McpTransportKind } from "../config.js";
 import {
@@ -10,6 +11,16 @@ import {
 } from "./config-writer.js";
 import { CMD_REINDEX, EXTENSION_ID } from "../constants.js";
 
+
+function detectMcporterInstalled(): boolean {
+  try {
+    const r = spawnSync("mcporter", ["--version"], { stdio: "ignore" });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
 function abortIfCancel(value: unknown): void {
   if (isCancel(value)) {
     cancel("Setup cancelled.");
@@ -167,7 +178,22 @@ export async function runSetupCommand(): Promise<void> {
     overlapChars = parseInt(rawOverlapChars as string, 10) || 100;
   }
 
-  // Step 4: Write config
+  // Step 4: Search verbosity defaults
+  // First install assumption: no mcporter => include params by default.
+  const hasMcporter = detectMcporterInstalled();
+  const schemaPreference = await confirm({
+    message: hasMcporter
+      ? "mcporter detected. Use compact mcp_search output by default?"
+      : "mcporter not detected. Keep full params in mcp_search by default?",
+    initialValue: true,
+  });
+  abortIfCancel(schemaPreference);
+
+  const includeParametersDefault = hasMcporter
+    ? !Boolean(schemaPreference)
+    : Boolean(schemaPreference);
+
+  // Step 5: Write config
   // Build mcpServers dict (key = server name, value = entry without name field)
   const mcpServers: Record<string, unknown> = {};
   for (const srv of servers) {
@@ -181,7 +207,7 @@ export async function runSetupCommand(): Promise<void> {
       model: embeddingModel,
       url: ollamaUrl as string,
     },
-    search: { topK, minScore },
+    search: { topK, minScore, includeParametersDefault },
     indexer: { maxChunkChars, overlapChars },
   };
 

package/src/test/config.test.ts

@@ -540,6 +540,7 @@ describe("parseConfig", () => {
       maxRetryDelay: 30_000,
       maxChunkChars: 500,
       overlapChars: 100,
+      generateCliArtifacts: false,
     });
   });
 
@@ -561,6 +562,7 @@ describe("parseConfig", () => {
       maxRetryDelay: 15_000,
       maxChunkChars: 4000,
       overlapChars: 400,
+      generateCliArtifacts: false,
     });
   });
 

package/src/test/indexer.test.ts

@@ -19,7 +19,7 @@ const mockCfg: McpRouterConfig = {
   embedding: { provider: "ollama", model: "embeddinggemma", baseUrl: "http://localhost:11434/v1" },
   vectorDb: { path: "/tmp/test-lancedb" },
   search: { topK: 5, minScore: 0.3 },
-  indexer: { connectTimeout: 60_000, maxRetries: 3, initialRetryDelay: 2_000, maxRetryDelay: 30_000, maxChunkChars: 500, overlapChars: 100 },
+  indexer: { connectTimeout: 60_000, maxRetries: 3, initialRetryDelay: 2_000, maxRetryDelay: 30_000, maxChunkChars: 500, overlapChars: 100, generateCliArtifacts: false },
 };
 
 function makeStore() {
@@ -71,6 +71,7 @@ describe("runIndexer", () => {
 
     expect(result.indexed).toBe(2);
     expect(result.failed).toBe(0);
+    expect(store.deleteServer).toHaveBeenCalledWith("fs");
     expect(store.upsertTool).toHaveBeenCalledTimes(2);
     expect(registry.registerToolOwner).toHaveBeenCalledWith("read_file", "fs");
     expect(registry.registerToolOwner).toHaveBeenCalledWith("list_dir", "fs");
@@ -155,6 +156,8 @@ describe("runIndexer", () => {
 
     // 1 tool per server × 2 servers
     expect(result.indexed).toBe(2);
+    expect(store.deleteServer).toHaveBeenCalledWith("server1");
+    expect(store.deleteServer).toHaveBeenCalledWith("server2");
   });
 
   // ── Retry behavior ──
@@ -396,6 +399,7 @@ describe("runIndexer", () => {
     });
 
     expect(result.indexed).toBe(1); // counts tools, not chunks
+    expect(store.deleteServer).toHaveBeenCalledWith("fs");
     expect(store.upsertTool).not.toHaveBeenCalled();
     expect(store.deleteToolChunks).toHaveBeenCalledWith("fs", "big_tool");
     expect(store.addToolEntries).toHaveBeenCalledTimes(1);
@@ -446,6 +450,7 @@ describe("runIndexer", () => {
     });
 
     expect(result.indexed).toBe(1);
+    expect(store.deleteServer).toHaveBeenCalledWith("fs");
     // Should use single upsertTool even for long description
     expect(store.upsertTool).toHaveBeenCalledTimes(1);
     expect(store.deleteToolChunks).not.toHaveBeenCalled();

package/src/test/tools/mcp-search-tool.test.ts

@@ -23,6 +23,7 @@ function makeTool(storeResults = makeStore()) {
     store: storeResults as never,
     embeddings: makeEmbeddings() as never,
     cfg: { topK: 5, minScore: 0.3 },
+    hasMcporter: false,
   });
 }
 
@@ -43,6 +44,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     const result = await tool.execute("id", { query: "list files" });
@@ -69,6 +71,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     const result = await tool.execute("id", { query: "read file" });
@@ -84,6 +87,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     await tool.execute("id", { query: "test", limit: 999 });
@@ -115,9 +119,10 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
-    const result = await tool.execute("id", { query: "test" });
+    const result = await tool.execute("id", { query: "test", include_schema: true });
     expect((result.content[0] as { text: string }).text).toContain("truncated");
   });
 
@@ -127,6 +132,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     await tool.execute("id", { query: "test", limit: 10 });
@@ -140,6 +146,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     await tool.execute("id", { query: "test", limit: 999 });
@@ -188,6 +195,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: store as never,
       embeddings: makeEmbeddings() as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     const result = await tool.execute("id", { query: "read file" });
@@ -209,6 +217,7 @@ describe(`${TOOL_MCP_SEARCH} tool`, () => {
       store: makeStore() as never,
       embeddings: embeddings as never,
       cfg: { topK: 5, minScore: 0.3 },
+      hasMcporter: false,
     });
 
     const result = await tool.execute("id", { query: "files" });

package/src/tools/mcp-search-tool.ts

@@ -6,7 +6,8 @@ import type { McpToolVectorStore } from "../vector-store.js";
 type SearchDeps = {
   store: McpToolVectorStore;
   embeddings: Embeddings;
-  cfg: { topK: number; minScore: number };
+  cfg: { topK: number; minScore: number; includeParametersDefault?: boolean };
+  hasMcporter: boolean;
 };
 
 /** Extract a string param tolerating both camelCase and snake_case keys. */
@@ -15,9 +16,32 @@ function readStringParam(params: Record<string, unknown>, key: string): string |
   return typeof val === "string" ? val : undefined;
 }
 
+function readBoolParam(params: Record<string, unknown>, key: string): boolean | undefined {
+  const val = params[key] ?? params[key.replace(/([A-Z])/g, "_$1").toLowerCase()];
+  return typeof val === "boolean" ? val : undefined;
+}
+
+function buildSignature(toolName: string, paramsJson: string): string {
+  try {
+    const schema = JSON.parse(paramsJson) as {
+      properties?: Record<string, { type?: string }>;
+      required?: string[];
+    };
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const parts = Object.entries(props).map(([name, def]) => {
+      const type = def?.type ?? "unknown";
+      return required.has(name) ? `${name}: ${type}` : `${name}?: ${type}`;
+    });
+    return `${toolName}(${parts.join(", ")})`;
+  } catch {
+    return `${toolName}(...)`;
+  }
+}
+
 /**
  * mcp_search — semantic search over indexed MCP tool definitions.
- * Returns formatted tool cards with name, description, and parameter schema.
+ * Returns compact cards by default (signature + CLI hint). Full JSON schema is optional.
  */
 export function createMcpSearchTool(deps: SearchDeps) {
   return {
@@ -25,7 +49,7 @@ export function createMcpSearchTool(deps: SearchDeps) {
     label: "MCP Search",
     description:
       "Search for MCP tools by describing what you want to do. " +
-      "Returns matching tool definitions with their parameter schemas. " +
+      "Returns matching tool definitions with compact signatures by default (schema optional). " +
       `Use this before ${TOOL_MCP_CALL} to find the right tool name.`,
     parameters: Type.Object({
       query: Type.String({
@@ -36,6 +60,11 @@ export function createMcpSearchTool(deps: SearchDeps) {
           description: "Max tools to return (default 5, max 20).",
         }),
       ),
+      include_schema: Type.Optional(
+        Type.Boolean({
+          description: "Include full JSON parameter schema in results. Default is auto (enabled when mcporter is unavailable).",
+        }),
+      ),
     }),
 
     async execute(_toolCallId: string, params: Record<string, unknown>) {
@@ -49,6 +78,10 @@ export function createMcpSearchTool(deps: SearchDeps) {
 
       const rawLimit = typeof params.limit === "number" ? params.limit : deps.cfg.topK;
       const limit = Math.max(1, Math.min(20, rawLimit));
+      const includeSchema =
+        readBoolParam(params, "include_schema") ??
+        deps.cfg.includeParametersDefault ??
+        !deps.hasMcporter;
 
       let vector: number[];
       try {
@@ -101,25 +134,37 @@ export function createMcpSearchTool(deps: SearchDeps) {
       const cards = results
         .map((r, i) => {
           const scoreStr = `${(r.score * 100).toFixed(0)}%`;
-          // Truncate large parameter schemas to keep context size bounded
-          const paramsStr =
-            r.entry.parameters_json.length > 2000
-              ? r.entry.parameters_json.slice(0, 2000) + "\n... (truncated)"
-              : r.entry.parameters_json;
+          const signature = buildSignature(r.entry.tool_name, r.entry.parameters_json);
+          const cliHint = `mcporter call ${r.entry.server_name}.${r.entry.tool_name} '{...}'`;
+          const fallbackHint = `${TOOL_MCP_CALL}(\"${r.entry.tool_name}\", '{...}')`;
+
+          const schemaBlock = includeSchema
+            ? `\n**Parameters (JSON Schema):**\n\`\`\`json\n${
+              r.entry.parameters_json.length > 2000
+                ? r.entry.parameters_json.slice(0, 2000) + "\n... (truncated)"
+                : r.entry.parameters_json
+            }\n\`\`\``
+            : "";
 
           return (
             `### ${i + 1}. ${r.entry.tool_name} (server: ${r.entry.server_name}, score: ${scoreStr})\n` +
             `**Description:** ${r.entry.description}\n` +
-            `**Parameters:**\n\`\`\`json\n${paramsStr}\n\`\`\``
+            `**Signature:** \`${signature}\`\n` +
+            `**Preferred (CLI):** \`${cliHint}\`\n` +
+            `**Fallback (JSON):** \`${fallbackHint}\`` +
+            schemaBlock
           );
         })
         .join("\n\n");
 
-      const text = `Found ${results.length} matching tool(s):\n\n${cards}`;
+      const text =
+        `Found ${results.length} matching tool(s). ` +
+        `${includeSchema ? "Including full schema." : "Using compact mode (set include_schema=true for full JSON schema; schema auto-enables when mcporter is unavailable)."}\n\n` +
+        cards;
 
       return {
         content: [{ type: "text", text }],
-        details: { count: results.length },
+        details: { count: results.length, includeSchema },
       };
     },
   };

package/tsconfig.json

@@ -3,7 +3,8 @@
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "strict": true
+    "strict": true,
+    "skipLibCheck": true
   },
   "include": ["src/**/*"]
 }