MCP发票服务

Name: MCP发票服务
Author: nfshanq

作者：nfshanq2 星标更新：2025-03-27

安装使用来源：spider==github.com

项目介绍

MCP 发票处理

这是一个使用Python开发的MCP（模型上下文协议）服务器项目，专注于发票和收据处理工具集。该项目利用OCR技术实现发票识别、数据提取和PDF处理功能，为AI助手提供发票处理能力。

功能

发票和收据OCR处理：
- 使用macOS Vision框架进行高精度文本识别
- 支持处理单个PDF或图像文件（JPEG、PNG）
- 支持批量处理目录中所有发票和收据文件
- 支持中文和英文的OCR识别，适用于各种发票格式
- 提供结构化数据提取，便于后续分析
PDF合并与管理功能：
- 支持将多个发票或收据PDF文件合并成一个
- 支持将多个发票图像（JPEG、PNG）合并成一个PDF文件
- 支持混合合并不同格式的发票和收据
高效内存处理方法减少磁盘I/O并提高处理速度

MCP部署指南

环境需求

MacOS系统（支持Vision框架）
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

# 或启用调试模式
M
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编辑器集成

在光标编辑器中配置MCP

在光标编辑器中，可以通过以下配置添加MCP发票服务：

打开光标编辑器的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发票服务配置：

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

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

在Cline中配置MCP

Cline与MCP的集成方法类似于光标：

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

在Roocode中配置MCP

在Roocode中集成MCP发票服务：

根据Roocode文档配置外部工具
指向已部署的MCP发票服务
使用自然语言请求在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框架错误
- 确保使用的是MacOS系统
- 确保已安装pyobjc框架vision 11.0或更高版本
UTF-8编码问题
- 所有OCR结果均使用UTF-8编码处理，确保多语言文本正确显示
PDF转换错误
- 确保已安装Poppler
- 检查PDF文件是否有访问和可读权限