读取PDF扩展服务

作者：irev0 星标更新：2025-11-04

项目介绍

ReadPDFx - OCR PDF MCP 服务器

官方 MCP SDK STDIO 服务器 - 遵循 MCP 协议 2025-06-18

<div align="left" style="display: flex; align-items: center; gap: 20px;"> <img src="./logo.png" alt="Read_PDF Logo" width="100" style="flex-shrink: 0;"> <div> ReadPDFx 是一个全面的 MCP（模型上下文协议）服务器，使用官方 MCP SDK 和 STDIO 传输提供智能 OCR 和 PDF 处理功能。它会自动检测 PDF 是否包含数字文本或扫描图像，并应用适当的处理方法。 </div> </div>

⚡ 快速开始（STDIO 服务器）

1. 安装依赖项

pip install -r requirements.txt

2. 验证安装

# 测试导入和工具
python validate_tools.py

3. 客户端集成

服务器通过 STDIO 协议运行 - 配置您的 MCP 客户端：

Claude Desktop:

{
  "mcpServers": {
    "ocr-pdf": {
      "command": "python",
      "args": ["d:/AI/MCP/python/ocr_pdf_mcp/mcp_server_stdio.py"],
      "env": {}
    }
  }
}

🚀 功能

🎯 官方 MCP SDK: 使用官方 FastMCP 框架构建
📡 STDIO 传输: 标准 MCP 协议通过 STDIO
🧠 智能 PDF 处理: 自动检测数字内容与扫描内容
🔧 5 种 OCR 工具: 文本提取、OCR 处理、组合操作
🌐 全面客户端支持: Claude Desktop, LM Studio, Continue.dev, Cursor
⚡ 轻量级: 约 200 行代码 vs HTTP 实现的 800+ 行
🛡️ 生产就绪: 综合错误处理和日志记录
📋 自动工具注册: 装饰器处理工具发现

🔧 安装

前提条件

Python 3.8+
Tesseract OCR

Windows

# 安装 Python 依赖项
pip install -r requirements.txt

# 安装 Tesseract
choco install tesseract

macOS

pip install -r requirements.txt
brew install tesseract

Linux

pip install -r requirements.txt
sudo apt-get install tesseract-ocr

📋 可用工具

1. 智能 PDF 处理

智能处理，自动 OCR 检测：

{
  "name": "process_pdf_smart",
  "arguments": {
    "pdf_path": "/path/to/document.pdf",
    "language": "eng"
  }
}

2. PDF 文本提取

从数字 PDF 中直接提取文本：

{
  "name": "extract_pdf_text", 
  "arguments": {
    "pdf_path": "/path/to/document.pdf",
    "page_range": "1-5"
  }
}

3. OCR 处理

对图像文件进行 OCR：

{
  "name": "perform_ocr",
  "arguments": {
    "image_path": "/path/to/image.png",
    "language": "eng"
  }
}

4. PDF 结构分析

分析文档结构和元数据：

{
  "name": "analyze_pdf_structure",
  "arguments": {
    "pdf_path": "/path/to/document.pdf"
  }
}

5. 批量处理

处理多个文件：

{
  "name": "batch_process_pdfs",
  "arguments": {
    "input_directory": "/path/to/pdfs/",
    "output_directory": "/path/to/output/",
    "file_pattern": "*.pdf"
  }
}

🔌 客户端集成

Claude Desktop

添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "readpdfx": {
      "command": "python",
      "args": ["path/to/readpdfx/run.py"],
      "env": {
        "PYTHONPATH": "path/to/readpdfx"
      }
    }
  }
}

LM Studio

配置 MCP 服务器：

命令: python
参数: path/to/readpdfx/run.py
URL: http://localhost:8000 (HTTP 模式)

Continue.dev

添加到 config.json:

{
  "contextProviders": [
    {
      "name": "mcp",
      "params": {
        "command": "python",
        "args": ["path/to/readpdfx/run.py"]
      }
    }
  ]
}

Cursor

在 settings.json 中配置：

{
  "mcp.servers": {
    "readpdfx": {
      "command": "python",
      "args": ["path/to/readpdfx/run.py"]
    }
  }
}

📁 查看 client-configs/ 以获取详细的集成指南。

🌐 API 端点

MCP 协议端点

POST /mcp/initialize - 初始化 MCP 会话
POST /mcp/tools/list - 列出可用工具
POST /mcp/tools/call - 调用 MCP 工具
GET /mcp/manifest - 获取 MCP 清单

HTTP 端点

GET /health - 健康检查
POST /jsonrpc - JSON-RPC 2.0 端点
GET /docs - API 文档
GET /tools - 工具发现

🔧 配置

环境变量

MCP_SERVER_HOST=localhost      # 服务器主机
MCP_SERVER_PORT=8000           # 服务器端口  
TESSERACT_CMD=/usr/bin/tesseract  # Tesseract 路径
PYTHONPATH=.                   # Python 路径

配置文件

mcp.json - MCP 协议配置
mcp-config.yaml - YAML 配置
pyproject.toml - Python 项目配置
package.json - Node.js 兼容性

🐳 Docker & Kubernetes

Docker 部署

使用 Docker 快速启动

