openclaw-mcp-router 0.2.1 → 0.2.6

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(npx tsc:*)",
+      "Bash(ls:*)"
+    ]
+  }
+}

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/CLAUDE.md

@@ -17,7 +17,7 @@ This is an **OpenClaw plugin** that solves MCP context bloat. Instead of loading
 
 ### Data Flow
 
-1. **Startup (indexing):** Plugin connects to each configured MCP server in parallel → lists tools → embeds descriptions via Ollama → stores vectors in local LanceDB
+1. **Startup (indexing):** Plugin connects to each configured MCP server in parallel (with retry/backoff per server) → lists tools → embeds descriptions via Ollama → stores vectors in local LanceDB. An `AbortController` governs the lifecycle — `stop()` cancels all in-flight connections and delays immediately.
 2. **Search:** Agent calls `mcp_search(query)` → query embedded → vector similarity search → returns matching tool cards with schemas
 3. **Execution:** Agent calls `mcp_call(tool_name, params_json)` → registry lookup for owning server → fresh MCP client connection → execute → return result
 
@@ -26,11 +26,11 @@ This is an **OpenClaw plugin** that solves MCP context bloat. Instead of loading
 | Module | Role |
 |--------|------|
 | `src/index.ts` | Plugin entry point — registers tools, CLI commands, and startup service with OpenClaw's `OpenClawPluginApi` |
-| `src/config.ts` | Parses plugin YAML config into typed `McpRouterConfig`; validates, applies defaults, expands `${VAR}` and `~/` |
+| `src/config.ts` | Parses plugin YAML config into typed `McpRouterConfig` (including `IndexerConfig` and per-server `timeout`); validates, applies defaults, expands `${VAR}` and `~/` |
 | `src/embeddings.ts` | `OllamaEmbeddings` — embeds text via Ollama's `/api/embeddings`; SSRF-safe (localhost-only); caches known model dimensions |
 | `src/vector-store.ts` | `McpToolVectorStore` — LanceDB wrapper; lazy init; upsert via delete-then-add; L2 distance → similarity score |
-| `src/indexer.ts` | `runIndexer()` — parallel server indexing with `Promise.allSettled`; graceful degradation if Ollama or a server is down |
-| `src/mcp-client.ts` | `McpClient` — thin MCP SDK wrapper; supports stdio/sse/http transports |
+| `src/indexer.ts` | `runIndexer()` — parallel server indexing with `Promise.allSettled`; per-server retry with exponential backoff; `AbortSignal` threading for cancellation; `abortableDelay()` helper |
+| `src/mcp-client.ts` | `McpClient` — thin MCP SDK wrapper; supports stdio/sse/http transports; `connect()` accepts optional `{ signal, timeout }` forwarded to SDK |
 | `src/mcp-registry.ts` | `McpRegistry` — in-memory `toolName → serverConfig` map; last-writer-wins on name collisions |
 | `src/tools/mcp-search-tool.ts` | `mcp_search` tool — embeds query, searches vector store, formats tool cards |
 | `src/tools/mcp-call-tool.ts` | `mcp_call` tool — resolves server from registry, opens fresh connection, executes, disconnects |
@@ -41,6 +41,8 @@ This is an **OpenClaw plugin** that solves MCP context bloat. Instead of loading
 - **Optional tool registration.** Both tools use `{ optional: true }` — they only appear in agent context when `tools.alsoAllow` includes them.
 - **Compound tool IDs.** Vector store entries use `"${serverName}::${toolName}"` as stable upsert keys.
 - **Graceful degradation.** Indexer uses `Promise.allSettled` — one failing server doesn't block others. Ollama being unreachable is a warning, not a crash.
+- **Retry with backoff.** Each server gets `maxRetries` attempts with exponential backoff (`initialRetryDelay * 2^(attempt-1)`, capped at `maxRetryDelay`). Per-server `timeout` overrides the global `indexer.connectTimeout`.
+- **AbortSignal lifecycle.** `runIndexer` accepts an optional `AbortSignal`. The plugin entry point manages an `AbortController` — `start()` creates one, `stop()` aborts it. The `reindex` CLI command handles SIGINT. `abortableDelay()` ensures backoff waits are cancelled immediately on abort.
 - **Fresh connections per call.** `mcp_call` opens a new MCP client connection for each invocation (stateless, no pooling).
 
 ## Testing

