AI导哈

PDF转换工具

一个基于MCP服务器的PDF处理工具，提供PDF到Markdown的转换及图像提取功能，适用于文档处理和内容管理场景。

  • by alinavlase
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 awels-io/mcp

使用说明

Awels MCP服务器-PDF处理工具

一种使用文档提供PDF处理功能的模型上下文协议（MCP）服务器。此服务器提供了一个将PDF文件转换为Markdown格式的工具，该工具具有可选的图像提取功能，旨在在隔离的环境中运行，以避免权限问题。

项目结构

awels-mcp/
├── src/
│   └── awels_mcp/
│       ├── pdf_processor/     # PDF processing functionality
│       │   └── __init__.py    # PDFProcessor implementation
│       ├── __init__.py        # Package initialization
│       ├── run_server.py      # Server entry point
│       └── server.py          # MCP server implementation
├── tests/                     # Test files
│   ├── artifacts/             # Test artifacts (PDFs, outputs)
│   │   ├── test_output_md/    # Generated markdown files
│   │   ├── test_output_images/# Extracted images
│   │   └── test_pdfs/         # Sample PDFs for testing
│   ├── test_client.py         # Test MCP client
│   ├── test_pdf_processor.py  # Unit tests for PDF processing
│   └── test_server.py         # Server tests
├── .gitignore
├── INSTALL.md                 # Installation instructions
├── LICENSE
├── PLAN.md
├── README.md                  # This file
├── pyproject.toml             # Project metadata and dependencies
└── requirements.txt           # Development dependencies

特性

  • PDF到Markdown转换：使用文档将PDF文件转换为干净的Markdown格式
  • 图像提取：从PDF中提取图像（页面图像、表格、图形）
  • 批处理：处理目录中的多个PDF文件（使用递归搜索）
  • 结构化输出：返回包含文件元数据和处理统计信息的详细JSON结果
  • 独立执行：设计用于与 uvx --isolated 防止权限问题
  • 错误处理：妥善处理权限错误和处理失败

安装

看 安装.md 有关详细的安装说明，请使用 uv.

快速开始

  1. 在开发模式下安装软件包：
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
  1. 运行测试以验证安装：
pytest tests/
  1. 启动MCP服务器：
python -m src.awels_mcp.run_server
  1. 在单独的终端中，运行测试客户端：
python tests/test_client.py

运行测试

测试套件包括：

  • PDF处理器的单元测试
  • MCP服务器的集成测试
  • 与客户端进行端到端测试

要运行所有测试，请执行以下操作：

pytest tests/

测试工件（生成的标记和图像）保存在 tests/artifacts/ 目录。

发展

项目结构

  • src/awels_mcp/：主包源代码
    • pdf_processor/：PDF处理功能
    • server.py：MCP服务器实现
    • run_server.py：MCP服务器的入口点

添加新功能

  1. 为您的功能创建新分支
  2. 在相应的测试文件中为您的功能添加测试
  3. 实现您的功能
  4. 运行测试以确保一切正常
  5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

与MCP客户端集成

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "awels-pdf-processor": {
      "command": "uvx",
      "args": [
        "--python=3.12",
        "--isolated", 
        "--from=git+https://github.com/your-org/awels-mcp.git",
        "awels-mcp-server"
      ]
    }
  }
}

工具参考

convert_pdf

使用可选的图像提取将目录中的PDF文件转换为Markdown。

参数：

  • directory （字符串，必填）：搜索PDF文件的目录路径
  • recursive （布尔值，可选）：是否在子目录中递归搜索（默认值：true）
  • markdown_output_path （字符串，可选）：保存markdown文件的目录
  • images_dir （字符串，可选）：从PDF中提取图像的目录

退货： 带处理结果的结构化JSON：

{
  "summary": {
    "total_files": 5,
    "successful": 4,
    "failed": 1,
    "total_pages": 120,
    "total_images_extracted": 25
  },
  "files": {
    "/path/to/file1.pdf": {
      "filename": "file1.pdf",
      "name": "file1.pdf",
      "size": 1024000,
      "modified": 1640995200.0,
      "pages": 10,
      "metadata": {
        "title": "Document Title",
        "author": "Author Name",
        "subject": "Document Subject"
      },
      "extracted_images": [
        "/path/to/images/file1-page-1.png",
        "/path/to/images/file1-table-1.png"
      ],
      "markdown_file": "/path/to/markdown/file1.md",
      "content": "# Document Title\n\nDocument content in markdown..."
    },
    "/path/to/file2.pdf": {
      "error": "Failed to convert PDF: Permission denied"
    }
  }
}

使用示例

基本PDF转换

# Convert all PDFs in a directory to markdown (content returned in response)
convert_pdf(directory="/path/to/pdfs")

保存Markdown文件

# Convert PDFs and save markdown files to disk
convert_pdf(
  directory="/path/to/pdfs",
  markdown_output_path="/path/to/output/markdown"
)

提取图像

# Convert PDFs and extract all images
convert_pdf(
  directory="/path/to/pdfs",
  markdown_output_path="/path/to/output/markdown",
  images_dir="/path/to/output/images"
)

非递归搜索

# Only process PDFs in the specified directory (no subdirectories)
convert_pdf(
  directory="/path/to/pdfs",
  recursive=false
)

建筑

服务器使用：

  • FastMCP：高级MCP服务器框架，便于工具定义
  • 文档：用于文本和图像提取的高级PDF处理库
  • 派丹蒂克：数据验证和结构化输出
  • 孤立执行：在隔离环境中运行以防止权限问题

错误处理

服务器优雅地处理：

  • 权限错误（设计用于在隔离环境中运行）
  • 缺少目录
  • 损坏的PDF文件
  • 处理失败
  • 文件系统错误

所有错误都会在结构化输出中报告，并附有详细的错误消息。

发展

项目结构

awels/
├── src/
│   └── awels_mcp/
│       ├── __init__.py
│       ├── server.py          # Main MCP server implementation
│       └── pdf_processor.py   # PDF processing logic
├── pyproject.toml             # Package configuration
├── README.md                  # This file
└── PLAN.md                    # Development plan

运行测试

# Install development dependencies
uv sync --group dev

# Run tests (when available)
uv run pytest

代码格式化

# Format code
uv run black src/
uv run isort src/

# Type checking
uv run mypy src/

需求

  • Python 3.10+
  • 文档化和文档化核心库
  • MCP Python SDK
  • 足够的磁盘空间用于临时文件和模型下载

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

支持

对于问题和疑问：

  • GitHub问题：https://github.com/your-org/awels-mcp/issues
  • 文件：技术细节见PLAN.md

相关 MCP