openclaw-mcp-router 0.2.1 → 1.0.1

package/.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
     types: [published]
 
 permissions:
-  contents: write
+  contents: read
   id-token: write          # npm provenance (links published package back to this repo+commit)
 
 jobs:
@@ -13,14 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          # Use a PAT so the version-bump commit can trigger other workflows if needed.
-          # Falls back to GITHUB_TOKEN (works fine, but commits won't trigger further CI).
-          token: ${{ secrets.PAT_TOKEN || secrets.GITHUB_TOKEN }}
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           registry-url: https://registry.npmjs.org
 
       - name: Extract version from release tag
@@ -39,19 +35,11 @@ jobs:
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "Resolved version: $VERSION"
 
-      - name: Bump package.json version
-        run: npm version "${{ steps.version.outputs.version }}" --no-git-tag-version
-
-      - name: Commit version bump
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add package.json package-lock.json 2>/dev/null || true
-          git commit -m "chore: bump version to ${{ steps.version.outputs.version }}" || echo "No changes to commit"
-          git push origin HEAD:${{ github.event.release.target_commitish }}
-
       - run: npm ci
 
+      - name: Set package version from tag (publish only, no commit)
+        run: npm version "${{ steps.version.outputs.version }}" --no-git-tag-version
+
       - name: Publish to npm
         run: npm publish --provenance --access public
         env:

package/README.md

@@ -1,124 +1,129 @@
-# openclaw-mcp-router
+# OpenClaw MCP Router 🚀
 
