Document Operations MCP Server

Language / 语言: English | 中文

Document Operations MCP Server - 一个用于文档处理、转换和自动化的通用MCP服务器。通过统一的API和工具集处理PDF、DOCX、HTML、Markdown等多种格式。

演示

视频

newnewnewn.mov

在这个演示中，我们展示了如何：

在 MCP 客户端中配置 doc-ops-mcp
将 docx 文档转换为 PDF 格式
将转换后的 PDF 文件加上默认水印

1. 快速开始

首先，将 Document Operations MCP 服务器添加到您的 MCP 客户端。

标准配置 适用于大多数 MCP 客户端：

{
  "mcpServers": {
    "doc-ops-mcp": {
      "command": "npx",
      "args": ["-y", "doc-ops-mcp"],
      "env": {
        "OUTPUT_DIR": "/path/to/your/output/directory",
        "CACHE_DIR": "/path/to/your/cache/directory",
      }
    }
  }
}

Claude Desktop

按照 MCP 安装指南，使用上面的标准配置。

VS Code

按照 MCP 安装指南，使用上面的标准配置。

Cursor

转到 Cursor Settings -> MCP -> Add new MCP Server。随意命名，使用 command 类型，命令为 npx -y doc-ops-mcp。

其他 MCP 客户端

对于其他 MCP 客户端，使用上面的标准配置，并参考您的客户端文档进行 MCP 服务器安装。

配置

Document Operations MCP 服务器支持通过环境变量进行配置。这些可以在 MCP 客户端配置中作为 "env" 对象的一部分提供：

{
  "mcpServers": {
    "doc-ops-mcp": {
      "command": "npx",
      "args": ["-y", "doc-ops-mcp"],
      "env": {
        "OUTPUT_DIR": "/path/to/your/output/directory",
        "CACHE_DIR": "/path/to/your/cache/directory",
        "WATERMARK_IMAGE": "/path/to/watermark.png",
        "QR_CODE_IMAGE": "/path/to/qrcode.png"
      }
    }
  }
}

支持的文档操作

格式	转换到PDF	转换到DOCX	转换到HTML	转换到Markdown	内容改写	水印/二维码
PDF	✅	❌	❌	❌	❌	✅
DOCX	✅	✅	✅	✅	✅	❌
HTML	✅	❌	✅	✅	✅	❌
Markdown	✅	✅	✅	✅	✅	❌

改写功能说明：

内容替换：支持文本内容的批量替换和正则表达式替换
格式调整：修改文档结构、标题层级和样式格式
智能改写：保持原文档格式的同时进行内容优化

使用示例

格式转换：

将 /Users/docs/report.docx 转换为 PDF
将 /Users/docs/article.md 转换为 HTML
将 /Users/docs/presentation.html 转换为 DOCX
将 /Users/docs/readme.md 转换为 PDF（带主题样式）

文档改写：

改写 /Users/docs/contract.md 中的公司名称
批量替换 /Users/docs/manual.docx 中的术语
调整 /Users/docs/article.html 的标题层级
更新 /Users/docs/policy.md 中的日期和版本号

PDF增强：

为 /Users/docs/document.pdf 添加水印
为 /Users/docs/report.pdf 添加二维码
为 /Users/docs/invoice.pdf 添加公司logo水印

环境变量

服务器支持环境变量来控制输出路径和PDF增强功能：

核心目录

OUTPUT_DIR: 控制所有生成文件的保存位置（默认：~/Documents）
CACHE_DIR: 临时文件和缓存文件的目录（默认：~/.cache/doc-ops-mcp）

PDF 增强功能

WATERMARK_IMAGE: PDF 文件的默认水印图片路径
- 自动添加到所有 PDF 转换中
- 支持格式：PNG、JPG
- 如果未设置，将使用默认文字水印"doc-ops-mcp"
QR_CODE_IMAGE: PDF 文件的默认二维码图片路径
- 仅在明确要求时添加到 PDF 中（addQrCode=true）
- 支持格式：PNG、JPG
- 如果未设置，二维码功能将不可用

输出路径规则：

