opencode-toolbox 0.4.0 → 0.5.1

package/README.md

@@ -63,7 +63,7 @@ Create `~/.config/opencode/toolbox.jsonc`:
 
 ## Usage
 
-The plugin exposes three tools:
+The plugin exposes four tools:
 
 ### toolbox_search_bm25
 
@@ -135,6 +135,86 @@ Toolbox: { "datetime": "2026-01-07T02:15:00+09:00", "timezone": "Asia/Tokyo" }
 LLM: "The current time in Tokyo is 2:15 AM on January 7, 2026."
 ```
 
+### toolbox_status
+
+Get toolbox status including plugin health, MCP server connections, and tool counts:
+
+```
+toolbox_status({})
+```
+
+Returns a comprehensive status object:
+
+```json
+{
+  "plugin": {
+    "initialized": true,
+    "configPath": "/Users/username/.config/opencode/toolbox.jsonc",
+    "uptime": 123.45,
+    "searches": 23,
+    "executions": 15,
+    "successRate": "93%"
+  },
+  "servers": {
+    "total": 3,
+    "connected": 2,
+    "failed": 1,
+    "connecting": 0,
+    "connectionRatio": "2/3",
+    "details": [
+      {
+        "name": "time",
+        "status": "connected",
+        "type": "local",
+        "toolCount": 5,
+        "error": null,
+        "healthy": true
+      },
+      {
+        "name": "github",
+        "status": "connected",
+        "type": "local",
+        "toolCount": 12,
+        "error": null,
+        "healthy": true
+      },
+      {
+        "name": "weather",
+        "status": "error",
+        "type": "remote",
+        "toolCount": 0,
+        "error": "Failed to connect: timeout",
+        "healthy": false
+      }
+    ]
+  },
+  "tools": {
+    "total": 17,
+    "available": 17,
+    "serversWithTools": 2
+  },
+  "health": {
+    "status": "degraded",
+    "message": "1 server(s) failed to connect"
+  }
+}
+```
+
+**Health Status:**
+- `healthy`: All servers connected successfully
+- `degraded`: Some servers failed to connect (check `servers.failed`)
+- `unknown`: No servers configured or initialization failed
+
+### /toolbox-status Slash Command
+
+The plugin automatically creates a `/toolbox-status` slash command on first launch:
+
+```
+~/.config/opencode/command/toolbox-status.md
+```
+
+Use it in OpenCode by typing `/toolbox-status` to get a formatted status report.
+
 ## Search Modes
 
 ### BM25 (Natural Language)
@@ -172,13 +252,69 @@ bun test --coverage   # Run with coverage
 bun run build
 ```
 
+## Observability
+
+The toolbox plugin provides built-in logging and status monitoring to help you understand what's happening.
+
+### Logging
+
+All plugin operations are logged **silently** to a dedicated log file (no screen output):
+
+```
+~/.local/share/opencode/toolbox.log
+```
+
+Log entries include:
+- Plugin initialization status
+- MCP server connection status (connected/error)
+- Tool search operations (BM25/regex queries + result counts)
+- Tool execution results (success/failure with duration)
+- Errors with details
+
+**View logs:**
+```bash
+# Watch logs in real-time
+tail -f ~/.local/share/opencode/toolbox.log
+
+# Check for errors only
+grep "ERROR" ~/.local/share/opencode/toolbox.log
+
+# Check for warnings
+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:35:00.456Z [INFO] BM25 search completed: "web search" -> 3 results
+```
+
+### Status Tool
+
+Use the `toolbox_status` command to check plugin health at any time:
+
+```
+toolbox_status({})
+```
+
+This shows:
+- **Plugin Status**: Initialization, config path, uptime, search/execution counts
+- **Server Status**: Connection ratio (e.g., "2/3"), details per server
+- **Tools**: Total available tools, servers with tools
+- **Health**: Overall health status (healthy/degraded/unknown)
+
+**Connection Ratio**: Shows `success/total` for servers. If `success < total`, it indicates failed connections.
+
 ## Troubleshooting
 
 ### Plugin not loading
 
