内容
# zed-markitdown-mcp
给你的 AI 代理一个 `convert_to_markdown` 工具，让它可以 **读取 PDF、DOCX、XLSX、PPTX 和图像** — 而且读取 **非常便宜**。将微软的 [`markitdown`](https://github.com/microsoft/markitdown) 连接到 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 上下文服务器，为 [Zed](https://zed.dev) 提供自愈健康检查，以证明它有效。
## 它做什么
Zed 的代理与文本一起工作。单独使用时，它无法读取二进制文档 — PDF 或 Word 文件对其来说是不透明的。这将 `markitdown` 注册为 MCP **上下文服务器**，为代理提供 `convert_to_markdown` 工具。指向 **文件路径或 URL**，它会返回干净的 Markdown：
- **PDF**、**DOCX**、**XLSX**、**PPTX**
- **图像**（PNG / JPG）
- HTML、CSV、JSON 等
代理通过 **路径** 读取文档 — 你给它路径，它会转换并读取。参见 [用法](#用法)。
## 为什么值得：节省令牌
重点不仅仅是“代理可以读取 PDF” — 而是 **多么便宜**。当代理读取 PDF 原始方式时，**每一页都会将提取的文本和页面的渲染图像发送到模型**（~1,500–3,000 个令牌每页）。`markitdown` 只提取 **文本**，完全跳过图像层。
对于富含文本的 PDF，大约 **10–18 倍减少令牌**:
> 15 页文本 PDF ≈ **22,000–45,000 个令牌** 原始读取 vs. ≈ **2,000–2,500 个令牌** 通过 markitdown。
**权衡 — 只有文本。** 跳过图像层意味着你会失去视觉效果。对于 **扫描的 PDF、图表、图表或布局繁重的页面**，让代理原始读取反而 — 那正是在页面图像承载信息的场景。
| 文档 | 使用 markitdown | 原始读取 |
|---|:---:|:---:|
| 文本 PDF、报告、合同、电子邮件线程 | ✅ 大量节省令牌 | |
| DOCX / XLSX / PPTX | ✅ 干净的 Markdown + 表格 | |
| 扫描 PDF、图表、图表、截图 | | ✅ 需要图像层 |
```
代理 ──stdio MCP──▶ uvx markitdown-mcp ──▶ markitdown ──▶ Markdown 文本
```
## 要求
- [Zed](https://zed.dev)（或任何 MCP 客户端 — 参见安装说明下的备注）
- [`uv`](https://docs.astral.sh/uv/)，提供 `uvx`：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
```
`uv` 管理其自己的 Python，因此您不需要单独安装 Python 3.10+。
## 安装
### 1. 预热缓存并验证（先执行此操作）
```bash
./install.sh
```
这将定位 `uvx`，下载 `markitdown-mcp` 一次，针对生成的样本文件运行健康检查，并打印确切的设置代码片段 — 带有您机器的正确 **绝对** `uvx` 路径。
### 2. 将上下文服务器添加到 Zed
打开您的 Zed `settings.json`（`cmd`/`ctrl` + `,`) 并添加一个 `context_servers` 块：
```jsonc
{
"context_servers": {
"markitdown": {
"command": "uvx",
"args": ["markitdown-mcp"],
"env": {}
}
}
}
```
> **macOS 提示：** 从 Dock 启动的 Zed 不总是继承您的 shell `PATH`，因此一个裸 `uvx` 可能会“找不到”。使用 **绝对** 路径代替（例如 `/opt/homebrew/bin/uvx`）。`install.sh` 为您打印正确的路径。
设置位置：
| 操作系统 | 路径 |
|----|------|
| macOS / Linux | `~/.config/zed/settings.json` |
| Windows | `%APPDATA%\Zed\settings.json` |
Zed 热加载设置；`markitdown` 服务器应该出现在代理面板中。如果它没有出现，请重新启动 Zed 或打开一个新的代理线程。
> **使用 Claude Code（或其他 MCP 客户端）？** `context_servers` 仅向 Zed 的 **原生** 代理提供 — 外部代理（例如通过 ACP 的 Claude Code）看不到它。请在其他客户端中注册相同的服务器。以 Claude Code 为例：
> ```bash
> claude mcp add markitdown -s user -- uvx markitdown-mcp
> ```
## 用法
1. 获取文件的路径 — 在 Zed 中，右键单击项目树中的文件 → **复制路径**（或使用任何绝对路径 / URL）。
2. 在 **代理** 线程中，粘贴路径并询问：*“使用 markitdown 读取此文档”*。
3. 代理调用 `convert_to_markdown` 并读取它。
要强制在 PDF 上使用廉价的文本路径，请说 *“使用 markitdown”*。对于扫描或视觉 PDF，请让代理原始读取。
> **这是基于路径的，不是拖放。** 将二进制文件放入 Zed 的聊天中不会附加它 — Zed 的聊天只接受文本，因此它会使用 *“二进制文件不受支持”* 拒绝 PDF/DOCX。 这是 Zed 的限制，此工具不会更改；工作流程是给代理 **路径** 并让它转换。
## 验证
随时重新运行健康检查：
```bash
python3 verify_markitdown_mcp.py # 自我测试（自动生成的样本）
python3 verify_markitdown_mcp.py mydoc.pdf file.docx # 测试您自己的文件
```
`RESULT: PASS` 表示 MCP 服务器是健康的，并且实际转换文件。检查器执行的操作：
- 驱动完整的 MCP stdio 握手（`initialize` → `tools/list` → `tools/call`），
- 实际转换文件并断言返回非空 Markdown，
- 无参数时，生成一个临时样本 PDF 和 DOCX（无第三方依赖，无个人数据），
- 如果因 **暂时性网络** 故障而失败，则重试整个扫描并延迟重试。
## 故障排除
| 症状 | 原因 / 修复 |
|---------|-------------|
| 服务器显示为错误 | 几乎总是 `PATH`。在您的配置中使用绝对 `uvx` 路径。 |
| 首次启动缓慢 | 首次运行下载软件包（一次）。后续启动使用 `uv` 缓存。 |
| `uvx: command not found` | 安装 `uv`（参见要求）并重新打开客户端。 |
| 健康检查因网络错误而失败 | 脚本自动重试；如果持续，请检查连接到 `pypi.org` 的连接。 |
| 代理以“昂贵的方式”读取 PDF | 它不会自动更喜欢 markitdown — 告诉它 *“使用 markitdown”* 以强制文本路径。 |
## 致谢
- [microsoft/markitdown](https://github.com/microsoft/markitdown) — 转换引擎和 `markitdown-mcp` 服务器。
- [模型上下文协议](https://modelcontextprotocol.io)
- [Zed](https://zed.dev)
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