package/README.md

@@ -21,10 +21,17 @@ The agent asks for tools it needs instead of receiving every schema upfront.
 openclaw plugins install openclaw-mcp-router
 ```
 
+**Alternative: install from source**
+
+```bash
+git clone https://github.com/lunarmoon26/openclaw-mcp-router.git
+openclaw plugins install ./openclaw-mcp-router
+```
+
 Requires [Ollama](https://ollama.ai) running locally with an embedding model:
 
 ```sh
-ollama pull nomic-embed-text
+ollama pull embeddinggemma
 ollama serve
 ```
 
@@ -39,7 +46,7 @@ tools:
     - mcp_call
 
 plugins:
-  mcp-router:
+  openclaw-mcp-router:
     enabled: true
     config:
       servers:
@@ -52,13 +59,41 @@ plugins:
           url: https://api.githubcopilot.com/mcp/
       embedding:
         provider: ollama
-        model: nomic-embed-text    # or mxbai-embed-large, all-minilm
+        model: embeddinggemma    # or qwen3-embedding:0.6b, all-minilm
         url: http://localhost:11434
       search:
         topK: 5        # tools returned per search (1–20)
         minScore: 0.3  # minimum similarity threshold (0–1)
 ```
 
+### Important: `tools.alsoAllow` is required
+
+The plugin registers `mcp_search` and `mcp_call` as **optional tools** (`optional: true`). This means the gateway loads them, but they are **not exposed to agents** unless explicitly allowlisted.
+
+If the plugin is running and `openclaw openclaw-mcp-router stats` shows indexed tools, but your agent can't call `mcp_search` — this is why. Add the allowlist to your config:
+
+```yaml
+# Global — all agents get access
+tools:
+  alsoAllow:
+    - mcp_search
+    - mcp_call
+```
+
+Or scope it to specific agents:
+
+```yaml
+# Per-agent or under agents.defaults
+agents:
+  defaults:
+    tools:
+      alsoAllow:
+        - mcp_search
+        - mcp_call
+```
+
+Restart the gateway after changing the config.
+
 ## Configuration reference
 
 ### `servers[]`
@@ -71,20 +106,54 @@ plugins:
 | `args` | stdio only | Arguments array |
 | `env` | no | Extra env vars merged over process.env; supports `${VAR}` expansion |
 | `url` | sse/http only | Server endpoint URL |
+| `timeout` | no | Per-server connect timeout in ms; overrides `indexer.connectTimeout` |
 
 ### `embedding`
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `provider` | `ollama` | Only Ollama is supported |
-| `model` | `nomic-embed-text` | Embedding model name |
+| `model` | `embeddinggemma` | Embedding model name |
 | `url` | `http://localhost:11434` | Ollama base URL (must be localhost) |
 
 ### `vectorDb`
 
 | Field | Default | Description |
 |-------|---------|-------------|
-| `path` | `~/.openclaw/mcp-router/lancedb` | LanceDB database directory |
+| `path` | `~/.openclaw/openclaw-mcp-router/lancedb` | LanceDB database directory |
+
+### `indexer`
+
+Controls retry behavior and timeouts when connecting to MCP servers at startup. Useful for self-hosted servers (e.g. started via `uvx`) that take time to start up.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `connectTimeout` | `60000` | Per-server default connect timeout in ms |
+| `maxRetries` | `3` | Retry attempts per server (0 = no retry) |
+| `initialRetryDelay` | `2000` | Initial backoff delay in ms |
+| `maxRetryDelay` | `30000` | Max backoff cap in ms |
+| `maxChunkChars` | `500` | Max characters per chunk for long tool descriptions. `0` = disable chunking |
+| `overlapChars` | `100` | Overlap characters between adjacent chunks |
+
+Retries use exponential backoff: delays are `initialRetryDelay * 2^(attempt-1)`, capped at `maxRetryDelay`. With defaults, a slow server gets attempts at ~0s, ~2s, ~4s, ~8s before giving up.
+
+**Chunking:** When a tool description exceeds `maxChunkChars`, it is split into overlapping chunks at semantic boundaries (paragraphs, lines, sentences). Each chunk is stored as a separate vector, and search results are deduplicated so each tool appears once with its best matching score. Short descriptions (the common case) are unaffected.
+
+Example for a slow-starting Python server:
+
+```yaml
+plugins:
+  openclaw-mcp-router:
+    config:
+      mcpServers:
+        my-python-server:
+          command: uvx
+          args: ["my-mcp-server"]
+          timeout: 120000  # this server needs 2 minutes to start
+      indexer:
+        maxRetries: 5
+        initialRetryDelay: 3000
+```
 
 ### `search`
 
