Handbook

Welcome to the Tool Compass handbook.

What’s inside

The handbook is organized by what you need to do, following the Diátaxis framework.

Tutorials — learn by doing

• Beginners — First-time setup walkthrough and core concepts
• Getting Started — Install, build the index, run the gateway (plus the new tool-compass CLI subcommands)
  • Register with your MCP client — copy-paste config recipes for Claude Desktop, Cursor, and Cline

How-To Guides — accomplish a specific task

• Operations — /ready, /metrics, trace IDs, graceful Ollama-offline behavior in production

Reference — propositional facts

• Tools — All 9 gateway MCP tools in detail (compass, describe, execute, status, audit, sync, analytics, chains, categories)
• Configuration — Environment variables, Docker, and the compass_config.json schema

Explanation — understand the design

• Architecture — How semantic search works under the hood (with Mermaid diagrams)

What’s new in v2.5.1

• Chain run — compass_chains(action="run") executes hops in order with $prev / $steps[n] argument plumbing.
• Execute dry-run + schema check — required/type/enum validation before the backend connect.
• Resources and prompts — compass_resources / compass_prompts list and read live MCP backends (not indexed).
• Pluggable vector store — hnswlib by default; numpy fallback if hnswlib cannot import (Python 3.13).
• Offline embedders — embedding_provider=hash or local for CI and air-gapped hosts.
• Gradio execute playground and tool-compass init --client snippets for Cursor, VS Code, and Claude Code.
• Atomic npx — npm publish waits until GitHub Release binaries exist.

What’s new in v2.3

• tool-compass init — first-run onboarding. Scaffolds a compass_config.json at your platform config path (refuses to clobber without --force), then prints next steps and a ready-to-paste Claude Desktop MCP snippet. See Register with your MCP client for Cursor + Cline recipes.
• npx @mcptoolshop/tool-compass — zero-prerequisite install. SHA256-verified binaries downloaded on first run, cached locally. No Python toolchain required.
• 6 new CLI subcommands — tool-compass ui, status, categories, audit, analytics, chains mirror the MCP surface for terminal users. All support --json.
• RFC 9457 error envelope — every error includes code, category, retryable, and (where applicable) nearest_tools[] suggestions. Backward-compatible: the legacy error: <str> field stays alongside.
• OTel gen_ai.* metrics — circuit-breaker transitions, fallback invocations, HNSW search latency histogram, embedder inflight, queue wait. Plus degraded: true flag on responses served from lexical fallback.
• Rich-powered CLI — --json everywhere, NO_COLOR/--no-color honored, progress spinners on doctor + sync, actionable error messages with hints.
• Golden-set Recall@k benchmark — frozen 38-query regression test running on every commit. Detects retrieval-quality drift before users do.

What changed in v2.2

• tool-compass CLI shell — search, describe, sync, doctor, serve subcommands. Default (no args) still launches the MCP server.
• Graceful Ollama-offline — compass() falls back to keyword search over the SQLite index, marks results degraded: true, and tells you what to start.
• Trace IDs — every MCP call returns an 8-char trace_id threaded through logs + responses for grepable bug reports.
• /ready + /metrics — deep readiness probe and Prometheus-format metrics for Fly.io / Kubernetes / any operator dashboard.
• Embedding cache — re-sync no longer re-embeds tool descriptions that haven’t changed.
• Multi-arch Docker — linux/amd64 and linux/arm64 from the same GHCR tag.

Full list in CHANGELOG.

Back to landing page