Name: SAF-T税务文件分析服务器
Author: Bloomidea

使用说明

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文件。在使用任何其他工具之前，必须先调用此命令。

参数	类型	说明
`file_path`	string	SAF-T XML文件的路径

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

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

`saft_validate`

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

参数	类型	默认值	说明
`rules`	list[string]	all	要检查的特定规则

可用规则：

规则	它检查什么
`xsd`	针对SAF-T PT 1.04_01 XSD模式的XML结构
`numbering`	每个系列中的顺序发票编号
`nif`	NIF（税务ID）mod-11校验位验证
`tax_codes`	税率与已知的葡萄牙增值税税率相匹配
`atcud`	ATCUD唯一文件代码存在且格式良好
`hash_chain`	发票序列之间的哈希连续性
`control_totals`	计算出的总计与声明的控制总计相匹配

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

`saft_summary`

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

退货：

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

`saft_query_invoices`

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

参数	类型	默认值	说明
`date_from`	string	-	开始日期（YYYY-MM-DD）
`date_to`	string	-	结束日期（YYYY-MM-DD）
`customer_nif`	string	-	按税务ID筛选（部分匹配）
`customer_name`	string	-	按名称筛选（不区分大小写，部分）
`doc_type`	string	-	FT、FR、NC、ND或FS
`min_amount`	number	-	最小总金额
`max_amount`	number	-	最大总金额
`status`	string	-	N（正常），A（已取消），F（已开票）
`limit`	integer	50	每页结果（最多500个）
`offset`	整数	0	分页偏移

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

`saft_tax_summary`

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

参数	类型	默认值	说明
`date_from`	string	-	开始日期（YYYY-MM-DD）
`date_to`	string	-	结束日期（YYYY-MM-DD）
`group_by`	字符串	`rate`	分组方式 `rate`, `month`，或 `doc_type`

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

`saft_query_customers`

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

参数	类型	默认值	说明
`name`	string	-	公司名称（不区分大小写，部分）
`nif`	string	-	税务ID（部分匹配）
`city`	string	-	计费城市（不区分大小写，部分）
`country`	string	-	国家代码（精确，例如“PT”、“ES”）
`limit`	integer	50	每页结果（最多500个）
`offset`	整数	0	分页偏移

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

`saft_query_products`

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

参数	类型	默认值	说明
`description`	string	-	产品描述（不区分大小写，局部）
`code`	string	-	产品代码（部分匹配）
`product_type`	string	-	P（产品），S（服务），O（其他），I（进口），E（出口）
`group`	string	-	产品组（不区分大小写，局部）
`limit`	integer	50	每页结果（最多500个）
`offset`	整数	0	分页偏移

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

`saft_get_invoice`

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

参数	类型	说明
`invoice_no`	string	确切的发票号码（例如“FR 2025A15/90”）

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

`saft_anomaly_detect`

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

参数	类型	默认值	说明
`checks`	list[string]	all	要运行的特定检查

可用支票：

检查	它检测到什么
`duplicate_invoices`	相同客户+金额+日期组合
`numbering_gaps`	每个系列中缺少序列号
`weekend_invoices`	周六或周日开具的发票
`unusual_amounts`	发票金额与平均值的偏差超过3个标准差
`cancelled_ratio`	每个系列的取消率很高
`zero_amount`	总金额为零的发票

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

`saft_compare`

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

参数	类型	默认值	说明
`file_path`	string	-	第二个SAF-T XML文件的路径
`metrics`	list[string]	all	要比较的指标

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

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

`saft_aging`

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

参数	类型	默认值	说明
`reference_date`	string	今天	从（YYYY-MM-DD）到年龄的日期
`buckets`	list[int]	[30,60,90120]	以天为单位的老化桶边界

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

`saft_export`

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

参数	类型	默认值	说明
`export_type`	string	-	`invoices`, `customers`, `products`, `tax_summary`，或 `anomalies`
`file_path`	string	-	输出CSV文件路径
`filters`	dict	-	可选过滤器（与相应的查询工具相同）

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

`saft_stats`

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

参数	类型	默认值	说明
`date_from`	string	-	开始日期（YYYY-MM-DD）
`date_to`	string	-	结束日期（YYYY-MM-DD）

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