# 使用 Docker 构建并运行
docker build -t ocr-pdf-mcp .
docker run -p 8000:8000 -v ./pdf-test:/app/pdf-test:ro ocr-pdf-mcp

# 或使用 Docker Compose
docker-compose up -d

自动化 Docker 部署

# Linux/macOS
./scripts/docker-deploy.sh run

# Windows
scripts\docker-deploy.bat run

可用的 Docker 命令：

build - 仅构建 Docker 镜像
run - 构建并运行容器（默认）
start - 启动容器（假设镜像已存在）
stop - 停止正在运行的容器
logs - 显示容器日志
clean - 停止容器并删除镜像
status - 显示容器状态

Kubernetes 部署

部署到 Kubernetes

# 快速部署
./scripts/k8s-deploy.sh deploy

# 手动部署
kubectl apply -f k8s/ -n ocr-pdf-mcp

Kubernetes 资源

部署: k8s/deployment.yaml - 主应用程序部署
服务: k8s/deployment.yaml - 服务暴露
入口: k8s/ingress.yaml - 外部访问
配置映射: k8s/configmap.yaml - 配置管理
HPA: k8s/hpa.yaml - 水平 Pod 自动扩展器

Kubernetes 命令

# 缩放部署
kubectl scale deployment ocr-pdf-mcp --replicas=5 -n ocr-pdf-mcp

# 端口转发以实现本地访问
kubectl port-forward svc/ocr-pdf-mcp-service 8000:80 -n ocr-pdf-mcp

# 查看日志
kubectl logs -f deployment/ocr-pdf-mcp -n o-ocr-pdf-mcp

# 检查状态
kubectl get pods,svc,ingress -n ocr-pdf-mcp

生产考虑

多阶段构建

使用 Dockerfile.prod 进行优化的生产构建：

docker build -f Dockerfile.prod -t ocr-pdf-mcp:prod .

环境变量

# Docker
docker run -e LOG_LEVEL=INFO -e CORS_ORIGINS="*" ocr-pdf-mcp

# Kubernetes - 更新 ConfigMap
kubectl edit configmap ocr-pdf-mcp-config -n ocr-pdf-mcp

持久存储

# 添加到 deployment.yaml
volumeMounts:
- name: pdf-storage
  mountPath: /app/pdf-test
volumes:
- name: pdf-storage
  persistentVolumeClaim:
    claimName: pdf-storage-pvc

🧪 测试

运行测试

python test_mcp_server.py

手动测试

# 健康检查
curl http://localhost:8000/health

# 列出工具  
curl -X POST http://localhost:8000/mcp/tools/list \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# 调用工具
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", 
    "method": "tools/call",
    "params": {
      "name": "process_pdf_smart",
      "arguments": {"pdf_path": "/path/to/test.pdf"}
    },
    "id": 1
  }'

📊 性能

启动时间: < 2 秒
内存使用: ~50MB 基础
吞吐量: 每分钟 10+ PDF
并发请求: 最多 100
文件大小限制: 每个文件 100MB

🛠️ 开发

开发模式

python run_server.py --dev --port 8000

项目结构

readpdfx/
├── run.py                 # 简单生产运行器
├── run_server.py          # 带选项的高级运行器  
├── mcp_server.py          # 核心 MCP 服务器
├── mcp_tools.py           # MCP 工具实现
├── mcp_types.py           # MCP 协议类型
├── mcp_server_runner.py   # HTTP 服务器运行器
├── client-configs/        # 客户端集成指南
├── backup/                # 遗留文件
└── tests/                 # 测试文件

添加新工具

在 mcp_tools.py 中定义工具模式
实现工具处理器方法
在 MCPToolsRegistry 中注册工具
更新测试和文档

🐛 故障排除

常见问题

服务器无法启动

# 检查端口可用性
netstat -an | grep 8000

# 尝试不同的端口
python run_server.py --port 8001

OCR 不工作

# 检查 Tesseract 安装
tesseract --version

# 安装语言数据
tesseract --list-langs

权限错误

确保对 PDF 文件有读取权限
检查输出目录的写入权限
使用适当的用户权限运行

连接超时

验证服务器是否运行：curl http://localhost:8000/health
检查防火墙设置
尝试使用 HTTP 而不是直接的 MCP 连接

调试模式

python run_server.py --dev

📈 监控

健康检查

curl http://localhost:8000/health

指标（未来）

请求计数和延迟
工具使用统计
错误率和类型
资源利用率

🤝 贡献

分叉仓库
创建功能分支：git checkout -b feature/new-tool
修改并添加测试
提交拉取请求

开发环境设置

git clone https://github.com/irev/mcp-readpdfx.git
cd readpdfx
pip install -r requirements-dev.txt
python test_mcp_server.py

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

🔗 链接

仓库: https://github.com/irev/mcp-readpdfx
问题: https://github.com/irev/mcp-readpdfx/issues
文档: https://github.com/irev/mcp-readpdfx#readme
MCP 协议: 模型上下文协议规范

🏆 致谢

MCP 协议团队为规范
FastAPI 为 Web 框架
Tesseract OCR 为文本识别
PyPDF2 和 pdfplumber 为 PDF 处理

为 MCP 社区制作 ❤️