@@ -97,28 +166,43 @@ plugins:
 
 ```sh
 # Re-index all configured MCP servers
-openclaw mcp-router reindex
+openclaw openclaw-mcp-router reindex
 
 # Show indexed tool count
-openclaw mcp-router stats
+openclaw openclaw-mcp-router stats
 ```
 
 ## How it works
 
-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.
+1. At gateway startup, the plugin connects to each MCP server in parallel (with retry and configurable timeouts), 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.
 
+Disabling the plugin (`openclaw plugins disable openclaw-mcp-router`) cancels any in-progress indexing immediately. Re-enabling starts fresh.
+
 ## Supported embedding models
 
 | Model | Dims | Notes |
 |-------|------|-------|
-| `nomic-embed-text` | 768 | Good balance, recommended default |
-| `mxbai-embed-large` | 1024 | Higher quality, larger footprint |
+| `embeddinggemma` | 768 | Good balance, recommended default |
+| `qwen3-embedding:0.6b` | 1024 | Higher quality, larger footprint |
 | `all-minilm` | 384 | Fast and lightweight |
 
 Any Ollama embedding model works — dimensions are detected automatically for unknown models.
 
+## Background
+
+This plugin is a basic implementation of the [Tool Search Tool](https://www.anthropic.com/engineering/advanced-tool-use) pattern from Anthropic's advanced tool use guide. The core idea: instead of injecting all tool schemas into the system prompt, provide a search tool that dynamically surfaces only relevant tools at runtime. Anthropic's benchmarks showed this improved tool selection accuracy from 49% to 74% (Opus 4) and 79.5% to 88.1% (Opus 4.5).
+
+Our approach is intentionally simple — pure vector similarity over tool descriptions. There's plenty of room to improve:
+
+- **Hybrid search (BM25 + embedding).** Pure embedding search can miss exact keyword matches. Combining sparse retrieval (BM25/TF-IDF) with dense vectors would improve recall, especially for tools with distinctive names like `git_diff` or `kubectl_apply`.
+- **LLM-based reranking.** After the initial vector search returns candidates, a small LLM could rerank them based on the full query context — catching semantic nuances that cosine similarity misses.
+- **Tool use examples.** Indexing not just descriptions but example invocations (input/output pairs) would let the search match against concrete usage patterns, not just what the tool claims to do.
+- **Programmatic tool calling.** Anthropic's guide describes letting the agent compose tool calls inside code blocks rather than pure JSON — reducing context pollution and enabling multi-step tool pipelines.
+
+Contributions welcome if any of these interest you.
+
 ## License
 
 MIT

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,7 +18,8 @@
             "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" }
           }
         }
       },
@@ -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": "0.2.6",
   "private": false,
   "description": "Dynamic MCP tool router for OpenClaw — semantic search over large MCP catalogs to eliminate context bloat",
   "type": "module",
@@ -23,10 +23,10 @@
     "@sinclair/typebox": "^0.34.48"
   },
   "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"
   },

package/src/chunker.ts