典型工作流程

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_ 前缀：

变量	默认值	描述
`SAFT_MCP_STREAMING_THRESHOLD_BYTES`	52428800（50 MB）	以上的文件使用流解析器
`SAFT_MCP_MAX_FILE_SIZE_BYTES`	524288000（500 MB）	可接受的最大文件大小
`SAFT_MCP_SESSION_TIMEOUT_SECONDS`	1800（30分钟）	不活动后会话到期
`SAFT_MCP_MAX_CONCURRENT_SESSIONS`	5	最大同时加载文件数
`SAFT_MCP_DEFAULT_QUERY_LIMIT`	50	每页默认结果
`SAFT_MCP_MAX_QUERY_LIMIT`	500	每页最大结果数
`SAFT_MCP_LOG_LEVEL`	信息	日志记录级别

建筑

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 (< 50 MB)  |
|    models.py     Pydantic data models    |
|                                          |
|  tools/                                  |
|    load.py            saft_load          |
|    validate.py        saft_validate      |
|    summary.py         saft_summary       |
|    query_invoices.py  saft_query_invoices|
|    query_customers.py saft_query_customer|
|    query_products.py  saft_query_products|
|    get_invoice.py     saft_get_invoice   |
|    tax_summary.py     saft_tax_summary   |
|    anomaly_detect.py  saft_anomaly_detect|
|    compare.py         saft_compare       |
|    aging.py           saft_aging         |
|    export.py          saft_export        |
|    stats.py           saft_stats         |
|                                          |
|  validators/                             |
|    xsd_validator.py   XSD 1.04_01        |
|    business_rules.py  Numbering, totals  |
|    nif.py             NIF mod-11         |
|    hash_chain.py      Hash continuity    |
|                                          |
|  schemas/                                |
|    saftpt1.04_01.xsd  Official XSD       |
+------------------------------------------+

关键设计决策：

所有货币价值使用 Decimal 避免税务计算中的浮点四舍五入
lxml 文件 对于XML解析，使用自动XSD 1.1功能剥离（葡萄牙官方XSD使用 xs:assert 和 xs:all 具有无界子项，lxml的XSD 1.0引擎无法原生处理）
Pydantic v2型号 根据真实的PHC公司出口进行验证
命名空间自动检测 通过扫描文件的前4KB（从不硬编码）
Windows-1252编码 通过XML声明本机处理

发展

# Install with dev dependencies
uv sync --extra dev

# Run tests (152 tests)
pytest

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Type check
mypy src/

项目结构

saft-mcp/
  src/saft_mcp/         # Source code
    server.py           # FastMCP entry point, tool registration
    config.py           # Settings (pydantic-settings, env vars)
    state.py            # Session store, parsed file state
    exceptions.py       # SaftError hierarchy
    parser/             # XML parsing (encoding, detection, models)
    tools/              # One file per MCP tool
    validators/         # XSD, business rules, NIF, hash chain
    schemas/            # Official XSD file
  tests/                # Mirrors src/ structure
  pyproject.toml        # Project config (hatch build, ruff, mypy, pytest)

路线图

[x] saft_query_customers --搜索和过滤客户主数据
[x] saft_query_products --搜索和筛选产品目录
[x] saft_get_invoice --包含行项目的完整发票详细信息
[x] saft_anomaly_detect --标记重复发票、编号缺口、异常金额
[x] saft_compare --区分两个SAF-T文件（例如，按月）
[x] saft_aging --应收账款账龄分析
[x] saft_export --将数据导出到CSV
[x] saft_stats --统计概述和分布
[ ] 流解析器 对于大文件（>=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，一个业务部门 Bloomidea

使用说明

SAF-T MCP服务器

什么是SAF-T PT？

快速开始

先决条件

1.安装

2.添加到您的AI助手

3.开始使用它

可用工具

saft_load

saft_validate

saft_summary

saft_query_invoices

saft_tax_summary

saft_query_customers

saft_query_products

saft_get_invoice

saft_anomaly_detect

saft_compare

saft_aging

saft_export

saft_stats

典型工作流程

配置

建筑

发展

项目结构

路线图

支持的SAF-T版本

许可证

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具