opencode-toolbox 0.3.1 → 0.5.0

package/README.md

@@ -30,7 +30,7 @@ Create `~/.config/opencode/toolbox.jsonc`:
 
 ```jsonc
 {
-  "servers": {
+  "mcp": {
     "time": {
       "type": "local",
       "command": ["npx", "-y", "@anthropic/mcp-time"]
@@ -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,89 @@ 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 and maintains a `/toolbox-status` slash command:
+
+```
+~/.config/opencode/command/toolbox-status.md
+```
+
+- **Auto-created** on first plugin launch
+- **Auto-updated** when plugin version changes (tracked via `toolbox_version` in frontmatter)
+
+Use it in OpenCode by typing `/toolbox-status` to get a formatted status report.
+
 ## Search Modes
 
 ### BM25 (Natural Language)
@@ -172,13 +255,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 +325,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, readFile } from "fs/promises";
+
 // node_modules/zod/v4/classic/external.js
 var exports_external2 = {};
 __export(exports_external2, {
@@ -32817,7 +32820,7 @@ var SettingsConfigSchema = exports_external2.object({
   defaultLimit: exports_external2.number().min(1).max(20).default(5)
 });
 var ConfigSchema = exports_external2.object({
-  servers: exports_external2.record(exports_external2.string(), ServerConfigSchema),
+  mcp: exports_external2.record(exports_external2.string(), ServerConfigSchema),
   settings: SettingsConfigSchema.optional()
 });
 // node_modules/jsonc-parser/lib/esm/impl/scanner.js
@@ -37908,8 +37911,69 @@ function generateSignature(tool3) {
   }).join(", ");
   return `${tool3.id.name}(${argList})`;
 }
+// package.json
+var package_default = {
+  name: "opencode-toolbox",
+  version: "0.5.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",
+  type: "module",
+  exports: {
+    ".": {
+      import: "./dist/index.js",
+      types: "./dist/index.d.ts"
+    }
+  },
+  scripts: {
+    build: "bun build src/index.ts --outdir dist --target bun",
+    dev: "bun --hot src/index.ts",
+    test: "bun test",
+    "test:coverage": "bun test --coverage",
+    typecheck: "tsc --noEmit"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  keywords: [
+    "opencode",
+    "plugin",
+    "tool-search",
+    "mcp"
+  ],
+  license: "MIT",
+  devDependencies: {
+    "@types/bun": "latest",
+    typescript: "^5.9.3"
+  },
+  peerDependencies: {
+    typescript: "^5"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@opencode-ai/plugin": "latest",
+    "jsonc-parser": "^3.3.1",
+    zod: "^4.3.5"
+  }
+};
+
 // src/plugin.ts
+var PLUGIN_VERSION = package_default.version;
 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`;
+function getCommandContent() {
+  return `---
+description: Check toolbox plugin status and server health
+toolbox_version: ${PLUGIN_VERSION}
+---
+Run toolbox_status({}) 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,14 +38012,38 @@ 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() {
+  const content = getCommandContent();
+  readFile(COMMAND_FILE_PATH, "utf-8").then((existing) => {
+    const versionMatch = existing.match(/toolbox_version:\s*([^\n]+)/);
+    const existingVersion = versionMatch?.[1]?.trim() ?? null;
+    if (existingVersion !== PLUGIN_VERSION) {
+      return writeFile(COMMAND_FILE_PATH, content).then(() => {
+        log("info", `Updated /toolbox-status command (${existingVersion} -> ${PLUGIN_VERSION})`);
+      });
+    }
+  }).catch(() => {
+    mkdir(COMMAND_DIR, { recursive: true }).then(() => writeFile(COMMAND_FILE_PATH, content)).then(() => log("info", `Created /toolbox-status command (v${PLUGIN_VERSION})`)).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
+## 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_.*" })
@@ -37965,43 +38053,78 @@ function generateSystemPrompt(mcpManager) {
   if (servers.length === 0) {
     return SYSTEM_PROMPT_BASE;
   }
-  const serverLines = [];
+  const toolboxSchema = {};
   for (const server of servers) {
     if (server.status === "connected" && server.tools.length > 0) {
-      const toolNames = server.tools.map((t) => t.id.name).join(", ");
-      serverLines.push(`- ${server.name}: ${toolNames}`);
+      toolboxSchema[server.name] = server.tools.map((t) => t.idString);
     }
   }
-  if (serverLines.length === 0) {
+  if (Object.keys(toolboxSchema).length === 0) {
     return SYSTEM_PROMPT_BASE;
   }
   return `${SYSTEM_PROMPT_BASE}
 
-## Registered MCP Servers
-${serverLines.join(`
-`)}`;
+## Toolbox Schema
+Tool names use \`<server>_<tool>\` format. Pass exact names to toolbox_execute().
+\`\`\`json
+${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 {
-      await mcpManager.initialize(config3.servers);
+      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;
     }
   }
@@ -38022,9 +38145,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);
         }
       }),
@@ -38043,15 +38173,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);
         }
       }),
@@ -38072,6 +38210,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')`
@@ -38082,25 +38223,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.3.1",
+  "version": "0.5.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",