MCP Invoice

This is a project for an MCP (Model Context Protocol) server developed using Python, focusing on a suite of tools for invoice and receipt processing. The project leverages OCR technology to achieve invoice recognition, data extraction, and PDF processing functions, providing AI assistants with the capability to handle invoices.

Features

• Invoice and Receipt OCR Processing:
  • High-accuracy text recognition using the macOS Vision framework
  • Supports processing of individual PDF or image files (JPEG, PNG)
  • Supports batch processing of all invoice and receipt files in a directory
  • Supports OCR recognition for both Chinese and English, suitable for various invoice formats
  • Provides structured data extraction for easy subsequent analysis
• PDF Merging and Management Functions:
  • Supports merging multiple invoice or receipt PDF files into one
  • Supports merging multiple invoice images (JPEG, PNG) into a single PDF file
  • Supports mixed merging of different formats of invoices and receipts
• Efficient memory handling to reduce disk I/O and improve processing speed

MCP Deployment Guide

Environment Requirements

• macOS system (supports Vision framework)
• Python 3.10 or higher
• uv dependency management tool

Installation from GitHub

1. Ensure that uv is installed:

bash
pip install uv

1. Clone the project from GitHub and install dependencies:

bash
git clone https://github.com/[username]/mcp-invoice.git
cd mcp-invoice
uv venv
source .venv/bin/activate
uv pip install -e .

Install PDF Processing Dependencies

pdf2image requires Poppler to be installed on the system:

bash
brew install poppler

Deploy as MCP Service

There are two ways to deploy the MCP service:

1. Run the Server Directly

bash

Standard mode

mcp-invoice

Or enable debug mode (includes text position information)

MCP_INVOICE_DEBUG=true mcp-invoice

2. Use the invoice_server.py Script

bash

Standard mode

python invoice_server.py

Or enable debug mode

MCP_INVOICE_DEBUG=true python invoice_server.py

Configure as System Service

You can configure the MCP service as a system service so that it starts automatically when the system boots up:

1. Create a LaunchAgent plist file:

bash
mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.user.mcp-invoice.plist << EOF

Create log directory

mkdir -p logs

Load the service

launchctl load ~/Library/LaunchAgents/com.user.mcp-invoice.plist

1. Start the service:

bash
launchctl start com.user.mcp-invoice

1. Stop the service:

bash
launchctl stop com.user.mcp-invoice

AI Editor Integration

Configuring MCP in Cursor

In the Cursor editor, you can add the MCP Invoice service through the following configuration:

1. Open the MCP configuration file for Cursor:

   • macOS: $HOME/Library/Application Support/Cursor/tools/tools.json
   • Linux: $HOME/.config/Cursor/tools/tools.json
   • Windows: %APPDATA%Cursor\tools\tools.json

2. Add the MCP Invoice service configuration in the tools.json file:

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. After restarting Cursor, you can directly request to use features in the AI assistant, for example:
"Please use the OCR tool to read the file: /path/to/document.pdf"
"Please merge these PDF files: /path/to/file1.pdf, /path/to/file2.pdf"

Configuring MCP in Cline

Integrating MCP with Cline is similar to Cursor:

1. Update the Cline configuration file to add this MCP tool.
2. Restart the Cline client.
3. Request to process invoice files in the same way as with Cursor.

Configuring MCP in Roocode

To integrate MCP Invoice service in Roocode:

1. Configure external tools according to the Roocode documentation.
2. Point to the deployed MCP Invoice service.
3. Use natural language in Roocode to request processing of invoice files.

MCP Service Debugging

1. Enable detailed logging:

bash
MCP_INVOICE_DEBUG=true mcp-invoice

1. Check if the service is running properly:

bash
ps aux | grep mcp-invoice

1. View logs:

bash
tail -f logs/mcp-invoice.log

Usage

The MCP server provides the following main tools:

1. process_file: Processes a single file and extracts text.

   • Parameters: file_path - The absolute path of the file.
   • Returns: A dictionary containing the file path and extracted text.

2. process_directory: Processes all PDF and image files in a directory.

   • Parameters: directory_path - The absolute path of the directory.
   • Returns: A list of dictionaries, each containing the file path and extracted text.

3. merge_pdfs: Merges multiple PDF and/or image files into one PDF.

   • Parameters: file_paths - A list of paths to the files to be merged.
   • Parameters: output_path - The path for the output PDF.
   • Returns: The path of the merged PDF.

Development and Extension

This project uses uv for dependency management and hatch for building.

Setting Up the Development Environment

1. Create a virtual environment:

bash
uv venv
source .venv/bin/activate

1. Install development dependencies:

bash
uv pip install -e ".[dev]"

Troubleshooting

1. Vision framework errors

   • Ensure you are using a macOS system.
   • Ensure pyobjc-framework-vision 11.0 or higher is installed.

2. UTF-8 encoding issues

   • All OCR results are processed using UTF-8 encoding to ensure correct display of multilingual text.

3. PDF conversion errors

   • Ensure poppler is installed.
   • Check that the PDF files have the necessary access permissions and are readable.