-1. Check OpenCode logs for plugin errors
-2. Verify `opencode-toolbox` is in the `plugin` array in `opencode.jsonc`
-3. Ensure `toolbox.jsonc` exists and is valid JSON
+1. Run `toolbox_status({})` to check initialization status
+2. Check OpenCode logs at `~/.local/share/opencode/log/` for plugin errors
+3. Verify `opencode-toolbox` is in the `plugin` array in `opencode.jsonc`
+4. Ensure `toolbox.jsonc` exists and is valid JSON
 
 ### Search finds no tools
 
@@ -186,11 +322,21 @@ bun run build
 2. Check tool descriptions for relevant keywords
 3. Try broader search terms or regex patterns
 
+### MCP servers not connecting
+
+1. Run `toolbox_status({})` to see which servers failed
+2. Check logs for specific error messages from failed servers
+3. Verify server command works standalone: `npx -y @anthropic/mcp-time`
+4. For remote servers, verify URL is accessible
+5. Check environment variables are set correctly
+
 ### Execute fails
 
-1. Verify the tool name format: `serverName_toolName`
-2. Check `arguments` is valid JSON
-3. Ensure underlying MCP server is running
+1. Run `toolbox_status({})` to check server health
+2. Verify tool name 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
 
 ## License
 

package/dist/index.js

@@ -19266,6 +19266,9 @@ function tool(input) {
   return input;
 }
 tool.schema = exports_external;
