lightpdf-aipdf-mcp 0.1.167

MCP Server for LightPDF AI-PDF

LightPDF AI-PDF MCP Server 🚀

基于 FastMCP 框架的现代化 PDF 处理工具，提供 22 个专业的文档处理功能。

✨ 项目特色

• 🚀 高效架构：基于 FastMCP，现代化设计
• 🔒 类型安全：100% 编译时参数验证
• ⚡ 开发友好：新工具开发速度提升 300%+
• 🔄 完全兼容：标准 MCP 协议 100% 兼容
• 🛠️ 功能丰富：22 个工具涵盖 PDF 处理所有核心功能

🚀 快速开始

安装和启动

# 安装依赖
uv sync

# 启动 stdio 模式（用于 MCP 客户端）
python run.py

# 启动 SSE 服务器模式（用于 Web 调试）
python run.py -p 8000 --sse

# 启动 HTTP 服务器模式（用于 HTTP 调试）
python run.py -p 8000

验证安装

# 运行完整测试套件
python test_server.py

🛠️ 可用工具（共22个）

📄 文档转换 (3个)

• convert_document - 文档格式转换，支持20+格式互转
• add_page_numbers - 为 PDF 添加页码
• remove_watermark - 去除 PDF 水印

🔧 PDF编辑 (6个)

• compress_pdf - PDF 压缩优化
• merge_pdfs - 合并多个 PDF
• split_pdf - 按页面、范围或书签拆分 PDF
• rotate_pdf - 旋转 PDF 页面
• unlock_pdf - 移除 PDF 密码保护
• protect_pdf - 为 PDF 添加密码保护

🎨 水印工具 (2个)

• add_text_watermark - 添加文本水印
• add_image_watermark - 添加图片水印

🤖 AI功能 (4个)

• create_pdf - 基于文本描述生成 PDF
• translate_pdf - PDF 文档翻译（35种语言）
• ocr_document - OCR 文字识别 (支持PDF/DOC/PPT/Excel/图片等)
• summarize_document - 文档摘要生成

🔧 专业工具 (7个)

• remove_margin - 去除 PDF 白边
• extract_images - 提取 PDF 中的图片
• flatten_pdf - 扁平化 PDF（表单转静态）
• repair_pdf - 修复损坏的 PDF
• curve_pdf - 文字转曲（防止文字提取）
• double_layer_pdf - 转换为双层 PDF（可搜索）
• delete_pdf_pages - 删除指定页面

🔒 安全功能 (2个)

• restrict_printing - 限制 PDF 打印权限
• resize_pdf - 调整 PDF 大小和分辨率
• replace_text - 替换 PDF 文本内容

📁 项目架构

采用清晰的现代化5层架构：

src/lightpdf_aipdf_mcp/
├── api/                    # API层 - FastMCP服务器与适配器
│   ├── server.py          # FastMCP主服务器 (22个工具)
│   └── adapter.py         # 业务逻辑适配器
├── core/                   # 核心层 - 统一业务逻辑
│   └── processor.py       # 核心业务处理器
├── services/              # 服务层 - 具体功能模块
│   ├── converter.py       # 文档转换服务
│   ├── editor.py         # PDF编辑服务
│   ├── create_pdf.py     # PDF创建服务
│   ├── translator.py     # 翻译服务
│   ├── summarizer.py     # 摘要服务
│   └── ocr.py           # OCR服务
├── models/               # 模型层 - 数据结构
│   └── schemas.py       # Pydantic数据模型
└── utils/               # 工具层 - 通用工具
    └── common.py        # 基础工具类

🔄 架构优势

特性	传统方式	FastMCP 方式
代码简洁度	复杂冗长	简洁高效
Schema 定义	手写 JSON	自动生成
类型检查	运行时	编译时
开发新工具	~200 行/工具	~20 行/工具
维护难度	高	低
调试友好度	一般	极高

🔧 开发指南

添加新工具

@mcp.tool
async def my_new_tool(
    ctx: Context,  # Context参数必须在第一位
    files: List[FileObject],
    my_param: str,
    optional_param: Optional[int] = None
) -> str:
    """
    我的新工具描述
    
    Args:
        files: 输入文件列表
        my_param: 必需参数
        optional_param: 可选参数
    
    Returns:
        JSON 格式的处理结果
    """
    logger = Logger(ctx, collect_info=False)
    await logger.log("info", f"开始处理 {len(files)} 个文件...")
    
    # 构建操作配置
    operation_config = generate_operation_config(
        operation_type="convert",  # 或 "edit", "translate", "ocr", "summarize"
        format_value="my-format",
        extra_params={"my_param": my_param}
    )
    
    # 调用适配器
    result = await process_tool_call_adapter(logger, files, operation_config)
    
    await logger.log("info", "处理完成")
    return result

测试工具

# 在 test_server.py 中添加
result = await client.call_tool("my_new_tool", {
    "files": [{"path": "test.pdf"}],
    "my_param": "test_value"
})

📚 技术栈

• FastMCP: 现代化的 MCP 服务器框架
• Pydantic: 数据验证和序列化
• asyncio: 异步 I/O 支持
• LightPDF API: 底层文档处理服务

🤝 开发最佳实践

1. 参数顺序：ctx: Context 参数始终放在第一位
2. 类型安全：使用 Pydantic 模型确保类型检查
3. 模块化：新功能优先在 services/ 层实现
4. 测试驱动：添加功能时同步编写测试用例
5. 日志记录：使用统一的 Logger 进行日志管理
6. 错误处理：提供详细的错误信息和调试信息

🎯 性能特点

• 启动速度: 快速启动，支持多种运行模式
• 内存效率: 优化的内存使用，支持大文件处理
• 并发处理: 智能并发控制，最大化处理效率
• 类型安全: 编译时参数验证，减少运行时错误

🌐 运行模式

支持多种运行模式：

1. stdio 模式：标准 MCP 客户端连接

   python run.py
   

2. HTTP 模式：HTTP API 服务

   python run.py -p 8000
   

3. SSE 模式：服务器发送事件模式

   python run.py -p 8000 --sse
   

📖 相关文档

• 功能介绍和配置指南（中文）
• Feature Introduction and Configuration Guide (English)
• LightPDF 开发者文档

🔑 配置说明

环境变量

• API_KEY: LightPDF API 密钥（必需）
• API_ENDPOINT: API 端点地址（默认：techsz.aoscdn.com/api）

MCP 客户端配置示例

{
  "mcpServers": {
    "lightpdf": {
      "command": "uvx",
      "args": ["lightpdf-aipdf-mcp@latest"],
      "env": {
        "API_KEY": "your_api_key_here",
        "API_ENDPOINT": "techsz.aoscdn.com/api"
      }
    }
  }
}

---

🎉 现代化、高效率、类型安全的 LightPDF Agent MCP Server，让 PDF 处理变得简单！