用途
md-vision-mcp 是一个 stdio MCP 服务器，提供两个只读工具，用于对 Markdown 文档进行智能体式 RAG（检索增强生成）。它旨在帮助 AI 智能体高效读取和索引包含图片的 Markdown 文档，避免为每张图片单独调用工具。
主要能力
该服务器提供两个工具：
-
read_md_with_images：读取 Markdown 文件，并将引用的图片以内联图片块（MCP image content）的形式返回。返回内容为 MCP 内容数组，按文档顺序交替出现文本块和图片块（PNG，base64 编码），frontmatter 保留在开头的文本中。每张内联图片前会有一个简短的文本块，携带解析后的图片 URL（对于 data: URI 和其他长引用则省略）。超出 max_images 的图片仍以 Markdown 图片语法保留在文本中。支持本地文件系统路径和 http(s):// URL。本地路径必须位于配置的 --allow-path 目录下。相对图片路径相对于 Markdown 文件位置或文档 URL 解析。图片可使用 Markdown 语法或 HTML <img src="..."> 标签。可选限定到特定章节或行范围。
-
index_md：为文件、URL 或 Markdown 文件夹返回紧凑的标题索引。返回 Markdown 字符串。对于每个文件，包含：YAML frontmatter（如果存在）；一个围栏 tsv 代码块，列包括 heading、line_start、n_images、char_count。每个文件被包裹在特定结构中。文件夹 URI 值会递归扫描 *.md / *.markdown 文件，按稳定排序顺序处理。围栏代码块内的标题不会被索引。
典型流程：先调用 index_md 发现标题和结构，再对所需章节调用 read_md_with_images。
使用方式
安装：通过 MCP 客户端配置。已发布包：npm 上的 md-vision。
在智能体配置（如 .agents/mcp.json 或类似文件）中，将 MCP 主机指向该服务器。示例配置支持远程 Markdown（允许所有 HTTP(S) 主机，或列出特定域名）。
服务器在启动时如果省略 --allow-path 或 --allow-domain 则会退出。更改配置后需重启 MCP 主机。
限制允许的路径和域名：等效形式包括 --allow-path=/path、--allow-domain=host.example、--allow-domain=all、--allow-domain=none。不要将裸 * 作为单独的 shell 参数传递——shell 会将其扩展为当前目录中的文件名。请改用 all 或 --allow-domain=all。
适用场景
- 对本地文档或允许的 URL 进行智能体式 RAG。
- 需要读取包含内联图片的 Markdown 文档，并希望减少工具调用次数的场景。
- 需要先索引标题结构再进行定向读取的文档导航场景。
限制
- 服务器在启动时如果省略 --allow-path 或 --allow-domain 则会退出。
- 本地路径必须位于配置的 --allow-path 目录下。
- 不要将裸 * 作为单独的 shell 参数传递。
- 围栏代码块内的标题不会被索引。
- 超出 max_images 的图片仍以 Markdown 图片语法保留在文本中。
部署说明
stdio MCP 服务器作为调用它们的智能体运行时的子进程运行。常见两种部署模式：
- Agent-in-sandbox（运行时共享智能体的文件系统）：服务器可以就地读取文档；将 --allow-path 限定到打算暴露的文档树。
- Sandbox-as-tool（运行时文件系统与工具沙箱不同）：MCP 进程通常在运行时环境中运行，因此 Markdown 必须复制或同步到服务器可读取的位置。
基准测试（进行中）
参见 benchmark/ 目录中的 MMLongBench-Doc A/B 测试框架，比较仅文件系统的智能体式 RAG 与使用 md-vision MCP 工具的同一智能体。
独立索引
md-vision 也可作为库使用，用于在 MCP 主机之外索引 Markdown——例如用于智能体式 RAG 的离线预处理管道。
安装包后，可使用 indexMarkdownText 索引内存中的 Markdown 内容，使用 indexMarkdownFile 加载并索引本地 Markdown 文件，使用 indexMarkdownFolder 递归索引 *.md 和 *.markdown 文件（按稳定排序顺序）。每个被索引的文件返回结构化数据。索引使用 Markdown AST 而非正则匹配，因此围栏代码块内的标题会被忽略。