-Dynamic MCP tool router for [OpenClaw](https://openclaw.ai) — semantic search over large MCP tool catalogs to eliminate context bloat.
+**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.
 
-## The problem
+## ⚡ The Problem: Context Window Exhaustion
 
-Loading all MCP tool schemas upfront burns 55k–134k tokens before your agent processes a single message. With 58 tools across 5 MCP servers, that's ~77k tokens wasted on schemas the agent may never use.
+Modern MCP catalogs are growing. Loading every tool schema upfront is expensive and inefficient:
 
-## The solution
+* **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.
 
-Two tiny tools replace the full schema dump:
+## 🛠️ The Solution: Semantic Tool Routing
 
-- **`mcp_search(query)`** — embed the query via Ollama, search a local LanceDB index, return only matching tool definitions (~8.7k tokens, 95% reduction)
-- **`mcp_call(tool_name, params_json)`** — look up the owning MCP server, execute the call, return the result
+Instead of a full schema dump, this plugin registers two lightweight "Meta-Tools":
 
-The agent asks for tools it needs instead of receiving every schema upfront.
+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.
 
-## Install
+> **Result:** Your agent "asks" for the tools it needs, keeping the context window clean and the reasoning sharp.
 
-```sh
-openclaw plugins install openclaw-mcp-router
-```
+---
+
+## 🚀 Quick Start
+
+### 1. Prerequisites
+
+Ensure you have **Ollama** running locally with an embedding model:
 
-Requires [Ollama](https://ollama.ai) running locally with an embedding model:
+```bash
+ollama pull embeddinggemma
 
-```sh
-ollama pull nomic-embed-text
-ollama serve
 ```
 
-## Configuration
-
-Add to `~/.openclaw/openclaw.yml`:
-
-```yaml
-tools:
-  alsoAllow:
-    - mcp_search
-    - mcp_call
-
-plugins:
-  mcp-router:
-    enabled: true
-    config:
-      servers:
-        - name: filesystem
-          transport: stdio
-          command: npx
-          args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
-        - name: github
-          transport: sse
-          url: https://api.githubcopilot.com/mcp/
-      embedding:
-        provider: ollama
-        model: nomic-embed-text    # or mxbai-embed-large, all-minilm
-        url: http://localhost:11434
-      search:
-        topK: 5        # tools returned per search (1–20)
-        minScore: 0.3  # minimum similarity threshold (0–1)
+### 2. Installation
+
+```bash
+openclaw plugins install openclaw-mcp-router
+
 ```
 
-## Configuration reference
+### 3. Setup & Indexing
 
-### `servers[]`
+Run the interactive wizard to configure your servers and automatically update your `alsoAllow` permissions:
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | yes | Unique server identifier |
-| `transport` | yes | `stdio`, `sse`, or `http` |
-| `command` | stdio only | Executable to run |
-| `args` | stdio only | Arguments array |
-| `env` | no | Extra env vars merged over process.env; supports `${VAR}` expansion |
-| `url` | sse/http only | Server endpoint URL |
+```bash
+openclaw openclaw-mcp-router setup
+openclaw openclaw-mcp-router reindex
 
-### `embedding`
+```
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `provider` | `ollama` | Only Ollama is supported |
-| `model` | `nomic-embed-text` | Embedding model name |
-| `url` | `http://localhost:11434` | Ollama base URL (must be localhost) |
+---
 
-### `vectorDb`
+## ⚙️ Configuration
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `path` | `~/.openclaw/mcp-router/lancedb` | LanceDB database directory |
+The plugin is highly configurable via `~/.openclaw/openclaw.json`.
 
-### `search`
+### Server Management
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `topK` | `5` | Max tools returned per search |
-| `minScore` | `0.3` | Minimum similarity score (0–1) |
+You can manage servers via the **Interactive TUI**:
 
-## CLI commands
+```bash
+openclaw openclaw-mcp-router control
 
-```sh
-# Re-index all configured MCP servers
-openclaw mcp-router reindex
+```
+
+### Manual Schema Example
+
+For power users, add servers directly to your `plugins.entries`:
+
+| 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` |
+
+```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" }
+        }
+      }
+    }
+  }
+}
 
-# Show indexed tool count
-openclaw mcp-router stats
 ```
 
-## How it works
+---
+
+## 🧠 How It Works: Under the Hood
+
+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`.
+
+
+
+---
+
+## 📈 Performance & Benchmarks
+
+Based on the [Anthropic Tool Search](https://www.anthropic.com/engineering/advanced-tool-use) pattern, dynamic routing can improve tool selection accuracy significantly:
+
+* **Standard Loading:** ~49% Accuracy (Large catalogs)
+* **Dynamic Routing:** **~88% Accuracy** (Opus 4.5 benchmarks)
 
-1. At gateway startup, the plugin connects to each MCP server, lists its tools, embeds each description via Ollama, and stores them in a local LanceDB index.
-2. When the agent needs to use an MCP capability, it calls `mcp_search("what I want to do")` to find relevant tools.
-3. The agent then calls `mcp_call("tool_name", '{"param": "value"}')` to execute the chosen tool.
+---
 
-## Supported embedding models
+## 🤝 Contributing
 
-| Model | Dims | Notes |
-|-------|------|-------|
-| `nomic-embed-text` | 768 | Good balance, recommended default |
-| `mxbai-embed-large` | 1024 | Higher quality, larger footprint |
-| `all-minilm` | 384 | Fast and lightweight |
+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!
 
-Any Ollama embedding model works — dimensions are detected automatically for unknown models.
+1. Fork the repo.
+2. Create your feature branch.
+3. Submit a PR.
 
-## License
+## 📄 License
 
-MIT
+Released under the [MIT License](https://www.google.com/search?q=LICENSE).

package/openclaw.plugin.json

@@ -1,5 +1,5 @@
 {
-  "id": "mcp-router",
+  "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.",
   "configSchema": {
@@ -18,13 +18,14 @@
             "url":       { "type": "string" },
             "serverUrl": { "type": "string" },
             "type":      { "type": "string", "enum": ["stdio", "sse", "http"] },
-            "headers":   { "type": "object", "additionalProperties": { "type": "string" } }
+            "headers":   { "type": "object", "additionalProperties": { "type": "string" } },
+            "timeout":   { "type": "number", "description": "Per-server connect timeout in ms; overrides indexer.connectTimeout" }
           }
         }
       },
       "mcpServersFile": {
         "type": "string",
-        "description": "Path to a .mcp.json file. Default: ~/.openclaw/.mcp.json"
+        "description": "Path to a .mcp.json file. Default: ~/.openclaw/openclaw-mcp-router/.mcp.json"
       },
       "servers": {
         "type": "array",
@@ -39,10 +40,23 @@
             "args":      { "type": "array", "items": { "type": "string" } },
             "env":       { "type": "object", "additionalProperties": { "type": "string" } },
             "url":       { "type": "string" },
-            "headers":   { "type": "object", "additionalProperties": { "type": "string" } }
+            "headers":   { "type": "object", "additionalProperties": { "type": "string" } },
+            "timeout":   { "type": "number", "description": "Per-server connect timeout in ms; overrides indexer.connectTimeout" }
           }
         }
       },
+      "indexer": {
+        "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)" }
+        }
+      },
       "embedding": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-mcp-router",
-  "version": "0.2.1",
+  "version": "1.0.1",
   "private": false,
   "description": "Dynamic MCP tool router for OpenClaw — semantic search over large MCP catalogs to eliminate context bloat",
   "type": "module",
@@ -18,15 +18,18 @@
     "ollama"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.0.1",
     "@lancedb/lancedb": "^0.26.2",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@sinclair/typebox": "^0.34.48"
+    "@sinclair/typebox": "^0.34.48",
+    "json5": "^2.2.3",
+    "open": "^11.0.0"
   },
   "peerDependencies": {
-    "openclaw": "^2026.2.24"
+    "openclaw": "^2026.2.23"
   },
   "devDependencies": {
-    "openclaw": "^2026.2.19",
+    "openclaw": "^2026.2.23",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
@@ -37,6 +40,9 @@
   "openclaw": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/mcp-router/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: mcp-router
+description: Discover and route tasks to configured MCP tools using mcp_search + mcp_call. Use when a task needs external capabilities (APIs, SaaS, databases, web, files, messaging, infra) and the best tool is not already known in-session, especially before falling back to manual shell/curl/web workflows.
+---
+
+# MCP Router
+
+Use MCP as the first integration layer for external capabilities.
+
+## Core Rule
+
+Before manual API calls, curl scripts, or ad-hoc web work, run:
+
+- `mcp_search("<action-oriented intent>")`
+
+If a relevant tool exists, use it with `mcp_call`.
+
+## Fast Workflow
+
+1. **Search capability**
+   - 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...}")`
+5. **Recover on failure**
+   - Fix schema/type mismatch or re-search with rewritten query.
+
+## Query Rewrite Ladder (Deterministic)
+
+If search quality is poor, retry in this order:
+
+1. **Action only**: `"read file"`
+2. **Action + system**: `"read file from s3"`, `"github create issue"`
+3. **Verb swap**: create/open, read/fetch/get, list/enumerate
+4. **Scope adjust**: broaden then narrow
+
+Stop once you have a high-confidence tool.
+
+## Tool Selection Rules
+
+When multiple tools match, rank by:
+
+1. Intent fit (description matches requested outcome)
+2. Required-input fit (you can provide required params now)
+3. Simplicity (fewer fragile/optional parameters)
+4. Score/order from search results (tie-breaker)
+
+## `mcp_call` Parameter Checklist
+
+`params_json` must be a **JSON string**.
+
+- Include all required fields.
+- Match exact types (`42` vs `"42"`, `true` vs `"true"`).
+- Respect enums and nested object shapes.
+- Do not add unsupported keys unless schema allows them.
+
+Examples:
+
+```text
+✅ mcp_call("filesystem::read_file", '{"path":"/tmp/a.txt"}')
+❌ mcp_call("filesystem::read_file", {"path":"/tmp/a.txt"})
+```
+
+```text
+✅ mcp_call("db::query", '{"sql":"select * from t where id=$1","params":[123]}')
+```
+
+## Error Handling
+
+- **Missing required / invalid type**: re-read schema and correct `params_json`.
+- **Unknown tool name**: re-run `mcp_search` and use exact returned name.
+- **Server-side error**: report clearly; retry only with changed inputs.
+- **No relevant tools**: use native fallback tools/workflow.
+
+## Practical Boundaries
+
+- Reuse known tool names in the same task; avoid unnecessary re-search.
+- Re-search when intent changes materially.
+- Do not loop retries blindly; each retry must change query or params.
+
+For full examples, see [references/workflows.md](references/workflows.md).

package/skills/mcp-router/references/workflows.md

@@ -0,0 +1,184 @@
+# Complete Workflow Examples
+
+---
+
+## Example 0: Check MCP before web search
+
+**Goal:** Research a topic — but before using a built-in web search, check if a configured MCP server already handles this.
+
+```
+mcp_search("search the web")
+```
+
+**Tool card returned:**
+```
+Tool: brave::web_search
+Description: Search the web using the Brave Search API.
+Input Schema:
+  - query (string, required): The search query
+  - count (number, optional): Number of results (default: 10)
+```
+
+**Call:**
+```
+mcp_call("brave::web_search", '{"query": "MCP server authentication patterns", "count": 5}')
+```
+
+If no web-search tool appears, fall back to whichever search capability is natively available.
+
+**The pattern applies everywhere:**
+- Need to fetch a URL? → `mcp_search("fetch a webpage")` before using curl
+- Need to query a DB? → `mcp_search("run a SQL query")` before writing a connection script
+- Need to post to Slack? → `mcp_search("send a Slack message")` before building an API request
+- Need to read a file? → `mcp_search("read a local file")` before opening a shell
+
+The configured MCP catalog is the toolbox. Exhaust it before doing things the hard way.
+
+These end-to-end examples show the full search → read tool card → call sequence with realistic inputs.
+
+---
+
+## Example 1: Read a local file
+
+**Goal:** Read the contents of `/tmp/report.txt`.
+
+```
+mcp_search("read a local file")
+```
+
+**Tool card returned:**
+```
+Tool: filesystem::read_file
+Description: Read the complete contents of a file from the local filesystem.
+Input Schema:
+  - path (string, required): Absolute path to the file
+  - encoding (string, optional): File encoding (default: "utf-8")
+```
+
+**Call:**
+```
+mcp_call("filesystem::read_file", '{"path": "/tmp/report.txt"}')
+```
+
+---
+
+## Example 2: Create a GitHub pull request
+
+**Goal:** Open a PR from branch `feature/add-auth` to `main`.
+
+```
+mcp_search("create a GitHub pull request")
+```
+
+**Tool card returned:**
+```
+Tool: github::create_pull_request
+Description: Creates a new pull request in a GitHub repository.
+Input Schema:
+  - owner (string, required): Repository owner (user or org)
+  - repo (string, required): Repository name
+  - title (string, required): PR title
+  - head (string, required): Branch containing the changes
+  - base (string, required): Branch to merge into
+  - body (string, optional): PR description in Markdown
+```
+
+**Call:**
+```
+mcp_call("github::create_pull_request", '{
+  "owner": "acme-corp",
+  "repo": "backend",
+  "title": "Add JWT authentication",
+  "head": "feature/add-auth",
+  "base": "main",
+  "body": "Implements JWT-based auth as described in issue #42."
+}')
+```
+
+---
+
+## Example 3: Query a database
+
+**Goal:** Count active users in a Postgres database.
+
+```
+mcp_search("execute a SQL query against a Postgres database")
+```
+
+**Tool card returned:**
+```
+Tool: postgres::query
+Description: Execute a read-only SQL query against the configured Postgres database.
+Input Schema:
+  - sql (string, required): SQL statement to execute
+  - params (array, optional): Positional parameters for parameterized queries
+```
+
+**Call:**
+```
+mcp_call("postgres::query", '{"sql": "SELECT COUNT(*) FROM users WHERE active = true"}')
+```
+
+---
+
+## Example 4: Multi-step workflow (search once, call multiple times)
+
+**Goal:** List files in a directory, then read one of them.
+
+```
+mcp_search("list files in a directory")
+```
+
+**Tool card returned:**
+```
+Tool: filesystem::list_directory
+Description: List the files and subdirectories in a given directory.
+Input Schema:
+  - path (string, required): Absolute path to the directory
+  - recursive (boolean, optional): Include subdirectories (default: false)
+```
+
+**Call 1 — list:**
+```
+mcp_call("filesystem::list_directory", '{"path": "/tmp/project"}')
+```
+
+**Result:** `["README.md", "config.json", "src/"]`
+
+**Call 2 — read (reuse known tool name `filesystem::read_file` from Example 1):**
+```
+mcp_call("filesystem::read_file", '{"path": "/tmp/project/config.json"}')
+```
+
+No second `mcp_search` needed — once a tool name is known, reuse it directly.
+
+---
+
+## Example 5: Handling a failed search
+
+**Goal:** Get the current weather for a city, but the first query returns nothing.
+
+```
+mcp_search("weather")
+```
+
+**Result:** No matches.
+
+**Rephrase with action verb + domain:**
+```
+mcp_search("get current weather conditions for a city")
+```
+
+**Tool card returned:**
+```
+Tool: weather-api::current
+Description: Fetches current weather conditions for a given city or coordinates.
+Input Schema:
+  - city (string, required): City name or "lat,lon" coordinates
+  - units (string, optional): "metric" or "imperial" (default: "metric")
+```
+
+**Call:**
+```
+mcp_call("weather-api::current", '{"city": "San Francisco", "units": "imperial"}')
+```