Metadata-Version: 2.4
Name: tool-compass
Version: 2.0.1
Summary: Semantic MCP tool discovery gateway - find tools by intent, not memory
Project-URL: Homepage, https://github.com/mikeyfrilot/tool-compass
Project-URL: Documentation, https://github.com/mikeyfrilot/tool-compass#readme
Project-URL: Repository, https://github.com/mikeyfrilot/tool-compass.git
Project-URL: Issues, https://github.com/mikeyfrilot/tool-compass/issues
Project-URL: Changelog, https://github.com/mikeyfrilot/tool-compass/blob/main/CHANGELOG.md
Author: Mikey Frilot
License-Expression: MIT
License-File: LICENSE
Keywords: ai,anthropic,claude,hnsw,llm,mcp,model-context-protocol,semantic-search,tool-discovery,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: hnswlib<1.0.0,>=0.8.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Provides-Extra: all
Requires-Dist: gradio<6.0.0,>=5.0.0; extra == 'all'
Requires-Dist: hypothesis>=6.100.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: ui
Requires-Dist: gradio<6.0.0,>=5.0.0; extra == 'ui'
Description-Content-Type: text/markdown

# Tool Compass 🧭

[![Tests](https://github.com/mikeyfrilot/tool-compass/actions/workflows/test.yml/badge.svg)](https://github.com/mikeyfrilot/tool-compass/actions/workflows/test.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)

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

```bash
# 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

```bash
# 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)

```bash
# 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`](.env.example) for all options.

## Usage

### The `compass()` Tool

```python
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:
```json
{
  "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

```bash
# 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`:
```python
import sys
print("Debug message", file=sys.stderr)
```

### Ollama Connection Failed

```bash
# Check Ollama is running
curl http://localhost:11434/api/tags

# Pull the embedding model
ollama pull nomic-embed-text
```

### Index Not Found

```bash
# Rebuild the index
python gateway.py --sync
```

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup
- Running tests
- Code style guide
- Pull request process

## Security

For security vulnerabilities, please see [SECURITY.md](SECURITY.md).

**Do not open public issues for security bugs.**

## License

[MIT](LICENSE) - 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.
