opencode-toolbox 0.7.0 → 0.9.0

package/README.md

@@ -1,5 +1,12 @@
 # opencode-toolbox (Tool Search Tool)
 
+[![npm version](https://badge.fury.io/js/opencode-toolbox.svg)](https://www.npmjs.com/package/opencode-toolbox)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-toolbox)](https://www.npmjs.com/package/opencode-toolbox)
+[![license](https://img.shields.io/npm/l/opencode-toolbox)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+[![Build Status](https://github.com/assagman/opencode-toolbox/actions/workflows/ci.yml/badge.svg)](https://github.com/assagman/opencode-toolbox/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/assagman/opencode-toolbox/branch/main/graph/badge.svg)](https://codecov.io/gh/assagman/opencode-toolbox)
+
 An OpenCode plugin that implements a **tool search tool** pattern, allowing users to keep only a tiny set of tools in LLM context while accessing a larger MCP catalog on-demand.
 
 ## Motivation
@@ -20,16 +27,26 @@ Add `opencode-toolbox` to your `~/.config/opencode/opencode.jsonc`:
 
 ```jsonc
 {
-  "plugin": ["opencode-toolbox"]
+  "plugin": ["opencode-toolbox@x.y.z"]
 }
 ```
 
+> **⚡ Performance Tip:** Always pin to a specific version for instant startup.
+>
+> | Configuration | Startup Time | Why |
+> |---------------|--------------|-----|
+> | ✅ `opencode-toolbox@x.y.z` | ~0ms | Cached version matches, skips npm check |
+> | ❌ `opencode-toolbox` | ~1000ms | Resolves "latest" via npm on every startup |
+>
+> OpenCode caches plugins by exact version. When you omit the version, it defaults to `"latest"` which doesn't match the cached resolved version, triggering a fresh `bun add` on every startup. Check [npm](https://www.npmjs.com/package/opencode-toolbox) for the latest version.
+
 ### 2. Configure Toolbox
 
 Create `~/.config/opencode/toolbox.jsonc`:
 
 ```jsonc
 {
+  "$schema": "https://unpkg.com/opencode-toolbox@latest/toolbox.schema.json",
   "mcp": {
     "time": {
       "type": "local",
@@ -56,6 +73,8 @@ Create `~/.config/opencode/toolbox.jsonc`:
 }
 ```
 
+> **Note:** The config file is auto-created with default settings if it doesn't exist.
+
 ### Environment Variables
 
 - `OPENCODE_TOOLBOX_CONFIG`: Path to config file (default: `~/.config/opencode/toolbox.jsonc`)
@@ -105,16 +124,16 @@ Both search tools return tool schemas so the LLM knows exact parameters:
       }
     }
   ],
-  "usage": "Use toolbox_execute({ name: '<tool_name>', arguments: '<json>' }) to run a discovered tool"
+  "usage": "Use toolbox_execute({ toolId: '<toolId>', arguments: '<json>' }) to run a discovered tool"
 }
 ```
 
 ### toolbox_execute
 
-Execute a discovered tool with JSON-encoded arguments:
+Execute a discovered tool with JSON-encoded arguments. The `toolId` format is `{serverName}_{toolName}`:
 
 ```
