tool-compass 2.0.1

Semantic MCP tool discovery gateway - find tools by intent, not memory

Tool Compass 🧭

A semantic navigator for MCP tools. Find the right tool by intent, not memory.

The Problem

MCP servers can expose dozens or hundreds of tools. Loading all tool definitions into context wastes tokens and slows down responses. Claude has to sift through 70+ tool schemas to find the one it needs.

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.

Before: 77 tools × ~500 tokens = 38,500 tokens per request
After:  1 compass tool + 3 results = ~2,000 tokens per request

Savings: 95%

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 for faster access
• Chain Detection: Automatically discovers common tool workflows
• Analytics: Track usage patterns and tool performance
• Cross-Platform: Works on Windows, macOS, and 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.    │                    │
│                    └──────────────────┘                     │
└─────────────────────────────────────────────────────────────┘

Quick Start

Option 1: Local Installation

# Prerequisites: Ollama with nomic-embed-text
ollama pull nomic-embed-text

# Clone and setup
git clone https://github.com/mikeyfrilot/tool-compass.git
cd tool-compass/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
python gateway.py --sync

# Run the MCP server
python gateway.py

# Or launch the Gradio UI
python ui.py

Option 2: Docker

# Clone the repo
git clone https://github.com/mikeyfrilot/tool-compass.git
cd tool-compass/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

Option 3: Docker (Standalone)

# Build the image
docker build -t tool-compass .

# Run with Ollama on host
docker run -p 7860:7860 \
  -e OLLAMA_URL=http://host.docker.internal:11434 \
  tool-compass

Environment Variables

Variable	Description	Default
TOOL_COMPASS_BASE_PATH	Project root directory	Auto-detected
TOOL_COMPASS_PYTHON	Python executable	Auto-detected
TOOL_COMPASS_CONFIG	Config file path	./compass_config.json
OLLAMA_URL	Ollama server URL	http://localhost:11434
COMFYUI_URL	ComfyUI server (for AI backend)	http://localhost:8188

See .env.example for all options.

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

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Skip integration tests (no Ollama required)
pytest -m "not integration"

# Run specific test file
pytest tests/test_indexer.py -v

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)

File Structure

tool_compass/
├── gateway.py           # MCP server with 9 tools
├── ui.py                # Gradio web interface
├── indexer.py           # HNSW index management
├── embedder.py          # Ollama integration
├── analytics.py         # Usage tracking
├── config.py            # Configuration handling
├── tests/               # Test suite
├── Dockerfile           # Container build
├── docker-compose.yml   # Multi-service deployment
└── db/                  # Index and analytics data

Troubleshooting

MCP Server Not Connecting (JSON Parse Errors)

If Claude Desktop logs show:

Unexpected token 'S', "Starting T"... is not valid JSON

Cause: print() statements corrupt the 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

# Rebuild the index
python gateway.py --sync

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup
• Running tests
• Code style guide
• Pull request process

Security

For security vulnerabilities, please see SECURITY.md.

Do not open public issues for security bugs.

License

MIT - see LICENSE file for details.

Credits

• HNSW: Malkov & Yashunin, "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs" (2016)
• nomic-embed-text: Nomic AI's open embedding model
• FastMCP: Anthropic's MCP framework
• Gradio: Hugging Face's ML web framework

---

"Syntropy above all else."

Tool Compass reduces entropy in the MCP ecosystem by organizing tools by semantic meaning, reducing context waste, and accelerating discovery through intent-based search.