tool-compass 2.0.2

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

Tool Compass

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 • 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

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

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

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	./compass_config.json
OLLAMA_URL	Ollama server URL	http://localhost:11434
COMFYUI_URL	ComfyUI server	http://localhost:8188

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

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.

Documentation • Issues • Discussions