Zero-prerequisite install

npx @mcptoolshop/tool-compass --help

This package is an npx-friendly launcher for the tool-compass Python CLI. It downloads the verified platform-specific binary from the GitHub Release, caches it locally, and runs it with full argument passthrough.

No Python install required. The binary is self-contained.

What is Tool Compass?

MCP servers expose dozens or hundreds of tools. Loading every tool definition into an LLM context wastes tokens and slows responses.

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

Savings: 95%

Tool Compass uses semantic search to find relevant tools from a natural-language description. Instead of loading every tool, the LLM calls compass() with an intent and gets back only the matching tools.

Quick start

Run the MCP gateway

npx @mcptoolshop/tool-compass serve

Launch the Gradio UI

npx @mcptoolshop/tool-compass ui

Diagnose your setup

npx @mcptoolshop/tool-compass doctor

Sync the index against your backends

npx @mcptoolshop/tool-compass sync

What gets installed

Nothing global. The launcher downloads the verified binary on first run, caches it under:

| OS | Cache path | |---------|--------------------------------------------------| | Linux | ~/.cache/mcptoolshop/tool-compass/<version>/ | | macOS | ~/.cache/mcptoolshop/tool-compass/<version>/ | | Windows | %LOCALAPPDATA%\mcptoolshop\tool-compass\<version>\ |

Every binary is SHA256-verified against checksums-<version>.txt from the GitHub Release. Mismatches abort execution and the file is deleted.

Configuration

Configuration lives in compass_config.json in the working directory. Start from the example:

{
  "backends": [
    {
      "name": "my-mcp-server",
      "command": "python",
      "args": ["-m", "my_server"]
    }
  ]
}

See the Configuration handbook page for the full schema.

MCP client setup

Add this to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "compass": {
      "command": "npx",
      "args": ["-y", "@mcptoolshop/tool-compass", "serve"]
    }
  }
}

How the launcher works

npx @mcptoolshop/tool-compass serve
        │
        ▼
  wrapper sets MCPTOOLSHOP_LAUNCH_CONFIG
        │
        ▼
  npm-launcher resolves your platform (linux-x64, darwin-arm64, win-x64)
        │
        ▼
  checks local cache
        │
        ├─ cached → run binary
        │
        └─ not cached:
             fetch checksums-<version>.txt
             download tool-compass-<version>-<os>-<arch>[.exe]
             verify SHA256
             cache + chmod +x
             run binary

Security & threat model

The npm wrapper downloads and executes a binary from GitHub Releases. Here's what it touches:

• Network: HTTPS only, to github.com and GitHub's CDN.
• Filesystem: Writes to the local cache only. Does not modify system files.
• Verification: SHA256-checked against the official Release checksums.
• No telemetry. No credentials handled.
• No elevated permissions.

See SECURITY.md for the full disclosure policy.

Alternative installs

• PyPI: pip install tool-compass
• Docker: docker run ghcr.io/mcp-tool-shop-org/tool-compass:latest
• From source: clone + pip install -e . — see CONTRIBUTING.md

Documentation

| Resource | Where | |----------|-------| | Handbook | https://mcp-tool-shop-org.github.io/tool-compass/handbook/ | | Source repo | https://github.com/mcp-tool-shop-org/tool-compass | | Changelog | https://github.com/mcp-tool-shop-org/tool-compass/blob/main/CHANGELOG.md | | Issues | https://github.com/mcp-tool-shop-org/tool-compass/issues |

License

MIT — same as the source repo.

Built by MCP Tool Shop.