Doc Ops Mcp

Name: Doc Ops Mcp
Author: Tele-AI

本地服务

github.com/Tele-AI生产力14062 周前更新

代码仓库

关于 Doc Ops Mcp

Doc Ops Mcp 是用于读取、编写、转换和处理文档的 MCP 服务，支持 PDF、DOCX、HTML 和 Markdown 等格式。它提供格式转换规划、样式保留以及 PDF 水印和二维码处理工具。

主要功能

01读取和写入多种文档格式
02在常见格式间转换
03规划转换路径并保留样式
04批量替换文本与调整格式
05为 PDF 添加水印或二维码

适用场景

01将 DOCX 或 Markdown 转为 PDF
02在 HTML、Markdown 与 DOCX 间转换
03批量更新合同或手册中的文本
04为 PDF 添加水印或二维码

MCP 相关

它向 MCP 客户端暴露文档读取、写入、转换规划、格式转换和 PDF 增强工具。客户端可通过 MCP 配置启动 `doc-ops-mcp` 并调用这些操作。

#document-conversion-file-converter-pdf-conversion-markdown-converter-watermark-document-processing-document-converter-docx-to-pdf-pdf-processing-docx2pdf-document-rewriting

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "doc-ops": {
      "command": "npx",
      "args": [
        "-y",
        "doc-ops-mcp"
      ],
      "env": {
        "OUTPUT_DIR": "<OUTPUT_DIR>",
        "CACHE_DIR": "<CACHE_DIR>"
      }
    }
  }
}

启动命令npx -y doc-ops-mcp

需要配置的环境变量

OUTPUT_DIR

CACHE_DIR

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmdoc-ops-mcpstdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
filePath	string	是	要读取的文档路径
extractMetadata	boolean	否	提取文档元数据
preserveFormatting	boolean	否	保留格式（HTML 输出）

详细介绍

文档操作 MCP 服务

语言 / 语言：English | 中文

文档操作 MCP 服务 - 用于文档处理、转换和自动化的通用 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. 快速开始

首先，将文档操作 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 服务安装方法。

配置

文档操作 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	✅	✅	✅	✅	✅	❌

改写功能：

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

使用示例

格式转换：

Convert /Users/docs/report.docx to PDF
Convert /Users/docs/article.md to HTML
Convert /Users/docs/presentation.html to DOCX
Convert /Users/docs/readme.md to PDF (with theme styling)

文档改写：

Rewrite company names in /Users/docs/contract.md
Batch replace terminology in /Users/docs/manual.docx
Adjust heading levels in /Users/docs/article.html
Update dates and version numbers in /Users/docs/policy.md

PDF 增强：

Add watermark to /Users/docs/document.pdf
Add QR code to /Users/docs/report.pdf
Add company logo watermark to /Users/docs/invoice.pdf

环境变量

该服务支持通过环境变量控制输出路径和 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 Client Layer                         │
│           (Claude Desktop, Cursor, VS Code, etc.)           │
└─────────────────────┬───────────────────────────────────────┘
                      │ JSON-RPC 2.0
┌─────────────────────┴───────────────────────────────────────┐
│                 Doc-Ops-MCP Server                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │   Tool Router   │  │  Request        │  │  Response   │ │
│  │   & Handler     │  │  Validator      │  │  Formatter  │ │
│  └────────┬────────┘  └────────┬────────┘  └──────┬──────┘ │
│           │                    │                  │        │
│  ┌────────┴────────────────────┴──────────────────┴─────┐ │
│  │                Document Processing Engine             │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │  Document   │  │   Format    │  │   Style     │   │ │
│  │  │   Reader    │  │  Converter  │  │  Processor  │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │ │
│  │                                                        │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │    PDF      │  │  Watermark/ │  │ Conversion  │   │ │
│  │  │ Enhancement │  │   QR Code   │  │  Planner    │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │ │
└────┴───────────────────────────────────────────────────────┴─┘
                            │
┌───────────────────────────┴─────────────────────────────────┐
│                    Core Dependencies Layer                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   pdf-lib   │  │word-extractor│  │   marked    │          │
│  │ (PDF Tools) │  │(DOCX Reader)│  │ (Markdown)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   cheerio   │  │    jszip    │  │    docx     │          │
│  │(HTML Parser)│  │(ZIP Handler)│  │(DOCX Gen.)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────┐  ┌─────────────┐                           │
│  │   xml2js    │  │Custom OOXML │                           │
│  │(XML Parser) │  │   Parser    │                           │
│  └─────────────┘  └─────────────┘                           │
└─────────────────────────────────────────────────────────────┘

架构概述

核心功能：

纯 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（字符串，必填）- 要读取的文档路径
extractMetadata（布尔值，可选）- 提取文档元数据，默认为 false
preserveFormatting（布尔值，可选）- 保留格式（HTML 输出），默认为 false

write_document

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

参数：

content（字符串，必填）- 要写入的内容
outputPath（字符串，可选）- 输出文件路径（未提供时自动生成）
encoding（字符串，可选）- 文件编码，默认为 utf-8

convert_document

在不同格式之间转换文档，并增强样式保留效果。

参数：

inputPath（字符串，必填）- 输入文件路径
outputPath（字符串，可选）- 输出文件路径（未提供时自动生成）
preserveFormatting（布尔值，可选）- 是否保留格式，默认为 true
useInternalPlaywright（布尔值，可选）- 转换为 PDF 时是否使用内置 Playwright，默认为 false