如果未提供 outputPath → 文件保存到 OUTPUT_DIR，使用自动生成的名称
如果 outputPath 是相对路径 → 相对于 OUTPUT_DIR 解析
如果 outputPath 是绝对路径 → 按原样使用，忽略 OUTPUT_DIR

详细文档请参见 OUTPUT_PATH_CONTROL.md。

2. 系统架构

Document Operations MCP Server 采用纯 JavaScript 架构设计，提供完整的文档处理能力：

┌─────────────────────────────────────────────────────────────┐
│                    MCP 客户端层                             │
│           (Claude Desktop, Cursor, VS Code等)               │
└─────────────────────┬───────────────────────────────────────┘
                      │ JSON-RPC 2.0
┌─────────────────────┴───────────────────────────────────────┐
│                 Doc-Ops-MCP 服务器                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │   工具路由器    │  │   请求验证器    │  │  响应格式化 │ │
│  │   & 处理器      │  │                 │  │     器      │ │
│  └────────┬────────┘  └────────┬────────┘  └──────┬──────┘ │
│           │                    │                  │        │
│  ┌────────┴────────────────────┴──────────────────┴─────┐ │
│  │                   文档处理引擎                         │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │   文档      │  │   格式      │  │   样式      │   │ │
│  │  │   读取器    │  │   转换器    │  │   处理器    │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │ │
│  │                                                        │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │   PDF       │  │   水印/     │  │   转换      │   │ │
│  │  │   增强      │  │   二维码    │  │   规划器    │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │ │
└────┴───────────────────────────────────────────────────────┴─┘
                            │
┌───────────────────────────┴─────────────────────────────────┐
│                    核心依赖层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   pdf-lib   │  │word-extractor│  │   marked    │          │
│  │   (PDF处理) │  │  (DOCX读取) │  │ (Markdown)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   cheerio   │  │    jszip    │  │    docx     │          │
│  │ (HTML解析)  │  │  (ZIP处理)  │  │ (DOCX生成)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────┐  ┌─────────────┐                           │
│  │   xml2js    │  │ 自定义OOXML │                           │
│  │ (XML解析)   │  │   解析器    │                           │
│  └─────────────┘  └─────────────┘                           │
└─────────────────────────────────────────────────────────────┘

架构说明

核心特性：

纯 JavaScript 实现，无外部系统依赖
完整的文档读取、转换、样式处理能力
内置 PDF 水印和二维码添加功能
智能转换规划和路径优化

转换流程：

直接转换：支持大部分格式间的直接转换
多步转换：复杂转换通过中间格式实现
样式保留：使用 OOXML 解析器确保样式完整性

3. 可选集成说明

本服务器可与 playwright-mcp 配合使用，获得增强的 PDF 转换能力。详细配置请参考 playwright-mcp 官方文档。

🔧 PDF转换工作流程

本服务器支持完整的PDF转换功能：

文档解析：使用OOXML解析器确保样式完整保留
格式转换：将文档转换为高质量HTML格式
PDF生成：内置转换器或可选配合 playwright-mcp 使用
增强处理：自动添加水印和二维码（如果配置）

工作原理

本服务器采用智能转换架构：

智能规划：plan_conversion 分析转换需求，选择最优路径
格式转换：使用专用转换器处理各种文档格式
样式保留：通过 OOXML 解析器确保样式完整性
增强处理：自动添加水印、二维码等增强功能
可选集成：支持与 playwright-mcp 配合获得增强能力

4. 功能特性

MCP 工具

核心文档工具

工具名称	功能描述	输入参数	外部依赖
`read_document`	读取文档内容	`filePath`: 文档路径 `extractMetadata`: 提取元数据 `preserveFormatting`: 保留格式	无
`write_document`	写入文档内容	`content`: 文档内容 `outputPath`: 输出文件路径 `encoding`: 文件编码	无
`convert_document`	智能文档转换	`inputPath`: 输入文件路径 `outputPath`: 输出文件路径 `preserveFormatting`: 保留格式	无
`plan_conversion`	转换规划器	`sourceFormat`: 源格式 `targetFormat`: 目标格式 `preserveStyles`: 保留样式 `quality`: 转换质量	无

