Content
# MCP Invoice
This is an MCP (Model Context Protocol) server project developed using Python, focusing on a toolkit for invoice and receipt processing. The project utilizes OCR (Optical Character Recognition) technology to achieve invoice recognition, data extraction, and PDF processing capabilities, providing invoice handling capabilities for AI assistants.
## Features
- Invoice and Receipt OCR Processing:
- High-precision text recognition using the macOS Vision framework
- Supports processing of single PDF or image files (JPEG, PNG)
- Supports batch processing of all invoice and receipt files in a directory
- Supports OCR recognition in both Chinese and English, suitable for various invoice formats
- Provides structured data extraction for subsequent analysis
- PDF Merging and Management Features:
- 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 uv is installed:
```bash
pip install uv
```
2. 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 a System Service
You can configure the MCP service as a system service to run automatically at system startup:
1. Create a LaunchAgent plist file:
```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
# Create log directory
mkdir -p logs
# Load the service
launchctl load ~/Library/LaunchAgents/com.user.mcp-invoice.plist
```
2. Start the service:
```bash
launchctl start com.user.mcp-invoice
```
3. Stop the service:
```bash
launchctl stop com.user.mcp-invoice
```
## AI Editor Integration
### Configure MCP in Cursor
In the Cursor editor, you can add the MCP Invoice service with the following configuration:
1. Open the MCP configuration file in 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 functionality from 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"
### Configure MCP in Cline
The integration method for Cline is similar to that of Cursor:
1. Update the Cline configuration file to add this MCP tool
2. Restart the Cline client
3. Use the same method as Cursor to request processing of invoice files
### Configure MCP in Roocode
To integrate the 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 requests in Roocode to process invoice files
## MCP Service Debugging
1. Enable detailed logging:
```bash
MCP_INVOICE_DEBUG=true mcp-invoice
```
2. Check if the service is running properly:
```bash
ps aux | grep mcp-invoice
```
3. View logs:
```bash
tail -f logs/mcp-invoice.log
```
## Usage
The MCP server provides the following main tools:
1. `process_file`: Process a single file and extract text
- Parameters: `file_path` - Absolute path of the file
- Returns: A dictionary containing the file path and extracted text
2. `process_directory`: Process all PDF and image files in a directory
- Parameters: `directory_path` - Absolute path of the directory
- Returns: A list of dictionaries containing each file path and extracted text
3. `merge_pdfs`: Merge multiple PDF and/or image files into a single PDF
- Parameters: `file_paths` - List of file paths to merge
- Parameters: `output_path` - Path for the output PDF
- Returns: Path of the merged PDF
## Development and Extension
This project uses uv for dependency management and hatch for building.
### Development Environment Setup
1. Create a virtual environment:
```bash
uv venv
source .venv/bin/activate
```
2. 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 version 11.0 or higher is installed
2. **UTF-8 encoding issues**
- All OCR results are processed using UTF-8 encoding, ensure multilingual text displays correctly
3. **PDF conversion errors**
- Ensure Poppler is installed
- Check if the PDF files have the necessary access permissions and are readable
