Index a local folder containing documentation files (.md, .txt, .rst; plus .pdf/.docx/.pptx/.epub when the optional [office] extra is installed — converted to Markdown locally). Parses by heading hierarchy into sections for efficient retrieval. An already-indexed source is recognized before storage is chosen: the established handle is reused (or refreshed), an explicit conflicting name returns a conflict instead of creating a duplicate index, and multiple equivalent legacy indexes return bounded ambiguity. Embeddings auto-enable when a provider is configured (GOOGLE_API_KEY, OPENAI_API_KEY, openai-compatible + JDOCMUNCH_OPENAI_COMPAT_URL + JDOCMUNCH_OPENAI_COMPAT_MODEL, or sentence-transformers).

Index a GitHub repository's documentation. Fetches .md/.txt files, parses sections, and saves to local storage. Embeddings auto-enable when a provider is configured (GOOGLE_API_KEY, OPENAI_API_KEY, openai-compatible + JDOCMUNCH_OPENAI_COMPAT_URL + JDOCMUNCH_OPENAI_COMPAT_MODEL, or sentence-transformers). Indexes .md and .txt only; every other file in the repo is ignored.

List every indexed documentation repo with its identifier and storage location. Call it first to find out whether the docs you need are already indexed, and to get the repo id every other tool needs. Lists only indexes under the active storage_path, so an empty list means nothing is indexed there.

v1.56+ — single-call repo snapshot: doc_count, section_count, total_byte_size, format_breakdown, top_tags, top_roles, indexed_at. Composition of v1.46/v1.50/v1.55 aggregations. Use for 'what is this repo at a glance?'. Counts come from the index, so they are only as fresh as the last index run.

v1.58+ — single-doc detail view. Pairs with list_docs (cross-doc inventory). Returns section list (handles), role_distribution, tag_distribution, byte_size, format, indexed_at for one doc. No content reads.

v1.55+ — flat per-doc inventory of an indexed repo: doc_path, section_count, format, byte_size for each indexed document. Lighter than get_toc_tree (which returns full section trees per doc). Sorted by doc_path. Inventory only; it returns no section titles and no content.

Get a flat table of contents for all sections in a repo, sorted by document order. Content is excluded — use get_section to retrieve content. Scope with path_glob; for a SINGLE document use get_document_outline (this tool has no doc_path parameter).

Get a nested table of contents tree per document. Shows parent/child heading relationships. Content is excluded.

Get the section hierarchy for a single document file, without content. Headings only, no content. Read a section with get_section.

Search sections by relevance. Hybrid (BM25 lexical + semantic embedding) fusion when the index was built with use_embeddings=true; falls back to lexical-only otherwise. Returns summaries only — use get_section for full content.

v1.59+ — count sections matching the same filter set as search_sections (path_glob, role/roles/exclude_roles, tags/exclude_tags, min/max_level, min/max_byte_length) but skip ranking. Use for UI counters or 'does anything match?' probes. Returns the count only, never the matching sections.

v1.57+ — fast title-only token-overlap match. Different from search_sections (full hybrid retrieval). Use for navigation: 'find the section whose heading text matches X'. Handle-only output ({id, title, level, doc_path, _score}); no content reads, no embeddings.

Retrieve the full content of a specific section using byte-range reads. Use after identifying section IDs via search_sections or get_toc. Returns this section's own bytes; nested child sections are not included.

Batch content retrieval for multiple sections in one call. Content only for the ids you pass; unknown ids come back as per-id errors, not a failed call.

Retrieve a section with its full hierarchy context: ancestor headings (root → parent) for orientation, the target section's content, and immediate child summaries. Prevents 'section too thin' without falling back to whole-file reads.

v1.54+ — consolidated handle bundle: full metadata + ancestor breadcrumb + prev/next/parent/first_child neighbors for one section in a single call. Saves three round-trips vs calling get_section_summary + get_section_path + section_neighbors separately. No content reads.

v1.37+ — return prev/next siblings (in document order), parent, and first child for a section. Handles only (id, title, level, doc_path) — no content. Use for fast sequential navigation without re-querying search_sections.

v1.47+ — list sections that have drifted from index state (edited_uncommitted or stale_index buckets via the v1.16 FreshnessProbe). By default compares the index against the cached raw-content mirror, NOT live workspace files; pass live_source=true to read the live files under the index's source_root. _meta.drift_layer reports which layer ran. Pre-flight check before deciding whether to re-index. Handle-only — no content reads.

