Skip to main content
Glama

index_local

Build a searchable index of a local documentation folder by splitting files into heading-based sections for precise retrieval, with incremental re-indexing that reports new, changed, and deleted files.

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "index_local"
  }
}

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 cap on scanned pages OCR reads (default 50). Every page is checked for a text layer; scanned pages past the cap are reported as ocr_pages_capped, 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. Changed1 schema field changedv1.151.1
    • changedInput schema / properties / ocr_max_pages / description
      Previous value: -"Per-document OCR page cap (default 50); pages past it are reported, not read."New value: +"Per-document cap on scanned pages OCR reads (default 50). Every page is checked for a text layer; scanned pages past the cap are reported as ocr_pages_capped, not read."
  2. 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"
      +}
  3. 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"
      +}
  4. Addedv1.118.0
  5. Removedv1.99.0
  6. First observedv1.66.3

TDQS

A4/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false; the description carries the real burden and does so thoroughly — handle reuse vs. conflict vs. bounded ambiguity on re-index, embeddings auto-enable conditions, the 5MB per-file cap surfacing under skip_counts.oversize, and the crucial distinction that `truncated` covers only the max_files cap while `coverage_complete`/`skip_counts` cover other drops.

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 first two sentences are front-loaded and strong, but the body collapses into a dense spec dump covering `changes` ordering, cap truncation, and `duplicate_anchors` fields in one unbroken paragraph. Since no output schema exists the detail is warranted, yet it is not structured for scanning.

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

Completeness4/5

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

For a 17-parameter write tool with no output schema, the description is unusually complete: it documents response coverage fields, change tracking, and the v1.147+ duplicate-anchor block, and warns about OCR risk on sensitive folders. It could still say more about overall return shape (handle/name, counts) and idempotency.

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% and the per-parameter descriptions are already extremely detailed, so the baseline is 3. The prose mostly restates param behavior (max_files truncation, embedding provider env vars) rather than adding new semantics, though tying max_files to the response's `truncated`/`discovered`/`indexed` fields is a small value-add.

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

Purpose4/5

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

Opens with a specific verb+resource ("Index a local folder containing documentation files") and enumerates supported formats plus the heading-hierarchy parsing model, so the agent knows exactly what is produced. It never distinguishes itself from the sibling `doc_index_repo`, leaving ambiguous which indexer applies to a given source.

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 concrete conditional guidance: use the CLI `jdocmunch-mcp index-local --path <dir>` when a folder has tens of thousands of files that would outlast a tool timeout, set `name` when two folders share a name, use `paths` to batch-index known files. Missing is any when-not or sibling routing against `doc_index_repo`.

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