内容
opendoc-mcp
<p align="center">
<img src=".svg" alt="opendoc-mcp logo" width="200" height="auto">
</p>
**高性能 Rust 文档处理服务器，专为 AI 代理设计。**
`opendoc-mcp` 是一个纯 Rust 实现的 [模型上下文协议（MCP）://modelcontextprotocol.io/) 服务器，为 AI 助手（如 Claude、ChatGPT、Cursor、VS Code 等）提供直接、原生的访问，以创建、读取、转换和管理 Office 文档和 PDF 文件 —— **无需外部依赖、LibreOffice、云 API 或重量级运行时**。
```text
一个二进制文件。零依赖。所有格式。极速运行。
```
---
## 功能特点
的格式
| 格式 | 读取 | 编辑转换到 |
|--------|------|------------|
| **DOCX** | ✅ | ✅ | ✅ | PDF, Markdown, JSON |
| **PPTX** | ✅ | ✅ | ✅, JSON |
| ** ✅ | ✅ | ✅ | 文本提取，JSON |
| **XLSX** | ✅ | ✅ | — | CSV, JSON |
| **HTML** | ✅ | ✅ | — | JSON |
| **Markdown** | — | ✅ | — | JSON |
| **CSV** | — | — | JSON |
| **TXT** | — | ✅ | — | JSON |
### 统一工具和功能
**文档智能**
- `open_document` — 打开返回结构化 JSON（支持 `detail_level`：`full`、`summary`、`metadata_only`）
- `read_document_text` — 从任意文档中提取纯文本
- `search_document` — 查找关键词或正则表达式匹配
- `replace_text` — 基于正则表达式的文本替换（在 IR 上操作）
- `diff_documents` — 基于 LCS 的段落级文档比较
- `chunk_for_embedding` — 用于 RAG / 嵌入的文本分块
- `fill_template` — 模板变量替换（接受原始 JSON `variables` 对象）
- `validate_document` — 检查完整性
**格式转换**
- `convert` — 跨格式转换（DOCX↔PDF、DOCX→MD、XLS→CSV 等）
- `create_html` — 将文档转换为样式化的 HTML
处理**
- `batch_convert` — 整个文档目录的并行转换
**作者和编辑**
- **DOCX**：`create_docx`、`docx_add_paragraph`、`docx_add_table`、`docx_add_image`
- **PPTX**：`create_pptx`、`pptx_add_slide`
- **XLSX**：`create_xlsx`（接受原始 JSON `sheets`- **PDF**：`create_pdf`、`dfs`、`extract_pdf_text`、`list_pdf_fields`、`fill_pdf_form`（接受原始 JSON `values）
**元**
- `find — 提取表格坐标数据
- `analyzeity` — 复杂度分析（OCR 需求、页面
**AI 功能**
ocr_document` — 扫描特征门控 OCR `--features ocr` `check_ocr_available 检查 OCR 引擎状态实用工具**
- `list_capabilities` — 所有综合类别列表
---
## MCP`opendoc-m 直接将文档作为只 资源公开：
- `doc://{absolute_path}` —文档的纯文本内容
- `doc://{absolute_path}/outline` — 公开文档的 JSON 大纲（章节、标题层次结构）
可以被代理直接读取，无需工具调用，使用标准的资源读取请求。
---
## 结构化错误（“错误作为）
所有工具错误都返回结构化的 JSON 有效载荷，以帮助 AI 代理动态```json
{
": "错误的详细描述 "error_code":_IO_ERROR",
"",
"suggestion": "验证文件是否存在于指定路径..."
}
```
---
## 快速入门
### 安装
```bash
cargo install opendoc-mcp
```
源代码构建：
```bash
git clone https.com/yourusername/op-mcp.git
cd opendoc-mcp
cargo build --release
./target/release/opendoc-mcp
```
### 配置
#### Claude Desktop
添加到您的 `claude_desktop_config.json`：
```json
{
"mcp {
"opendoc-mcp": {
"command": "/path/to/opendoc-mcp"
}
}
}
```
#### VS Code（Cline / Roo Code）
添加到您的 MCP 设置：
{
"servers": {
"opendoc": {
"commandpath/to/opendoc"
}
}
}
```
#### Cursor
在 Cursor 设置 → MCP 服务器 → 添加中配置：
```
名称：-mcp
类型：stdio
命令：/pathendoc-mcp
## 性能
`-mcp` 设计用于 AI 代理工作负载，每重要：
| 指标 | `opendoc-m（Rust） | Node.js-based MCP | Python-based MCP |
|--------|---------------------|-------------------|-------------------|
| 二进制大小 | ~5 MB | ~50 MB+（带 node_modules）30 MB+（带 venv） |
| 启动时间 | < 10 ms | ~200-500 ms | ~300-800 ms |
| 内存（空闲） | ~3-5 MB | ~30-50 MB | ~40-80 MB |
| DOCX 读取 | ~2 ms | ~15 ms | ~25 ms |
| PDF 合并（5 个文件） | ~8 ms | ~60 ms | ~100 ms |
---
## 架构
```
────────│ MCP 主机） │
│ Claude / Cursor / VS Code / 自定义 │
└──────────────┬────────────────────────── │ JSON-RPC over stdio
▼
┌────────────────────────────────────────│ opendoc-mcp 服务器 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ DOCX │ │ PPTX │ │ PDF │ │
│ │ 处理器 │ │ 处理器 │ │处理器 │ │
│ └────┬─────┘ └────┬─────┘─┬────┘ │
│ │ │ │
│ ┌────┴──────────────────┴────┐ │
│ │ 核心（rmcp │ │
│ MCP 协议 · 传输 · 工具 │ │
│ └─────────────────────────────────────┘ │
└────────────────────────────────
```
**关键设计决策：**
- **文件** — 无，无 npm/pip，无- **stdio 传输** — 零网络，立即启动
纯 Rust** — 内存安全、可预测的性能
- **模块化处理器** — 每个格式都是隔离的；添加新格式非常简单
---
## 开发
```bash
# 检查编译
cargo check
# 运行测试
cargo test
# 构建发布版本
cargo build --release
# 运行并启用日志记录
RUST_LOG=debug cargo run
```
### 项目结构
```
opendoc-mcp/
├── Cargo.toml
├── README.md
├── assets/ # Logo，品牌
├── benches/ # Criterion 基准测试
├── docs/
│ ├── architecture.md
│ ├── changelog.md
│ ├── implementationplan.md
│ ├── spec.md
│ └── superpowers/ # 高级用法指南
├── src/
│ ├── main.rs # 入口点：MCP 服务器或 CLI
│ ├── lib.rs # 模块导出
│ ├── server.rs # MCP #[tool] 定义
│ ├── cli.rs # CLI 子命令（clap）
│ ├── ir/ # 内部表示（文档、段落等）
│ ├── engine/ # 搜索、替换、模板、差异、复杂度
│ ├── handlers/ # docx/pptx/pdf/xlsx/html/md/csv/pdf_forms
│ ├── converters/ # 跨格式转换
│ ├── batch/ # Rayon 并行批量处理
│ ├── validators/ # 文档结构验证
│ ├── ocr/ # 特征门控 OCR（--features ocr）
│ └── security.rs # 路径验证沙盒
└── tests/
└── common/ # 共享测试工具
```
---
## 路线图
**v0.0.2 ✅** — IR 引擎、格式扩展（XLSX、HTML、MD、CSV）、批量处理、CLI、基准测试、文档注释
**v0.0.3 ✅** — 增强的模板引擎、多页 PDF 布局、DOCX 图片插入、80%+ 测试覆盖率
**v0.0.4 ✅** — 用于 RAG 的文本分块、图片提取、PDF 按范围拆分、密码支持
**v0.0.5 ✅** — 批量操作转换 CLI/MCP 工具扩展、直接转换性能分析
**v0.0.6 — 电子表格写入、更新和编辑支持（XLSX）
**v0.7 ✅** — 视觉文档差异（arkdown 高亮）
**v08 ✅**增强的 DOCX/PPTX 样式
**v0.0.9 ✅** — 扫描 PDF 集成
0.0 ✅** — 文档截图）、递归 ZIP摘要和域模板**v0.0.12 ✅** — WASM 目标支持和 PDF/A 合规性验证器
**.1.0** — 数字式 HTTP 传输、安全强化
**v1.0.0** — 生产就绪：、完整的
查看 [docs/.md](docs/implementationplan.md) 获取详细信息。
## 本地安装和更新
在用户空间编译并全局安装二进制文件（安装到 `~/.local/bin/`）：
```bash
./localinstall.sh
```
当您对源代码进行拉取新更新时，请重新编译并更新全局安装：
```bash
update.sh
```
---
## 系统需求和性能
`opendoc-m 设计为极其轻量和高性能：
RAM**：~3-5 MB（空闲），在批量处理或 OCR 时最高可达 ~20-30 MB。
- **ROM（存储）**：~5 MB（单个自包含编译二进制文件）。
- **处理器**：完全支持单核或多核 x86_64 和 ARM 处理器。批量转换和复杂解析会自动在多个核心上扩展，使用 `rayon`。
- **速度**：启动时间小于 10ms。文本提取、替换、模板解析和转换等操作通常在 2-15ms 内执行。
---
## 与其他 MCP 服务器的比较
| 功能 | `-mcp`（） | `opendocswork-m | `spreadcp` |
|---------|----------------------------|--------------------|-------------------|
| **语言纯 Rust | / Python | Go / Python |
| **空闲内存** | **~3-5 MB** | ~40-70 MB | ~30-60 MB |
|时间** | **< 10ms** |-800ms | ~200-500ms |
| **外部依赖** | **无**（自包含） | 需要 LibreOffice / Node | 需要外部库 |
| **ZIP 存档提取和摘要** | **是**（递归） | 否 | 否 |
|模态视觉推理 **是**（渲染到图片目录） | 否 | 否 |
| ** 合规性验证是**字体、加密检查 否 | 否 |
|化元数据 **是**、财务、） | 否 |---
## 为什么 AI工具选择 Rust？代理需要工具- ** — 毫秒级需预热
轻量级** — 最小化 RAM/C便多个代理并行运行
- **可靠 无垃圾回收暂停崩溃
- **可移植** — 平台（Linux、macOS、Windows）的单个
Rust 提供了功能。大多数文档 MCP 服务器目前是 Node.js —— `opendoc` 是第一个纯 Rust品。
---
许可证
MIT 许可证 — 查看 [LICENSE]( 获取详细信息。
---
## 贡献
欢迎贡献！的领域：
- PDF 布局和- 用于文档生成的（嵌套对象- DOCX 图片插入
- WASM目标
- 附加格式支持（ODT）
