README.md•6.1 kB
# MCP Invoice
这是一个使用 Python 开发的 MCP (Model Context Protocol) 服务器项目，专注于发票和收据处理的工具集合。该项目利用 OCR 技术实现发票识别、数据提取和 PDF 处理功能，为 AI 助手提供发票处理能力。
## 功能特点
- 发票和收据 OCR 处理：
- 使用 macOS Vision framework 进行高精度文本识别
- 支持处理单个 PDF 或图片文件（JPEG、PNG）
- 支持批量处理目录下的所有发票和收据文件
- 支持中英文 OCR 识别，适用于各类发票格式
- 提供结构化数据提取，方便后续分析
- PDF合并和管理功能：
- 支持将多个发票或收据 PDF 文件合并为一个
- 支持将多张发票图片（JPEG、PNG）合并为一个 PDF 文件
- 支持混合合并不同格式的发票和收据
- 高效的内存处理方式，减少磁盘 I/O，提高处理速度
## MCP 部署指南
### 环境要求
- macOS 系统（支持 Vision framework）
- Python 3.10 或更高版本
- uv 依赖管理工具
### 从 GitHub 安装
1. 确保已安装 uv：
```bash
pip install uv
```
2. 从 GitHub 克隆项目并安装依赖：
```bash
git clone https://github.com/[username]/mcp-invoice.git
cd mcp-invoice
uv venv
source .venv/bin/activate
uv pip install -e .
```
### 安装 PDF 处理依赖
pdf2image 需要系统上安装 Poppler：
```bash
brew install poppler
```
### 部署为 MCP 服务
有两种方式部署 MCP 服务：
#### 1. 直接运行服务器
```bash
# 标准模式
mcp-invoice
# 或启用调试模式（包含文本位置信息）
MCP_INVOICE_DEBUG=true mcp-invoice
```
#### 2. 使用 invoice_server.py 脚本
```bash
# 标准模式
python invoice_server.py
# 或启用调试模式
MCP_INVOICE_DEBUG=true python invoice_server.py
```
### 配置为系统服务
可以将 MCP 服务配置为系统服务，使其在系统启动时自动运行：
1. 创建 LaunchAgent plist 文件：
```bash
mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.user.mcp-invoice.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.mcp-invoice</string>
<key>ProgramArguments</key>
<array>
<string>$(which python)</string>
<string>$(pwd)/invoice_server.py</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>$(pwd)/logs/mcp-invoice.log</string>
<key>StandardErrorPath</key>
<string>$(pwd)/logs/mcp-invoice-error.log</string>
<key>WorkingDirectory</key>
<string>$(pwd)</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
</dict>
</plist>
EOF
# 创建日志目录
mkdir -p logs
# 加载服务
launchctl load ~/Library/LaunchAgents/com.user.mcp-invoice.plist
```
2. 启动服务：
```bash
launchctl start com.user.mcp-invoice
```
3. 停止服务：
```bash
launchctl stop com.user.mcp-invoice
```
## AI 编辑器集成
### 在 Cursor 中配置 MCP
在 Cursor 编辑器中，可以通过以下配置添加 MCP Invoice 服务：
1. 打开 Cursor 的 MCP 配置文件：
- macOS: `$HOME/Library/Application Support/Cursor/tools/tools.json`
- Linux: `$HOME/.config/Cursor/tools/tools.json`
- Windows: `%APPDATA%\Cursor\tools\tools.json`
2. 在 `tools.json` 文件中添加 MCP Invoice 服务配置：
```json
{
"tools": {
"invoice": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-invoice",
"run",
"invoice_server.py"
],
"env": {
"MCP_INVOICE_DEBUG": "false"
},
"alwaysAllow": [
"process_file",
"process_directory",
"merge_pdfs"
]
}
}
}
```
3. 重启 Cursor 后，你可以在 AI 助手中直接请求使用功能，例如：
"请使用 OCR 工具读取文件：/path/to/document.pdf"
"请合并这些 PDF 文件：/path/to/file1.pdf, /path/to/file2.pdf"
### 在 Cline 中配置 MCP
Cline 与 MCP 集成方法类似于 Cursor：
1. 更新 Cline 配置文件来添加此 MCP 工具
2. 重启 Cline 客户端
3. 使用与 Cursor 相同的方式来请求处理发票文件
### 在 Roocode 中配置 MCP
在 Roocode 中集成 MCP Invoice 服务：
1. 按照 Roocode 文档配置外部工具
2. 指向已部署的 MCP Invoice 服务
3. 在 Roocode 中使用自然语言请求处理发票文件
## MCP 服务调试
1. 启用详细日志：
```bash
MCP_INVOICE_DEBUG=true mcp-invoice
```
2. 检查服务是否正常运行：
```bash
ps aux | grep mcp-invoice
```
3. 查看日志：
```bash
tail -f logs/mcp-invoice.log
```
## 使用方法
MCP 服务器提供以下主要工具：
1. `process_file`: 处理单个文件并提取文本
- 参数：`file_path` - 文件的绝对路径
- 返回：包含文件路径和提取文本的字典
2. `process_directory`: 处理一个目录中的所有 PDF 和图片文件
- 参数：`directory_path` - 目录的绝对路径
- 返回：包含每个文件路径和提取文本的字典列表
3. `merge_pdfs`: 合并多个PDF和/或图片文件为一个PDF
- 参数：`file_paths` - 要合并的文件路径列表
- 参数：`output_path` - 输出PDF的路径
- 返回：合并后PDF的路径
## 开发和扩展
本项目使用 uv 进行依赖管理，使用 hatch 进行构建。
### 开发环境设置
1. 创建虚拟环境：
```bash
uv venv
source .venv/bin/activate
```
2. 安装开发依赖：
```bash
uv pip install -e ".[dev]"
```
## 故障排除
1. **Vision framework 错误**
- 确保使用 macOS 系统
- 确保已安装 pyobjc-framework-vision 11.0 或更高版本
2. **UTF-8 编码问题**
- 所有 OCR 结果均使用 UTF-8 编码处理，确保多语言文本正确显示
3. **PDF 转换错误**
- 确保已安装 poppler
- 检查 PDF 文件是否有权限访问和可读