Skip to main content
Glama
jgravelle

jdocmunch-mcp

by jgravelle
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

index_local

Index local documentation folders into a searchable section hierarchy, letting agents retrieve precise sections instead of reading entire files and reducing token usage.

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
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.
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.
extra_ignore_patternsNoAdditional gitignore-style patterns to exclude from indexing

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
+}
  2. Addedv1.118.0
  3. Removedv1.99.0
  4. First observedv1.66.3

TDQS

A4.5/5.0
Behavior5/5

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

With only readOnlyHint=false in annotations, the description carries the full burden of behavioral disclosure and does so thoroughly. It discloses existing-index reconciliation, conflict/duplicate behavior, bounded ambiguity for legacy indexes, embedding auto-enablement, and precise `truncated`/`skip_counts` semantics. It also clarifies that office documents are converted locally, which is important non-obvious behavior.

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

Conciseness4/5

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

Every sentence carries non-redundant information, and the core purpose is front-loaded in the first clause. However, the description is a dense wall of semicolon-heavy prose with long parentheticals, making it harder to scan than ideal. For a 14-parameter tool it is appropriately sized, but not exemplary in structure.

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 mutating tool with 14 parameters and no output schema, the description covers many high-risk edge cases: duplicate indices, legacy reconciliation, truncation, oversize files, and embedding provider activation. The main gap is that the returned handle/response payload is not explicitly described beyond the coverage-related fields. It is still sufficiently complete for correct invocation.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema by clarifying that `truncated` answers only the max_files cap and that oversize files appear under skip_counts.oversize. It also explains behavior of the handle/name layer, which affects how `name` and `paths` are interpreted. This elevates it above the baseline.

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?

The first sentence states a specific verb and resource: 'Index a local folder containing documentation files,' and enumerates the supported formats. The heading-hierarchy parsing and embedding details make the operation unmistakable. The 'local folder' scope clearly distinguishes it from the many retrieval-oriented siblings and the repo-centric index sibling.

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?

The description gives clear context: this tool is for indexing local documentation folders, with format caveats and optional configuration conditions. It does not explicitly name an alternative such as doc_index_repo or state when-not-to-use this tool, so it stops short of a 5. The context is clear enough that an agent can select it appropriately.

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