@@ -0,0 +1,117 @@
+export type ChunkConfig = {
+  /** Max characters per chunk. 0 = disable chunking. */
+  maxChunkChars: number;
+  /** Overlap characters between adjacent chunks. */
+  overlapChars: number;
+};
+
+export type Chunk = {
+  /** 0-based chunk index */
+  index: number;
+  /** Total chunks for this tool */
+  total: number;
+  /** Chunk text content */
+  text: string;
+};
+
+/**
+ * Split text into overlapping chunks that respect semantic boundaries.
+ *
+ * Fast path: if the text fits in a single chunk (or chunking is disabled),
+ * returns a single chunk with zero overhead.
+ *
+ * @param text - The full text to chunk (e.g. "tool_name: description")
+ * @param toolNamePrefix - Prefixed to chunks with index > 0 so the embedding
+ *   model always sees the tool name (e.g. "tool_name: ... ")
+ * @param config - Chunking parameters
+ */
+export function chunkText(
+  text: string,
+  toolNamePrefix: string,
+  config: ChunkConfig,
+): Chunk[] {
+  // Fast path: single chunk
+  if (config.maxChunkChars === 0 || text.length <= config.maxChunkChars) {
+    return [{ index: 0, total: 1, text }];
+  }
+
+  const segments = splitSegments(text);
+  const chunks = mergeSegments(segments, toolNamePrefix, config);
+  const total = chunks.length;
+
+  return chunks.map((text, index) => ({ index, total, text }));
+}
+
+/**
+ * Split text into segments using a separator hierarchy that preserves
+ * semantic boundaries: \n\n → \n → ". " → hard character boundary.
+ */
+function splitSegments(text: string): string[] {
+  // Try separators in order of preference
+  const separators = ["\n\n", "\n", ". "];
+
+  for (const sep of separators) {
+    if (text.includes(sep)) {
+      const parts = text.split(sep);
+      // Re-attach separator to end of each part (except last)
+      return parts.map((part, i) => (i < parts.length - 1 ? part + sep : part));
+    }
+  }
+
+  // No separators found — return the whole text as one segment
+  // (will be hard-split in mergeSegments if needed)
+  return [text];
+}
+
+/**
+ * Greedily merge segments into chunks up to maxChunkChars.
+ * When a chunk is full, start a new one with overlap from the previous chunk's tail.
+ * Chunks with index > 0 get the tool name prefix.
+ */
+function mergeSegments(
+  segments: string[],
+  toolNamePrefix: string,
+  config: ChunkConfig,
+): string[] {
+  const { maxChunkChars, overlapChars } = config;
+  const continuationPrefix = `${toolNamePrefix}: ... `;
+  const chunks: string[] = [];
+
+  let current = "";
+
+  for (const segment of segments) {
+    // If adding this segment exceeds the limit, finalize current chunk
+    if (current.length > 0 && current.length + segment.length > maxChunkChars) {
+      chunks.push(current);
+      // Start new chunk with overlap from the tail of the previous chunk
+      const overlap = overlapChars > 0 ? current.slice(-overlapChars) : "";
+      current = continuationPrefix + overlap;
+    }
+
+    // If a single segment is too long, hard-split it
+    if (segment.length > maxChunkChars) {
+      // Flush anything accumulated
+      if (current.length > 0 && current !== continuationPrefix) {
+        // There may be partial content — include it
+      }
+
+      let remaining = current + segment;
+      while (remaining.length > maxChunkChars) {
+        chunks.push(remaining.slice(0, maxChunkChars));
+        const overlap = overlapChars > 0 ? remaining.slice(maxChunkChars - overlapChars, maxChunkChars) : "";
+        remaining = continuationPrefix + overlap + remaining.slice(maxChunkChars);
+      }
+      current = remaining;
+      continue;
+    }
+
+    current += segment;
+  }
+
+  // Flush remaining
+  if (current.length > 0) {
+    chunks.push(current);
+  }
+
+  return chunks;
+}

package/src/config.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { EXTENSION_ID } from "./constants.js";
 import type { EmbeddingConfig, EmbeddingProvider } from "./embeddings.js";
 
 export type McpTransportKind = "stdio" | "sse" | "http";
