Toolrator

The local-first discovery layer for AI agents.
@toolrator/toolconnector runs on your machine and bridges a stdio MCP client to search backends and external servers. Requests go to the endpoints you choose.

Current interface: Toolconnector 0.4.1 exposes three tools and OAuth login. Toolpanel 0.3.0 provides local configuration without the legacy device flow.

---

---

🚀 Highlights

🧠 MCP 2026-07-28 (official)	Built on the stateless protocol revision — SEP-2575, MRTR, Tasks extension, Streamable HTTP
🔌 Local MCP Bridge	Connect a stdio MCP client to remote servers and configured search engines
🔍 Typo-Tolerant Search	MeiliSearch + ONNX hybrid vector search for finding MCP servers and tools
🏠 Self-Hostable	Run Toolpanel + Toolhub locally; remote servers still need network access
📋 3-Tool Surface	Search, inspect/execute, and authentication
🔄 Auto-Fallback	Works with both 2026-07-28 and legacy 2025-11-25 servers

---

📋 Overview

This repository publishes the open-source client and discovery infrastructure for the Model Context Protocol. Three packages, one ecosystem:

🔐 Authentication: The default upstream is https://toolrator.org, with OAuth login and search configuration. Local Toolpanel provides configuration and accepts a non-empty machine credential; it does not implement an OAuth authorization server. Bind it only to loopback.

Package	Type	Run	Description
🔌 toolconnector	NPM CLI & Library	npx -y @toolrator/toolconnector	Local stdio MCP bridge — connects AI agents to search backends and external MCP servers
🛠️ toolpanel	NPM CLI & Package	npx -y @toolrator/toolpanel	Local control panel — search-engine config and admin UI; no authentication
🔍 toolhub	Server Package	npm run dev	Typo-tolerant + hybrid vector search engine — MeiliSearch or in-memory backend

---

📦 Packages

🔌 @toolrator/toolconnector

The universal MCP adapter. A stdio server that exposes 3 unified tools to any MCP-compatible AI client:

Tool	Purpose	Key Parameters
search_mcp_ecosystem	Search registry for tools, resources, prompts	engine, arguments
mcp_server	Generic JSON-RPC passthrough to any external MCP (list, call, fetch, tasks)	target, method, params
manage_auth	OAuth login, status, and logout	action, target, redirect_url
—	MRTR support, Tasks extension, Pluggable search engines

🛠️ @toolrator/toolpanel

Local control panel for toolconnector and toolhub. Configure search engines and manage your own index. No built-in authentication; keep it on loopback.

Feature	Endpoint	Description
Landing page	/	Status-aware cards for toolconnector & toolhub
Connector config	/panel/toolconnector	CRUD for search-engines.json
Public search	/panel/search	Queries toolhub with faceted filters
Search admin	/panel/search/admin	Index / edit / delete MCP servers

🔍 @toolrator/toolhub

High-performance search engine with typo tolerance, faceted filtering, and hybrid vector search.

• Two backends: MeiliSearch (production) or in-memory (dev)
• ONNX embeddings: Xenova/multilingual-e5-small — 384-dim local vector search
• Tool-level matching: toolHits extracted from capabilities.tools
• LRU caching: Search results (60s) and query embeddings (1h)

---

🏗️ Architecture

graph TB
    subgraph Client["💻 Client Machine"]
        Agent["🤖 AI Agent / IDE<br/>Claude · Cursor · Custom"]
        style Agent fill:#1a1a2e,stroke:#7c3aed,stroke-width:2px,color:#fff
        Agent <-->|stdio JSON-RPC| TC["🔌 @toolrator/toolconnector"]
        style TC fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
    end

    subgraph SelfHosted["🏠 Self-Hosted"]
        TC <-->|HTTP / Auto-Discovery| TP["🛠️ @toolrator/toolpanel"]
        style TP fill:#1a1a2e,stroke:#e94560,stroke-width:2px,color:#fff
        TP <-->|Proxy Search| SE["🔍 @toolrator/toolhub"]
        style SE fill:#16213e,stroke:#e94560,stroke-width:2px,color:#fff
        SE <-->|Vector + Lexical| Meili["📦 MeiliSearch / Memory"]
        style Meili fill:#0f3460,stroke:#533483,stroke-width:2px,color:#fff
    end

    subgraph External["🌐 External"]
        TC <-->|Streamable HTTP / SSE| M1["MCP Server A"]
        TC <-->|Streamable HTTP| M2["MCP Server B"]
        TC <-->|Streamable HTTP| M3["MCP Server C"]
    end

---

⚡ Quick Start

Connect an AI client

Add this to your MCP client configuration (Node.js ≥20):

{
  "mcpServers": {
    "toolconnector": {
      "command": "npx",
      "args": ["-y", "@toolrator/toolconnector@0.4.1"]
    }
  }
}

