Jdocmunch MCP

停止向AI提供文档树

大多数人工智能代理仍然以昂贵的方式探索文档：

打开文件→ 浏览数百个不相关的段落→ 打开另一个文件→ 重复

这会烧毁令牌，用噪音淹没上下文窗口，并迫使模型推理出大量他们一开始就不需要的文本。

jDocMunch MCP允许AI代理按节导航文档，而不是通过暴力读取文件。\ 它对文档集进行一次索引，然后从原始文件中精确提取字节，准确检索代理实际需要的部分。

索引一次。永远低价查询。\ 精确上下文胜过暴力上下文。

______________________________________________________________________

jDocMunch MCP

面向严重代理的AI原生文档导航

 ](https://pypi.org/project/jdocmunch-mcp/) ](https://pypi.org/project/jdocmunch-mcp/)

## 商业许可证 jDocMunch MCP是 免费用于非商业用途. 商业使用需要付费许可证。 jDocMunch仅许可 - 建筑商——29美元 --1名开发人员 - 工作室——99美元 --最多5名开发人员 - 平台——499美元 --全组织内部部署 想要同时检索代码和文档吗？ - 蒙克二重奏组合——89美元 - 蒙克二人工作室套餐——399美元 - 蒙克双平台捆绑包——2249美元

### 1.x兼容性承诺 每个1.x许可证都使您有权获得未来的每个1.x版本。我们永远不会发布以下1.x版本： - 删除或重命名MCP工具（弃用的工具名称保留其别名）， - 下降a Section 从响应形状中提取字段， - 强制重新索引，而不在首次加载时自动迁移现有索引， - 以破坏现有消费者的方式更改任何工具响应的JSON线格式， - 或者使先前默认的行为升高。 任何需要打破这些承诺的东西都保留给未来的主要版本（2.x）。整机检查合同通过以下方式执行 tests/test_server.py （工具名称和所需字段不变量）和在每个版本上运行的重播夹具门。

停止将文档文件转储到上下文窗口中。开始按结构浏览文档。

jDocMunch通过标题层次结构和节结构对文档进行一次索引，然后让MCP兼容的代理精确访问他们实际需要的解释，而不是强迫他们强行读取文件。

它是为令牌效率、上下文卫生和代理可靠性很重要的工作流而构建的。

______________________________________________________________________

为什么存在

大上下文窗口并不能修复检索错误。

代理在以下情况下浪费金钱和推理带宽：

• 打开整个文档以查找一个配置块
• 反复重读标题、样板和无关章节
• 在超大的上下文有效载荷中丢失重要的解释
• 将文档作为平面文本而不是结构化知识使用

jDocMunch通过更改访问单位来修复这个问题 文件 到 部分.

它可以准确地检索，而不是将整个文档交给代理：

• 安装部分
• 配置部分
• API解释
• 故障排除部分
• 相关标题的特定子树

这使得文档探索更便宜、更快、更稳定。

______________________________________________________________________

是什么让它与众不同

第一节检索

按节搜索和检索文档，而不仅仅是文件路径或关键字匹配。

字节精确提取

完整内容按需从精确的字节偏移量拉入原始文件。

稳定的区段ID

当路径、标题文本和标题级别保持不变时，节在重新索引过程中保留持久标识。

当地第一建筑

索引和原始文档存储在本地。不需要托管依赖关系。

MCP本地工作流

适用于Claude Desktop、Claude Code、Google Antigravity和其他MCP兼容客户端。

______________________________________________________________________

什么会被索引

每个部分存储：

• 标题和标题级别
• 单行摘要
• 提取的标签和引用
• 用于漂移检测的SHA-256内容哈希
• 原始文件中的字节偏移量

这允许代理从结构上发现文档，然后只请求他们需要的特定部分。

______________________________________________________________________

为什么代理商需要这个

传统的文档检索方法都有不同的突破：

• 文件扫描 加载太多不相关的文本
• 关键字搜索 找到术语，但经常失去上下文
• 分块 打破作者的层次结构，将解释与示例分开

jDocMunch保留了人类作者想要的结构：

• 标题层次结构
• 亲子关系
• 区段边界
• 连贯的解释单位

代理不需要更大的上下文窗口。\ 他们需要更好的导航。

______________________________________________________________________

运作原理

jDocMunch实现 jMRI完整 --结构化检索MCP服务器的开放规范。jMRI Full涵盖了整个堆栈：发现、搜索、检索和元数据操作，包括批检索、基于哈希的漂移检测、字节偏移寻址和完整的 _meta 每个电话上都有信封。

1. 发现

GitHub API或本地目录行走

1. 安全过滤

横向保护、秘密排除、二进制检测

1. 解析

支持格式的节分割：基于标题（Markdown/MDX/HTML/RST/AsciiDoc）、基于结构（OpenAPI标签、JSON键、XML元素）或基于单元格（Jupyter）

1. 层次布线

建立父母/子女关系

1. 摘要

标题文本→ AI批次摘要→ 标题回退

1. 存储

JSON索引+本地存储的原始文件 ~/.doc-index/

1. 检索

通过稳定段ID查找O（1）字节偏移量

______________________________________________________________________

稳定的区段ID

{repo}::{doc_path}::{ancestor-chain/slug}#{level}

slug的前缀是祖先标题链，使ID既可读又稳定。在文档的一个分支中插入的新标题永远不会对另一个分支的ID重新编号。

示例：

• owner/repo::docs/install.md::installation#1
• owner/repo::docs/install.md::installation/prerequisites#3
• owner/repo::README.md::usage/configuration/advanced-configuration#4
• local/myproject::guide.md::configuration#2

当文件路径、标题文本、标题级别和父标题链不变时，ID在重新索引过程中保持稳定。

______________________________________________________________________

安装

先决条件

• Python 3.10+
• pip

安装

pip install jdocmunch-mcp

验证：

jdocmunch-mcp --help

______________________________________________________________________

配置MCP客户端

PATH注释： MCP客户端通常在受限环境中运行 jdocmunch-mcp 即使它在你的shell中工作，也可能找不到。使用 uvx 是推荐的方法，因为它按需解析包，而不依赖于您的系统PATH。如果你愿意 pip install，请改用可执行文件的绝对路径。

通用可执行路径

• Linux： /home//.local/bin/jdocmunch-mcp
• macOS： /Users//.local/bin/jdocmunch-mcp
• 窗户： C:\\Users\\\\AppData\\Roaming\\Python\\Python3xx\\Scripts\\jdocmunch-mcp.exe

______________________________________________________________________

克劳德桌面/克劳德代码

配置文件位置：

最小配置

{
  "mcpServers": {
    "jdocmunch": {
      "command": "uvx",
      "args": ["jdocmunch-mcp"]
    }
  }
}

带有可选的AI摘要和GitHub认证

{
  "mcpServers": {
    "jdocmunch": {
      "command": "uvx",
      "args": ["jdocmunch-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

对于Anthropic或Gemini来说，基础 uvx jdocmunch-mcp 一旦 存在相应的API密钥。对于OpenAI兼容的提供商，如OpenAI， MiniMax或GLM-5在启动器命令中包含可选依赖项：

{
  "mcpServers": {
    "jdocmunch": {
      "command": "uvx",
      "args": ["--with", "openai", "jdocmunch-mcp"],
      "env": {
        "MINIMAX_API_KEY": "mx-...",
        "JDOCMUNCH_SUMMARIZER_PROVIDER": "minimax"
      }
    }
  }
}

保存配置后， 重新启动克劳德桌面/Claude代码.

Claude代码挂钩（推荐）

jDocMunch提供执法钩子，让你的代理人保持诚实：

• 预工具使用 --当克劳德试图 Read 一个大的文档文件，建议 search_sections + get_section
• 后工具使用 --之后自动重新索引文档文件 Edit/Write 所以指数永远不会过时
• 准紧的 --在上下文压缩之前注入会话快照，以便文档方向得以保留

在一个命令中安装所有内容：

jdocmunch-mcp init

这将检测您的MCP客户端，修补其配置，将文档探索策略安装到CLAUDE.md中，设置强制挂钩，并为您的当前目录建立索引。使用 --dry-run 为了预览， --demo 获取福利摘要，或 --yes 用于非交互模式。

仅适用于挂钩：

jdocmunch-mcp init --hooks

如果你也使用 jCodeMunch，运行以下两项：

jcodemunch-mcp init
jdocmunch-mcp init

CLI子命令

______________________________________________________________________

谷歌反重力

1. 打开“代理”窗格
2. 点击 ⋯ menu → MCP服务器 → 管理MCP服务器
3. 点击 查看原始配置 打开 mcp_config.json
4. 添加以下条目，保存，然后重新启动MCP服务器

{
  "mcpServers": {
    "jdocmunch": {
      "command": "uvx",
      "args": ["jdocmunch-mcp"]
    }
  }
}

龙虾

选项A--CLI（一个命令）：

openclaw mcp set jdocmunch '{"command":"uvx","args":["jdocmunch-mcp"]}'

选项B——直接编辑配置：

将条目添加到 ~/.openclaw/openclaw.json 在...之下 mcpServers:

{
  "mcpServers": {
    "jdocmunch": {
      "command": "uvx",
      "args": ["jdocmunch-mcp"],
      "transport": "stdio"
    }
  }
}

可选AI摘要：

{
  "mcpServers": {
    "jdocmunch": {
      "command": "uvx",
      "args": ["jdocmunch-mcp"],
      "transport": "stdio",
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

重新启动网关并验证：

openclaw gateway restart
openclaw mcp list

每个代理路由（可选）：

{
  "agents": {
    "researcher": {
      "mcpServers": ["jdocmunch", "brave-search", "fetch"]
    }
  }
}

告诉你的OpenClaw代理使用它

如果没有明确的指示，即使jDocMunch已连接，您的代理也会忽略它。创建系统提示文件（例如。 ~/.openclaw/agents/researcher.md)与：

## Documentation Policy
Always use jDocMunch-MCP tools for documentation exploration.
- Before reading a doc file: use search_sections or get_toc
- To retrieve specific content: use get_section with the section ID
- To index local docs: use index_local with the docs folder path
- Never open documentation files directly — navigate by section.

把你的经纪人指进去 ~/.openclaw/openclaw.json:

{
  "agents": {
    "named": {
      "researcher": {
        "systemPromptFile": "~/.openclaw/agents/researcher.md"
      }
    }
  }
}

______________________________________________________________________

使用示例

index_local:          { "path": "/path/to/docs" }
index_repo:           { "url": "owner/repo" }

get_toc:              { "repo": "owner/repo" }
get_toc_tree:         { "repo": "owner/repo" }
get_document_outline: { "repo": "owner/repo", "doc_path": "docs/config.md" }
search_sections:      { "repo": "owner/repo", "query": "authentication" }
get_section:          { "repo": "owner/repo", "section_id": "owner/repo::docs/config.md::authentication#1" }

______________________________________________________________________

工具表面

搜索和检索工具包括 _meta 信封具有时间、代币节省和避免成本的特点。

例子：

"_meta": {
  "latency_ms": 12,
  "sections_returned": 5,
  "tokens_saved": 1840,
  "total_tokens_saved": 94320,
  "cost_avoided": { "claude_opus": 0.0276, "gpt5_latest": 0.0184 },
  "total_cost_avoided": { "claude_opus": 1.4148, "gpt5_latest": 0.9432 }
}

total_tokens_saved 和 total_cost_avoided 在工具调用中积累并持续 ~/.doc-index/_savings.json.

检查您的代币储蓄

每个jDocMunch工具响应都包含一个 _meta 块状 tokens_saved （本次通话）以及 total_tokens_saved （终身）。要查看您的累计储蓄，请让您的代理人调用任何jDocMunch工具（例如。 get_toc 或 search_sections)看看 _meta 信封。终身统计数据保持不变 ~/.doc-index/_savings.json 跨届会议。

______________________________________________________________________

支持格式

– 标题；锅炉板剥离| |OpenAPI/Swagger| .yaml, .yml, .json, .jsonc |OpenAPI 3.x和Swagger 2.x；按标签分组为部分的操作| |JSON/JSONC| .json, .jsonc |顶层按键作为部分；JSONC注释在解析前被剥离| |XML/SVG/XHTML| .xml, .svg, .xhtml` |用于截面结构的元素层次结构|

看 ARCHITECTURE.md 有关解析器的详细信息。

______________________________________________________________________

安全

内置保护包括：

• 路径遍历预防
• 符号链接逃逸保护
• 机密文件排除(.env, *.pem，及类似）
• 二进制文件检测
• 可配置的文件大小限制
• 通过以下方式防止存储路径注入 _safe_content_path()
• 原子索引写入

看 SECURITY.md 了解详情。

______________________________________________________________________

最佳用例

• 代理驱动的文档探索
• 查找配置和API参考部分
• 熟悉不熟悉的框架
• 令牌高效的多代理文档工作流程
• 包含数十个文件的大型文档集

______________________________________________________________________

不适用于

• 源代码符号索引（使用 jCodeMunch 为此）
• 实时文件监视
• 跨存储库全局搜索
• 语义/向量相似性搜索作为一个独立的产品（启用嵌入时支持混合BM25+语义融合——默认为 "auto"，只要配置了提供者，就会打开——但核心工作流仍然是结构优先）

______________________________________________________________________

环境变量

______________________________________________________________________

社区储蓄表

每个工具调用都可以向实时全局计数器贡献一个匿名增量 j.gravelle.us仅发送两个值：

• 已保存令牌
• 随机匿名安装ID

不发送任何内容、文件路径、仓库名称或标识材料。

匿名安装ID只生成一次并存储在 ~/.doc-index/_savings.json.

要禁用报告，请设置：

JDOCMUNCH_SHARE_SAVINGS=0

______________________________________________________________________

贡献

PR欢迎！所有贡献者必须签署 贡献者许可协议 在合并他们的PR之前，CLA Assistant会自动提示您。看 贡献.md 了解详情。

______________________________________________________________________

文档

• 用户指南.md
• 建筑.md
• 规格.md
• 安全.md
• TOKEN_SAVINGS.md

______________________________________________________________________

许可证（双重用途）

此存储库是 免费用于非商业用途 根据以下条款。 商业使用需要付费的商业许可证。

______________________________________________________________________

适用于

jDocMunch可以插入任何兼容MCP的代理或IDE。测试配置：

Hermes Agent config

# ~/.hermes/config.yaml
mcp_servers:
  jdocmunch:
    command: "uvx"
    args: ["jdocmunch-mcp"]

明星历史

______________________________________________________________________

版权和许可文本

版权所有（c）2026 J.Gravelle

1.非商业许可授予（免费）

特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人使用、复制、修改、合并、发布和分发本软件的权限 个人、教育、研究、爱好或其他非商业目的，须符合以下条件：

1. 上述版权声明和本许可声明应包含在软件的所有副本或实质部分中。
2. 对软件所做的任何修改都必须清楚地表明它们来自原始作品，并且原始作者（J.Gravelle）的姓名必须保持不变。他有点自以为是。
3. 以源代码形式重新分发软件必须包括一个突出的通知，说明对原始版本的任何修改。

2.商业用途

软件的商业使用需要作者单独支付商业许可证。

“商业用途”包括但不限于：

• 在商业环境中使用软件
• 营利性组织内部使用
• 整合到提供销售的产品或服务中
• 用于创收、咨询、SaaS、托管或收费服务

商业许可查询： j@gravelle.us https://j.gravelle.us

在获得商业许可证之前，不允许商业使用。

3.免责声明

软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和不侵权保证。

在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而产生、产生或与之相关的任何索赔、损害赔偿或其他责任承担责任，无论是在合同、侵权或其他诉讼中。