read_document

读取各种文档格式，包括PDF、DOCX、DOC、HTML、MD等格式。

参数：

filePath (string, 必需) - 要读取的文档路径
extractMetadata (boolean, 可选) - 提取文档元数据，默认为false
preserveFormatting (boolean, 可选) - 保留格式（HTML输出），默认为false

write_document

将内容写入指定格式的文档文件。

参数：

content (string, 必需) - 要写入的内容
outputPath (string, 可选) - 输出文件路径（不指定则自动生成）
encoding (string, 可选) - 文件编码，默认为utf-8

convert_document

在格式间转换文档，支持样式保留增强。

参数：

inputPath (string, 必需) - 输入文件路径
outputPath (string, 可选) - 输出文件路径（不指定则自动生成）
preserveFormatting (boolean, 可选) - 保留格式，默认为true
useInternalPlaywright (boolean, 可选) - 使用内置Playwright进行PDF转换，默认为false

convert_docx_to_pdf

DOCX转PDF，自动添加水印（如果配置）。

参数：

docxPath (string, 必需) - DOCX文件路径
outputPath (string, 可选) - 输出PDF路径（不指定则自动生成）
addQrCode (boolean, 可选) - 是否添加二维码，默认为false
preserveFormatting (boolean, 可选) - 保留原始格式，默认为true
chineseFont (string, 可选) - 中文字体，默认为Microsoft YaHei

convert_markdown_to_pdf

Markdown转PDF，自动添加水印（如果配置）。

参数：

markdownPath (string, 必需) - Markdown文件路径
outputPath (string, 可选) - 输出PDF路径（不指定则自动生成）
theme (string, 可选) - 主题样式，默认为"github"
includeTableOfContents (boolean, 可选) - 是否包含目录，默认为false
addQrCode (boolean, 可选) - 是否添加二维码，默认为false

convert_markdown_to_html

Markdown转HTML。

参数：

markdownPath (string, 必需) - Markdown文件路径
outputPath (string, 可选) - 输出HTML路径（不指定则自动生成）
theme (string, 可选) - 主题样式，默认为"github"
includeTableOfContents (boolean, 可选) - 是否包含目录，默认为false

convert_markdown_to_docx

Markdown转DOCX。

参数：

markdownPath (string, 必需) - Markdown文件路径
outputPath (string, 可选) - 输出DOCX路径（不指定则自动生成）

convert_html_to_markdown

HTML转Markdown。

参数：

htmlPath (string, 必需) - HTML文件路径
outputPath (string, 可选) - 输出Markdown路径（不指定则自动生成）

plan_conversion

🎯 智能转换规划器 - 分析转换需求并生成最优转换方案。

参数：

sourceFormat (string, 必需) - 源文件格式（pdf, docx, html, markdown, md, txt, doc）
targetFormat (string, 必需) - 目标文件格式（pdf, docx, html, markdown, md, txt, doc）
sourceFile (string, 可选) - 源文件路径（用于生成具体转换参数）
preserveStyles (boolean, 可选) - 是否保留样式格式，默认为true
includeImages (boolean, 可选) - 是否包含图片，默认为true
theme (string, 可选) - 转换主题，默认为github
quality (string, 可选) - 转换质量要求（fast, balanced, high），默认为balanced

process_pdf_post_conversion

参数：

playwrightPdfPath (string, 必需) -生成的PDF文件路径
targetPath (string, 可选) - 目标PDF文件路径（不指定则自动生成）
addWatermark (boolean, 可选) - 是否添加水印，默认为false
addQrCode (boolean, 可选) - 是否添加二维码，默认为false
watermarkImage (string, 可选) - 水印图片路径
qrCodePath (string, 可选) - 二维码图片路径

PDF 增强工具

add_watermark

🎨 PDF水印添加工具 - 为PDF文档添加图片或文字水印。

参数：

