Skip to main content
Glama
jgravelle

jdocmunch-mcp

by jgravelle
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

index_local

Index local documentation folders by parsing heading hierarchy into sections for efficient retrieval. Reuses existing indexes and reports added, changed, or 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). 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.

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.4/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 behavioral burden and does so thoroughly: it discloses conversion, heading-based parsing, conflict/ambiguity outcomes, embedding auto-enablement, coverage semantics, and exactly how truncated/changes fields behave. It also clarifies which drop reasons set truncated, preventing a common misread.

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?

The description is long but information-dense; almost every sentence earns its place and complex semantics are explained precisely. It loses a point for being a single dense paragraph with some redundancy against the schema, such as repeating the embedding-provider environment variables.

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 14-parameter tool with no output schema, the description is unusually complete: it explains response semantics, coverage fields, truncation behavior, changes list ordering, and edge cases like legacy ambiguity and oversize files. Missing details like discovered/indexed are already covered in the rich schema parameter descriptions.

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 description coverage is 100%, so the schema already documents every parameter. The description adds valuable behavioral context for max_files and truncated, and mentions the JDOCMUNCH_MAX_FILE_SIZE cap, but it does not explain the remaining parameters beyond what the schema states. Baseline 3 is appropriate.

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 description opens with a specific verb and resource: 'Index a local folder containing documentation files'. It enumerates supported formats, parsing behavior, and clearly separates this local-indexing tool from the many query/read siblings in the tool list.

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?

It gives clear context for when the tool applies—indexing local documentation folders—and describes important situational behavior such as reusing an existing handle, handling conflicting names, and auto-enabling embeddings. It does not explicitly compare against sibling tools like doc_index_repo or state when not to use it, so it stops short of a 5.

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