Keeping you up to date on AI and Model Context Protocol (MCP)

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 安装

确保已安装 uv：

pip install uv

从 GitHub 克隆项目并安装依赖：

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：

brew install poppler

部署为 MCP 服务

有两种方式部署 MCP 服务：

1. 直接运行服务器

## 标准模式
mcp-invoice

## 或启用调试模式（包含文本位置信息）
MCP_INVOICE_DEBUG=true mcp-invoice

2. 使用 invoice_server.py 脚本

## 标准模式
python invoice_server.py

## 或启用调试模式
MCP_INVOICE_DEBUG=true python invoice_server.py

配置为系统服务

可以将 MCP 服务配置为系统服务，使其在系统启动时自动运行：

创建 LaunchAgent plist 文件：

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

启动服务：

launchctl start com.user.mcp-invoice

停止服务：

launchctl stop com.user.mcp-invoice

AI 编辑器集成

在 Cursor 中配置 MCP

在 Cursor 编辑器中，可以通过以下配置添加 MCP Invoice 服务：

打开 Cursor 的 MCP 配置文件：
- macOS: $HOME/Library/Application Support/Cursor/tools/tools.json
- Linux: $HOME/.config/Cursor/tools/tools.json
- Windows: %APPDATA%\Cursor\tools\tools.json
在 tools.json 文件中添加 MCP Invoice 服务配置：

{
  "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"
      ]
    }
  }
}

重启 Cursor 后，你可以在 AI 助手中直接请求使用功能，例如： "请使用 OCR 工具读取文件：/path/to/document.pdf" "请合并这些 PDF 文件：/path/to/file1.pdf, /path/to/file2.pdf"

在 Cline 中配置 MCP

Cline 与 MCP 集成方法类似于 Cursor：

更新 Cline 配置文件来添加此 MCP 工具
重启 Cline 客户端
使用与 Cursor 相同的方式来请求处理发票文件

在 Roocode 中配置 MCP

在 Roocode 中集成 MCP Invoice 服务：

按照 Roocode 文档配置外部工具
指向已部署的 MCP Invoice 服务
在 Roocode 中使用自然语言请求处理发票文件

MCP 服务调试

启用详细日志：

MCP_INVOICE_DEBUG=true mcp-invoice

检查服务是否正常运行：

ps aux | grep mcp-invoice

查看日志：

tail -f logs/mcp-invoice.log

使用方法

MCP 服务器提供以下主要工具：

process_file: 处理单个文件并提取文本
- 参数：file_path - 文件的绝对路径
- 返回：包含文件路径和提取文本的字典
process_directory: 处理一个目录中的所有 PDF 和图片文件
- 参数：directory_path - 目录的绝对路径
- 返回：包含每个文件路径和提取文本的字典列表
merge_pdfs: 合并多个PDF和/或图片文件为一个PDF
- 参数：file_paths - 要合并的文件路径列表
- 参数：output_path - 输出PDF的路径
- 返回：合并后PDF的路径

开发和扩展

本项目使用 uv 进行依赖管理，使用 hatch 进行构建。

开发环境设置

创建虚拟环境：

uv venv
source .venv/bin/activate

安装开发依赖：

uv pip install -e ".[dev]"

故障排除

Vision framework 错误
- 确保使用 macOS 系统
- 确保已安装 pyobjc-framework-vision 11.0 或更高版本
UTF-8 编码问题
- 所有 OCR 结果均使用 UTF-8 编码处理，确保多语言文本正确显示
PDF 转换错误
- 确保已安装 poppler
- 检查 PDF 文件是否有权限访问和可读