convert_docx_to_pdf

将 DOCX 转换为 PDF，并自动添加水印（如果已配置）。

参数：

docxPath（字符串，必填）- DOCX 文件路径
outputPath（字符串，可选）- 输出 PDF 路径（未提供时自动生成）
addQrCode（布尔值，可选）- 是否添加二维码，默认为 false
preserveFormatting（布尔值，可选）- 是否保留原始格式，默认为 true
chineseFont（字符串，可选）- 中文字体，默认为 Microsoft YaHei

convert_markdown_to_pdf

将 Markdown 转换为 PDF，并自动添加水印（如果已配置）。

参数：

markdownPath（字符串，必填）- Markdown 文件路径
outputPath（字符串，可选）- 输出 PDF 路径（未提供时自动生成）
theme（字符串，可选）- 主题样式，默认为 "github"
includeTableOfContents（布尔值，可选）- 是否包含目录，默认为 false
addQrCode（布尔值，可选）- 是否添加二维码，默认为 false

convert_markdown_to_html

将 Markdown 转换为 HTML。

参数：

markdownPath（字符串，必填）- Markdown 文件路径
outputPath（字符串，可选）- 输出 HTML 路径（未提供时自动生成）
theme（字符串，可选）- 主题样式，默认为 "github"
includeTableOfContents（布尔值，可选）- 是否包含目录，默认为 false

convert_markdown_to_docx

将 Markdown 转换为 DOCX。

参数：

markdownPath（字符串，必填）- Markdown 文件路径
outputPath（字符串，可选）- 输出 DOCX 路径（未提供时自动生成）

convert_html_to_markdown

将 HTML 转换为 Markdown。

参数：

htmlPath（字符串，必填）- HTML 文件路径
outputPath（字符串，可选）- 输出 Markdown 路径（未提供时自动生成）

plan_conversion

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

参数：

sourceFormat（字符串，必填）- 源文件格式（pdf、docx、html、markdown、md、txt、doc）
targetFormat（字符串，必填）- 目标文件格式（pdf、docx、html、markdown、md、txt、doc）
sourceFile（字符串，可选）- 源文件路径（用于生成特定的转换参数）
preserveStyles（布尔值，可选）- 是否保留样式格式，默认为 true
includeImages（布尔值，可选）- 是否包含图像，默认为 true
theme（字符串，可选）- 转换主题，默认为 github
quality（字符串，可选）- 转换质量要求（fast、balanced、high），默认为 balanced

process_pdf_post_conversion

参数：

playwrightPdfPath（字符串，必填）- 生成的 PDF 文件路径
targetPath（字符串，可选）- 目标 PDF 文件路径（未提供时自动生成）
addWatermark（布尔值，可选）- 是否添加水印，默认为 false
addQrCode（布尔值，可选）- 是否添加二维码，默认为 false
watermarkImage（字符串，可选）- 水印图像路径
qrCodePath（字符串，可选）- 二维码图像路径

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 样式保留

安装

# Global installation
npm install -g doc-ops-mcp

# Or using pnpm
pnpm add -g doc-ops-mcp

# Or using bun
bun add -g doc-ops-mcp

架构组件

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

5. 开源许可证

项目许可证

本项目：MIT 许可证
兼容性：可用于商业和非商业用途

第三方依赖项

库	版本	许可证	用途
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 部署

快速开始

使用预构建镜像

# Pull the latest image
docker pull docops/doc-ops-mcp:latest

# Run with default configuration
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  docops/doc-ops-mcp:latest

从源代码构建

# Clone the repository
git clone https://github.com/JefferyMunoz/doc-ops-mcp.git
cd doc-ops-mcp

# Build the Docker image
docker build -t doc-ops-mcp .

# Run the container
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
    
  # Optional: Add Nginx for reverse proxy
  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`

卷挂载

挂载本地目录以实现持久化存储：

# Documents directory for file processing
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  -v $(pwd)/documents:/app/documents \
  -v $(pwd)/output:/app/output \
  doc-ops-mcp

Docker 配置示例

生产部署

# Production setup with Docker Swarm
docker swarm init
docker stack deploy -c docker-compose.yml doc-ops

# Scale the service
docker service scale doc-ops_mcp=3

健康检查

容器内置健康检查：

# Check container health
docker ps

# View health check logs
docker inspect --format='{{.State.Health.Status}}' doc-ops-mcp

# Manual health check
docker exec doc-ops-mcp curl -f http://localhost:3000/health || exit 1

8. 开发指南

本地开发

# Clone the repository
git clone https://github.com/your-org/doc-ops-mcp.git
cd doc-ops-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

项目结构

src/
├── index.ts          # MCP server entry point
├── tools/            # Tool implementations
│   ├── documentConverter.ts
│   ├── pdfTools.ts
│   └── ...
├── types/            # Type definitions
└── utils/            # Utility functions

添加新工具

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

9. 故障排除

常见问题

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

调试模式

# Run with debug logging
docker run -d \
  --name doc-ops-mcp \
  -p 3000:3000 \
  -e LOG_LEVEL=debug \
  doc-ops-mcp

# View logs
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 文件。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Doc Ops Mcp

关于 Doc Ops Mcp

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

文档操作 MCP 服务

演示

视频

目录

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. 贡献

如何贡献

知识产权许可

代码规范

报告问题

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？