opencode-toolbox 0.8.0 → 0.10.0

package/README.md

@@ -46,6 +46,7 @@ Create `~/.config/opencode/toolbox.jsonc`:
 
 ```jsonc
 {
+  "$schema": "https://unpkg.com/opencode-toolbox@latest/toolbox.schema.json",
   "mcp": {
     "time": {
       "type": "local",
@@ -72,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`)
@@ -165,6 +168,9 @@ Returns a comprehensive status object:
 {
   "plugin": {
     "initialized": true,
+    "initState": "ready",
+    "initMode": "eager",
+    "initDurationMs": 1234,
     "configPath": "/Users/username/.config/opencode/toolbox.jsonc",
     "uptime": 123.45,
     "searches": 23,
@@ -182,8 +188,9 @@ Returns a comprehensive status object:
         "name": "time",
         "status": "connected",
         "type": "local",
-        "toolCount": 5,
+        "toolCount": 2,
         "error": null,
+        "commandString": "uvx mcp-server-time",
         "healthy": true
       },
       {
@@ -192,6 +199,7 @@ Returns a comprehensive status object:
         "type": "local",
         "toolCount": 12,
         "error": null,
+        "commandString": "npx -y @anthropic/mcp-github",
         "healthy": true
       },
       {
@@ -199,16 +207,25 @@ Returns a comprehensive status object:
         "status": "error",
         "type": "remote",
         "toolCount": 0,
-        "error": "Failed to connect: timeout",
+        "error": "Connection timeout after 5000ms",
+        "url": "https://mcp.example.com/weather",
         "healthy": false
       }
     ]
   },
   "tools": {
-    "total": 17,
-    "available": 17,
+    "total": 14,
+    "indexed": 14,
     "serversWithTools": 2
   },