@@ -18,6 +19,23 @@ export type McpServerConfig = {
   url?: string;
   /** sse/http: extra headers; ${VAR} expanded */
   headers?: Record<string, string>;
+  /** Per-server connect timeout in ms; overrides indexer.connectTimeout */
+  timeout?: number;
+};
+
+export type IndexerConfig = {
+  /** Per-server default connect timeout in ms (default: 60_000) */
+  connectTimeout: number;
+  /** Retry attempts per server, 0 = no retry (default: 3) */
+  maxRetries: number;
+  /** Initial backoff delay in ms (default: 2_000) */
+  initialRetryDelay: number;
+  /** Max backoff cap in ms (default: 30_000) */
+  maxRetryDelay: number;
+  /** Max characters per chunk for long tool descriptions. 0 = disable chunking. (default: 500) */
+  maxChunkChars: number;
+  /** Overlap characters between adjacent chunks (default: 100) */
+  overlapChars: number;
 };
 
 export type McpRouterConfig = {
@@ -25,6 +43,7 @@ export type McpRouterConfig = {
   embedding: EmbeddingConfig;
   vectorDb: { path: string };
   search: { topK: number; minScore: number };
+  indexer: IndexerConfig;
 };
 
 export type ParseConfigOpts = {
@@ -53,7 +72,7 @@ function resolveHome(p: string): string {
 }
 
 const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
-const DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
+const DEFAULT_EMBEDDING_MODEL = "embeddinggemma";
 const DEFAULT_MCP_SERVERS_FILE = "~/.openclaw/.mcp.json";
 
 // ── mcpServers dict parsing ──────────────────────────────────────────────
@@ -62,7 +81,7 @@ function parseMcpServersDict(dict: Record<string, unknown>): McpServerConfig[] {
   const servers: McpServerConfig[] = [];
   for (const [name, raw] of Object.entries(dict)) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-      throw new Error(`mcp-router: mcpServers["${name}"] must be an object`);
+      throw new Error(`${EXTENSION_ID}: mcpServers["${name}"] must be an object`);
     }
     const sv = raw as Record<string, unknown>;
 
@@ -74,14 +93,14 @@ function parseMcpServersDict(dict: Record<string, unknown>): McpServerConfig[] {
       transport = "http";
     } else {
       throw new Error(
-        `mcp-router: mcpServers["${name}"] must have either "command" (stdio) or "url"/"serverUrl" (http)`,
+        `${EXTENSION_ID}: mcpServers["${name}"] must have either "command" (stdio) or "url"/"serverUrl" (http)`,
       );
     }
 
     // Allow explicit type override (e.g. "sse" for legacy servers)
     if (typeof sv.type === "string") {
       if (!["stdio", "sse", "http"].includes(sv.type)) {
-        throw new Error(`mcp-router: mcpServers["${name}"].type must be stdio, sse, or http`);
+        throw new Error(`${EXTENSION_ID}: mcpServers["${name}"].type must be stdio, sse, or http`);
       }
       transport = sv.type as McpTransportKind;
     }
@@ -98,6 +117,7 @@ function parseMcpServersDict(dict: Record<string, unknown>): McpServerConfig[] {
       env: expandEnvRecord(rawEnv),
       url,
       headers: Object.keys(rawHeaders).length > 0 ? expandEnvRecord(rawHeaders) : undefined,
+      timeout: typeof sv.timeout === "number" ? sv.timeout : undefined,
     });
   }
   return servers;
@@ -118,11 +138,11 @@ function loadMcpServersFile(filePath: string, opts?: ParseConfigOpts): McpServer
   try {
     parsed = JSON.parse(content);
   } catch {
-    throw new Error(`mcp-router: failed to parse ${resolved} as JSON`);
+    throw new Error(`${EXTENSION_ID}: failed to parse ${resolved} as JSON`);
   }
 
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`mcp-router: ${resolved} must contain a JSON object`);
+    throw new Error(`${EXTENSION_ID}: ${resolved} must contain a JSON object`);
   }
 
   const obj = parsed as Record<string, unknown>;