+// src/plugin.ts
+import { appendFile, mkdir, writeFile, access } from "fs/promises";
+
 // node_modules/zod/v4/classic/external.js
 var exports_external2 = {};
 __export(exports_external2, {
@@ -37910,6 +37913,16 @@ function generateSignature(tool3) {
 }
 // src/plugin.ts
 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`;
+var COMMAND_DIR = `${process.env.HOME}/.config/opencode/command`;
+var COMMAND_FILE_PATH = `${COMMAND_DIR}/toolbox-status.md`;
+var COMMAND_CONTENT = `---
+description: Check toolbox plugin status and server health
+---
+Run toolbox_status({}) tool and show me the results in a readable format.
+Highlight any failed servers or issues.
+`;
 function parseToolName(fullName) {
   const underscoreIndex = fullName.indexOf("_");
   if (underscoreIndex === -1) {
@@ -37948,12 +37961,29 @@ 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.`;
+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.`;
+function log(level, message, extra) {
+  const timestamp = new Date().toISOString();
+  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(() => {});
+}
+function ensureCommandFile() {
+  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(() => {});
+  });
+}
 var SYSTEM_PROMPT_BASE = `# Extended Toolbox
 
 You have access to an extended toolbox with additional capabilities (web search, time utilities, code search, etc.).
 
 ## Rule
 ALWAYS search before saying "I cannot do that" or "I don't have access to."
+DO NOT try to execute a tool without having the tool's exact tool schema. If you don't have the tool's schema
+  then run toolbox_search_* to get them.
 
 ## Workflow
 1. Search: toolbox_search_bm25({ text: "what you need" }) or toolbox_search_regex({ pattern: "prefix_.*" })
@@ -37981,26 +38011,60 @@ ${JSON.stringify(toolboxSchema, null, 2)}
 \`\`\``;
 }
 var ToolboxPlugin = async (ctx) => {
+  const { client } = ctx;
   const configPath = process.env.OPENCODE_TOOLBOX_CONFIG || DEFAULT_CONFIG_PATH;
   const configResult = await loadConfig(configPath);
   if (!configResult.success) {
-    console.error("[Toolbox] Failed to load config:", configResult.error.issues);
+    const errorMsg = `Failed to load config from ${configPath}: ${configResult.error.issues.map((i) => i.message).join(", ")}`;
+    log("error", errorMsg);
     return {};
   }
   const config3 = configResult.data;
   const mcpManager = new MCPManager;
   const bm25Index = new BM25Index;
   let initialized = false;
+  let searchCount = 0;
+  let executionCount = 0;
+  let executionSuccessCount = 0;
+  ensureCommandFile();
+  const serverNames = Object.keys(config3.mcp);
+  log("info", `Toolbox plugin loaded successfully`, {
+    configPath,
+    serverCount: serverNames.length,
+    servers: serverNames
+  });
   async function ensureInitialized() {
     if (initialized)
       return;
     try {
+      log("info", "Initializing MCP servers...");
       await mcpManager.initialize(config3.mcp);
       const allTools = mcpManager.getAllCatalogTools();
       bm25Index.indexTools(allTools);
       initialized = true;
+      const servers = mcpManager.getAllServers();
+      const connectedServers = servers.filter((s) => s.status === "connected");
+      const failedServers = servers.filter((s) => s.status === "error");
+      const initMsg = `Initialization complete: ${connectedServers.length}/${servers.length} servers connected, ${allTools.length} tools indexed`;
+      log("info", initMsg, {
+        totalServers: servers.length,
+        connectedServers: connectedServers.length,
+        failedServers: failedServers.length,
+        totalTools: allTools.length,
+        servers: servers.map((s) => ({
+          name: s.name,
+          status: s.status,
+          toolCount: s.tools.length,
+          error: s.error || null
+        }))
+      });
+      if (failedServers.length > 0) {
+        const warnMsg = `${failedServers.length} server(s) failed to connect: ${failedServers.map((s) => s.name).join(", ")}`;
+        log("warn", warnMsg);
+      }
     } catch (error92) {
-      console.error("[Toolbox] Failed to initialize MCP servers:", error92);
+      const errorMsg = `Failed to initialize MCP servers: ${error92 instanceof Error ? error92.message : String(error92)}`;
+      log("error", errorMsg);
       throw error92;
     }
   }
@@ -38021,9 +38085,16 @@ var ToolboxPlugin = async (ctx) => {
               error: `Failed to initialize: ${error92 instanceof Error ? error92.message : String(error92)}`
             });
           }
+          searchCount++;
           const searchLimit = args.limit || config3.settings?.defaultLimit || 5;
           const allTools = mcpManager.getAllCatalogTools();
           const results = bm25Index.search(args.text, searchLimit);
+          log("info", `BM25 search completed: "${args.text}" -> ${results.length} results`, {
+            searchType: "bm25",
+            query: args.text,
+            resultsCount: results.length,
+            limit: searchLimit
+          });
           return formatSearchResults(results, allTools);
         }
       }),
@@ -38042,15 +38113,23 @@ var ToolboxPlugin = async (ctx) => {
               error: `Failed to initialize: ${error92 instanceof Error ? error92.message : String(error92)}`
             });
           }
+          searchCount++;
           const searchLimit = args.limit || config3.settings?.defaultLimit || 5;
           const allTools = mcpManager.getAllCatalogTools();
           const result = searchWithRegex(allTools, args.pattern, searchLimit);
           if ("error" in result) {
+            log("warn", `Regex search failed: "${args.pattern}" -> ${result.error}`);
             return JSON.stringify({
               success: false,
               error: result.error
             });
           }
+          log("info", `Regex search completed: "${args.pattern}" -> ${result.length} results`, {
+            searchType: "regex",
+            pattern: args.pattern,
+            resultsCount: result.length,
+            limit: searchLimit
+          });
           return formatSearchResults(result, allTools);
         }
       }),
