Tool Compass
mcp-tool-shop-org/tool-compass
Descubra ferramentas MCP por intenção com busca semântica
Ver no GitHubGateway semântico de descoberta de ferramentas MCP que encontra tools por intenção, não por memória. Usa busca semântica para retornar apenas as ferramentas relevantes, economizando 95% de tokens de contexto. Funciona como servidor MCP, CLI ou interface Gradio.
Instalação
npx convez-ai mcp-tool-shop-org/tool-compass1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Reduzir consumo de tokens ao descobrir tools relevantes
- Integrar descoberta inteligente de ferramentas em agentes MCP
- Navegar ecossistemas com muitas ferramentas disponíveis
Veredito

Solução pragmática para um problema real em sistemas MCP: economia drástica de tokens através de discovery semântico. Bem documentado, multi-plataforma e produção-ready com observabilidade nativa.
README
A tradução para o português deste README ainda está na fila.
Semantic navigator for MCP tools - Find the right tool by intent, not memory
95% fewer tokens. Find tools by describing what you want to do.
Installation • Usage • Docker • Handbook • Performance • Contributing
The Problem
MCP servers expose dozens or hundreds of tools. Loading all tool definitions into context wastes tokens and slows down responses.
Before: 77 tools × ~500 tokens = 38,500 tokens per request
After: 1 compass tool + 3 results = ~2,000 tokens per request
Savings: 95%
The Solution
Tool Compass uses semantic search to find relevant tools from a natural language description. Instead of loading all tools, Claude calls compass() with an intent and gets back only the relevant tools.
Quick Start
📖 Full documentation: See the Tool Compass Handbook for installation, configuration, and architecture deep-dives.
Option 1: npm (zero-prerequisite, no Python install)
npx @mcptoolshop/tool-compass --help
npx @mcptoolshop/tool-compass serve # MCP gateway
npx @mcptoolshop/tool-compass ui # Gradio UI
npx @mcptoolshop/tool-compass doctor # Diagnose setup
Downloads a verified platform binary on first run (SHA256-checked against the GitHub Release). Cached locally — subsequent invocations launch instantly. See @mcptoolshop/tool-compass on npm.
Option 2: PyPI
pip install tool-compass
tool-compass --help
Option 3: Local clone
# Prerequisites: Ollama with nomic-embed-text
ollama pull nomic-embed-text
# Clone and setup
git clone https://github.com/mcp-tool-shop-org/tool-compass.git
cd tool-compass
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Build the search index
tool-compass sync
# Run the MCP server
tool-compass serve
# Or launch the Gradio UI
tool-compass ui
Option 4: Docker
# Clone the repo
git clone https://github.com/mcp-tool-shop-org/tool-compass.git
cd tool-compass
# Start with Docker Compose (requires Ollama running locally)
docker-compose up
# Or include Ollama in the stack
docker-compose --profile with-ollama up
# Access the UI at http://localhost:7860
The GHCR image (
ghcr.io/mcp-tool-shop-org/tool-compass) supportslinux/amd64andlinux/arm64, so the same tag runs on x86_64 servers and Apple Silicon / ARM workstations.
Features
- Semantic Search - Find tools by describing what you want to do
- Progressive Disclosure -
compass()→describe()→execute() - Hot Cache - Frequently used tools are pre-loaded
- Chain Detection - Automatically discovers common tool workflows
- Analytics - Track usage patterns and tool performance
- Cross-Platform - Windows, macOS, Linux
- Docker Ready - One-command deployment
Architecture
┌─────────────────────────────────────────────────────────────┐
│ TOOL COMPASS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Ollama │ │ hnswlib │ │ SQLite │ │
│ │ Embedder │───▶│ HNSW │◀───│ Metadata │ │
│ │ (nomic) │ │ Index │ │ Store │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Gateway (9 tools)│ │
│ │ compass, describe│ │
│ │ execute, etc. │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Usage
The compass() Tool
compass(
intent="I need to generate an AI image from a text description",
top_k=3,
category=None, # Optional: "file", "git", "database", "ai", etc.
min_confidence=0.3
)
Returns:
{
"matches": [
{
"tool": "comfy:comfy_generate",
"description": "Generate image from text prompt using AI",
"category": "ai",
"confidence": 0.912
}
],
"total_indexed": 44,
"tokens_saved": 20500,
"hint": "Found: comfy:comfy_generate. Use describe() for full schema."
}
Available Tools
| Tool | Description |
|---|---|
compass(intent) | Semantic search for tools |
describe(tool_name) | Get full schema for a tool |
execute(tool_name, args) | Run a tool on its backend |
compass_categories() | List categories and servers |
compass_status() | System health and config |
compass_analytics(timeframe) | Usage statistics |
compass_chains(action) | Manage tool workflows |
compass_sync(force) | Rebuild index from backends |
compass_audit() | Full system report |
Progressive Disclosure Pattern
Tool Compass uses a three-step progressive disclosure pattern to minimize token usage:
1. compass("your intent") → Get tool name + short description (~100 tokens)
2. describe("tool:name") → Get full parameter schema (~500 tokens)
3. execute("tool:name", args) → Run the tool
Why this matters:
- Loading 77 tools upfront = ~38,500 tokens
- Progressive disclosure = ~600 tokens per tool used
- Savings: 95%+ for typical workflows
Example workflow:
# Step 1: Find the right tool
compass("generate an image from text")
# Returns: comfy:comfy_generate (confidence: 0.91)
# Step 2: Get the schema (only if needed)
describe("comfy:comfy_generate")
# Returns: Full parameter definitions, types, examples
# Step 3: Execute
execute("comfy:comfy_generate", {"prompt": "a sunset over mountains"})
The hint field in compass results guides this flow, suggesting when to use describe().
Configuration
| Variable | Description | Default |
|---|---|---|
TOOL_COMPASS_BASE_PATH | Project root | Auto-detected |
TOOL_COMPASS_PYTHON | Python executable | Auto-detected |
TOOL_COMPASS_CONFIG | Config file path | ~/.config/tool-compass/compass_config.json |
TOOL_COMPASS_DATA_DIR | Data directory | Platform-specific (see below) |
OLLAMA_URL | Ollama server URL | http://localhost:11434 |
COMFYUI_URL | ComfyUI server | http://localhost:8188 |
PORT | Set to enable HTTP transport (e.g., for Fly.io) | unset (stdio) |
Default data directories:
- Windows:
%LOCALAPPDATA%\tool-compass\ - macOS:
~/Library/Application Support/tool-compass/ - Linux:
~/.config/tool-compass/(or$XDG_CONFIG_HOME/tool-compass/)
See .env.example for all options.
Performance
| Metric | Value |
|---|---|
| Index build time | ~5s for 44 tools |
| Query latency | ~15ms (including embedding) |
| Token savings | ~95% (38K → 2K) |
| Accuracy@3 | ~95% (correct tool in top 3) |
Testing
# Run all tests
pytest
# Run with coverage
pytest --cov=. --cov-report=html
# Skip integration tests (no Ollama required)
pytest -m "not integration"
Troubleshooting
MCP Server Not Connecting
If Claude Desktop logs show JSON parse errors:
Unexpected token 'S', "Starting T"... is not valid JSON
Cause: print() statements corrupt JSON-RPC protocol.
Fix: Use logging or file=sys.stderr:
import sys
print("Debug message", file=sys.stderr)
Ollama Connection Failed
# Check Ollama is running
curl http://localhost:11434/api/tags
# Pull the embedding model
ollama pull nomic-embed-text
Index Not Found
python gateway.py --sync
Related Projects
Part of the Compass Suite for AI-powered development:
- File Compass - Semantic file search
- Integradio - Vector-embedded Gradio components
- Backpropagate - Headless LLM fine-tuning
- Comfy Headless - ComfyUI without the complexity
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Security & Data Scope
Tool Compass is a local-first development tool. See SECURITY.md for full policy.
- Data touched: tool descriptions indexed in local HNSW vector DB, search queries logged to local SQLite (
compass_analytics.db), embeddings generated via local Ollama. - Data NOT touched: no user code, no file contents, no credentials. Tool call arguments are hashed, not stored in plain text.
- Network: connects to local Ollama for embeddings. Optional Gradio UI binds to localhost. No external telemetry.
- No telemetry: collects nothing externally. Analytics are local-only.
Scorecard
Per-category scores are regenerated post-swarm via
bash scripts/regenerate-scorecard.sh (which wraps npx @mcptoolshop/shipcheck audit). See SCORECARD.md for the
current authoritative breakdown — the table below mirrors it and is
intentionally not hand-authored. Hand-curated sections (Known Gaps,
Remediation History) live outside the <!-- SHIPCHECK-AUTO-START/END -->
markers in SCORECARD.md and survive regenerations.
| Category | Score | Notes |
|---|---|---|
| A. Security | TBD | SHA-pinned actions; digest-pinned base image; SLSA provenance + SBOM on PyPI + GHCR; pre-commit secrets scan |
| B. Error Handling | TBD | Structured results, graceful degradation, exit codes |
| C. Operator Docs | TBD | README, CHANGELOG, LICENSE, Makefile verify + verify-metrics + scorecard |
| D. Shipping Hygiene | TBD | CI consolidated; timeout-minutes + retention-days on every job; pytest config in pyproject.toml |
| E. Identity (soft) | TBD | Logo, landing page, GitHub metadata; explicit maintainers in pyproject.toml |
| Total | TBD | Regenerate via make scorecard |
License
MIT - see LICENSE file for details.