v1.50+ — list every distinct role classification across the repo with per-role section counts and id samples. Companion to v1.46 get_all_tags. Sections without metadata.role are bucketed under 'unknown'. Use to discover what roles exist before constructing a role= or profile= query.

v1.46+ — list every unique #hashtag across the repo with per-tag section counts. Companion to the v1.45 tags filter on search_sections — use this to discover what tag namespaces exist before constructing a tag-filtered query. Lowercase-normalized. Aggregates the tags the index stored on each section, so a tag added since the last index is missing.

v1.43+ — return every descendant of a section (BFS over parent_id) in document order with depth offset. Pairs with get_section_path (ancestors). Optional max_depth caps the walk; max_depth=1 returns immediate children only. Handles only — no content.

v1.49+ — batch counterpart to get_section_excerpt. Resolves N previews in one call against a single index load. Per-id errors reported in-line. _meta.tokens_saved aggregates byte savings across the batch. Previews are truncated by design; read full content with get_sections.

v1.41+ — return a short content preview (default 500 bytes) for one section. Trimmed to last newline before the cap so it ends on a paragraph boundary. Use to peek at content before paying for a full get_section read. _meta.tokens_saved reports the byte-savings vs full content.

v1.40+ — return the breadcrumb chain (root → ... → target) for a section_id. Walks parent_id upward; cycle-protected. Handles only ({id, title, level, doc_path}) per step plus depth.

v1.39+ — list sections whose doc_path receives zero inbound references from any other doc. Companion to get_broken_links and get_stale_pages: documentation that exists but nobody links to. Inbound links are counted across indexed docs only, so a link from code or an external site does not rescue a section.

v1.38+ — return full indexed metadata (title, summary, role, tags, metadata, parent_id, children, content_hash, byte_start/end, byte_length) for one section without fetching content. Use to inspect role/tags before deciding whether to read the content via get_section.

v1.48+ — batch version of get_section_summary. Resolve metadata for many ids in one call against a single index load. Per-id errors are reported in-line on the corresponding result entry rather than aborting the batch.

Remove a repo index and its cached raw files. Deletes the index and its cached files, never your source documents. There is no undo; re-index to restore.