-toolbox_execute({ name: "time_get_current_time", arguments: '{"timezone": "Asia/Tokyo"}' })
+toolbox_execute({ toolId: "time_get_current_time", arguments: '{"timezone": "Asia/Tokyo"}' })
 ```
 
 ## Example Flow
@@ -128,7 +147,7 @@ LLM: I need to find a time-related tool.
 Toolbox: Returns time_get_current_time with its schema
 
 LLM: Now I know the parameters. Let me call it.
-     toolbox_execute({ name: "time_get_current_time", arguments: '{"timezone":"Asia/Tokyo"}' })
+     toolbox_execute({ toolId: "time_get_current_time", arguments: '{"timezone":"Asia/Tokyo"}' })
 
 Toolbox: { "datetime": "2026-01-07T02:15:00+09:00", "timezone": "Asia/Tokyo" }
 
@@ -368,7 +387,7 @@ This shows:
 ### Execute fails
 
 1. Run `toolbox_status({})` to check server health
-2. Verify tool name format: `serverName_toolName`
+2. Verify `toolId` format: `{serverName}_{toolName}`
 3. Check `arguments` is valid JSON
 4. Ensure underlying MCP server is running and connected
 5. Check logs for detailed error messages

package/dist/index.js

@@ -32809,7 +32809,7 @@ var LocalServerConfigSchema = exports_external2.object({
 });
 var RemoteServerConfigSchema = exports_external2.object({
   type: exports_external2.literal("remote"),
-  url: exports_external2.string().url().describe("SSE endpoint URL"),
+  url: exports_external2.string().url().describe("Remote MCP endpoint URL"),
   headers: exports_external2.record(exports_external2.string(), exports_external2.string()).optional().describe("HTTP headers for authentication")
 });
 var ServerConfigSchema = exports_external2.discriminatedUnion("type", [
@@ -33953,6 +33953,7 @@ var InitializedNotificationSchema = NotificationSchema.extend({
   method: literal2("notifications/initialized"),
   params: NotificationsParamsSchema.optional()
 });
+var isInitializedNotification = (value) => InitializedNotificationSchema.safeParse(value).success;
 var PingRequestSchema = RequestSchema.extend({
   method: literal2("ping"),
   params: BaseRequestParamsSchema.optional()
@@ -37584,6 +37585,395 @@ class SSEClientTransport {
   }
 }
 
+// node_modules/eventsource-parser/dist/stream.js
+class EventSourceParserStream extends TransformStream {
+  constructor({ onError, onRetry, onComment } = {}) {
+    let parser;
+    super({
+      start(controller) {
+        parser = createParser({
+          onEvent: (event) => {
+            controller.enqueue(event);
+          },
+          onError(error92) {
+            onError === "terminate" ? controller.error(error92) : typeof onError == "function" && onError(error92);
+          },
+          onRetry,
+          onComment
+        });
+      },
+      transform(chunk) {
+        parser.feed(chunk);
+      }
+    });
+  }
+}
+
+// node_modules/@modelcontextprotocol/sdk/dist/esm/client/streamableHttp.js
+var DEFAULT_STREAMABLE_HTTP_RECONNECTION_OPTIONS = {
+  initialReconnectionDelay: 1000,
+  maxReconnectionDelay: 30000,
+  reconnectionDelayGrowFactor: 1.5,
+  maxRetries: 2
+};
+
+class StreamableHTTPError extends Error {
+  constructor(code, message) {
+    super(`Streamable HTTP error: ${message}`);
+    this.code = code;
+  }
+}
+
+class StreamableHTTPClientTransport {
+  constructor(url3, opts) {
+    this._hasCompletedAuthFlow = false;
+    this._url = url3;
+    this._resourceMetadataUrl = undefined;
+    this._scope = undefined;
+    this._requestInit = opts?.requestInit;
+    this._authProvider = opts?.authProvider;
+    this._fetch = opts?.fetch;
+    this._fetchWithInit = createFetchWithInit(opts?.fetch, opts?.requestInit);
+    this._sessionId = opts?.sessionId;
+    this._reconnectionOptions = opts?.reconnectionOptions ?? DEFAULT_STREAMABLE_HTTP_RECONNECTION_OPTIONS;
+  }
+  async _authThenStart() {
+    if (!this._authProvider) {
+      throw new UnauthorizedError("No auth provider");
+    }
+    let result;
+    try {
+      result = await auth(this._authProvider, {
+        serverUrl: this._url,
+        resourceMetadataUrl: this._resourceMetadataUrl,
+        scope: this._scope,
+        fetchFn: this._fetchWithInit
+      });
+    } catch (error92) {
+      this.onerror?.(error92);
+      throw error92;
+    }
+    if (result !== "AUTHORIZED") {
+      throw new UnauthorizedError;
+    }
+    return await this._startOrAuthSse({ resumptionToken: undefined });
+  }
+  async _commonHeaders() {
+    const headers = {};
+    if (this._authProvider) {
+      const tokens = await this._authProvider.tokens();
+      if (tokens) {
+        headers["Authorization"] = `Bearer ${tokens.access_token}`;
+      }
+    }
+    if (this._sessionId) {
+      headers["mcp-session-id"] = this._sessionId;
+    }
+    if (this._protocolVersion) {
+      headers["mcp-protocol-version"] = this._protocolVersion;
+    }
+    const extraHeaders = normalizeHeaders(this._requestInit?.headers);
+    return new Headers({
+      ...headers,
+      ...extraHeaders
+    });
+  }
+  async _startOrAuthSse(options) {
+    const { resumptionToken } = options;
+    try {
+      const headers = await this._commonHeaders();
+      headers.set("Accept", "text/event-stream");
+      if (resumptionToken) {
+        headers.set("last-event-id", resumptionToken);
+      }
+      const response = await (this._fetch ?? fetch)(this._url, {
+        method: "GET",
+        headers,
+        signal: this._abortController?.signal
+      });
+      if (!response.ok) {
+        await response.body?.cancel();
+        if (response.status === 401 && this._authProvider) {
+          return await this._authThenStart();
+        }
+        if (response.status === 405) {
+          return;
+        }
+        throw new StreamableHTTPError(response.status, `Failed to open SSE stream: ${response.statusText}`);
+      }
+      this._handleSseStream(response.body, options, true);
+    } catch (error92) {
+      this.onerror?.(error92);
+      throw error92;
+    }
+  }
+  _getNextReconnectionDelay(attempt) {
+    if (this._serverRetryMs !== undefined) {
+      return this._serverRetryMs;
+    }
+    const initialDelay = this._reconnectionOptions.initialReconnectionDelay;
+    const growFactor = this._reconnectionOptions.reconnectionDelayGrowFactor;
+    const maxDelay = this._reconnectionOptions.maxReconnectionDelay;
+    return Math.min(initialDelay * Math.pow(growFactor, attempt), maxDelay);
+  }
+  _scheduleReconnection(options, attemptCount = 0) {
+    const maxRetries = this._reconnectionOptions.maxRetries;
+    if (attemptCount >= maxRetries) {
+      this.onerror?.(new Error(`Maximum reconnection attempts (${maxRetries}) exceeded.`));
+      return;
+    }
+    const delay = this._getNextReconnectionDelay(attemptCount);
+    this._reconnectionTimeout = setTimeout(() => {
+      this._startOrAuthSse(options).catch((error92) => {
+        this.onerror?.(new Error(`Failed to reconnect SSE stream: ${error92 instanceof Error ? error92.message : String(error92)}`));
+        this._scheduleReconnection(options, attemptCount + 1);
+      });
+    }, delay);
+  }
+  _handleSseStream(stream, options, isReconnectable) {
+    if (!stream) {
+      return;
+    }
+    const { onresumptiontoken, replayMessageId } = options;
+    let lastEventId;
+    let hasPrimingEvent = false;
+    let receivedResponse = false;
+    const processStream = async () => {
+      try {
+        const reader = stream.pipeThrough(new TextDecoderStream).pipeThrough(new EventSourceParserStream({
+          onRetry: (retryMs) => {
+            this._serverRetryMs = retryMs;
+          }
+        })).getReader();
+        while (true) {
+          const { value: event, done } = await reader.read();
+          if (done) {
+            break;
+          }
+          if (event.id) {
+            lastEventId = event.id;
+            hasPrimingEvent = true;
+            onresumptiontoken?.(event.id);
+          }
+          if (!event.data) {
+            continue;
+          }
+          if (!event.event || event.event === "message") {
+            try {
+              const message = JSONRPCMessageSchema.parse(JSON.parse(event.data));
+              if (isJSONRPCResultResponse(message)) {
+                receivedResponse = true;
+                if (replayMessageId !== undefined) {
+                  message.id = replayMessageId;
+                }
+              }
+              this.onmessage?.(message);
+            } catch (error92) {
+              this.onerror?.(error92);
+            }
+          }
+        }
+        const canResume = isReconnectable || hasPrimingEvent;
+        const needsReconnect = canResume && !receivedResponse;
+        if (needsReconnect && this._abortController && !this._abortController.signal.aborted) {
+          this._scheduleReconnection({
+            resumptionToken: lastEventId,
+            onresumptiontoken,
+            replayMessageId
+          }, 0);
+        }
+      } catch (error92) {
+        this.onerror?.(new Error(`SSE stream disconnected: ${error92}`));
+        const canResume = isReconnectable || hasPrimingEvent;
+        const needsReconnect = canResume && !receivedResponse;
+        if (needsReconnect && this._abortController && !this._abortController.signal.aborted) {
+          try {
+            this._scheduleReconnection({
+              resumptionToken: lastEventId,
+              onresumptiontoken,
+              replayMessageId
+            }, 0);
+          } catch (error93) {
+            this.onerror?.(new Error(`Failed to reconnect: ${error93 instanceof Error ? error93.message : String(error93)}`));
+          }
+        }
+      }
+    };
+    processStream();
+  }
+  async start() {
+    if (this._abortController) {
+      throw new Error("StreamableHTTPClientTransport already started! If using Client class, note that connect() calls start() automatically.");
+    }
+    this._abortController = new AbortController;
+  }
+  async finishAuth(authorizationCode) {
+    if (!this._authProvider) {
+      throw new UnauthorizedError("No auth provider");
+    }
+    const result = await auth(this._authProvider, {
+      serverUrl: this._url,
+      authorizationCode,
+      resourceMetadataUrl: this._resourceMetadataUrl,
+      scope: this._scope,
+      fetchFn: this._fetchWithInit
+    });
+    if (result !== "AUTHORIZED") {
+      throw new UnauthorizedError("Failed to authorize");
+    }
+  }
+  async close() {
+    if (this._reconnectionTimeout) {
+      clearTimeout(this._reconnectionTimeout);
+      this._reconnectionTimeout = undefined;
+    }
+    this._abortController?.abort();
+    this.onclose?.();
+  }
+  async send(message, options) {
+    try {
+      const { resumptionToken, onresumptiontoken } = options || {};
+      if (resumptionToken) {
+        this._startOrAuthSse({ resumptionToken, replayMessageId: isJSONRPCRequest(message) ? message.id : undefined }).catch((err) => this.onerror?.(err));
+        return;
+      }
+      const headers = await this._commonHeaders();
+      headers.set("content-type", "application/json");
+      headers.set("accept", "application/json, text/event-stream");
+      const init = {
+        ...this._requestInit,
+        method: "POST",
+        headers,
+        body: JSON.stringify(message),
+        signal: this._abortController?.signal
+      };
+      const response = await (this._fetch ?? fetch)(this._url, init);
+      const sessionId = response.headers.get("mcp-session-id");
+      if (sessionId) {
+        this._sessionId = sessionId;
+      }
+      if (!response.ok) {
+        const text = await response.text().catch(() => null);
+        if (response.status === 401 && this._authProvider) {
+          if (this._hasCompletedAuthFlow) {
+            throw new StreamableHTTPError(401, "Server returned 401 after successful authentication");
+          }
+          const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
+          this._resourceMetadataUrl = resourceMetadataUrl;
+          this._scope = scope;
+          const result = await auth(this._authProvider, {
+            serverUrl: this._url,
+            resourceMetadataUrl: this._resourceMetadataUrl,
+            scope: this._scope,
+            fetchFn: this._fetchWithInit
+          });
+          if (result !== "AUTHORIZED") {
+            throw new UnauthorizedError;
+          }
+          this._hasCompletedAuthFlow = true;
+          return this.send(message);
+        }
+        if (response.status === 403 && this._authProvider) {
+          const { resourceMetadataUrl, scope, error: error92 } = extractWWWAuthenticateParams(response);
+          if (error92 === "insufficient_scope") {
+            const wwwAuthHeader = response.headers.get("WWW-Authenticate");
+            if (this._lastUpscopingHeader === wwwAuthHeader) {
+              throw new StreamableHTTPError(403, "Server returned 403 after trying upscoping");
+            }
+            if (scope) {
+              this._scope = scope;
+            }
+            if (resourceMetadataUrl) {
+              this._resourceMetadataUrl = resourceMetadataUrl;
+            }
+            this._lastUpscopingHeader = wwwAuthHeader ?? undefined;
+            const result = await auth(this._authProvider, {
+              serverUrl: this._url,
+              resourceMetadataUrl: this._resourceMetadataUrl,
+              scope: this._scope,
+              fetchFn: this._fetch
+            });
+            if (result !== "AUTHORIZED") {
+              throw new UnauthorizedError;
+            }
+            return this.send(message);
+          }
+        }
+        throw new StreamableHTTPError(response.status, `Error POSTing to endpoint: ${text}`);
+      }
+      this._hasCompletedAuthFlow = false;
+      this._lastUpscopingHeader = undefined;
+      if (response.status === 202) {
+        await response.body?.cancel();
+        if (isInitializedNotification(message)) {
+          this._startOrAuthSse({ resumptionToken: undefined }).catch((err) => this.onerror?.(err));
+        }
+        return;
+      }
+      const messages = Array.isArray(message) ? message : [message];
+      const hasRequests = messages.filter((msg) => ("method" in msg) && ("id" in msg) && msg.id !== undefined).length > 0;
+      const contentType = response.headers.get("content-type");
+      if (hasRequests) {
+        if (contentType?.includes("text/event-stream")) {
+          this._handleSseStream(response.body, { onresumptiontoken }, false);
+        } else if (contentType?.includes("application/json")) {
+          const data = await response.json();
+          const responseMessages = Array.isArray(data) ? data.map((msg) => JSONRPCMessageSchema.parse(msg)) : [JSONRPCMessageSchema.parse(data)];
+          for (const msg of responseMessages) {
+            this.onmessage?.(msg);
+          }
+        } else {
+          await response.body?.cancel();
+          throw new StreamableHTTPError(-1, `Unexpected content type: ${contentType}`);
+        }
+      } else {
+        await response.body?.cancel();
+      }
+    } catch (error92) {
+      this.onerror?.(error92);
+      throw error92;
+    }
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  async terminateSession() {
+    if (!this._sessionId) {
+      return;
+    }
+    try {
+      const headers = await this._commonHeaders();
+      const init = {
+        ...this._requestInit,
+        method: "DELETE",
+        headers,
+        signal: this._abortController?.signal
+      };
+      const response = await (this._fetch ?? fetch)(this._url, init);
+      await response.body?.cancel();
+      if (!response.ok && response.status !== 405) {
+        throw new StreamableHTTPError(response.status, `Failed to terminate session: ${response.statusText}`);
+      }
+      this._sessionId = undefined;
+    } catch (error92) {
+      this.onerror?.(error92);
+      throw error92;
+    }
+  }
+  setProtocolVersion(version3) {
+    this._protocolVersion = version3;
+  }
+  get protocolVersion() {
+    return this._protocolVersion;
+  }
+  async resumeStream(lastEventId, options) {
+    await this._startOrAuthSse({
+      resumptionToken: lastEventId,
+      onresumptiontoken: options?.onresumptiontoken
+    });
+  }
+}
+
 // src/mcp-client/remote.ts
 class RemoteMCPClient {
   client;
@@ -37591,12 +37981,17 @@ class RemoteMCPClient {
   toolsCache;
   name;
   config;
+  transportType;
   constructor(config3) {
     this.transport = null;
     this.toolsCache = null;
     this.name = config3.name;
     this.config = config3;
-    this.client = new Client({
+    this.transportType = null;
+    this.client = this.createClient();
+  }
+  createClient() {
+    return new Client({
       name: `opencode-toolbox-client-${this.name}`,
       version: "0.1.0"
     }, {});
@@ -37606,12 +38001,46 @@ class RemoteMCPClient {
       throw new Error(`Remote MCP server ${this.name} has no URL`);
     }
     const url3 = new URL(this.config.url);
-    this.transport = new SSEClientTransport(url3, {
-      requestInit: {
-        headers: this.config.headers
+    this.transportType = null;
+    let streamableTransport = null;
+    try {
+      streamableTransport = new StreamableHTTPClientTransport(url3, {
+        requestInit: {
+          headers: this.config.headers
+        }
+      });
+      await this.client.connect(streamableTransport);
+      this.transport = streamableTransport;
+      this.transportType = "streamable-http";
+      return;
+    } catch (error92) {
+      if (streamableTransport) {
+        await streamableTransport.close().catch(() => {});
       }
-    });
-    await this.client.connect(this.transport);
+      this.client = this.createClient();
+    }
+    let sseTransport = null;
+    try {
+      const sseHeaders = {
+        Accept: "text/event-stream",
+        ...this.config.headers
+      };
+      sseTransport = new SSEClientTransport(url3, {
+        requestInit: {
+          headers: sseHeaders
+        }
+      });
+      await this.client.connect(sseTransport);
+      this.transport = sseTransport;
+      this.transportType = "sse";
+    } catch (error92) {
+      if (sseTransport) {
+        await sseTransport.close().catch(() => {});
+      }
+      this.transport = null;
+      this.transportType = null;
+      throw error92;
+    }
   }
   async listTools() {
     const result = await this.client.listTools();
@@ -37630,10 +38059,14 @@ class RemoteMCPClient {
       this.transport = null;
     }
     this.toolsCache = null;
+    this.transportType = null;
   }
   getCachedTools() {
     return this.toolsCache;
   }
+  getTransportType() {
+    return this.transportType;
+  }
 }
 // src/mcp-client/manager.ts
 import { EventEmitter } from "events";
@@ -38294,7 +38727,7 @@ function formatSearchResults(results, allTools) {
         schema: catalogTool?.inputSchema || null
       };
     }),
-    usage: "Use toolbox_execute({ name: '<tool_name>', arguments: '<json>' }) to run a discovered tool"
+    usage: "Use toolbox_execute({ toolId: '<toolId>', arguments: '<json>' }) to run a discovered tool"
   };
   return JSON.stringify(output, null, 2);
 }
@@ -38308,7 +38741,8 @@ Use when you know part of a tool name or server prefix (e.g., "time_.*", "exa_.*
 Returns tools with schemas. Use toolbox_execute() to run them.`;
 var EXECUTE_DESC = `Execute a tool discovered via toolbox_search_bm25 or toolbox_search_regex.
 
-Pass arguments as JSON string matching the tool's schema.`;
+Pass arguments as JSON string matching the tool's schema.
+toolId format: {serverName}_{toolName}`;
 var STATUS_DESC = `Get toolbox status including plugin initialization, MCP server connections, and tool counts.
 
 Shows success/total metrics to highlight failures. Use to check if toolbox is working correctly.`;
@@ -38320,7 +38754,11 @@ var TEST_DESC = `Test all toolbox tools with minimal predefined prompts.
 Executes every registered tool with super simple inputs to verify they work. Returns pass/fail for each tool.`;
 var TEST_PROMPTS = {
   time_get_current_time: {},
-  time_convert_time: { source_timezone: "UTC", time: "12:00", target_timezone: "America/New_York" },
+  time_convert_time: {
+    source_timezone: "UTC",
+    time: "12:00",
+    target_timezone: "America/New_York"
+  },
   brave_brave_web_search: { query: "test", count: 1 },
   brave_brave_local_search: { query: "coffee", count: 1 },
   brave_brave_video_search: { query: "test", count: 1 },
@@ -38328,14 +38766,20 @@ var TEST_PROMPTS = {
   brave_brave_news_search: { query: "test", count: 1 },
   brave_brave_summarizer: { key: "test" },
   brightdata_search_engine: { query: "hello", engine: "google", count: 1 },
-  brightdata_search_engine_batch: { queries: [{ query: "test", engine: "google", count: 1 }] },
+  brightdata_search_engine_batch: {
+    queries: [{ query: "test", engine: "google", count: 1 }]
+  },
   brightdata_scrape_as_markdown: { url: "https://example.com" },
   brightdata_scrape_as_html: { url: "https://example.com" },
   brightdata_scrape_batch: { urls: ["https://example.com"] },
   brightdata_extract: { url: "https://example.com" },
   brightdata_session_stats: {},
-  brightdata_web_data_reuter_news: { url: "https://www.reuters.com/technology/" },
-  brightdata_web_data_github_repository_file: { url: "https://github.com/octocat/Hello-World/blob/master/README" },
+  brightdata_web_data_reuter_news: {
+    url: "https://www.reuters.com/technology/"
+  },
+  brightdata_web_data_github_repository_file: {
+    url: "https://github.com/octocat/Hello-World/blob/master/README"
+  },
   "tavily_tavily-search": { query: "test", maxResults: 1 },
   "tavily_tavily-extract": { urls: ["https://example.com"] },
   "tavily_tavily-map": { url: "https://example.com" },
@@ -38398,26 +38842,56 @@ function ensureCommandFile() {
     mkdir(COMMAND_DIR, { recursive: true }).then(() => writeFile(COMMAND_FILE_PATH, COMMAND_CONTENT)).then(() => log("info", "Created /toolbox-status command file")).catch(() => {});
   });
 }
-var SYSTEM_PROMPT_BASE = `# Extended Toolbox
-
-You have access to an extended toolbox with additional capabilities (web search, time utilities, code search, etc.).
-
-## Rules
-1. ALWAYS toolbox_search_* before saying "I cannot do that" or "I don't have access to."
-2. ALWAYS toolbox_search_* if you think that user wants you to use some tools
-3. ALWAYS toolbox_search_* if you think that user may refer specific tool name which is not exist in the context
-
-## Workflow
-1. Search: toolbox_search_bm25({ text: "what you need" }) or toolbox_search_regex({ pattern: "prefix_.*" })
-2. Execute: toolbox_execute({ name: "tool_name", arguments: '{"key": "value"}' })`;
 function generateSystemPrompt(configuredServers) {
-  if (configuredServers.length === 0) {
-    return SYSTEM_PROMPT_BASE;
-  }
-  return `${SYSTEM_PROMPT_BASE}
-
-## Registered MCP Servers
-- ${configuredServers.join(", ")}`;
+  const registry3 = configuredServers.length > 0 ? configuredServers.map((s) => `${s}_*`).join(`
+`) : "(no servers configured)";
+  return `
+<MCPTools>
+  <Rules>
+    ALWAYS toolbox_search_* before saying "I cannot do that" or "I don't have access to"
+    ALWAYS toolbox_search_* if user wants to use tools or refers to unknown tool names
+  </Rules>
+  <MCPServers>
+    <Registry>
+      ${registry3}
+    </Registry>
+    <NamingConvention>
+      serverName: MCP server name
+      toolName: tool name provided by MCP server
+      toolId: {serverName}_{toolName}
+    </NamingConvention>
+    <Patterns>
+      ALL: ".*"
+      SERVER: "{serverName}_.*"
+      TOOL: "{serverName}_{toolName}"
+    </Patterns>
+    <Discovery>
+      <ListAllTools>
+        toolbox_search_regex({ pattern: ".*" })
+      </ListAllTools>
+      <ServerTools>
+        toolbox_search_regex({ pattern: "serverName_.*" })
+      </ServerTools>
+      <FreeSearch>
+        toolbox_search_bm25({ text: "description keywords" })
+      </FreeSearch>
+    </Discovery>
+    <Execute>
+      toolbox_execute({ toolId: "toolId", arguments: '{}' })
+    </Execute>
+    <When>
+      regex: know server name or partial tool name
+      bm25: know what you want to do, not tool name
+    </When>
+    <Fallback>
+      toolbox_search_regex \u2192 toolbox_search_bm25 \u2192 toolbox_status \u2192 ask user
+    </Fallback>
+    <Troubleshoot>
+      If tool not found: check server prefix, try bm25 with descriptive text
+      Check server health: toolbox_status()
+    </Troubleshoot>
+  </MCPServers>
+</MCPTools>`;
 }
 var ToolboxPlugin = async (ctx) => {
   const pluginLoadStart = performance.now();
@@ -38565,7 +39039,7 @@ var ToolboxPlugin = async (ctx) => {
       toolbox_execute: tool({
         description: EXECUTE_DESC,
         args: {
-          name: tool.schema.string().describe("Full tool name from search results (e.g., 'time_get_current_time', 'exa_web_search')"),
+          toolId: tool.schema.string().describe("Tool ID from search results. Format: {serverName}_{toolName} (e.g., 'time_get_current_time', 'brave_web_search')"),
           arguments: tool.schema.string().optional().describe("JSON-encoded arguments for the tool, matching its schema. Use '{}' or omit for tools with no required arguments.")
         },
         async execute(args) {
@@ -38579,15 +39053,15 @@ var ToolboxPlugin = async (ctx) => {
               error: `Failed to initialize: ${error92 instanceof Error ? error92.message : String(error92)}`
             });
           }
-          const parsed = parseToolName(args.name);
+          const parsed = parseToolName(args.toolId);
           if (!parsed) {
             timer();
-            log("warn", `Invalid tool name format: ${args.name}`, {
-              toolName: args.name
+            log("warn", `Invalid toolId format: ${args.toolId}`, {
+              toolId: args.toolId
             });
             return JSON.stringify({
               success: false,
-              error: `Invalid tool name format: ${args.name}. Expected format: serverName_toolName (e.g., 'time_get_current_time')`
+              error: `Invalid toolId format: ${args.toolId}. Expected format: {serverName}_{toolName} (e.g., 'time_get_current_time')`
             });
           }
           let toolArgs = {};
@@ -38596,8 +39070,8 @@ var ToolboxPlugin = async (ctx) => {
               toolArgs = JSON.parse(args.arguments);
             } catch (error92) {
               timer();
-              log("warn", `Failed to parse arguments as JSON for ${args.name}`, {
-                toolName: args.name,
+              log("warn", `Failed to parse arguments as JSON for ${args.toolId}`, {
+                toolId: args.toolId,
                 arguments: args.arguments
               });
               return JSON.stringify({
@@ -38611,7 +39085,7 @@ var ToolboxPlugin = async (ctx) => {
             const result = await mcpManager.callTool(parsed.serverName, parsed.toolName, toolArgs);
             const duration5 = timer();
             executionSuccessCount++;
-            log("info", `Tool executed successfully: ${args.name} in ${duration5.toFixed(2)}ms`, {
+            log("info", `Tool executed successfully: ${args.toolId} in ${duration5.toFixed(2)}ms`, {
               server: parsed.serverName,
               tool: parsed.toolName,
               durationMs: duration5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-toolbox",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Tool Search Tool Plugin for OpenCode - search and execute tools from MCP servers on-demand",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -24,7 +24,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "toolbox.schema.json"
   ],
   "keywords": [
     "opencode",

package/toolbox.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/opencode-toolbox@latest/toolbox.schema.json",
+  "title": "OpenCode Toolbox Configuration",
+  "description": "Configuration schema for opencode-toolbox plugin",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor support"
+    },
+    "mcp": {
+      "type": "object",
+      "description": "MCP servers to connect to",
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "object",
+            "description": "Local MCP server (stdio)",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "local",
+                "description": "Server type: local process via stdio"
+              },
+              "command": {
+                "type": "array",
+                "items": { "type": "string" },
+                "minItems": 1,
+                "description": "Command and arguments to spawn the MCP server"
+              },
+              "environment": {
+                "type": "object",
+                "additionalProperties": { "type": "string" },
+                "description": "Environment variables for the process. Use {env:VAR_NAME} for interpolation."
+              }
+            },
+            "required": ["type", "command"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "description": "Remote MCP server (HTTP/SSE)",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "remote",
+                "description": "Server type: remote HTTP/SSE endpoint"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Remote MCP endpoint URL"
+              },
+              "headers": {
+                "type": "object",
+                "additionalProperties": { "type": "string" },
+                "description": "HTTP headers for authentication. Use {env:VAR_NAME} for interpolation."
+              }
+            },
+            "required": ["type", "url"],
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "settings": {
+      "type": "object",
+      "description": "Plugin settings",
+      "properties": {
+        "defaultLimit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20,
+          "default": 5,
+          "description": "Default number of search results to return"
+        },
+        "initMode": {
+          "type": "string",
+          "enum": ["eager", "lazy"],
+          "default": "eager",
+          "description": "Initialization mode: 'eager' connects on plugin load, 'lazy' connects on first use"
+        },
+        "connection": {
+          "type": "object",
+          "description": "Connection settings for MCP servers",
+          "properties": {
+            "connectTimeout": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 60000,
+              "default": 5000,
+              "description": "Connection timeout in milliseconds"
+            },
+            "requestTimeout": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 300000,
+              "default": 30000,
+              "description": "Request timeout in milliseconds"
+            },
+            "retryAttempts": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 10,
+              "default": 2,
+              "description": "Number of retry attempts on connection failure"
+            },
+            "retryDelay": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 30000,
+              "default": 1000,
+              "description": "Delay between retries in milliseconds"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["mcp"],
+  "additionalProperties": false
+}