ReadPDFx - OCR PDF MCP Server

ReadPDFx-OCR PDF MCP服务器

*官方MCP SDK STDIO服务器-符合MCP协议2025-06-18*

ReadPDFx is a comprehensive MCP (Model Context Protocol) server that provides intelligent OCR and PDF processing capabilities using the official MCP SDK with STDIO transport. It automatically detects whether a PDF contains digital text or scanned images and applies the appropriate processing method.

⚡ 快速入门（STDIO服务器）

1.安装依赖项

pip install -r requirements.txt

2.验证安装

# Test imports and tools
python validate_tools.py

3.客户集成

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

克劳德桌面：

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

🚀 特性

• 🎯 官方MCP SDK：采用官方FastMCP框架构建
• 📡 STDIO传输：STDIO上的标准MCP协议
• 🧠 智能PDF处理：自动检测数字内容与扫描内容
• 🔧 5个OCR工具：文本提取、OCR处理、组合操作
• 🌐 通用客户端支持：克劳德桌面、LM工作室、Continue.dev、Cursor
• ⚡ 轻量级：约200行对比HTTP实现中的800+行
• 🛡️ 生产就绪：全面的错误处理和记录
• 📋 自动工具注册：装饰器处理工具发现

🔧 安装

先决条件

• Python 3.8+
• Tesseract OCR

视窗

# Install Python dependencies
pip install -r requirements.txt

# Install 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_config.json:

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

LM 工作室

使用以下配置MCP服务器：

• 命令: python
• 参数: path/to/readpdfx/run.py
• 统一资源定位符: http://localhost:8000 （HTTP模式）

Continue.dev

添加到config.json：

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

光标

在settings.json中配置：

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

📁 看 客户端配置/ 获取详细的集成指南。

🌐 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      # Server host
MCP_SERVER_PORT=8000           # Server port  
TESSERACT_CMD=/usr/bin/tesseract  # Tesseract path
PYTHONPATH=.                   # Python path

配置文件

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

🐳 Docker和Kubernetes

Docker部署

Docker快速入门

# Build and run with Docker
docker build -t ocr-pdf-mcp .
docker run -p 8000:8000 -v ./pdf-test:/app/pdf-test:ro ocr-pdf-mcp

# Or use 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

# Quick deployment
./scripts/k8s-deploy.sh deploy

# Manual deployment
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命令

# Scale deployment
kubectl scale deployment ocr-pdf-mcp --replicas=5 -n ocr-pdf-mcp

# Port forward for local access
kubectl port-forward svc/ocr-pdf-mcp-service 8000:80 -n ocr-pdf-mcp

# View logs
kubectl logs -f deployment/ocr-pdf-mcp -n ocr-pdf-mcp

# Check status
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 - update ConfigMap
kubectl edit configmap ocr-pdf-mcp-config -n ocr-pdf-mcp

持久化存储

# Add to deployment.yaml
volumeMounts:
- name: pdf-storage
  mountPath: /app/pdf-test
volumes:
- name: pdf-storage
  persistentVolumeClaim:
    claimName: pdf-storage-pvc

🧪 测试

运行测试

python test_mcp_server.py

手动测试

# Health check
curl http://localhost:8000/health

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

# Call tool
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                 # Simple production runner
├── run_server.py          # Advanced runner with options  
├── mcp_server.py          # Core MCP server
├── mcp_tools.py           # MCP tools implementation
├── mcp_types.py           # MCP Protocol types
├── mcp_server_runner.py   # HTTP server runner
├── client-configs/        # Client integration guides
├── backup/                # Legacy files
└── tests/                 # Test files

添加新工具

1. 在中定义工具架构 mcp_tools.py
2. 实施工具处理程序方法
3. 在中注册工具 MCPToolsRegistry
4. 更新测试和文档

🐛 故障排除

常见问题

服务器无法启动

# Check port availability
netstat -an | grep 8000

# Try different port
python run_server.py --port 8001

OCR不工作

# Check Tesseract installation
tesseract --version

# Install language data
tesseract --list-langs

权限错误

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

连接超时

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

调试模式

python run_server.py --dev

📈 监控

健康检查

curl http://localhost:8000/health

指标（未来）

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

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/new-tool
3. 进行更改并添加测试
4. 提交拉取请求

开发环境设置

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

📄 许可证

MIT许可证-请参阅 许可证 文件。

🔗 链接

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

🏆 致谢

• MCP协议团队负责规范
• web框架的FastAPI
• Tesseract OCR用于文本识别
• 用于PDF处理的PyPDF2和pdfplumber

______________________________________________________________________

由以下材料制成❤️ 对于MCP社区