pdfPath (string, 必需) - PDF文件路径
watermarkImage (string, 可选) - 水印图片路径（PNG/JPG）
watermarkText (string, 可选) - 水印文字内容
watermarkImageScale (number, 可选) - 图片缩放比例，默认为0.25
watermarkImageOpacity (number, 可选) - 图片透明度，默认为0.6
watermarkImagePosition (string, 可选) - 图片位置，默认为fullscreen

add_qrcode

📱 PDF二维码添加工具 - 为PDF文档添加二维码。

参数：

pdfPath (string, 必需) - PDF文件路径
qrCodePath (string, 可选) - 二维码图片路径
qrScale (number, 可选) - 二维码缩放比例，默认为0.15
qrOpacity (number, 可选) - 二维码透明度，默认为1.0
qrPosition (string, 可选) - 二维码位置，默认为bottom-center
addText (boolean, 可选) - 是否添加说明文字，默认为true

系统要求

Node.js ≥ 18.0.0
零外部系统依赖 - 所有处理通过npm包实现
可选集成：playwright-mcp用于增强PDF转换

核心技术栈

pdf-lib - PDF操作和增强
word-extractor - DOCX文档文本提取
marked - Markdown解析和渲染
cheerio - HTML解析和操作
docx - DOCX文档生成
jszip - ZIP文件处理
xml2js - XML解析和转换
自定义OOXML解析器 - 高级DOCX样式保留

安装

# 全局安装
npm install -g doc-ops-mcp

# 或使用 pnpm
pnpm add -g doc-ops-mcp

# 或使用 bun
bun add -g doc-ops-mcp

架构组件

MCP服务器核心: 处理JSON-RPC 2.0通信和工具注册
智能路由器: 将请求路由至最优处理模块
转换引擎: 包含针对不同文档类型的专用转换器
样式处理器: 确保格式转换中的样式保留
安全模块: 提供路径验证和内容安全处理

5. 开源协议

项目协议

本项目：MIT License
兼容性：可用于商业和非商业项目

第三方依赖协议

依赖库	版本	协议	用途
pdf-lib	^1.17.1	MIT	PDF 文档操作和处理
word-extractor	^1.0.4	MIT	DOCX 文档文本提取
marked	^15.0.12	MIT	Markdown 解析和渲染
cheerio	^1.0.0-rc.12	MIT	HTML 解析和操作
docx	^9.5.1	Apache-2.0	DOCX 文档生成
jszip	^3.10.1	MIT	ZIP 文件处理
xml2js	^0.6.2	MIT	XML 解析和转换

协议兼容性

✅ 商业使用：所有依赖均支持商业使用
✅ 分发：可自由分发和修改
✅ 专利保护：Apache-2.0 提供专利保护
⚠️ 注意事项：使用时需保留原始协议声明

6. 未来规划

核心功能

🔄 增强转换质量：改进复杂文档的样式保留
📊 Excel 支持：完整的 Excel 读写和转换功能
🎨 模板系统：支持自定义文档模板
🔍 OCR 集成：图片文字识别功能

系统改进

🌐 多语言支持：国际化和本地化
🔐 安全增强：文档加密和权限控制
⚡ 性能优化：大文件处理和内存优化
🔌 插件系统：可扩展的处理器架构

版本路线图

v2.0：完整的 Excel 支持和模板系统
v3.0：OCR 集成和多语言支持
v4.0：高级安全功能和插件系统

7. Docker部署

快速开始

使用预构建镜像

# 拉取最新镜像
docker pull docops/doc-ops-mcp:latest

# 使用默认配置运行
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  docops/doc-ops-mcp:latest

从源码构建

# 克隆仓库
git clone https://github.com/JefferyMunoz/doc-ops-mcp.git
cd doc-ops-mcp

# 构建Docker镜像
docker build -t doc-ops-mcp .

# 运行容器
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  -v $(pwd)/documents:/app/documents \
  doc-ops-mcp

Docker Compose部署

创建 docker-compose.yml 文件：

version: '3.8'

services:
  doc-ops-mcp:
    image: docops/doc-ops-mcp:latest
    container_name: doc-ops-mcp
    ports:
      - "3000:3000"
    volumes:
      - ./documents:/app/documents
      - ./config:/app/config
    environment:
      - NODE_ENV=production
      - PORT=3000
    restart: unless-stopped
    
  # 可选：添加Nginx反向代理
  nginx:
    image: nginx:alpine
    container_name: doc-ops-nginx
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - doc-ops-mcp
    restart: unless-stopped

