hubdocs

Local MCP for arc42 × C4 docs hubs: index architecture/product IDs, deps, orphans, broken links, and chapter routing — so agents query the hub without dumping whole trees.

Indexes and validates Markdown only — does not replace Structurizr or diagram renderers.

• GitHub: raintr91/hubdocs

• Init (agents): docs/INIT.md

• Package bootstrap: docs/INSTALL.md

Independence

Hubdocs owns the architecture authoring harness (/architecture family + /hubdocs) and the docs ID/graph tools. ArtifactGraph is an optional accelerator for registries/tags/parity only.

• Hubdocs never requires ArtifactGraph.

• ArtifactGraph must not index or own architecture Markdown.

• Missing ArtifactGraph falls back to targeted local reads and emits one deduplicated hubdocs.missing-optional event per run/optional with measured fileReads and contextBytes; token usage is not estimated.

• Missing Hubdocs MCP never blocks Markdown authoring: use repository search and targeted file reads.

Related MCP server: Documentation MCP Server

What it does

Quick start

Linux / WSL

curl -fsSL https://raw.githubusercontent.com/raintr91/hubdocs/main/install.sh | bash
hubdocs version
cd /path/to/your/docs-hub    # thư mục có architecture/
hubdocs init --location=local --yes
# hubdocs init               # interactive; local is the default

Windows

irm https://raw.githubusercontent.com/raintr91/hubdocs/main/install.ps1 | iex

Requires Node ≥ 22.

Local init lấy docs root theo thứ tự --docs-root → HUBDOCS_ROOT → cwd có architecture/. Không có sibling fallback hay package-global root marker.

Global wiring phải dùng --location=global. Không truyền --docs-root thì MCP global là rootless và mỗi tool call phải truyền docsRoot.

Sau init: restart agent → thử tool hubdocs_list_ids.

Update

Cùng lệnh cài — ghi đè ~/.hubdocs + symlink CLI:

curl -fsSL https://raw.githubusercontent.com/raintr91/hubdocs/main/install.sh | bash
hubdocs version

Pin bản cụ thể:

HUBDOCS_REF=v1.0.2 curl -fsSL https://raw.githubusercontent.com/raintr91/hubdocs/v1.0.2/install.sh | bash

Windows: chạy lại irm …/install.ps1 | iex.

Sau update: nếu đổi wire MCP thì cd docs hub → hubdocs init --location=local --yes rồi restart agent.

Uninstall: curl -fsSL …/install.sh | bash -s -- --uninstall

Commands

install = deprecated alias của init.

Harness installs record direct-copy Hubdocs assets in .hubdocs/install-manifest.json. Upgrades preserve locally modified managed files unless --force is passed. Assets removed from a newer package become stale; prune is a dry run, and prune --yes deletes only stale files whose hash still matches the installed copy. Shared merged .cursor/extracts/extract-registry.json and platform-repos.json are never claimed or pruned. The Hubdocs-owned optional fallback schema is installed at .cursor/schemas/hubdocs/missing-optional-event.schema.json and follows the same managed lifecycle.

Agents hỗ trợ: Claude · Cursor · Codex · opencode · Hermes · Gemini · Antigravity · Kiro · Kilo.

MCP tools

Manual Cursor snippet: mcp.cursor.example.json. Ưu tiên hubdocs init sau install.sh.

Docs root: tool docsRoot → project MCP HUBDOCS_ROOT → valid cwd → setup error. Hub phải có architecture/.

Redirect stubs (old flat C4) bị bỏ qua khi index. DYN-* không còn được index — dùng FLOW-*.

License

MIT