Tool Compass

English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

---

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
npx @mcptoolshop/tool-compass execute fs:read_file '{"path":"README.md"}'  # Smoke-test a proxied call

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

Or run the published image directly, without cloning:

docker run --rm -p 7860:7860   -v tool-compass-data:/app/tool_compass/db   ghcr.io/mcp-tool-shop-org/tool-compass:latest

Mount the volume. The semantic index lives in /app/tool_compass/db, and building it means embedding every tool in every configured server. Without a volume that work is thrown away when the container exits and paid again on the next start — which reads as "Tool Compass is slow" rather than as a missing flag. The image warns you if you forget. docker compose up already mounts a named volume, so this only applies to bare docker run.

The GHCR image (ghcr.io/mcp-tool-shop-org/tool-compass) supports linux/amd64 and linux/arm64, so the same tag runs on x86_64 servers and Apple Silicon / ARM workstations.

Features

• Hybrid Search - Semantic (HNSW) + lexical fusion with exact-name boost — describe what you want, or paste a tool name and it ranks #1
• Full-Schema Progressive Disclosure - compass() → describe() → execute(); describe() returns the complete inputSchema (required fields, descriptions, enums, defaults)
• stdio + HTTP backends - Front local subprocess MCP servers and remote / SaaS servers over streamable-http, with optional bearer-token auth
• Per-tool timeouts & allow/deny - Override the default timeout per backend/tool; expose a safe subset of a broad backend
• Hot Cache & Chain Detection - Frequently used tools pre-loaded; common tool workflows discovered automatically
• Analytics - Track usage patterns and tool performance (with retention/prune)
• Cross-Platform & Docker Ready - Windows, macOS, Linux; 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)	Hybrid semantic + lexical search with exact-name boost
describe(tool_name)	Get the full inputSchema for a tool (required/enums/defaults)
execute(tool_name, args)	Run a tool on its backend
compass_categories()	List categories and servers
compass_status(active)	System health and config; active=True runs a live backend liveness probe
compass_analytics(timeframe)	Usage statistics
compass_chains(action)	Manage tool workflows
compass_sync(force)	Rebuild index from backends
compass_audit()	Full system report

The same actions are available from the CLI — including tool-compass execute <tool> '<json>' to smoke-test a proxied call from the terminal.

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)
TOOL_COMPASS_GATEWAY_AUTH_TOKEN	Bearer token required on the HTTP transport (opt-in; overrides the gateway_auth_token config field)	unset (no auth)

Default data directories:

• Windows: %LOCALAPPDATA%\tool-compass\
• macOS: ~/Library/Application Support/tool-compass/
• Linux: ~/.config/tool-compass/ (or $XDG_CONFIG_HOME/tool-compass/)

Config-file settings (in compass_config.json) added in v2.5.0 — hybrid_search, exact_name_boost, per-backend default_timeout / tool_timeouts, allow_tools / deny_tools, analytics_retention_days, and HTTP (type: "http") backends — are documented in the Handbook → Configuration. See .env.example for env-var 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

tool-compass 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.

Latest shipcheck audit: 32 checked · 0 unchecked · 5 skipped · 100% pass — all hard gates pass.

Category	Score	Notes
A. Security	✅ Pass	SHA-pinned actions; digest-pinned base image; SLSA provenance + SBOM on PyPI + GHCR; pre-commit secrets scan; opt-in gateway bearer auth
B. Error Handling	✅ Pass	Structured results, graceful degradation, exit codes
C. Operator Docs	✅ Pass	README, CHANGELOG, LICENSE, Makefile verify + verify-metrics + scorecard
D. Shipping Hygiene	✅ Pass	CI consolidated; timeout-minutes + retention-days on every job; pytest config in pyproject.toml
E. Identity (soft)	✅ Pass	Logo, landing page, GitHub metadata; explicit maintainers in pyproject.toml
Total	100%	All hard gates pass — regenerate via make scorecard

License

MIT - see LICENSE file for details.

---

Built by MCP Tool Shop