Skip to main content
Glama
jgravelle

jdocmunch-mcp

by jgravelle
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

index_local

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

Instructions

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). For a folder of tens of thousands of files, which can outlast a client's tool timeout, run jdocmunch-mcp index-local --path <dir> from a shell instead; this server reads the index it writes. Coverage: coverage_complete answers 'did I get everything', with skip_counts / skipped_paths naming what was dropped and why; truncated answers ONLY the max_files cap and is false when a file was dropped for any other reason. Files over the per-file size cap (5MB default, JDOCMUNCH_MAX_FILE_SIZE) are reported under skip_counts.oversize. Response includes a changes list with one {doc_path, status: new|changed|deleted, mtime} entry per file, sorted newest first and capped at 50 entries, useful for a 'recently edited' map at session start. changes_total is the uncapped count and changes_truncated is true when entries were dropped. Deleted files sort last, so the cap drops them first: the new/changed/deleted count fields are the authority, not the length of changes. v1.147+ — a response that indexes the folder or finds nothing to change returns duplicate_anchors (empty when none; at most 20 entries, each with section_ids and titles capped at 20 and section_ids_truncated), duplicate_anchors_total (uncapped), duplicate_anchors_truncated and duplicate_anchor_warning for explicit {#id} headings written twice in one document.

Input Schema

