SUNAT XML MCP服务器和代理
模型上下文协议（MCP）服务器和基于Ollama的代理，用于从符合SUNAT标准的XML发票（UBL 2.1格式）中提取结构化会计数据。
概述
该项目提供：
- MCP服务器：公开用于解析SUNAT XML发票和生成会计分录的确定性工具
- Ollama代理商：使用本地LLM模型与MCP服务器交互的自然语言界面
特性
- Parse Sunat UBL 2.1 XML发票（发票、票据、贷记/借记票据）
- 提取结构化数据，包括供应商、客户、金额、税款和行项目
- 生成会计日记账分录建议
- 将分类账数据导出到CSV或SQLite
- 通过Ollama进行自然语言交互
先决条件
- Python 3.11或更高版本
- 奥拉玛 在本地安装并运行
- 本地LLM模型（例如。，
llama3)途经Ollama
安装
- 克隆存储库 （如适用）：
cd sunat_mcp- 创建并激活虚拟环境:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项:
pip install -r requirements.txt或作为软件包安装：
pip install -e .- 安装Ollama （如果尚未安装）：
- 请遵循以下说明 https://ollama.ai - 拉一个模型： ollama pull llama3
项目结构
sunat_mcp/
├── src/
│ ├── sunat_mcp/
│ │ ├── __init__.py
│ │ ├── server.py # MCP server implementation
│ │ ├── parser.py # SUNAT UBL 2.1 XML parser
│ │ ├── models.py # Data models
│ │ └── storage.py # CSV/SQLite export
│ └── agent/
│ ├── __init__.py
│ └── ollama_agent.py # Ollama-based agent
├── tests/
│ ├── test_parser.py
│ └── fixtures/
│ └── sample_invoice.xml
├── requirements.txt
├── pyproject.toml
└── README.md用法
运行MCP服务器
MCP服务器可以通过stdio传输独立运行：
python src/sunat_mcp/server.py或者通过在MCP设置中配置它，将其与MCP客户端（如Claude Desktop、Cursor等）一起使用。
使用代理
运行交互式代理：
python src/agent/ollama_agent.py交互示例：
You: List all XML files in ./invoices
Agent: [Lists XML files]
You: Parse invoice F001-000123.xml
Agent: [Parses and displays invoice data]
You: Process all invoices from November and calculate total IGV
Agent: [Processes invoices and calculates totals]MCP工具
服务器公开了以下工具：
- list_文档（目录）
- 列出目录中的所有XML文件 - 返回文件元数据（名称、路径、大小、修改日期）
- parse_invoice（xml_path）
- 解析SUNAT UBL 2.1 XML发票 - 返回包含所有发票字段的结构化JSON
- propose_gjournal_entry（发票数据）
- 生成会计日记账分录建议 - 根据单据类型返回借记/贷记账户建议
- export_ledger（journal_entries、output_path、format）
- 将日记条目导出到CSV或SQLite - 格式：“csv”或“sqlite”
示例：Python API用法
from sunat_mcp.parser import parse_invoice, list_xml_files
from sunat_mcp.models import Invoice
from sunat_mcp.storage import export_to_csv, export_to_sqlite
# List XML files
xml_files = list_xml_files("./invoices")
print(f"Found {len(xml_files)} XML files")
# Parse an invoice
invoice = parse_invoice("./invoices/F001-000123.xml")
print(f"Invoice: {invoice.series_number}")
print(f"Total: {invoice.total} {invoice.currency}")
# Generate journal entry
from sunat_mcp.server import propose_journal_entry_from_invoice
journal_entry = propose_journal_entry_from_invoice(invoice)
# Export to CSV
export_to_csv([journal_entry], "./ledger.csv")支持的文档类型
- 01：事实（发票）
- 03：博莱塔（收据）
- 07：信用票据（信用票据）
- 08：借方票据（借方票据）
提取字段
- 文件类型和系列/编号
- 签发日期
- 货币
- 供应商信息（RUC，名称）
- 客户信息（RUC，姓名）
- 金额（小计、IGV/税、总计）
- 不良信息（如有）
- 标有数量和价格的行项目
发展
运行测试
该项目包括使用真实发票数据文件的全面测试。
基于真实数据的快速测试
使用测试运行器脚本测试您的 data 目录：
python test_runner.py这将：
- 解析中的所有XML文件
data目录 - 显示每个文件的详细信息
- 显示成功/失败率摘要
- 测试日记账分录生成
运行Pytest测试
运行所有单元测试：
pytest tests/运行特定的测试文件：
# Test parser with real data files
pytest tests/test_data_files.py -v
# Test MCP tools
pytest tests/test_mcp_tools.py -v
# Test basic parser functionality
pytest tests/test_parser.py -v运行详细输出：
pytest tests/ -v -s # -s shows print statements测试结构
tests/test_parser.py-使用夹具进行基本解析器单元测试tests/test_data_files.py-使用来自的真实发票文件进行测试data/目录tests/test_mcp_tools.py-MCP服务器工具的集成测试
测试套件自动检测和测试：
- 发票 （类型01）-
factura_1.xml,factura_2.xml - 博莱塔斯 （03型）-
boleta_1.xml,boleta_2.xml - 应收票据 （07型）-
nc_1.xml,nc_2.xml - 借方票据 （08型）-
nd_1.xml,nd_2.xml - 子目录中的文件，如
Factesol_2024-01-01_2024-11-20/
代码格式化
black src/
ruff check src/配置
代理支持通过以下方式进行配置 .env 文件或YAML配置文件，无需修改代码即可轻松定制模型和Ollama URL。
使用.env文件（推荐）
创建一个 .env 项目根目录中的文件：
cp .env.example .env然后编辑 .env 使用您的设置：
# Ollama Configuration
OLLAMA_MODEL=llama3
OLLAMA_BASE_URL=http://localhost:11434
# MCP Server Configuration
MCP_SERVER_PATH=src/sunat_mcp/server.py
# Default Directories
DEFAULT_INVOICE_DIR=./invoices
DEFAULT_OUTPUT_DIR=./output使用YAML配置
或者，创建一个 config.yaml 项目根目录中的文件：
cp config.yaml.example config.yaml然后编辑 config.yaml:
# Ollama Configuration
ollama:
model: llama3
base_url: http://localhost:11434
# MCP Server Configuration
mcp:
server_path: src/sunat_mcp/server.py
# Default Directories
default:
invoice_dir: ./invoices
output_dir: ./output配置优先
配置值按以下顺序加载（最高优先级优先）：
- 环境变量（来自
.env文件） - YAML配置文件(
config.yaml) - 默认值
程序化配置
您还可以通过编程方式覆盖配置：
from agent.ollama_agent import SUNATAgent
# Override specific settings
agent = SUNATAgent(
model="llama3.2",
ollama_base_url="http://localhost:11434",
config_file="custom_config.yaml" # Optional custom config file
)参考文献
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。