npm package: @mcpcn/mcp-pdf-operation
Description: PDF Operation MCP Server - 提供PDF合并、拆分、转图片、加水印、加密等功能。零配置安装，纯JavaScript实现。
Author: MCPCN
Latest version: 1.1.1

# PDF Operation MCP

这是一个基于 Model Context Protocol (MCP) 的 PDF 操作服务，提供 PDF 合并、拆分、转图片、加水印、加密等功能。

## ✨ 突出特点

### 📦 **零配置安装**
- **一步到位**：`npm install` 后即可使用
- **无需额外依赖**：不需要手动安装系统工具
- **纯JavaScript实现**：所有核心功能都基于纯JS库
- **跨平台支持**：支持Windows、macOS、Linux

### 🚀 **功能特点**

- **📄 PDF合并** - 将多个PDF文件合并成一个完整的PDF文档，支持详细进度报告
- **✂️ PDF拆分** - 智能拆分PDF文件，支持按页面或自定义范围拆分
- **🖼️ PDF转图片** - 高质量图片转换（JPEG/PNG），可调节分辨率和质量
- **🏷️ PDF加水印** - 智能中英文水印处理，自动转换中文为图片水印，9种位置选择
- **🎨 中文水印创建** - 专门生成中文水印图片，完美解决中文字体编码问题
- **🔒 PDF加密** - 文档保护功能，支持基础保护方案（完整加密需第三方工具）

### 🎆 **体验优化**

- **详细进度报告**：实时显示处理进度和结果统计
- **智能错误处理**：友好的错误提示和解决建议
- **文件安全验证**：自动验证文件格式和存在性
- **友好的输出格式**：结构化的JSON回复和详细统计信息

## 📦 安装

```bash
cd typescript/mcp-pdf-operation
npm install
npm run build
```

## 🔧 配置

在您的 MCP 配置文件中添加以下配置：

### Claude Desktop 配置 (macOS)

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "mcp-pdf-operation": {
      "command": "node",
      "args": [
        "/Users/你的用户名/path/to/skills/typescript/mcp-pdf-operation/dist/index.js"
      ],
      "autoApprove": [
        "merge-pdf",
        "split-pdf",
        "pdf-to-image",
        "add-watermark",
        "encrypt-pdf"
      ]
    }
  }
}
```

### Cline/Cursor 配置

在 Cursor 设置中添加：

```json
{
  "mcpServers": {
    "mcp-pdf-operation": {
      "command": "node",
      "args": [
        "path/to/skills/typescript/mcp-pdf-operation/dist/index.js"
      ]
    }
  }
}
```

## 🛠️ 功能说明

### 1. PDF合并 (merge-pdf)

将多个PDF文件合并成一个完整的PDF文档。

**参数：**
- `inputPaths`: PDF文件路径数组 (必需)
- `outputPath`: 输出PDF文件路径 (必需)  
- `title`: 合并后PDF的标题 (可选)

**示例：**
```bash
请合并这些PDF文件：["/docs/report1.pdf", "/docs/report2.pdf"] 到 "/merged/combined_report.pdf"
```

**特性：**
- 支持合并任意数量的PDF文件
- 保持原始页面格式和质量
- 自动设置文档元数据
- 详细的合并统计报告
- 自动添加.pdf扩展名

### 2. PDF拆分 (split-pdf)

将PDF文件拆分成多个独立的文件，支持按页面或自定义范围拆分。

**参数：**
- `inputPath`: 输入PDF文件路径 (必需)
- `outputDir`: 输出目录 (必需)
- `splitMode`: 拆分模式 - `pages`(每页一个文件) 或 `ranges`(按范围拆分)，默认pages (可选)
- `ranges`: 页面范围数组，如 ["1-3", "4-6"]，仅ranges模式需要 (可选)
- `prefix`: 输出文件名前缀 (可选)

**示例：**
```bash
请将 "/documents/manual.pdf" 按页面拆分到 "/pages/" 目录
```

```bash
请将PDF按范围拆分：["1-5", "6-10", "11-15"]
```

**特性：**
- 两种拆分模式：逐页拆分或范围拆分
- 灵活的页面范围设置
- 保持原始页面格式
- 自动文件命名和编号
- 详细的拆分统计

### 3. PDF转图片 (pdf-to-image)

将PDF页面转换为高质量的图片文件，支持多种格式和自定义设置。

**参数：**
- `inputPath`: 输入PDF文件路径 (必需)
- `outputDir`: 输出目录 (必需)
- `format`: 图片格式 - `jpeg` 或 `png`，默认jpeg (可选)
- `quality`: 图片质量 1-100，默认80 (可选)
- `dpi`: 分辨率DPI 50-600，默认150 (可选)
- `pages`: 页面范围，如 "1-3" 或 "1,3,5"，默认全部页面 (可选)
- `prefix`: 输出文件名前缀 (可选)

**示例：**
```bash
请将 "/docs/presentation.pdf" 转换为PNG图片，分辨率300 DPI
```

```bash
请只转换PDF的第1、3、5页为JPEG图片
```

**特性：**
- 支持JPEG和PNG格式
- 可调节图片质量和分辨率
- 灵活的页面选择（范围、列表、单页）
- 批量处理所有页面
- 详细的转换统计信息

### 4. PDF加水印 (add-watermark)

为PDF文件添加文字或图片水印。

**参数：**
- `inputPath`: 输入PDF文件路径 (必需)
- `outputPath`: 输出PDF文件路径 (必需)
- `watermarkText`: 水印文字内容 (可选)
- `watermarkImagePath`: 水印图片路径，与文字水印二选一 (可选)
- `opacity`: 水印透明度 0-1，默认0.3 (可选)
- `fontSize`: 文字水印字体大小，默认24 (可选)
- `position`: 水印位置 - `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`，默认center (可选)
- `rotation`: 水印旋转角度 -360到360，默认0 (可选)

**示例：**
```bash
请为PDF添加文字水印 "机密文档"，透明度0.3，位置在中心
```

```bash
请为PDF添加图片水印，使用 "/watermarks/logo.png"，位置在右下角
```

**特性：**
- 支持文字和图片水印
- 可调节透明度和位置
- 支持水印旋转
- 自动适应页面大小
- 批量处理所有页面

### 5. PDF文档保护 (encrypt-pdf) ⚠️

为PDF文件添加基础保护信息和权限记录。

**⚠️ 重要说明**：
- 当前提供**基础文档保护**，会在PDF开头添加保护信息页面
- **不是真正的密码加密**，仅作为访问提醒和权限记录
- 适合内部文档流转和一般保护需求

**参数：**
- `inputPath`: 输入PDF文件路径 (必需)
- `outputPath`: 输出PDF文件路径 (必需)
- `userPassword`: 用户密码（将记录在保护信息中）(必需)
- `ownerPassword`: 所有者密码（权限密码）(可选)
- `permissions`: 权限设置对象 (可选)
  - `printing`: 是否允许打印，默认false
  - `modifying`: 是否允许修改，默认false
  - `copying`: 是否允许复制，默认false
  - `annotating`: 是否允许添加注释，默认false
  - `fillingForms`: 是否允许填写表单，默认false

**示例：**
```bash
请为PDF添加保护信息，密码为 "123456"，禁止打印和复制
```

**实现效果：**
- ✅ 在PDF开头添加保护信息页面
- ✅ 显示密码提示和权限说明
- ✅ 添加"PROTECTED"水印标记
- ✅ 记录生成时间和权限设置

**获得真正PDF加密的方式：**
1. **在线服务**：iLovePDF、SmallPDF、PDF24等
2. **桌面软件**：Adobe Acrobat、PDFCreator、Foxit Reader
3. **系统工具**：PDFtk Server、qpdf等（需安装）

### 6. 中文水印图片生成 (create-text-image) 🆕

**专门解决中文水印问题** - 将中文文字转换为高质量图片，完美解决PDF中文字体编码限制。

**参数：**
- `text`: 要转换的文字内容（支持中文、英文、数字、符号）(必需)
- `outputPath`: 输出图片文件路径（可选，默认为 watermark_文字.png）
- `fontSize`: 字体大小（可选，默认24）
- `color`: 文字颜色（可选，默认#808080，支持十六进制格式）
- `backgroundColor`: 背景颜色（可选，默认transparent透明）

**使用流程（两步法）：**
```bash
# 步骤1: 创建中文水印图片
"创建中文水印图片，文字内容为'机密文档'"
# → 生成文件: watermark_机密文档.png

# 步骤2: 使用图片添加水印  
"为PDF添加图片水印，使用图片文件 watermark_机密文档.png"
```

**高级定制示例：**
```bash
# 自定义样式
"创建水印图片，文字'重要资料'，字体大小32，颜色#FF0000"

# 指定输出路径
"生成水印图片，文字'内部使用'，保存到 /path/to/my_watermark.png"

# 带背景色
"创建水印图片，文字'版权所有'，背景颜色#FFFFFF"
```

**功能特点：**
- ✅ **完美中文支持**：使用系统优化字体，显示清晰美观
- ✅ **高质量输出**：PNG格式，支持透明背景，无损质量
- ✅ **智能适配**：根据文字长度自动计算最佳图片尺寸
- ✅ **即用即得**：生成后可直接用于图片水印，无需额外处理
- ✅ **完全兼容**：解决传统PDF库中文字体编码问题

**特性：**
- 支持用户密码和所有者密码
- 灵活的权限控制
- 高强度加密算法
- 保持文档格式不变

## 📄 使用示例

### 基本操作示例

1. **合并PDF文件**
   ```
   用户：请将桌面上的 report1.pdf 和 report2.pdf 合并为 final_report.pdf
   
   助手：我来帮你合并这两个PDF文件...
   成功合并2个PDF文件，总共包含25页。
   ```

2. **拆分PDF文件**
   ```
   用户：请将 document.pdf 按每页拆分到 pages 文件夹中
   
   助手：我来帮你拆分PDF文件...
   成功拆分PDF文件，生成15个文件。
   ```

3. **PDF转图片**
   ```
   用户：请将 presentation.pdf 的前3页转换为高质量PNG图片
   
   助手：我来将PDF转换为图片...
   成功将PDF转换为图片，生成3个PNG文件。
   ```

4. **添加水印**
   ```
   用户：请为 contract.pdf 添加"CONFIDENTIAL"水印，透明度0.5
   
   助手：我来为PDF添加水印...
   成功为PDF添加文字水印。
   ```

5. **加密PDF**
   ```
   用户：请为 sensitive.pdf 设置密码"secret123"，禁止打印和复制
   
   助手：我来为PDF添加密码保护...
   成功为PDF添加密码保护和权限控制。
   ```

### 智能路径处理功能

🎯 **新增特性**：零配置的智能路径处理和自动目录创建

**自动创建目录示例**：
```
用户：请将document.pdf拆分到新建的split_pages文件夹中

助手：📁 创建输出目录: /Users/username/Documents/split_pages
      ✂️ 按页面拆分模式: 每页一个文件  
      ✅ PDF拆分成功！生成15个文件
```

**智能路径解析示例**：
```
用户：请将PDF转换为图片，保存到images/converted文件夹

助手：📁 创建输出目录: /Users/username/Documents/images/converted
      🖼️ 开始PDF转图片...
      ✅ PDF转图片成功！生成8个PNG文件
```

**路径处理规则**：
- 📁 **自动创建**：输出目录不存在时自动创建，无需手动创建
- 🏠 **智能默认**：仅指定文件名时，输出到原文件同目录
- 📂 **相对路径**：相对于原文件目录进行解析
- 🗂️ **绝对路径**：完全按照指定路径输出
- 🔄 **跨平台**：自动适配Windows、macOS、Linux路径格式

## ⚠️ 注意事项

1. **文件路径**: 请使用绝对路径，确保文件存在且可访问
2. **权限要求**: 确保对源文件和目标目录有相应的读写权限
3. **PDF格式**: 支持标准PDF格式，不支持受损或加密的PDF文件（加密功能除外）
4. **图片格式**: 支持常见的图片格式作为水印（PNG、JPG）
5. **内存使用**: 大文件处理可能需要更长时间和更多内存
6. **依赖要求**: 
   - PDF操作基于 `pdf-lib` 纯JavaScript实现
   - PDF转图片功能需要 `pdf2pic` 和 `sharp` 库
   - 某些功能可能需要系统支持额外的图形库

## 🐛 故障排除

### 常见问题

1. **中文水印解决方案** ✅
   
   **新功能**: 现在完美支持中文水印！
   ```bash
   # 🎉 现在可以直接使用中文水印
   "请为PDF添加中文水印'机密文档'"
   # → 系统自动将中文转换为图片水印，无需额外操作
   ```
   
   **三种使用方式**:
   1. **智能自动转换**: 直接使用中文水印，系统自动处理
   2. **两步法**: 先创建图片，再添加水印
      ```bash
      "创建中文水印图片，文字内容为'机密文档'"
      "为PDF添加图片水印，使用图片文件 watermark_机密文档.png"
      ```
   3. **英文直接水印**: 英文水印依然支持字体模式
      ```bash
      "请为PDF添加英文水印'CONFIDENTIAL'"
      ```

2. **文件不存在错误**
   ```
   错误：文件不存在: /path/to/file.pdf
   ```
   **解决方案**: 检查文件路径是否正确，使用绝对路径

3. **权限错误**
   ```
   错误：EACCES: permission denied
   ```
   **解决方案**: 检查文件和目录访问权限

4. **PDF格式错误**
   ```
   错误：无法加载PDF文件
   ```
   **解决方案**: 确认PDF文件格式正确且未损坏

5. **内存不足**
   ```
   错误：JavaScript heap out of memory
   ```
   **解决方案**: 处理大文件时增加Node.js内存限制
   ```bash
   node --max-old-space-size=4096 dist/index.js
   ```

6. **PDF加密功能限制** ⚠️
   ```
   错误：PDF加密功能当前不可用
   ```
   **说明**: 
   - 纯JavaScript环境下，真正的PDF密码加密技术限制较大
   - 当前提供基础文档保护（添加保护信息页面）
   
   **解决方案**:
   - **在线加密**: iLovePDF (https://www.ilovepdf.com/encrypt-pdf)
   - **桌面软件**: Adobe Acrobat、PDFCreator
   - **替代保护**: 使用我们的水印功能添加"CONFIDENTIAL"等保护标识
   
   **临时保护方案**:
   ```bash
   # 添加保护水印
   "为PDF添加英文水印'CONFIDENTIAL - DO NOT COPY'"
   
   # 创建保护声明
   "创建中文水印图片，文字内容为'机密文档 - 禁止复制'"
   ```

5. **图片转换失败**
   ```
   错误：转换失败
   ```
   **解决方案**: 确保系统已安装必要的图形处理库

### 调试技巧

1. 查看控制台错误信息
2. 确认文件路径和权限
3. 测试较小的PDF文件
4. 检查依赖库安装状态

## 📝 开发信息

- **基于**: Model Context Protocol (MCP) SDK
- **主要依赖**: 
  - `pdf-lib`: PDF处理核心库
  - `pdf2pic`: PDF转图片功能
  - `sharp`: 图片处理优化
  - `fs-extra`: 增强文件系统操作
- **支持格式**: PDF, JPEG, PNG
- **Node.js版本**: >= 14.0.0

## 📄 许可证

本项目采用 MIT 许可证。