know-hub 0.1.0

Minimal, stateless docs search for AI coding agents (MCP server + CLI) — ripgrep-ranked, no index, no schema bloat

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):

Tool	Purpose
kh_search(query, scope, limit, project)	Ranked search across docs/ — ripgrep + a ~30-line scorer. Returns snippets + wiki-link connections.
kh_read(path, section, project)	Read one doc (or one ## section), with a metadata header (links-to / linked-by). Large files are preview-guarded.
kh_list(scope, project)	Enriched catalog of every doc: name [STATUS] purpose, plus a one-line health header (orphans, missing-status, broken-links).

CLI subcommands (occasional, zero schema cost):

Command	Purpose
kh-search init	First-time setup — create docs/ + a starter index.md, print the MCP registration snippet.
kh-search new <name> [--scope <folder>]	Scaffold a new doc that already follows the format standard.
kh-search lint	Check every doc against the format standard + link rules (orphans, broken links).
kh-search doctor	Health check: ripgrep, docs root, MCP registrations (and that their launch commands still exist), corpus health.
kh-search uninstall [--yes]	Remove know-hub's MCP registrations (dry run without --yes). Never touches docs/.

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.