内容
# MarkItDown 网页界面 2
[English](README.md) | [简体中文](README.zh-CN.md)
本地文档转 Markdown 网页界面，支持图片 OCR 和自动 MCP 集成，适用于 **Claude Code、Codex 和 Hermes Agent**。
- 私有本地网页界面，地址为 `http://localhost:5001`
- 微软 MarkItDown，支持 PDF、Office、HTML、数据和文本文件
- 无限 OCR MLX Int4，适用于 Apple Silicon，支持布局感知 OCR
- 快速 OCR PP-OCRv6 小型模型，支持 NVIDIA CUDA 和自动 CPU 降级，适用于 Windows
- Tesseract 备用方案，支持快速中文和英文 OCR
- 本地 stdio MCP 服务器，无需 API 密钥，无需云上传
## 一键安装（macOS）
```bash
curl -fsSL https://raw.githubusercontent.com/nfeuism/markitdown-webui2/main/scripts/bootstrap.sh | bash
```
安装完成后打开：
```bash
open http://localhost:5001
```
安装程序会自动：
1. 安装 `uv` 并创建隔离的 Python 3.12 运行环境；
2. 安装网页界面、MarkItDown 和 MCP 服务器依赖项；
3. 安装 Apple Silicon MLX OCR 运行环境；
4. 下载并缓存约 2.35 GB 的本地 OCR 模型；
5. 安装 Homebrew 可用时的 Tesseract 语言数据；
6. 启动私有 macOS LaunchAgent，支持登录和崩溃后重启；
7. 在 Mac 上找到的所有支持的代理 CLI 中注册 MCP 服务器。
该命令可安全地再次运行以更新或修复安装。如果您希望在执行脚本之前检查脚本，请克隆存储库并在本地运行 `./install.sh`。
## 一键安装（Windows）
打开 **PowerShell** 并运行：
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/nfeuism/markitdown-webui2/main/scripts/bootstrap.ps1 | iex"
```
然后打开网页界面：
```powershell
Start-Process http://localhost:5001
```
安装程序会检测 `nvidia-smi`。在支持的 NVIDIA 系统上，它会安装捆绑的 PP-OCRv6 小型中英文模型的 ONNX Runtime CUDA。如果 CUDA 不可用或 GPU 推理失败，**Auto** 会立即在 CPU 上重试相同的小型模型。没有 NVIDIA 硬件的 PC 会直接安装 CPU 运行环境。请参阅 [中文指南](README.zh-CN.md)，了解先决条件、管理命令、MCP 设置和故障排除。
## 网页界面工作流程
1. 拖入文档、截图或扫描图像。
2. 对于图像，请保持 **OCR 引擎 → 自动**，除非您需要强制使用某个引擎。
3. 预览 Markdown。
4. 选择 **下载 Markdown**。
在 Apple Silicon 上，**自动** 首先使用 Unlimited-OCR。在 Windows 上，它会尝试 RapidOCR NVIDIA CUDA，然后尝试 RapidOCR CPU。Tesseract 仍然是最终的备用方案，支持 JPG、PNG、WebP、BMP 和 TIFF 等图像格式。其他支持的输入格式包括 PDF、Word、PowerPoint、Excel、HTML、CSV、JSON、XML、TXT 和 Markdown。
## 代理 MCP 集成
相同的安装程序会检查以下命令并注册一个名为 `markitdown-webui2` 的用户级 stdio 服务器：
| 客户端 | 安装程序使用的注册方式 |
|---|---|
| Codex | `codex mcp add markitdown-webui2 -- …/python …/mcp_server.py` |
| Claude Code | `claude mcp add --scope user --transport stdio markitdown-webui2 -- …` |
| Hermes Agent | `hermes mcp add markitdown-webui2 --command …/python --args …/mcp_server.py` |
重启已经运行的代理会话后，您可以询问：
```text
使用 markitdown-webui2 对 ~/Desktop/receipt.png 进行 OCR，并将 Markdown 保存在旁边。
```
MCP 服务器公开：
| 工具 | 用途 |
|---|---|
| `ocr_status` | 显示可用的 OCR 引擎和模型缓存状态。 |
| `convert_file` | 转换任何支持的本地文档或图像。 |
| `ocr_image` | 使用自动、无限 OCR、RapidOCR GPU/CPU 或 Tesseract 对图像进行 OCR。 |
重新注册已安装的客户端：
```bash
~/Library/Application\ Support/MarkItDownWebUI2/runtime/install-mcp.sh
```
在 Windows 上：
```powershell
& "$env:LOCALAPPDATA\MarkItDownWebUI2\runtime\install-mcp.ps1"
```
此设置遵循 [Codex](https://developers.openai.com/codex/mcp/)、[Claude Code](https://code.claude.com/docs/en/mcp) 和 [Hermes Agent](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/mcp.md) 记录的当前 stdio MCP 配置。
## 状态和控制
使用一键安装设置：
```bash
RUNTIME="$HOME/Library/Application Support/MarkItDownWebUI2/runtime"
"$RUNTIME/status.sh"
"$RUNTIME/restart.sh"
"$RUNTIME/stop.sh"
"$RUNTIME/start.sh"
"$RUNTIME/uninstall.sh"
```
健康检查端点：
```bash
curl http://localhost:5001/health
curl http://localhost:5001/api/ocr-capabilities
```
## 安装程序选项
环境变量可以更改默认值：
```bash
# 使用另一个端口和上传限制
PORT=5055 MAX_FILE_SIZE_MB=250 ./install.sh
# 安装时不立即下载模型
DOWNLOAD_OCR_MODEL=0 ./install.sh
# 跳过代理 MCP 注册
INSTALL_MCP=0 ./install.sh
# 使用另一个兼容的 MLX 视觉模型
MARKITDOWN_OCR_MODEL=owner/model ./install.sh
```
通过 MLX 实现的无限 OCR 需要 Apple Silicon Mac。其他 Mac 可以使用已安装的 Tesseract。网页界面仅绑定到 `127.0.0.1`；它不对 LAN 或互联网公开。
## 手动开发设置（macOS）
```bash
git clone https://github.com/nfeuism/markitdown-webui2.git
cd markitdown-webui2
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt -r requirements-local-ocr.txt
.venv/bin/python serve.py
```
运行检查：
```bash
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall app.py converter_service.py local_ocr.py mcp_server.py
bash -n install.sh install-mcp.sh scripts/bootstrap.sh
```
## 存储和隐私
- 运行环境：`~/Library/Application Support/MarkItDownWebUI2/runtime`
- 引导程序管理的源代码：`~/Library/Application Support/MarkItDownWebUI2/source`
- 模型缓存：`~/.cache/huggingface`
- 服务日志：`~/Library/Application Support/MarkItDownWebUI2/runtime/logs/webui.log`
- 临时上传：自动有资格在 1 小时后清理
OCR 和转换在本地进行。应用程序不需要 API 密钥，也不会将输入文件上传到外部服务。第一个模型安装会从 Hugging Face 下载模型文件。
## 鸣谢
围绕 [微软 MarkItDown](https://github.com/microsoft/markitdown)、[百度 Unlimited-OCR](https://huggingface.co/baidu/Unlimited-OCR)、[RapidOCR](https://github.com/RapidAI/RapidOCR)、MLX、ONNX Runtime 和 Tesseract 构建。本存储库独立维护，不是 GitHub 分叉。
## 许可证
MIT。请参阅 [LICENSE](LICENSE)。