Scan indexed doc files for internal cross-references that no longer resolve. Checks markdown links, RST :ref:/:doc: directives, and anchor-only links (#heading). External links (http/https) are skipped. Output: list of {source_file, source_section, target, reason} where reason is 'file_not_found', 'section_not_found', or 'anchor_not_found'.

Check which jcodemunch symbols have matching documentation in this doc index. Given a list of jcodemunch symbol IDs, reports which symbols are mentioned in section titles (documented) vs absent (undocumented). Bridges jcodemunch <-> jdocmunch. symbol_ids capped at 200. Output: {documented, undocumented, coverage_pct}.

Find all sections that link TO a given document (inverse reference graph). Useful for the LLM Wiki pattern: when a source changes, find which wiki pages reference it. Output: list of {source_file, source_section, source_section_id, link}. Counts links found inside indexed docs only.

Find wiki pages whose declared sources have been modified on disk. Convention: wiki pages include YAML frontmatter with a 'sources' list of relative paths to raw source files. This tool checks whether those source files have changed since the page was last indexed. Output: list of {doc_path, title, stale_sources} where each stale source has a reason: 'modified', 'missing', or 'untracked'.

Wiki health dashboard. Returns: orphan pages (zero inbound internal links), most-linked pages (top 10), tag distribution, total internal link count, and sections-per-doc min/max/avg. Use for periodic wiki lint checks.

Per-tool latency analysis. window='session' reads the in-memory ring (last 512 calls per tool — always available); window='1h'|'24h'|'7d'|'all' reads the persistent SQLite sink at ~/.doc-index/telemetry.db (opt-in via JDOCMUNCH_PERF_TELEMETRY=1). Returns {window, telemetry_enabled, source, per_tool:{tool:{count,p50_ms,p95_ms,max_ms,errors,error_rate}}}.

Session self-monitor: returns {latency_per_tool, total_tokens_saved}. Lightweight; reads the in-memory latency ring + persistent savings counter. For windowed analysis use analyze_perf. The latency ring lives in memory, so a server restart clears it.

Doc-watcher coverage + login-service state. Reports whether the jdocmunch-watch background service is active and, per locally-indexed doc repo, whether its source_root still exists on disk (watchable). Returns {service, watchable_repo_count, local_repo_count, repos[], hint}. Run jdocmunch-mcp watch (foreground) or watch-install (login service) to keep indexes fresh on any on-disk doc change. Covers locally-indexed repos only; a GitHub-indexed repo has no source_root to watch.

Finalize one canonical Markdown handoff for a completed documentation audit/analysis (jdocmunch.handoff/v1; suite parity with jCodeMunch). The server assembles YOUR sections deterministically, validates every evidence_refs entry against what this session actually retrieved (section ids or doc paths served by search_sections / search_titles / get_section / get_sections — unknown refs fail closed), persists the result session-scoped, and returns a compact receipt {handoff_id, resource_uri, sha256, length, canonical:true}. Read the immutable body via the munch://handoff/ resource; repeated reads are byte-identical. Appendices are included exactly once; no character limit; never writes to the documentation corpus.

Search fenced code blocks across the indexed docs by BM25 over the block content. Returns one row per block with {block_id, section_id, doc_path, title, lang, byte_start, byte_end, snippet, _score}. Optional lang filter (e.g. 'python', 'bash') and doc_path/path_glob scope filters (applied before scoring, same contract as search_sections). Use after index_local; requires INDEX_VERSION>=3.

Best-effort bridge from doc code blocks to jcodemunch code symbols. For each block, tokenizes identifiers and looks them up via jcodemunch's search_symbols. Returns {by_block, by_symbol, _meta} where _meta.bridge_available reports whether jcodemunch-mcp is importable.

Map a jdocmunch docs repo to candidate jCodeMunch code repo handles by source_root. The two suites use independent repo-identity models, so a docs handle (e.g. 'local/foo-docs') is NOT a valid jCodeMunch code_repo. Given a docs repo, returns candidates[{repo, confidence, reason, source_root}] (exact source_root match = high; containment = medium/low), an 'ambiguous' flag, and _meta.bridge_available. Use it to pick the right code_repo for the link_code_to_symbols / get_undocumented_symbols bridge tools.

Resolve a filesystem path (index root, subfolder, or file) to its indexed documentation repo handle via stored source_root metadata — O(1)-sized response, use instead of doc_list_repos when the path is known. Exact root match wins, then the most specific containing root; equally-specific duplicates return ambiguous:true with a bounded candidates list (max 5) plus total_matches. GitHub-indexed corpora (no source_root) never match. Read-only: never creates, refreshes, or deletes an index. Prefer absolute paths; relative paths resolve against the server CWD (echoed as _meta.resolved_path).

Find OpenAPI operations by path glob, method, and/or tag. All filters AND'd. Returns one row per match with {section_id, doc_path, method, path, operationId, summary, tags, deprecated}. Requires the spec to have been indexed under v1.18+ so structured metadata is present.

Return every operation whose tags list contains the given tag (exact). Convenience wrapper around find_endpoint with only a tag filter.

Return every operation whose request body or any response references the given schema. Each row gets a referenced_in list of all schema names that operation pulls in (so you can see the broader dependency cluster). Resolves references inside the indexed OpenAPI document only.

BFS walk of the schema reference graph from a root schema name. Returns {root, nodes:{name:{type, properties, required, refs}}, edges:[[from, to]], unresolved}. max_depth bounds the walk (default 5).

Glossary lookup. Returns every entry whose term equals the query (case-insensitive, exact). Glossary entries are extracted at index time from Term — definition Markdown patterns and RST .. glossary:: blocks.

List glossary terms in alphabetical order, optionally filtered by prefix. Capped at max_results (default 100).

v2.0+ related-section graph. Returns structural neighbors (siblings, children, parent, optional cousins) and semantic neighbors (top-N cosine over stored embeddings, score >= min_score). mode: structural | semantic | both.

Unified diff between the indexed snapshot and the current on-disk byte range for a section. Returns hashes + diff text; identical=true when the section is in sync with disk.

One-shot index health diagnostics. Returns section_count, doc_count, role_distribution, freshness counts, broken_link_count, drift status, BM25 corpus sanity, and embedding coverage. Diagnoses the index, not the writing; a healthy report says nothing about whether the docs are correct.

Six-axis health radar for a doc repo: freshness, link_integrity, orphan_health, embedding_coverage, role_coverage, drift_health (omitted when no canary). Each axis is 0-100, plus composite + A-F grade. Pairs with diff_doc_health_radar for snapshot deltas. Mirrors jcm's and jData's health-radar shape — third leg of the suite-wide pattern. Grades the index, not the prose; none of the six axes read the writing itself.

Composite doc-PR risk profile. Fuses volume + blast_radius + backlink_burden + tutorial_disruption + role_weight signals over a caller-supplied list of changed sections into a 0-1 risk_score with risk_level (low/medium/high/critical), top-5 blockers, and a one-line recommended_action. Caller computes the change list from a git diff or pairs with get_recent_changes. Mirrors jcm's get_pr_risk_profile.

Diff two doc_health_radar payloads. Pure function — pass the radar sub-field from two doc_health_radar responses (e.g. yesterday vs today). Returns per-axis deltas, composite delta, grade change, regression and improvement lists (threshold: 3 points), one-line verdict.

Reconstruct an ordered tutorial chain starting from section_id. Detects frontmatter next:/prev: keys, inline 'Next:' / 'Previous:' markdown links, or ordered numeric filename prefixes (01-intro.md). Returns chain[] of {section_id, doc_path, title} plus the strategy used. Follows only the three conventions above, so a tutorial wired up any other way returns a short chain.

Best-effort inverse coverage: enumerate symbols in the jcodemunch code_repo and return those whose name (or qualified name) does not appear anywhere in this doc index. _meta.bridge_available=false when jcodemunch-mcp is not importable in this environment.

List defined repo groups (v1.26+). Each group is a named alias for a set of indexed repos that search_sections can fan out across via the repo_group kwarg. Lists the group definitions only; it does not check that every member repo is still indexed.

Create, replace, or delete a repo group (v1.26+). Empty repos list deletes the group. Persisted to ~/.doc-index/_groups.jsonc (JSONC — hand-edits welcome).

Online weight tuning. Reads ranking_events from ~/.doc-index/telemetry.db (requires JDOCMUNCH_PERF_TELEMETRY=1) and proposes a per-repo semantic_weight step. dry_run=true skips the disk write. min_events gates against early overfitting. Learns from a recency window of the ledger (default 90 days) so stale events can't anchor the weights. Learning compares confidence WITH vs WITHOUT the semantic channel, so a workload that only ever runs one mode produces no signal at all — use set_weight there instead of waiting.

Byte-offset integrity check. Walks every section, byte-range-reads the bytes, recomputes SHA-256, and compares to the stored content_hash. source='cache' (default) checks the INDEX MIRROR: a clean result proves the index is internally consistent, NOT that the source document is still current. source='live' checks the real workspace files under the index source_root, so an edited source drifts and a deleted one goes missing. _meta.verify_layer always names which one ran. Reports drift / missing / error counts plus the drifting section ids. Sample N sections via the sample arg for cheap CI checks.

Embedding-drift canary. Without args, re-embeds the saved CANARY_STRINGS and reports per-canary cosine drift; alarm fires when max_drift > threshold (default 0.05 ≈ cosine<0.95). Pass capture=true to seed the snapshot first (idempotent unless force=true). Catches silent provider model upgrades that would otherwise corrupt index recall without changing dim.

Multi-signal section dedup detection. Fuses embedding cosine (when available) with title + body lexical Jaccard, clusters via union-find, ranks each cluster's canonical by backlink_count + size. Verdict tiers: near_duplicate, overlapping_topic, parallel_tutorial. Read-only.

Transitive impact of rewriting / restructuring a section. Walks the inbound reference graph to max_depth (default 3), classifies each hit as anchor / doc / tutorial, and returns direct_impact, transitive_impact, a summary, and a normalised blast_score in [0, 1]. Companion to get_backlinks (which is depth 1 only). Read-only.

Composite preflight: is this section safe to delete? Fuses tutorial-path membership, anchor-specific backlinks, transitive doc-level backlinks, and recent-edit recency into a single verdict (safe_to_delete, tutorial_path_blocking, anchor_referenced, backlinks_blocking, recently_edited_blocking) plus up to 5 ranked blockers and a one-line recommended_action. Read-only — never mutates the index.

Return the version-current CLAUDE.md / AGENT.md policy snippet for jdocmunch-mcp. Lets an agent keep a one-line CLAUDE.md (e.g. "Call jdocmunch_guide and strictly follow its instructions.") instead of pasting a static snippet that drifts from the installed version. Idempotent, no repo context required. Sibling of jcodemunch_guide.