saft MCP

SAF-T MCP服务器

使用AI助手解析和分析葡萄牙SAF-T税务文件

    

入门指南 · 可用工具 · 配置

*Versao 葡萄牙语* · *13个工具·152次测试*

______________________________________________________________________

A. 模型上下文协议（MCP）服务器 它使Claude、Cursor和Windsurf等人工智能助手能够加载、验证和分析葡萄牙语 SAF-T （税务标准审计文件）XML文件。加载SAF-T文件并立即查询发票，获取收入摘要、增值税明细，并验证是否符合葡萄牙税务规则。

什么是SAF-T PT？

SAF-T PT是一个强制性的XML文件，所有葡萄牙公司都必须能够从其会计/计费软件导出。它包含公司的发票、付款、客户、产品、税务条目等。此MCP服务器将XML转换为AI助手的可查询数据源。

______________________________________________________________________

快速开始

先决条件

• Python 3.11+ 和 紫外线 （推荐）或pip
• A. SAF-T PT XML文件 从任何葡萄牙计费/会计软件（PHC、Sage、Primavera等）导出

1.安装

pip install saft-mcp

或来源：

git clone https://github.com/bybloom-ai/saft-mcp.git
cd saft-mcp
uv sync

2.添加到您的AI助手

Claude Code

claude mcp add saft-mcp -- /path/to/saft-mcp/.venv/bin/python -m saft_mcp

Claude Desktop

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "saft-mcp": {
      "command": "/path/to/saft-mcp/.venv/bin/python",
      "args": ["-m", "saft_mcp"]
    }
  }
}

Cursor / VS Code / Other MCP clients

添加到MCP客户端配置中：

{
  "mcpServers": {
    "saft-mcp": {
      "command": "/path/to/saft-mcp/.venv/bin/python",
      "args": ["-m", "saft_mcp"]
    }
  }
}

3.开始使用它

问你的AI助手：

“在~/Documents/saft_2025.xml中加载我的SAF-T文件，并给我一个收入摘要”

服务器将解析文件，提取所有发票和税务数据，并通过自然对话进行查询。

______________________________________________________________________

可用工具

saft_load

加载并解析SAF-T PT XML文件。在使用任何其他工具之前，必须先调用此命令。

返回公司名称、NIF、会计期间、SAF-T版本和记录计数（客户、产品、发票、付款）。

处理Windows-1252和UTF-8编码、BOM剥离和自动命名空间检测。50MB以下的文件使用完整DOM进行解析；较大的文件使用流媒体。

______________________________________________________________________

saft_validate

根据官方XSD模式和葡萄牙语业务规则验证加载的文件。

可用规则：

返回结果，包括严重性（错误/警告）、位置和修复建议。

______________________________________________________________________

saft_summary

生成加载文件的执行摘要。不需要参数。

退货：

• 收入总额（毛额、贷方票据、净额）
• 发票和贷记单计数
• 增值税税率明细
• 按收入排名的前10位客户
• 文件类型分布（FT、FR、NC、ND、FS）

______________________________________________________________________

saft_query_invoices

使用完整分页搜索和筛选发票。

返回具有文档编号、日期、类型、客户、金额、状态和行数的匹配发票。

______________________________________________________________________

saft_tax_summary

生成按费率、月份或文档类型分组的增值税分析。

返回应税基数、增值税金额、每组总金额以及总金额。

______________________________________________________________________

saft_query_customers

搜索和过滤客户主数据，增加收入。

向客户返回发票计数和每位客户的总收入。

______________________________________________________________________

saft_query_products

使用销售统计数据搜索和筛选产品目录。

返回产品，包括销售次数、总数量和总收入。

______________________________________________________________________

saft_get_invoice

获取单个发票的完整详细信息，包括所有行项目。

返回完整的发票，包括标题、文件总计、特殊制度以及所有包含产品、数量、价格、税费、免税额和参考的行。

______________________________________________________________________

saft_anomaly_detect

检测加载文件中的可疑模式和异常。

可用支票：

返回异常，包括类型、严重性、描述和受影响的文档。

______________________________________________________________________

saft_compare

将加载的SAF-T文件与第二个文件进行比较（例如，按月、按年）。

可用指标： revenue, customers, products, doc_types, vat.

返回周期标签和一个按度量返回before/after/delta的变化字典。包括最新/最流失的客户、最活跃的客户和百分比变化。

______________________________________________________________________

saft_aging

根据发票和付款计算应收账款账龄。

每个客户的退货，按未付总额排序，每个桶中的金额。根据发票使用FIFO分配付款。

______________________________________________________________________

saft_export

将数据导出到CSV文件，以便在电子表格或其他工具中使用。

返回文件路径、行数和列名。

______________________________________________________________________

saft_stats

生成发票数据的统计概述。

返回发票统计数据（平均值、中位数、标准偏差）、每日/每周/每月分布、客户集中度（帕累托分析）和顶部/底部发票。

______________________________________________________________________

典型工作流程

1. saft_load            -> Parse the XML file
2. saft_validate        -> Check compliance (XSD + business rules)
3. saft_summary         -> Get the big picture (revenue, top customers, VAT)
4. saft_query_invoices  -> Drill into specific invoices
5. saft_get_invoice     -> Full detail for a single invoice
6. saft_tax_summary     -> VAT analysis by rate, month, or doc type
7. saft_anomaly_detect  -> Flag suspicious patterns
8. saft_stats           -> Statistical distributions and trends
9. saft_compare         -> Diff against another SAF-T file
10. saft_export         -> Export results to CSV

加载文件后可以问的示例问题：

• “公司今年的收入是多少？”
• “给我看看所有500欧元以上的贷记单”
• “每月的增值税明细是多少？”
• “此文件中是否存在任何验证错误？”
• “列出第三季度客户XPTO的发票”
• “前五名客户占收入的百分比是多少？”
• “有任何可疑的模式或异常吗？”
• “将此文件与上个月的SAF-T进行比较”
• “应收账款账龄如何？”
• “将所有发票导出为CSV”

______________________________________________________________________

配置

所有设置都可以通过环境变量进行配置 SAFT_MCP_ 前缀：

______________________________________________________________________

建筑

AI Assistant (Claude, Cursor, etc.)
        |
        | MCP Protocol (stdio)
        v
+------------------------------------------+
|           saft-mcp server                |
|                                          |
|  server.py       FastMCP entry point     |
|  state.py        Session management      |
|                                          |
|  parser/                                 |
|    detector.py   Namespace detection     |
|    encoding.py   Charset handling        |
|    full_parser.py   DOM parse (=50MB）
- \[\]会计SAF-T支持（日记账分录、总账、试算表）
- \[ \] `saft_trial_balance` --根据会计数据生成试算表
- \[ \] `saft_ies_prepare` --预填IES年度纳税申报表字段
- \[ \] `saft_cross_check` --交叉引用发票与会计SAF-T
- \[x\] PyPI包(`pip install saft-mcp`)
- \[x\] GitHub操作CI（pytest+ruff+mypy）

______________________________________________________________________

## 支持的SAF-T版本

- **SAF-T PT 1.04_01** （现行葡萄牙标准）

用PHC公司的实际出口进行测试。应使用任何兼容的葡萄牙软件（Sage、Primavera、PHC、Moloni、InvoiceXpress等）中的SAF-T文件。

______________________________________________________________________

## 许可证

麻省理工学院

______________________________________________________________________

建造于 [bybloom.ai](https://bybloom.ai)，一个业务部门 [Bloomidea](https://bloomidea.com/en)