@@ -155,7 +175,7 @@ function resolveEmbeddingConfig(
     } else if (provider === "ollama") {
       baseUrl = DEFAULT_OLLAMA_BASE_URL;
     } else {
-      throw new Error(`mcp-router: embedding.baseUrl is required for provider "${provider}"`);
+      throw new Error(`${EXTENSION_ID}: embedding.baseUrl is required for provider "${provider}"`);
     }
 
     return {
@@ -212,25 +232,25 @@ function resolveEmbeddingConfig(
 function parseLegacyServers(serversRaw: unknown[]): McpServerConfig[] {
   return serversRaw.map((s: unknown, i: number) => {
     if (!s || typeof s !== "object" || Array.isArray(s)) {
-      throw new Error(`mcp-router: servers[${i}] must be an object`);
+      throw new Error(`${EXTENSION_ID}: servers[${i}] must be an object`);
     }
     const sv = s as Record<string, unknown>;
 
     if (typeof sv.name !== "string" || !sv.name.trim()) {
-      throw new Error(`mcp-router: servers[${i}].name is required`);
+      throw new Error(`${EXTENSION_ID}: servers[${i}].name is required`);
     }
     const transport = sv.transport as McpTransportKind;
     if (!["stdio", "sse", "http"].includes(transport)) {
-      throw new Error(`mcp-router: servers[${i}].transport must be stdio, sse, or http`);
+      throw new Error(`${EXTENSION_ID}: servers[${i}].transport must be stdio, sse, or http`);
     }
 
     if (transport === "stdio") {
       if (typeof sv.command !== "string" || !sv.command.trim()) {
-        throw new Error(`mcp-router: servers[${i}] with transport=stdio requires command`);
+        throw new Error(`${EXTENSION_ID}: servers[${i}] with transport=stdio requires command`);
       }
     } else {
       if (typeof sv.url !== "string" || !sv.url.trim()) {
-        throw new Error(`mcp-router: servers[${i}] with transport=${transport} requires url`);
+        throw new Error(`${EXTENSION_ID}: servers[${i}] with transport=${transport} requires url`);
       }
     }
 
@@ -245,6 +265,7 @@ function parseLegacyServers(serversRaw: unknown[]): McpServerConfig[] {
       env: expandEnvRecord(rawEnv),
       url: typeof sv.url === "string" ? sv.url : undefined,
       headers: Object.keys(rawHeaders).length > 0 ? expandEnvRecord(rawHeaders) : undefined,
+      timeout: typeof sv.timeout === "number" ? sv.timeout : undefined,
     };
   });
 }
@@ -253,10 +274,12 @@ function parseLegacyServers(serversRaw: unknown[]): McpServerConfig[] {
 
 /** Parse and validate raw plugin config, applying defaults. Throws on invalid input. */
 export function parseConfig(raw: unknown, opts?: ParseConfigOpts): McpRouterConfig {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("mcp-router: config must be an object");
+  // Treat null/undefined as empty config — allows auto-loading from default file
+  const normalized = raw ?? {};
+  if (typeof normalized !== "object" || Array.isArray(normalized)) {
+    throw new Error(`${EXTENSION_ID}: config must be an object`);
   }
-  const r = raw as Record<string, unknown>;
+  const r = normalized as Record<string, unknown>;
 
   // ── Server resolution priority: mcpServers > mcpServersFile > servers (legacy) ──
   let servers: McpServerConfig[] = [];
@@ -272,11 +295,8 @@ export function parseConfig(raw: unknown, opts?: ParseConfigOpts): McpRouterConf
     servers = loadMcpServersFile(DEFAULT_MCP_SERVERS_FILE, opts);
   }
 
-  if (servers.length === 0) {
-    throw new Error(
-      "mcp-router: no servers configured. Provide mcpServers, mcpServersFile, or servers[].",
-    );
-  }
+  // Empty servers is valid — user may add servers later.
+  // Callers should check servers.length and skip indexing if zero.
 
   // ── Embedding config ──
   const embRaw = r.embedding && typeof r.embedding === "object" && !Array.isArray(r.embedding)
@@ -289,7 +309,7 @@ export function parseConfig(raw: unknown, opts?: ParseConfigOpts): McpRouterConf
   const dbPath =
     typeof vdbRaw.path === "string"
       ? resolveHome(vdbRaw.path)
-      : path.join(os.homedir(), ".openclaw", "mcp-router", "lancedb");
+      : path.join(os.homedir(), ".openclaw", EXTENSION_ID, "lancedb");
   const vectorDb = { path: dbPath };
 
   // ── search defaults ──
@@ -299,5 +319,16 @@ export function parseConfig(raw: unknown, opts?: ParseConfigOpts): McpRouterConf
     minScore: typeof srchRaw.minScore === "number" ? srchRaw.minScore : 0.3,
   };
 
-  return { servers, embedding, vectorDb, search };
+  // ── indexer defaults ──
+  const idxRaw = (r.indexer ?? {}) as Record<string, unknown>;
+  const indexer: IndexerConfig = {
+    connectTimeout: typeof idxRaw.connectTimeout === "number" ? idxRaw.connectTimeout : 60_000,
+    maxRetries: typeof idxRaw.maxRetries === "number" ? Math.max(0, idxRaw.maxRetries) : 3,
+    initialRetryDelay: typeof idxRaw.initialRetryDelay === "number" ? idxRaw.initialRetryDelay : 2_000,
+    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,
+  };
+
+  return { servers, embedding, vectorDb, search, indexer };
 }

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** The OpenClaw extension ID and npm package name. */
+export const EXTENSION_ID = "openclaw-mcp-router";