hub / github.com/Tele-AI/doc-ops-mcp

github.com/Tele-AI/doc-ops-mcp @main

Chat with this repo

repository ↗ · DeepWiki ↗ · + Follow

453 symbols 954 edges 15 files 225 documented · 50%

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

Document Operations MCP Server

Language / 语言: English | 中文

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

演示

视频

https://github.com/user-attachments/assets/43dfeeec-8097-413e-8519-a7de98e31136

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

在 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
如果未设置，二维码功能将不可用

输出路径规则： 1. 如果未提供 outputPath → 文件保存到 OUTPUT_DIR，使用自动生成的名称 2. 如果 outputPath 是相对路径 → 相对于 OUTPUT_DIR 解析 3. 如果 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转换功能： 1. 文档解析：使用OOXML解析器确保样式完整保留 2. 格式转换：将文档转换为高质量HTML格式 3. PDF生成：内置转换器或可选配合 playwright-mcp 使用 4. 增强处理：自动添加水印和二维码（如果配置）

工作原理

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

4. 功能特性

MCP 工具

核心文档工具

工具名称	功能描述	输入参数	外部依赖
`read_document`	读取文档内容	`filePath`: 文档路径

extractMetadata: 提取元数据

outputPath: 输出文件路径

outputPath: 输出文件路径

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

健康检查

容器包含内置健康检查：

```bash

检查容

Extension points exported contracts — how you extend this code

ConversionRequest (Interface)

* 文档转换规划器 - 智能转换路径规划和建议 * 为大模型提供最佳的文档转换策略和步骤

src/tools/conversionPlanner.ts

ReadDocumentOptions (Interface)

(no doc)

src/index.ts

SecurityConfig (Interface)

(no doc)

src/security/securityConfig.ts

MarkdownToDocxOptions (Interface)

(no doc)

src/tools/markdownToDocxConverter.ts

WriteDocumentOptions (Interface)

(no doc)

src/index.ts

MarkdownToDocxResult (Interface)

(no doc)

src/tools/markdownToDocxConverter.ts

ConvertDocumentOptions (Interface)

(no doc)

src/index.ts

ParsedElement (Interface)

(no doc)

src/tools/markdownToDocxConverter.ts

Core symbols most depended-on inside this repo

escapeHtml

called by 31

src/tools/documentConverter.ts

validatePath

called by 11

src/index.ts

validateAndSanitizePath

called by 11

src/security/securityConfig.ts

twipToPixel

called by 9

src/tools/ooxmlParser.ts

hexToRgb

called by 9

src/tools/documentConverter.ts

cssToString

called by 7

src/tools/ooxmlParser.ts

getFileContent

called by 6

src/tools/ooxmlParser.ts

parseXml

called by 6

src/tools/ooxmlParser.ts

Shape

Method 276

Function 121

Interface 36

Class 20

Languages

TypeScript100%

Modules by API surface

src/index.ts107 symbols

src/tools/ooxmlParser.ts77 symbols

src/tools/htmlConverter.ts62 symbols

src/tools/enhancedHtmlToDocxConverter.ts37 symbols

src/tools/mediaHandler.ts34 symbols

src/tools/documentConverter.ts30 symbols

src/tools/markdownToDocxConverter.ts28 symbols

src/tools/enhancedHtmlToMarkdownConverter.ts27 symbols

src/tools/conversionPlanner.ts20 symbols

src/tools/markdownToHtmlConverter.ts14 symbols

src/security/securityConfig.ts12 symbols

src/security/errorHandler.ts5 symbols

For agents

$ claude mcp add doc-ops-mcp \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact