md-vision

md-vision MCP 服务

stdio MCP 服务，提供两个只读工具，用于基于 Markdown 文档进行 Agentic RAG：

• read_md_with_images — 返回 Markdown 内容，并将引用的图片作为穿插其中的图片块返回。读取时无需为每张图片额外调用一次工具。可选按特定章节或行范围限定内容。
• index_md — 返回文件、URL 或 Markdown 文件文件夹的紧凑标题索引。用于动态索引文件，以便有针对性地读取。

典型流程：调用 index_md 查找标题和结构，然后对需要的章节调用 read_md_with_images。

安装：MCP 客户端配置

已发布的软件包：npm 上的 md-vision

在 Agent 配置文件（.agents/mcp.json 或类似文件）中，将 MCP 宿主指向此服务。示例：

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "none"
      ]
    }
  }
}

使用远程 Markdown（允许所有 HTTP(S) 主机，或列出特定域名）：

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "all"
      ]
    }
  }
}

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "raw.githubusercontent.com"
      ]
    }
  }
}

如果省略 --allow-path 或 --allow-domain，服务会在启动时退出。

更改配置后，请重启 MCP 宿主。

限制允许的路径和域名

标志	必填	作用
--allow-path <dir>	是（至少一个）	本地文件必须解析到某个允许的目录下（可重复指定）。
--allow-domain <host>	是（至少一个）	控制 HTTP(S) 访问。使用 all 允许任意主机，使用 none 禁用 URL（仅限本地文件），也可以列出特定主机（可重复指定；支持后缀匹配，例如 example.com 可允许 docs.example.com）。

等效形式：--allow-path=/path、--allow-domain=host.example、--allow-domain=all、--allow-domain=none。

不要将单独的 * 作为参数传入 shell——shell 会将其展开为当前目录中的文件名。请改用 all 或 --allow-domain=all。

要求

• Node.js 20+

工具

read_md_with_images

读取 Markdown 文件，并将引用的图片以内嵌 MCP 图片内容的形式返回。

参数	类型	说明
uri	string	本地路径或 http(s):// URL
section	string，可选	要读取的精确标题，例如 ## Introduction（匹配时使用；否则回退到 line_range）
line_range	[start, end]，可选	文档行范围，起止行均包含，行号从 1 开始（未提供 section 或未找到标题时使用）
max_images	integer，可选	内嵌图片的上限（默认 10，最大 50）

返回： MCP 内容数组——按文档顺序交替包含 text 和 image 块（PNG、base64）；前置元数据保留在开头的文本中。每张内嵌图片前都会附带一个简短的 text 块，其中包含解析后的图片 URL（data: URI 和其他较长的引用除外）。超过 max_images 上限的图片会保留为文本中的 Markdown 图片语法。

URI 形式： 本地文件系统路径和 http(s):// URL。本地路径必须位于已配置的 --allow-path 目录下。相对图片路径会根据 Markdown 文件位置或文档 URL 解析。图片可使用 Markdown ![](...) 语法或 HTML <img src="..."> 标签。

index_md

在有针对性地读取内容前，先为导航建立标题索引。

参数	类型	说明
uri	string	Markdown 文件、http(s):// URL 或本地文件夹

返回： Markdown 字符串。对于每个文件：

1. 存在时返回 YAML 前置元数据。
2. 返回一个带围栏的 tsv 代码块，包含以下列：heading、line_start、n_images、char_count。

每个文件都包装在：

<file path="..." lines=X chars=Y>
...
</file>

文件夹形式的 uri 会按稳定排序递归扫描 *.md / *.markdown。围栏代码块中的标题不会编入索引。

使用此 MCP 服务部署 Agent 的说明

stdio MCP 服务作为调用它的 Agent 运行时的子进程运行。常见的部署模式有两种：

• Agent 在沙箱中（运行时与 Agent 共用文件系统）：服务可以就地读取文档；请将 --allow-path 限定为你要公开的文档目录。
• 沙箱作为工具（运行时文件系统与工具沙箱不同）：MCP 进程通常在运行时环境中运行，因此必须将 Markdown 文件复制或同步到服务可读取的位置。

基准测试（进行中）

请参阅 benchmark/，了解 MMLongBench-Doc A/B 测试框架，该框架将仅使用文件系统的 Agentic RAG 与使用相同 Agent 和 md-vision MCP 工具的方案进行比较。

独立索引

当你想在 MCP 宿主之外为 Markdown 建立索引时，也可以将 md-vision 用作库，例如用于 Agentic RAG 的离线预处理流水线。

安装软件包：

npm install md-vision

为 Markdown 文本建立索引

如果 Markdown 内容已在内存中，请使用 indexMarkdownText。

import { indexMarkdownText } from "md-vision";

const markdown = `# Guide

Intro text.

## Setup

![diagram](./setup.png)
`;

const index = indexMarkdownText(markdown);

console.log(index.rows);

结果示例：

[
  {
    heading: "# Guide",
    lineStart: 1,
    imageCount: 1,
    charCount: 42
  },
  {
    heading: "## Setup",
    lineStart: 5,
    imageCount: 1,
    charCount: 24
  }
]

为文件建立索引

使用 indexMarkdownFile 加载本地 Markdown 文件并为其建立索引。

import { indexMarkdownFile } from "md-vision";

const index = await indexMarkdownFile("./docs/guide.md");

await saveToVectorStoreMetadata({
  path: index.path,
  frontmatter: index.frontmatter,
  headings: index.rows,
});

为文件夹建立索引

使用 indexMarkdownFolder 按稳定的排序顺序递归为 *.md 和 *.markdown 文件建立索引。

import { indexMarkdownFolder } from "md-vision";

const files = await indexMarkdownFolder("./docs");

for (const file of files) {
  console.log(file.path, file.rows);
}

输出结构

每个已索引文件都会返回结构化数据：

type MarkdownFileIndex = {
  path?: string;
  frontmatter: string;
  lineCount: number;
  charCount: number;
  rows: HeadingIndexRow[];
};

type HeadingIndexRow = {
  heading: string;
  lineStart: number;
  imageCount: number;
  charCount: number;
};

由于索引使用的是 Markdown AST，而不是正则表达式匹配，因此会忽略围栏代码块中的标题。