opencode-mcp-tool-search

A dynamic MCP tool search plugin for OpenCode that reduces context usage by loading tools on-demand.

The Problem

When you have many MCP servers configured, each with multiple tools, the tool definitions can consume a significant portion of your context window:

• 50+ MCP tools can use ~67k tokens just for tool definitions
• This leaves less context for your actual conversation and code

The Solution

This plugin implements a search-based meta-tool pattern:

1. Instead of loading all tools upfront, provides a single mcp_tool_search meta-tool
2. Search for tools by name, description, or server
3. Call tools directly via mcp_call_tool

User: "What's the weather in NYC?"
    |
    v
OpenCode decides: need a weather tool
    |
    v
Calls: mcp_tool_search({ query: "weather" })
    |
    v
Search returns: [{ name: "get_weather", server: "weather-api", ... }]
    |
    v
Calls: mcp_call_tool({ server: "weather-api", tool: "get_weather", args: { location: "NYC" } })

Token Savings

Requirements

• OpenCode v1.0.0 or later
• Node.js 18+ or Bun 1.0+

Installation

npm install opencode-mcp-tool-search

Then add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-mcp-tool-search"]
}

Important: When using this plugin, you must remove all mcpServers from your opencode.json. This plugin takes over MCP server management - configure your servers in the plugin instead (see Quick Start below).

Quick Start

1. Remove MCP Servers from OpenCode Config

Important: This plugin manages MCP server connections directly. You must remove any mcpServers from your opencode.json to avoid duplicate connections and conflicts.

Before (remove this):

{
  "$schema": "https://opencode.ai/config.json",
  "mcpServers": {
    "github": { ... },
    "filesystem": { ... }
  }
}

After:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-mcp-tool-search"]
}

2. Configure MCP Servers in the Plugin

Create a plugin configuration file and move your MCP server configs here:

// .opencode/plugin/mcp-search.ts
import { createMCPToolSearchPlugin } from "opencode-mcp-tool-search";

export const MCPToolSearch = createMCPToolSearchPlugin({
  mcpServers: [
    {
      name: "github",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
    },
    {
      name: "filesystem",
      command: "npx",
      args: [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir",
      ],
    },
  ],
});

3. Use the Tools

Once configured, OpenCode can search and call MCP tools:

# Search for tools
mcp_tool_search({ query: "github pull request" })

# Call a tool
mcp_call_tool({ server: "github", tool: "create_pull_request", args: { ... } })

# List all servers
mcp_tool_search({ list_servers: true })

Available Tools

mcp_tool_search

Search for MCP tools by query.

Examples:

// Search by keyword
mcp_tool_search({ query: "weather" });

// Filter by server
mcp_tool_search({ query: "pull request", server: "github" });

// List all servers
mcp_tool_search({ list_servers: true });

mcp_call_tool

Call an MCP tool on a specific server.

Example:

mcp_call_tool({
  server: "github",
  tool: "create_issue",
  args: {
    owner: "myorg",
    repo: "myrepo",
    title: "Bug report",
    body: "Description of the issue",
  },
});

mcp_tool_info

Get detailed information about a specific tool, including its full JSON schema.

Example:

mcp_tool_info({ tool_name: "create_pull_request" });

mcp_tool_search_status

Check plugin and server connection status.

Example:

mcp_tool_search_status();
// Returns: server count, connection status, tool count, any errors

Configuration

Full Configuration Example

// .opencode/plugin/mcp-search.ts
import { createMCPToolSearchPlugin } from "opencode-mcp-tool-search";

export const MCPToolSearch = createMCPToolSearchPlugin({
  // MCP servers to connect to
  mcpServers: [
    {
      name: "my-server",
      command: "node",
      args: ["./my-mcp-server.js"],
      env: { API_KEY: process.env.API_KEY },
      cwd: "/path/to/server",
      instructions: "This server provides weather and calendar tools",
      timeout: 30000, // Connection timeout in ms
    },
  ],

  // Search configuration
  maxResults: 10, // Maximum results to return (default: 10)
  fuzzyMatch: true, // Enable fuzzy matching for typos (default: true)
  minScore: 0.1, // Minimum match score 0-1 (default: 0.1)
  searchInstructions: true, // Search server instructions too (default: true)
});

Configuration Options

MCP Server Configuration

How Search Works

The search uses Fuse.js for fuzzy matching with weighted fields:

Search features:

• Fuzzy matching handles typos (e.g., "gihub" matches "github")
• Extended search syntax for advanced queries
• Results sorted by relevance score

Architecture

+----------------------------------------------------------+
|                      OpenCode                             |
+----------------------------------------------------------+
|  Plugin: opencode-mcp-tool-search                        |
|  +----------------------------------------------------+  |
|  |  State                                             |  |
|  |  - servers: Map<name, MCPServer>                   |  |
|  |  - allTools: MCPTool[]                             |  |
|  +----------------------------------------------------+  |
|                          |                                |
|  +----------------------------------------------------+  |
|  |              Tools (exposed to OpenCode)              |  |
|  |  - mcp_tool_search     (search tools)             |  |
|  |  - mcp_call_tool       (execute tools)            |  |
|  |  - mcp_tool_info       (inspect tools)            |  |
|  |  - mcp_tool_search_status (check status)          |  |
|  +----------------------------------------------------+  |
|                          |                                |
|  +----------------------------------------------------+  |
|  |              MCP Client                             |  |
|  |  - Stdio transport to MCP servers                  |  |
|  |  - Parallel server connections                     |  |
|  |  - Tool listing and execution                      |  |
|  +----------------------------------------------------+  |
+----------------------------------------------------------+
              |                    |                    |
        +-----+----+        +------+-----+       +------+-----+
        | MCP      |        | MCP        |       | MCP        |
        | Server 1 |        | Server 2   |       | Server N   |
        +----------+        +------------+       +------------+

Benefits

• Massive Token Savings: ~99% reduction in tool token usage
• No Protocol Changes: Works with standard MCP servers
• Transparent: MCP servers don't need any modifications
• Better Discovery: Search helps find the right tool faster
• Parallel Connections: Connects to all servers simultaneously

Tradeoffs

• Extra step to search before calling tools
• Requires good search queries to find the right tools
• Server instructions improve discoverability

Development

# Clone the repository
git clone https://github.com/francisco-m001/opencode-mcp-tool-search.git
cd opencode-mcp-tool-search

# Install dependencies
npm install
# or
bun install

# Build
npm run build
# or
bun run build

# Watch mode for development
npm run dev
# or
bun run dev

Project Structure

opencode-mcp-tool-search/
├── src/
│   ├── index.ts       # Plugin entry point and tool definitions
│   ├── search.ts      # Fuse.js search implementation
│   ├── mcp-client.ts  # MCP SDK client wrapper
│   ├── types.ts       # TypeScript interfaces
│   └── utils.ts       # Helper functions
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Related Projects

• OpenCode - AI-powered coding assistant
• Model Context Protocol - The MCP specification
• @modelcontextprotocol/sdk - Official MCP TypeScript SDK

License

MIT License - see LICENSE for details.