How baharul0111/toolrouter works
ToolRouter is a local AI assistant that discovers MCP tools, indexes their descriptions, retrieves a small task-specific set, and lets a local LLM call those tools. The main request path runs through the API and service into the agent loop; the loop retrieves tools, validates and gates proposed calls, dispatches approved calls through MCP, then can search again between steps. The README documents gateway mode, a web UI, and optional Phoenix tracing. Some subsystem wiring is based on README documentation because those source excerpts were not sampled.
Main entry points: loop.py Agent loop · service.py Service coordinator · pipeline.py Retrieval pipeline · main.py HTTP API
Components 25
User interfaces
- Web UI
ui/app.py - HTTP API
toolrouter/api/main.py - MCP gateway
toolrouter/gateway.py
Assistant runtime
- Service coordinator
toolrouter/service.py - Agent loop
toolrouter/agent/loop.py - Prompt builder
toolrouter/agent/prompt.py - Input validator
toolrouter/agent/validator.py - Safety checks
toolrouter/agent/safety.py - Run and cache store
toolrouter/db.py
Tool catalog
- Tool registry
toolrouter/registry/sync.py - Tool enrichment
toolrouter/indexing/enrich.py - Index builder
toolrouter/indexing/build_index.py - Tool pair graph
toolrouter/indexing/buddy_graph.py
Tool retrieval
- Retrieval pipeline
toolrouter/retrieval/pipeline.py - Semantic search
toolrouter/retrieval/dense.py - Keyword search
toolrouter/retrieval/bm25.py - Rank fusion
toolrouter/retrieval/fusion.py - Candidate reranker
toolrouter/retrieval/reranker.py - Adaptive selector
toolrouter/retrieval/selector.py
Models and tools
- MCP client pool
toolrouter/mcp_client/pool.py - MCP tool servers
servers - Ollama LLM
- Qdrant index
- Phoenix tracing
Other components
- User
Connections 31
- User → Web UI: submits request
- Web UI → HTTP API: sends requests
- HTTP API → Service coordinator: uses service
- HTTP API → Agent loop: runs and resumes
- HTTP API → Run and cache store: reads run history
- Service coordinator → MCP client pool: starts and lists tools
- Service coordinator → Tool registry: syncs listings
- Service coordinator → Index builder: builds index
- Service coordinator → Agent loop: creates agent
- Service coordinator → Run and cache store: creates store
- Service coordinator → Phoenix tracing: configures tracing
- Tool registry → Tool enrichment: enriches cards
- Tool registry → Run and cache store: caches enrichment
- Index builder → Retrieval pipeline: populates index
- Retrieval pipeline → Semantic search: runs semantic search
- Retrieval pipeline → Keyword search: runs keyword search
- Retrieval pipeline → Rank fusion: merges rankings
- Retrieval pipeline → Candidate reranker: rescores candidates
- Retrieval pipeline → Adaptive selector: selects tools
- Retrieval pipeline → Tool pair graph: adds paired tools
- Semantic search → Qdrant index: searches vectors
- Agent loop → Retrieval pipeline: searches per step
- Agent loop → Prompt builder: builds prompt
- Agent loop → Ollama LLM: requests responses
- Agent loop → Input validator: checks arguments
- Agent loop → Safety checks: checks risky calls
- Agent loop → MCP client pool: calls approved tools
- Agent loop → Run and cache store: records runs
- MCP client pool → MCP tool servers: lists and calls tools
- MCP gateway → Service coordinator: uses service
- MCP gateway → User: serves MCP clients