MCP Meta-Router (Tool Compass)

Discovery, inventory, smart routing, context-aware routing, and dynamic server management for MCP ecosystems.

Version: 0.4.0 | Status: MVP-3 Live | Tools: 12 | Tests: 152 passing

Tools

Tool	Phase	Description
list_available_servers	MVP-0	Overview of all configured servers with tool/prompt/resource counts
list_all_tools	MVP-0	Search across all tools by keyword
describe_server	MVP-0	Deep-dive into a specific server's full capabilities
refresh_discovery	MVP-0	Force re-discovery of all servers
recommend_tools	MVP-1	Ranked tool recommendations for a natural language task description
get_workflow	MVP-1	Multi-step workflow suggestions using tools across servers
update_context	MVP-2	Tell the router what you're working on (improves suggestions)
suggest_next_tool	MVP-2	Context-aware suggestion for what tool to use next
get_context	MVP-2	View current session context state
reload_server	MVP-3	Re-discover a single server without refreshing all
reload_config	MVP-3	Re-read .mcp.json and sync server list (picks up additions/removals)
get_server_health	MVP-3	Per-server health status and diagnostics

Quick Examples

# "What tools do I have?"
list_available_servers()

# "Find tools related to images"
list_all_tools(keyword="image")

# "What should I use to send a message to Nelly?"
recommend_tools(task_description="send a message to Nelly about the build results")

# "How do I create a video?"
get_workflow(task_description="create a video about machine learning trends")

# Context-aware routing (MVP-2)
update_context(task_summary="Building a video about AI trends")
suggest_next_tool(last_tool_used="define_story_beats")  # → generate_shot_list
get_context()  # → see current session state

# Dynamic server management (MVP-3)
reload_server(server_name="agent-comm")   # → refresh one server
reload_config()                            # → pick up .mcp.json changes
get_server_health()                        # → per-server status report

Architecture

• Advisor-only — discovers but does NOT proxy tool calls
• Lazy discovery — servers discovered on first call, cached after
• Zero runtime deps — smart routing uses pure Python keyword scoring (no ML libs)
• WSL-aware — auto-translates wsl launch commands when running inside WSL
• Session context — tracks current task and tools used for smarter suggestions
• Dynamic reload — single-server refresh and config hot-reload without restart

Roadmap

Phase	Name	Status
MVP-0	Discovery & Inventory	Done
MVP-1	Smart Routing	Done
MVP-2	Context-Aware Routing	Done
MVP-3	Dynamic Tool Loading	Done

Setup

cd mcp-router

# Create a virtual environment and install
uv venv .venv --python 3.12
uv pip install -e "." --python .venv/bin/python
uv pip install -e ".[dev]" --python .venv/bin/python

WSL note: For best performance on WSL, place the venv on native Linux filesystem (/home/...) rather than /mnt/d/. Pydantic model compilation is 5-6x faster on native fs.

.mcp.json entry

"mcp-router": {
  "command": "bash",
  "args": ["-c", "cd /path/to/mcp-router && .venv/bin/python -m src.server"]
}

Configuration

export MCP_ROUTER_CONFIG="/path/to/.mcp.json"

Defaults to the calling project's .mcp.json. Override via env var MCP_ROUTER_CONFIG.

Known Issue: WSL Filesystem Performance

mcp 1.26.0 + fastmcp 3.1.0 have heavy pydantic model compilation at import time. On /mnt/d/ (Windows FS via WSL) this takes 12-18 seconds, exceeding MCP connection timeouts.

Fix: Always use a venv on native Linux filesystem (/home/...). Import drops to 2-3 seconds.

Template Libraries

The templates/ directory contains configurable JSON files that power the router's intelligence:

• templates/scoring/ — Keyword weights, stopwords, synonyms, and category definitions for tool ranking
• templates/workflows/ — Workflow patterns and tool succession maps for get_workflow and suggest_next_tool
• templates/config/ — MCP server config and pyproject.toml templates
• templates/testing/ — Test fixtures and mock server definitions for the test suite

See templates/README.md for full details on customizing these templates.

Run & Test

.venv/bin/python -m src.server                    # Run server
.venv/bin/python -m pytest tests/ -v              # Run tests (152 passing)

Documentation

Full guide with examples, scoring weights, workflow patterns, and troubleshooting: docs/GUIDE.md

Showcase

See the switchcore showcase site for demos and interactive documentation.

License

MIT - see LICENSE