NameRequiredDescriptionDefault
ocrNo[ocr] extra (v1.149.0): read scanned PDF pages with an OCR engine already on the machine (Tesseract, or Windows' built-in OCR). Runs ONLY if the user also set JDOCMUNCH_OCR=1 in config; the response's `ocr` block says whether OCR was requested, enabled and used. Omit to keep this index's stored choice; false turns it off. OCR text is marked text_source="ocr" and may contain errors; tables and forms may come out scrambled. Scanned tax forms or IDs become searchable text, so only use it on folders the user meant to have read. Nothing is installed or downloaded.
nameNoOptional repo identifier override. Use this when two folders share the same name (e.g. both named 'docs'). If omitted, the folder name is used. Example: 'requests-docs', 'flask-docs'.
pathYesPath to local folder (absolute or relative, supports ~ for home directory)
pathsNoOptional list of explicit paths to index. When provided, the directory walk is skipped; only these files (and the contents of any directories in the list) are indexed. Entries may be absolute or relative to `path`. Useful for batch-indexing exactly the files an agent already knows about — e.g. the doc files git just touched.
sort_byNoOrder in which files are truncated when discovered > max_files. 'newest' (default) keeps the most recently-edited files so a fresh edit is always in the index. 'walk_order' preserves filesystem-walk order for deterministic reproducible builds. No effect when corpus fits under the cap.newest
autotuneNov1.29+ — when true, runs tune_weights against accumulated ranking events at the end of indexing. No-op when telemetry isn't enabled.
max_filesNoMaximum number of doc files to index. Default 10000. When the cap is hit, the response includes `truncated: true`, `discovered: <total found>`, and `indexed: <max_files>` so the caller can detect data loss programmatically. Raise this for very large corpora.
incrementalNoWhen true (default), only re-index files that changed since the last index. Set to false to force a full re-index.
ocr_max_pagesNoPer-document OCR page cap (default 50); pages past it are reported, not read.
worktree_modeNoLinked-worktree behavior (jdoc#83). 'reuse_equivalent' (default) reuses a proven-fresh established index from another linked worktree instead of creating a duplicate; uncertain outcomes return a bounded decision with no write. 'branch_local' intentionally creates/refreshes an exact-path index for this worktree.reuse_equivalent
use_embeddingsNoGenerate semantic embeddings for each section, enabling hybrid (BM25+semantic) search. true/false/"auto". "auto" (default) enables embeddings when an embedding provider is configured (GOOGLE_API_KEY, OPENAI_API_KEY, openai-compatible + JDOCMUNCH_OPENAI_COMPAT_URL + JDOCMUNCH_OPENAI_COMPAT_MODEL, or sentence-transformers installed).auto
follow_symlinksNoWhether to follow symlinks. Default false for security.
include_dot_dirsNojdoc#113 - directory NAMES to index even though they start with a dot, e.g. [".claude"]. Dotted directories are skipped by default so a tool's dotfile cache cannot be ingested as documentation; .github is always indexed. Names only, not paths.
legacy_reconcileNoPart C.2 legacy reconciliation (jdoc#87). Requires an explicit name= selecting a pre-1.102 fieldless legacy index and a full refresh. 'report' proves whether it is an exact duplicate of its single modern peer (same verified identity, same clean certified commit, full path-and-hash coverage) without changing anything; 'apply' repeats the proof and retires the selected legacy handle — the only possible loser; the peer is never touched. Omitted: ordinary refresh, backfill-only, never retires.
use_ai_summariesNoUse AI to generate section summaries (requires ANTHROPIC_API_KEY or GOOGLE_API_KEY). When false, uses heading text.
ocr_budget_secondsNoTime budget for OCR in this call (default 60). A document that can't finish is skipped as ocr_budget_exhausted and resumes on the next call; for big scanned folders use the CLI `index-local --ocr`, which has no budget.
extra_ignore_patternsNoAdditional gitignore-style patterns to exclude from indexing

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.150.0
    • addedInput schema / properties / ocr
      Added value: +{
+  "description": "[ocr] extra (v1.149.0): read scanned PDF pages with an OCR engine already on the machine (Tesseract, or Windows' built-in OCR). Runs ONLY if the user also set JDOCMUNCH_OCR=1 in config; the response's `ocr` block says whether OCR was requested, enabled and used. Omit to keep this index's stored choice; false turns it off. OCR text is marked text_source=\"ocr\" and may contain errors; tables and forms may come out scrambled. Scanned tax forms or IDs become searchable text, so only use it on folders the user meant to have read. Nothing is installed or downloaded.",
+  "type": "boolean"
+}
    • addedInput schema / properties / ocr_budget_seconds
      Added value: +{
+  "description": "Time budget for OCR in this call (default 60). A document that can't finish is skipped as ocr_budget_exhausted and resumes on the next call; for big scanned folders use the CLI `index-local --ocr`, which has no budget.",
+  "type": "number"
+}
    • addedInput schema / properties / ocr_max_pages
      Added value: +{
+  "description": "Per-document OCR page cap (default 50); pages past it are reported, not read.",
+  "type": "integer"
+}
  2. Changed1 schema field changedv1.130.0
    • addedInput schema / properties / include_dot_dirs
      Added value: +{
+  "description": "jdoc#113 - directory NAMES to index even though they start with a dot, e.g. [\".claude\"]. Dotted directories are skipped by default so a tool's dotfile cache cannot be ingested as documentation; .github is always indexed. Names only, not paths.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  3. Addedv1.118.0
  4. Removedv1.99.0
  5. First observedv1.66.3

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare only readOnlyHint=false, so the description must carry the behavior, and it does extensively: duplicate/conflict handling, handle reuse, embeddings auto-enable conditions, OCR gating via JDOCMUNCH_OCR, oversize skip reporting, and changes-list capping. This is far beyond what the single annotation conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, which is good, but the remainder is a single dense mega-paragraph blending parameter detail, output-field semantics (coverage_complete, skip_counts, changes, duplicate_anchors), and version notes. It earns its length somewhat (no output schema exists) but lacks structure, making it hard to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter mutation tool with no output schema, the description compensates thoroughly by explaining return semantics: coverage vs truncation, skip_counts, the capped `changes` list with deleted-last ordering, and duplicate_anchors reporting. An agent has enough to call it correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all 17 parameters are already documented in structured fields (including complex ones like legacy_reconcile, worktree_mode, sort_by). The description mostly restates output/truncation semantics rather than adding meaning to individual parameters, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Index a local folder containing documentation files'), names the accepted file types, and implicitly distinguishes itself from retrieval siblings (search_sections, get_section, etc.). An agent knows this is the build/ingestion step, not a query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use-alternative: for tens of thousands of files that outlast a client timeout, run the `jdocmunch-mcp index-local` CLI instead. Also explains incremental default. Does not, however, explicitly route the agent between this and the sibling `doc_index_repo`, leaving that choice implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools