PDF Handle MCP

PDF Handle MCP

English | 简体中文

一个基于 MCP (Model Context Protocol) 的 PDF 文档处理服务，提供 PDF 文件的合并和拆分功能，并集成阿里云 OSS 存储服务。

功能特性

• PDF 合并: 将多个 PDF 文件合并为单个文档
• PDF 拆分: 按指定页数将 PDF 文件拆分为多个小文件
• 云存储集成: 自动上传处理结果到阿里云 OSS
• MCP 协议支持: 基于标准 MCP 协议，易于集成到各种 AI 应用中
• HTTP 服务: 提供 RESTful API 接口

技术栈

• Go 1.24+: 主要开发语言
• MCP-Go: MCP 协议的 Go 实现
• pdfcpu: PDF 文档处理库
• 阿里云 OSS SDK: 对象存储服务
• godotenv: 环境变量管理

项目结构

pdf-handle-mcp/
├── main.go              # 主程序入口
├── handlers/            # 请求处理器
│   └── pdf_handlers.go  # PDF 处理逻辑
├── tools/               # MCP 工具定义
│   └── pdf_tools.go     # PDF 工具配置
├── oss/                 # 对象存储模块
│   ├── oss.go          # OSS 接口定义
│   ├── aliyun.go       # 阿里云 OSS 实现
│   └── factory.go      # 工厂模式实现
├── .env                # 环境变量配置
├── go.mod              # Go 模块定义
└── go.sum              # 依赖版本锁定

快速开始

环境要求

• Go 1.24 或更高版本
• 阿里云 OSS 账户和访问凭证

安装依赖

go mod tidy

配置环境变量

复制 .env 文件并配置你的阿里云 OSS 信息：

# 阿里云OSS配置
ENDPOINT="your-endpoint"
KEY_ID="your-access-key-id"
KEY_SECRET="your-access-key-secret"
BUCKET="your-bucket-name"
REGION="your-region"
DOMAIN="your-domain"

运行服务

go run main.go

服务将在 :9900 端口启动。

API 使用

PDF 合并工具

工具名称: pdf_merge

描述: 将多个 PDF 文件合并为单个 PDF 文档

参数:

• file_url_list (数组): 待合并的 PDF 文件 URL 数组，至少包含 2 个文件

返回: 合并后的 PDF 文件 URL

PDF 拆分工具

工具名称: pdf_split

描述: 将 PDF 文件按指定页数拆分为多个小文件

参数:

• file_url (字符串): 待拆分的 PDF 文件 URL
• size (数字): 每个拆分文件包含的页数，必须为正整数

返回: 拆分后的多个 PDF 文件 URL 数组

架构设计

MCP 协议集成

本项目基于 MCP (Model Context Protocol) 协议构建，使得 AI 模型可以直接调用 PDF 处理功能。MCP 是一个开放标准，用于 AI 应用与外部工具的安全连接。

存储策略

• 使用工厂模式设计 OSS 客户端，便于扩展其他云存储服务
• 临时文件自动清理，避免磁盘空间浪费
• 支持大文件处理和并发上传

错误处理

• 完善的错误处理机制
• 资源自动清理
• 详细的错误信息返回

开发指南

添加新的 PDF 处理功能

1. 在 tools/pdf_tools.go 中定义新的工具
2. 在 handlers/pdf_handlers.go 中实现处理逻辑
3. 在 main.go 中注册工具和处理器

扩展存储服务

1. 在 oss/ 目录下创建新的存储服务实现
2. 实现 Client 接口
3. 创建对应的工厂类
4. 在 InitOSS() 中注册新的工厂

许可证

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

联系方式

如有问题或建议，请通过 GitHub Issues 联系我们。

更新日志

v1.0.0

• 初始版本发布
• 支持 PDF 合并和拆分功能
• 集成阿里云 OSS 存储
• 基于 MCP 协议的工具接口