环境变量

变量名	描述	默认值
`PORT`	服务器端口	`3000`
`NODE_ENV`	环境模式	`production`
`LOG_LEVEL`	日志级别	`info`
`MAX_FILE_SIZE`	最大文件大小(MB)	`50`

卷挂载

为持久化存储挂载本地目录：

# 文档目录用于文件处理
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  -v $(pwd)/documents:/app/documents \
  -v $(pwd)/output:/app/output \
  doc-ops-mcp

Docker配置示例

生产环境部署

# 使用Docker Swarm进行生产部署
docker swarm init
docker stack deploy -c docker-compose.yml doc-ops

# 扩展服务
docker service scale doc-ops_mcp=3

健康检查

容器包含内置健康检查：

# 检查容器健康状态
docker ps

# 查看健康检查日志
docker inspect --format='{{.State.Health.Status}}' doc-ops-mcp

# 手动健康检查
docker exec doc-ops-mcp curl -f http://localhost:3000/health || exit 1

8. 开发指南

本地开发

# 克隆项目
git clone https://github.com/your-org/doc-ops-mcp.git
cd doc-ops-mcp

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

项目结构

src/
├── index.ts          # MCP 服务器入口
├── tools/            # 工具实现
│   ├── documentConverter.ts
│   ├── pdfTools.ts
│   └── ...
├── types/            # 类型定义
└── utils/            # 工具函数

添加新工具

在 src/tools/ 中创建新的工具文件
实现工具逻辑
在 src/index.ts 中注册工具
添加测试用例
更新文档

9. 故障排除

常见问题

端口冲突：在docker-compose.yml中修改主机端口
权限问题：确保卷挂载具有正确的权限
内存问题：增加Docker内存分配

调试模式

# 使用调试日志运行
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  -e LOG_LEVEL=debug \
  doc-ops-mcp

# 查看日志
docker logs -f doc-ops-mcp

10. 贡献指南

如何贡献

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

知识产权授权

通过提交 Pull Request，您同意所有通过 Pull Request 提交的贡献都将在 MIT 许可证下授权。 这意味着：

您授予项目维护者和用户在 MIT 许可证下使用、修改和分发您的贡献的权利
您确认您有权进行这些贡献
您理解您的贡献将成为开源项目的一部分
您放弃对贡献代码的独占所有权声明

如果您不能同意这些条款，请不要提交 Pull Request。

代码规范

使用 TypeScript
遵循 ESLint 配置
添加适当的测试
更新相关文档

报告问题

使用 GitHub Issues
提供详细的错误信息和重现步骤
包含系统环境信息

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

Uh oh!

FilesExpand file tree

README_zh.md

Latest commit

History

README_zh.md

File metadata and controls

Document Operations MCP Server

目录

演示

视频

1. 快速开始

配置

支持的文档操作

使用示例

环境变量

核心目录

PDF 增强功能

2. 系统架构

架构说明

3. 可选集成说明

🔧 PDF转换工作流程

工作原理

4. 功能特性

MCP 工具

核心文档工具

read_document

write_document

convert_document

convert_docx_to_pdf

convert_markdown_to_pdf

convert_markdown_to_html

convert_markdown_to_docx

convert_html_to_markdown

plan_conversion

process_pdf_post_conversion

PDF 增强工具

add_watermark

add_qrcode

系统要求

系统要求

核心技术栈

安装

架构组件

5. 开源协议

项目协议

第三方依赖协议

协议兼容性

6. 未来规划

核心功能

系统改进

版本路线图

7. Docker部署

快速开始

使用预构建镜像

从源码构建

Docker Compose部署

环境变量

卷挂载

Docker配置示例

生产环境部署

健康检查

8. 开发指南

本地开发

项目结构

添加新工具

9. 故障排除

常见问题

调试模式

10. 贡献指南

如何贡献

知识产权授权

代码规范

报告问题

许可证