Metadata-Version: 2.4
Name: know-hub
Version: 0.1.0
Summary: Minimal, stateless docs search for AI coding agents (MCP server + CLI) — ripgrep-ranked, no index, no schema bloat
Project-URL: Homepage, https://github.com/amitnexTech/knowledge-hub
Project-URL: Repository, https://github.com/amitnexTech/knowledge-hub
Project-URL: Issues, https://github.com/amitnexTech/knowledge-hub/issues
Author-email: Amit Kushwaha <amitkushwaha2805@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,documentation,mcp,ripgrep,search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Requires-Dist: mcp<2.0,>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](docs/DESIGN.md).
> Requires [ripgrep](https://github.com/BurntSushi/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`](docs/DESIGN.md) for the complete, decision-by-decision
design.

## Install

```sh
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](docs/getting-started.md)** — install, set up a project,
  register the server, verify.
- **[Usage](docs/usage.md)** — the three tools day-to-day, and how to write
  docs that search well.
- **[Troubleshooting](docs/troubleshooting.md)** — server won't connect, empty
  results, lint errors.
- **[Design](docs/DESIGN.md)** — the complete, decision-by-decision design.
- **[Agent skill](skills/know-hub/SKILL.md)** — 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](LICENSE).