Restart the client, then ask it to run manage_auth with action: "start_oauth" and show the verification URL. After approving login, ask it to search the configured catalog. Results depend on the servers listed by that search engine.

Server developers: see the publication guide to list an existing reachable MCP endpoint.

🐳 Optional: Run the search stack locally

Requires Node.js ≥22.9 for Toolpanel and the Toolhub development scripts. Clone https://github.com/toolrator/Toolrator.git first; use separate terminals for the services.

cd packages/toolhub
npm install
SEARCH_BACKEND=memory npm run dev
# → http://127.0.0.1:7600

npx -y @toolrator/toolpanel@0.3.0
# → http://127.0.0.1:7800

Add to your MCP client config:

{
  "mcpServers": {
    "toolconnector": {
      "command": "npx",
      "args": ["-y", "@toolrator/toolconnector@0.4.1"],
      "env": {
        "TOOLPANEL_URL": "http://127.0.0.1:7800",
        "CONNECTOR_SEARCH_CONFIG_MODE": "toolpanel",
        "CONNECTOR_API_KEY": "toolpanel-local"
      }
    }
  }
}

💡 Local configuration: In the MCP client's env block, set TOOLPANEL_URL=http://127.0.0.1:7800, CONNECTOR_SEARCH_CONFIG_MODE=toolpanel, and CONNECTOR_API_KEY=toolpanel-local. Toolpanel accepts any non-empty credential. An empty local index returns no servers; populate your own index through the panel. Remote MCP endpoints still require network access.

---

✅ Protocol Compliance

The Toolrator OSS stack is built against MCP 2026-07-28 — the official stable revision of the Model Context Protocol (released 2026-07-28). The matrix below tracks what is implemented and tested; deferred and not-applicable rows are marked as such.

Feature	SEP	Status	Detail
Stateless protocol (no initialize)	SEP-2575	✅	Per-request _meta carries protocolVersion, clientCapabilities
server/discover RPC	SEP-2575	✅	Auto-probed on every connection
Streamable HTTP transport	SEP-2243	✅	Primary transport; SSE fallback for legacy
Multi Round-Trip Requests	SEP-2322	✅	input_required / inputResponses / requestState
Tasks extension	SEP-2663	✅	tasks/get, tasks/update, tasks/cancel
CacheableResult (ttlMs/cacheScope)	SEP-2549	✅	Client-side caching on tools/list, resources/list, prompts/list
JSON Schema 2020-12	SEP-2106	✅	Default dialect; outputSchema on tool definitions
Error codes -32020/-32021/-32022	—	✅	Classified by classifyUpstreamError()
x402 payments	SEP-2009	⏳	Deferred — awaiting spec stabilization
OpenTelemetry tracing	SEP-414	➖	N/A (optional)

See packages/toolconnector/MCP-FEATURES.md for the complete 185-line matrix covering all 13 feature areas — base protocol, transport, state management, caching, MRTR, Tasks, error codes, auth, schema, subscriptions, deprecated features, SDK migration, and payments roadmap.

Servers running 2025-11-25 are handled automatically. The SDK's versionNegotiation: { mode: 'auto' } probes via server/discover first; if the server doesn't support the 2026-07-28 revision, it falls back to the initialize handshake transparently.

---

⚙️ Configuration

Variable	Default	Purpose
CONNECTOR_API_KEY	—	Pre-configured machine credential
CONNECTOR_CONFIG_DIR	OS default	Credentials, search-engines
CONNECTOR_UPSTREAM_URL	https://toolrator.org	Auth endpoint base URL
TOOLPANEL_URL	http://127.0.0.1:7800	Self-hosted control panel URL
TOOLPANEL_DISCOVERY	auto	Probe toolpanel at boot
CONNECTOR_SEARCH_CONFIG_MODE	auto	Engine resolution strategy
CONNECTOR_LOG_LEVEL	info	Log verbosity

OS	Config Directory
Windows	%APPDATA%\toolconnector\
macOS	~/Library/Application Support/toolconnector/
Linux	$XDG_CONFIG_HOME/toolconnector/ or ~/.config/toolconnector/

---

❓ FAQ

---

🤝 Contributing

We welcome contributions from humans and AI agents alike.

Step	Action
1	Clone the repo and cd packages/<package>
2	npm install
3	Make your changes
4	Run tests: npm test (Node.js built-in node --test, no Jest/Vitest)
5	Typecheck: npm run typecheck
6	Open a PR against main

• Docs: CONTRIBUTING.md · CODE_OF_CONDUCT.md
• Issues: GitHub Issues
• Security: security@toolrator.org

---

📄 License

Apache 2.0 · open infrastructure · no lock-in