Search Toolkit

Official-first web tools for AI agents, with persistent multi-key rotation and three entry points: MCP, CLI, and Agent Skills.

简体中文

Design

Search Toolkit preserves provider-specific capabilities instead of flattening every backend into one generic search endpoint.

• Official Remote MCP proxy: Exa, Tavily, and LinkUp.

• Official STDIO MCP proxy: Firecrawl.

• Thin official-API adapters: Querit, Serper, Brave, Jina Search, TinyFish Search, Doubao Search, and xAI Responses Web/X Search.

• Persistent per-provider key pools backed by SQLite.

• Provider-prefixed upstream tool names and schemas are discovered from official MCP servers at startup, then filtered by an optional provider tool policy.

• Raw keys stay outside the repository in a local JSON file.

Official references used by the implementation include the Codex MCP configuration guide, MCP TypeScript SDK, Exa MCP, Tavily MCP, LinkUp MCP, and Firecrawl MCP.

Provider capabilities

Install

git clone https://github.com/TheWiseWolfHolo/search-toolkit E:/Script/Services/search-toolkit
cd E:/Script/Services/search-toolkit
npm install
npm run build

Node.js 22 or newer is required. Node.js 24 is recommended because the persistent rotation store uses the built-in node:sqlite module.

Configure

Copy config.example.json to a private path outside the repository and replace placeholder keys:

$env:SEARCH_TOOLKIT_CONFIG = "$HOME/.config/search-toolkit/providers.json"

The local one-time importer can migrate configured Kelivo search keys into the standalone text config:

npm run import:kelivo

The importer reads Kelivo once and writes %USERPROFILE%/.config/search-toolkit/providers.json on Windows. This avoids MSIX AppData/Local virtualization, so Codex, Claude Code, and ordinary CLI processes read the same physical file. Runtime MCP and CLI processes never access Kelivo.

CLI

node dist/src/cli.js tools
node dist/src/cli.js status
node dist/src/cli.js call querit_search '{"query":"latest AI agent news","limit":5}'
node dist/src/cli.js probe querit "Search Toolkit rotation probe"

MCP

Build first, then add the local STDIO server to Codex:

[mcp_servers.searchToolkit]
command = "C:/path/to/node.exe"
args = ["E:/Script/Services/search-toolkit/dist/src/mcp-server.js", "--config", "C:/Users/you/.config/search-toolkit/providers.json"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true
default_tools_approval_mode = "writes"

The MCP server exposes:

• Provider-prefixed official upstream tools selected by the provider's tool policy. Firecrawl defaults to seven focused retrieval/acquisition tools instead of its entire management catalog.

• Every configured REST adapter tool.

• search_auto for capability-aware default routing with auditable {provider, tool, upstreamTool} metadata.

• search_pool_status for masked key-pool diagnostics.

• search_rotation_probe for a live, quota-consuming rotation proof.

Set toolPolicy.allow to ["*"] for a provider only when exposing its full upstream catalog is intentional. Write and destructive tools retain corrected annotations so clients can request approval.

Key rotation

Each request selects one key from the relevant provider pool. The cursor persists across process restarts and is coordinated across concurrent agent processes through SQLite.

• 200: advance normally.

• 429 or 402: cool down the current key.

• 401 or 403: disable the current key.

• 5xx or network failure: retry once with the next key.

• 400, 404, or 422: preserve the request error without blaming another key.

providers.json, raw keys, and rotation state are ignored by Git. Command output and MCP metadata show only masked key slots.

Skill

The reusable skill is under skills/search-toolkit/. Copy or link it into your agent's skill directory. It routes normal research directly to Search Toolkit and keeps deep-research orchestration for genuinely multi-stage work.

Development

npm test
npm run smoke:mcp
npm pack --dry-run

License

MIT