+  "toolboxTools": [
+    "toolbox_search_bm25",
+    "toolbox_search_regex",
+    "toolbox_execute",
+    "toolbox_status",
+    "toolbox_perf",
+    "toolbox_test"
+  ],
   "health": {
     "status": "degraded",
     "message": "1 server(s) failed to connect"
@@ -223,7 +240,7 @@ Returns a comprehensive status object:
 
 ### /toolbox-status Slash Command
 
-The plugin automatically creates a `/toolbox-status` slash command on first launch:
+The plugin automatically creates and maintains the `/toolbox-status` slash command:
 
 ```
 ~/.config/opencode/command/toolbox-status.md
@@ -231,6 +248,8 @@ The plugin automatically creates a `/toolbox-status` slash command on first laun
 
 Use it in OpenCode by typing `/toolbox-status` to get a formatted status report.
 
+> **Note:** The command file auto-updates when the plugin version changes.
+
 ### toolbox_perf
 
 Get detailed performance metrics for the toolbox plugin:
@@ -337,8 +356,10 @@ grep "WARN" ~/.local/share/opencode/toolbox.log
 **Log format:**
 ```
 2026-01-08T12:34:56.789Z [INFO] Toolbox plugin loaded successfully {"configPath":"...","serverCount":6}
-2026-01-08T12:34:57.123Z [INFO] Initialization complete: 5/6 servers connected, 42 tools indexed
-2026-01-08T12:34:57.124Z [WARN] 1 server(s) failed to connect: weather
+2026-01-08T12:34:57.100Z [INFO] time - connection time: 648.12ms, indexed 2 tools in 0.07ms
+2026-01-08T12:34:57.200Z [INFO] github - connection time: 892.45ms, indexed 12 tools in 0.15ms
+2026-01-08T12:34:58.500Z [INFO] Initialization complete in 1723.45ms: 2/3 servers, 14 tools indexed
+2026-01-08T12:34:58.501Z [WARN] Server weather failed: Connection timeout after 5000ms
 2026-01-08T12:35:00.456Z [INFO] BM25 search completed: "web search" -> 3 results
 ```
 
@@ -381,6 +402,8 @@ This shows:
 4. For remote servers, verify URL is accessible
 5. Check environment variables are set correctly
 
+> **Note:** Connection retries use exponential backoff (100ms → 200ms → 400ms..., max 30s) before failing.
+
 ### Execute fails
 
 1. Run `toolbox_status({})` to check server health

package/dist/index.js

@@ -19267,7 +19267,7 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/plugin.ts
-import { appendFile, mkdir, writeFile, access } from "fs/promises";
+import { appendFile, mkdir as mkdir2, writeFile as writeFile2, readFile } from "fs/promises";
 
 // node_modules/zod/v4/classic/external.js
 var exports_external2 = {};
@@ -32812,10 +32812,14 @@ var RemoteServerConfigSchema = exports_external2.object({
   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", [
+var ServerConfigSchema = exports_external2.object({
+  type: exports_external2.enum(["local", "remote"], {
+    error: 'Server "type" must be "local" or "remote"'
+  })
+}).passthrough().pipe(exports_external2.discriminatedUnion("type", [
   LocalServerConfigSchema,
   RemoteServerConfigSchema
-]);
+]));
 var ConnectionConfigSchema = exports_external2.object({
   connectTimeout: exports_external2.number().min(100).max(60000).default(5000),
   requestTimeout: exports_external2.number().min(100).max(300000).default(30000),
@@ -32828,6 +32832,7 @@ var SettingsConfigSchema = exports_external2.object({
   connection: ConnectionConfigSchema.optional()
 });
 var ConfigSchema = exports_external2.object({
+  $schema: exports_external2.string().optional(),
   mcp: exports_external2.record(exports_external2.string(), ServerConfigSchema),
   settings: SettingsConfigSchema.optional()
 });
@@ -33636,6 +33641,47 @@ var ParseErrorCode;
 })(ParseErrorCode || (ParseErrorCode = {}));
 
 // src/config/loader.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname } from "path";
+var NPM_PACKAGE = "opencode-toolbox";
+function getSchemaUrl(_version) {
+  return `https://unpkg.com/${NPM_PACKAGE}@latest/toolbox.schema.json`;
+}
+function generateDefaultConfig(version3) {
+  const schemaUrl = getSchemaUrl(version3);
+  return `{
+  "$schema": "${schemaUrl}",
+  "mcp": {
+    // Add your MCP servers here
+    // Example:
+    // "time": {
+    //   "type": "local",
+    //   "command": ["npx", "-y", "@anthropic/mcp-time"]
+    // }
+  },
+  "settings": {
+    "defaultLimit": 5,
+    "initMode": "eager"
+  }
+}
+`;
+}
+async function createDefaultConfigIfMissing(filePath, version3) {
+  try {
+    const file3 = Bun.file(filePath);
+    const exists = await file3.exists();
+    if (exists) {
+      return false;
+    }
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const content = generateDefaultConfig(version3);
+    await writeFile(filePath, content, "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
 function interpolateEnvVars(obj) {
   if (typeof obj === "string") {
     return obj.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, varName) => {
@@ -38343,7 +38389,10 @@ class MCPManager extends EventEmitter {
       } catch (error92) {
         lastError = error92 instanceof Error ? error92 : new Error(String(error92));
         if (attempt < maxAttempts) {
-          await sleep(this.connectionConfig.retryDelay);
+          const baseDelay = this.connectionConfig.retryDelay;
+          const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+          const delayMs = Math.min(exponentialDelay, 30000);
+          await sleep(delayMs);
         }
       }
     }
@@ -38379,7 +38428,7 @@ class MCPManager extends EventEmitter {
     });
     this.clients.set(name, client);
     globalProfiler.recordServerConnect(name, connectTime, catalogTools.length, "connected");
-    this.emit("server:connected", name, catalogTools);
+    this.emit("server:connected", name, catalogTools, connectTime);
     this.checkPartialReady();
   }
   checkPartialReady() {
@@ -38693,6 +38742,7 @@ function generateSignature(tool3) {
   return `${tool3.id.name}(${argList})`;
 }
 // src/plugin.ts
+var PACKAGE_VERSION = "0.8.0";
 var DEFAULT_CONFIG_PATH = `${process.env.HOME}/.config/opencode/toolbox.jsonc`;
 var LOG_FILE_PATH = `${process.env.HOME}/.local/share/opencode/toolbox.log`;
 var LOG_DIR = `${process.env.HOME}/.local/share/opencode`;
@@ -38702,6 +38752,13 @@ var COMMAND_CONTENT = `---
 description: Check toolbox plugin status and server health
 ---
 Run toolbox_status({}) tool and show me the results in a readable format.
+
+Include:
+1. MCP Servers table (name, type, tools, status)
+2. Tool distribution chart
+3. Toolbox's own tools list (from toolboxTools field)
+4. Health status
+
 Highlight any failed servers or issues.
 `;
 function parseToolName(fullName) {
@@ -38833,14 +38890,16 @@ function log(level, message, extra) {
   const extraStr = extra ? ` ${JSON.stringify(extra)}` : "";
   const line = `${timestamp} [${level.toUpperCase()}] ${message}${extraStr}
 `;
-  mkdir(LOG_DIR, { recursive: true }).then(() => appendFile(LOG_FILE_PATH, line)).catch(() => {});
+  mkdir2(LOG_DIR, { recursive: true }).then(() => appendFile(LOG_FILE_PATH, line)).catch(() => {});
 }
 function ensureCommandFile() {
   if (isTestEnv)
     return;
-  access(COMMAND_FILE_PATH).catch(() => {
-    mkdir(COMMAND_DIR, { recursive: true }).then(() => writeFile(COMMAND_FILE_PATH, COMMAND_CONTENT)).then(() => log("info", "Created /toolbox-status command file")).catch(() => {});
-  });
+  mkdir2(COMMAND_DIR, { recursive: true }).then(() => readFile(COMMAND_FILE_PATH, "utf-8").catch(() => "")).then((existing) => {
+    if (existing !== COMMAND_CONTENT) {
+      return writeFile2(COMMAND_FILE_PATH, COMMAND_CONTENT).then(() => log("info", existing ? "Updated /toolbox-status command file" : "Created /toolbox-status command file"));
+    }
+  }).catch(() => {});
 }
 function generateSystemPrompt(configuredServers) {
   const registry3 = configuredServers.length > 0 ? configuredServers.map((s) => `${s}_*`).join(`
@@ -38897,9 +38956,19 @@ var ToolboxPlugin = async (ctx) => {
   const pluginLoadStart = performance.now();
   const { client } = ctx;
   const configPath = process.env.OPENCODE_TOOLBOX_CONFIG || DEFAULT_CONFIG_PATH;
+  if (!isTestEnv) {
+    const created = await createDefaultConfigIfMissing(configPath, PACKAGE_VERSION);
+    if (created) {
+      log("info", `Created default config file at ${configPath}`);
+    }
+  }
   const configResult = await loadConfig(configPath);
   if (!configResult.success) {
-    const errorMsg = `Failed to load config from ${configPath}: ${configResult.error.issues.map((i) => i.message).join(", ")}`;
+    const formattedErrors = configResult.error.issues.map((issue3) => {
+      const path = issue3.path.length > 0 ? `at "${issue3.path.join(".")}"` : "";
+      return `${issue3.message} ${path}`.trim();
+    }).join("; ");
+    const errorMsg = `Failed to load config from ${configPath}: ${formattedErrors}`;
     log("error", errorMsg);
     return {};
   }
@@ -38927,12 +38996,12 @@ var ToolboxPlugin = async (ctx) => {
     initMode,
     loadDurationMs: Math.round(pluginLoadDuration * 100) / 100
   });
-  mcpManager.on("server:connected", (serverName, tools) => {
+  mcpManager.on("server:connected", (serverName, tools, connectTime) => {
     const startTime = performance.now();
     bm25Index.addToolsBatch(tools);
     const indexTime = performance.now() - startTime;
     globalProfiler.recordIncrementalUpdate(tools.length);
-    log("info", `Server ${serverName} connected, indexed ${tools.length} tools in ${indexTime.toFixed(2)}ms`);
+    log("info", `${serverName} - connection time: ${connectTime.toFixed(2)}ms, indexed ${tools.length} tools in ${indexTime.toFixed(2)}ms`);
   });
   mcpManager.on("server:error", (serverName, error92) => {
     log("warn", `Server ${serverName} failed: ${error92}`);
@@ -39103,9 +39172,34 @@ var ToolboxPlugin = async (ctx) => {
               error: errorMsg,
               durationMs: duration5
             });
+            const server = mcpManager.getServer(parsed.serverName);
+            const configuredServer = config3.mcp[parsed.serverName];
+            const serverInfo = server ? {
+              name: server.name,
+              status: server.status,
+              type: server.config.type,
+              error: server.error || null,
+              command: server.config.type === "local" ? server.config.command || null : undefined,
+              commandString: server.config.type === "local" && server.config.command ? server.config.command.join(" ") : undefined,
+              url: server.config.type === "remote" ? server.config.url || null : undefined
+            } : configuredServer ? {
+              name: parsed.serverName,
+              status: "unknown",
+              type: configuredServer.type,
+              error: null,
+              command: configuredServer.type === "local" ? configuredServer.command || null : undefined,
+              commandString: configuredServer.type === "local" && configuredServer.command ? configuredServer.command.join(" ") : undefined,
+              url: configuredServer.type === "remote" ? configuredServer.url || null : undefined
+            } : {
+              name: parsed.serverName,
+              status: "unknown",
+              type: "unknown",
+              error: null
+            };
             return JSON.stringify({
               success: false,
-              error: errorMsg
+              error: errorMsg,
+              server: serverInfo
             });
           }
         }
@@ -39155,6 +39249,9 @@ var ToolboxPlugin = async (ctx) => {
                 type: server.config.type,
                 toolCount: server.tools.length,
                 error: server.error || null,
+                command: server.config.type === "local" ? server.config.command || null : undefined,
+                commandString: server.config.type === "local" && server.config.command ? server.config.command.join(" ") : undefined,
+                url: server.config.type === "remote" ? server.config.url || null : undefined,
                 healthy: server.status === "connected"
               }))
             },
@@ -39163,6 +39260,14 @@ var ToolboxPlugin = async (ctx) => {
               indexed: bm25Index.size,
               serversWithTools: servers.filter((s) => s.tools.length > 0).length
             },
+            toolboxTools: [
+              "toolbox_search_bm25",
+              "toolbox_search_regex",
+              "toolbox_execute",
+              "toolbox_status",
+              "toolbox_perf",
+              "toolbox_test"
+            ],
             health: {
               status: failedServers.length === 0 && servers.length > 0 ? "healthy" : failedServers.length > 0 ? "degraded" : "unknown",
               message: servers.length === 0 ? "No servers configured" : failedServers.length === 0 ? "All servers connected" : `${failedServers.length} server(s) failed to connect`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-toolbox",
-  "version": "0.8.0",
+  "version": "0.10.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
+}