@@ -38071,6 +38150,9 @@ var ToolboxPlugin = async (ctx) => {
           }
           const parsed = parseToolName(args.name);
           if (!parsed) {
+            log("warn", `Invalid tool name format: ${args.name}`, {
+              toolName: args.name
+            });
             return JSON.stringify({
               success: false,
               error: `Invalid tool name format: ${args.name}. Expected format: serverName_toolName (e.g., 'time_get_current_time')`
@@ -38081,25 +38163,106 @@ var ToolboxPlugin = async (ctx) => {
             try {
               toolArgs = JSON.parse(args.arguments);
             } catch (error92) {
+              log("warn", `Failed to parse arguments as JSON for ${args.name}`, {
+                toolName: args.name,
+                arguments: args.arguments
+              });
               return JSON.stringify({
                 success: false,
                 error: `Failed to parse arguments as JSON: ${error92 instanceof Error ? error92.message : String(error92)}`
               });
             }
           }
+          executionCount++;
           try {
+            const startTime = Date.now();
             const result = await mcpManager.callTool(parsed.serverName, parsed.toolName, toolArgs);
+            const duration5 = Date.now() - startTime;
+            executionSuccessCount++;
+            log("info", `Tool executed successfully: ${args.name}`, {
+              server: parsed.serverName,
+              tool: parsed.toolName,
+              durationMs: duration5
+            });
             return JSON.stringify({
               success: true,
               result
             });
           } catch (error92) {
+            const errorMsg = `Tool execution failed: ${error92 instanceof Error ? error92.message : String(error92)}`;
+            log("error", errorMsg, {
+              server: parsed.serverName,
+              tool: parsed.toolName,
+              error: errorMsg
+            });
             return JSON.stringify({
               success: false,
-              error: `Tool execution failed: ${error92 instanceof Error ? error92.message : String(error92)}`
+              error: errorMsg
             });
           }
         }
+      }),
+      toolbox_status: tool({
+        description: STATUS_DESC,
+        args: {},
+        async execute() {
+          if (!initialized) {
+            try {
+              await ensureInitialized();
+            } catch (error92) {
+              return JSON.stringify({
+                status: "error",
+                message: "Failed to initialize toolbox",
+                error: error92 instanceof Error ? error92.message : String(error92)
+              });
+            }
+          }
+          const servers = mcpManager.getAllServers();
+          const connectedServers = servers.filter((s) => s.status === "connected");
+          const failedServers = servers.filter((s) => s.status === "error");
+          const connectingServers = servers.filter((s) => s.status === "connecting");
+          const totalTools = mcpManager.getAllCatalogTools().length;
+          const status = {
+            plugin: {
+              initialized: true,
+              configPath,
+              uptime: process.uptime(),
+              searches: searchCount,
+              executions: executionCount,
+              successRate: executionCount > 0 ? `${Math.round(executionSuccessCount / executionCount * 100)}%` : "N/A"
+            },
+            servers: {
+              total: servers.length,
+              connected: connectedServers.length,
+              failed: failedServers.length,
+              connecting: connectingServers.length,
+              connectionRatio: `${connectedServers.length}/${servers.length}`,
+              details: servers.map((server) => ({
+                name: server.name,
+                status: server.status,
+                type: server.config.type,
+                toolCount: server.tools.length,
+                error: server.error || null,
+                healthy: server.status === "connected"
+              }))
+            },
+            tools: {
+              total: totalTools,
+              available: totalTools,
+              serversWithTools: servers.filter((s) => s.tools.length > 0).length
+            },
+            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`
+            }
+          };
+          log("info", `Status requested: ${connectedServers.length}/${servers.length} servers connected`, {
+            connectedServers: connectedServers.length,
+            totalServers: servers.length,
+            totalTools
+          });
+          return JSON.stringify(status, null, 2);
+        }
       })
     },
     "experimental.chat.system.transform": async (_input, output) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-toolbox",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Tool Search Tool Plugin for OpenCode - search and execute tools from MCP servers on-demand",
   "main": "dist/index.js",
   "module": "dist/index.js",