fiscocheck

fiscocheck

fiscocheck 是一个小型本地桥接程序，连接到托管的 imperioutils fisco-it MCP 服务，该服务集合了 意大利税务工具。通过它，Agent 可以检查并生成 codice fiscale，验证 partita IVA、IBAN 或 PEC 地址，查询 CAP 或 ATECO 代码，运行常见计算（regime forfettario、IVA、reverse charge、split payment、 IMU），解析 FatturaPA 文档，根据调用方已 计算的金额填写 F24 表格行，处理 Intrastat 周期与组成，读取 NIS2 参考数据，验证收款人， 并运行 guardian 供应商检查。上游的工具描述为意大利语， 此桥接程序按捕获时的原样提供，不作翻译。

此桥接程序不包含自己的税务表。它在本地应答 工具列表，内容与从实时端点捕获的完全一致， 并将每次工具调用转发到上游，原样返回收到的 任何内容。此接口中的工具不会提交申报或执行 付款：F24 和 Intrastat 填写工具根据调用方提供的行组装 文档，而 guardian 工具则检查调用方提供的供应商数据 （IBAN、partita IVA 和 codice fiscale 校验和，以及 欧盟 VIES 公共登记册）。

工具

28 个工具，按类别分组：

• 标识符：validate_codice_fiscale、 generate_codice_fiscale、validate_partita_iva、 validate_iban、validate_pec。
• 查询：lookup_cap、lookup_ateco、 search_ateco。
• 计算：calc_forfettario、calc_iva、 calc_reverse_charge、calc_split_payment、 calc_imu。
• 文档：parse_fatturapa、 parse_verify_fatturapa、compose_f24。
• Intrastat：intrastat_periodicity、 intrastat_compose、intrastat_reference。
• NIS2：nis2_tipologie、nis2_ambito、 nis2_reference。
• 收款人与 guardian：verify_payee、 guardian_list_suppliers、 guardian_supplier_ledger、 guardian_supplier_status、guardian_check_iban、 guardian_watch_supplier。

五个工具（calc_imu、intrastat_reference、 nis2_tipologie、nis2_reference、verify_payee） 捕获时的 required: [] 列表为空，另有三个 guardian 工具（guardian_list_suppliers、 guardian_supplier_ledger、 guardian_supplier_status）捕获时完全没有 required 键；两种形式都会按原样提供。根据原始注册记录，23 个工具 免费，5 个 guardian 工具属于需密钥的工具集。

配置

• IMPERIOUTILS_MCP_URL（可选）——覆盖 上游端点。默认为 https://imperioutils.com/api/mcp。（此覆盖 钩子是本次重建自行标注的复原内容。）
• IMPERIOUTILS_API_KEY（可选）——设置后，每个 上游请求都会携带 X-API-Key: <key> 标头，其中使用调用方自己的 imperioutils API 密钥。 未设置时，不会发送密钥标头。（标头名称由原始注册 记录确定；该记录未指定软件包环境变量名称，因此 从此环境变量转发密钥属于标注的复原内容——原始接口是在不带密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会在上游打开一个可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo 名称为 fiscocheck），然后发送 notifications/initialized 通知，接着发送携带调用方 参数且未经修改的 tools/call 请求。上游以 Mcp-Session-Id 标头应答 initialize 时，该值会附带在 此会话的后续每个请求中，并在进程存续期间重复使用。 回复可能是普通 JSON，也可能是服务器发送的事件； 两种格式都会读取。

上游的成功结果会原样传递，包括上游设置的任何 isError 标记。失败情况——JSON-RPC 错误、非 2xx 状态、 无法读取的响应，或无法完成的请求——会作为 isError 结果 返回，其文本以 fiscocheck error: 开头（这种呈现方式 是本次重建自行标注的复原内容）。

命令行

每个工具也是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/fiscocheck validate_iban '{"iban":"IT60X0542811101000000123456"}'
npx @reneturcios/fiscocheck validate_codice_fiscale '{"codice_fiscale":"RSSMRA80A01H501U"}'
npx @reneturcios/fiscocheck calc_imu '{}'
npx @reneturcios/fiscocheck --version

退出代码：成功时为 0，返回 isError 结果时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/fiscocheck mcp

MCP 客户端配置：

{
  "mcpServers": {
    "fiscocheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/fiscocheck", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/fiscocheck
docker run --rm ghcr.io/cloudcorprecords/fiscocheck --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；任何其他参数都会正常传递给命令行。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对存根化的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。