know-hub

Minimal, stateless docs search for AI coding agents. An MCP server + CLI that lets an agent find, read, and catalog a project's docs/ folder without burning tokens — ripgrep-ranked at query time, no index, no schema bloat.

Status: v0.1 implemented — MCP server + CLI working, 42 tests green. The full locked design lives in docs/DESIGN.md. Requires ripgrep on PATH.

Why

Heavy documentation MCP servers eagerly load dozens of tool schemas into every session's cold prefix (~30k tokens for a 20-tool server), even when an agent only ever uses search + read. know-hub exposes 3 MCP tools (~850 schema tokens) and pushes everything occasional (setup, scaffolding, linting) into CLI subcommands that cost zero schema tokens — a ~35× reduction.

It also never loads a whole doc when it doesn't have to: search returns ranked snippets, read returns a section, and large files are guarded behind a preview.

What it is

MCP tools (always-on, loaded per session):

CLI subcommands (occasional, zero schema cost):

How it works

• Stateless. No index, no database, no cache. A search is ripgrep over the corpus at query time (a few hundred KB scans in single-digit milliseconds). Nothing to keep in sync, nothing to go stale.
• The doc-format standard is the backbone. Every doc carries a keyword-rich H1, a one-line purpose, a **Status:** line, searchable headings, and wiki-links. Because the format guarantees these signals, the tools grep for them directly instead of guessing.

See docs/DESIGN.md for the complete, decision-by-decision design.

Install

uv pip install -e .          # from a clone
kh-search init               # in a project that needs a docs/ folder

Then register the MCP server (the exact snippet is printed by kh-search init), and run kh-search doctor to verify.

Documentation

• Getting Started — install, set up a project, register the server, verify.
• Usage — the three tools day-to-day, and how to write docs that search well.
• Troubleshooting — server won't connect, empty results, lint errors.
• Design — the complete, decision-by-decision design.
• Agent skill — a drop-in SKILL.md that teaches a coding agent the three tools and the doc format. Copy skills/know-hub/ into your project's .claude/skills/ (or ~/.claude/skills/ for all projects).

License

MIT — see LICENSE.