ContaBridge

contabridge-mcp

一款 MCP 服务，用于在西班牙会计软件与 QuickBooks / Xero 之间迁移簿记数据，专为服务于众多客户的 gestorías 和会计师事务所中的 AI Agent 打造。它不会在调用之间存储任何数据，且每个结果都是确定性的。

工具	积分	功能
convert_journal	2	转换 a3ASESOR/a3ECO/a3CON（SUENLACE.DAT）、Sage ContaPlus / Sage 50（包含 142 个字段的 Diario CSV，或 XDiario ASCII）、电子表格 CSV（Holded、Excel、任意 ERP）、QuickBooks（Desktop IIF、Online journal CSV）和 Xero（manual journal CSV）之间的日记账。调整子科目位数（4300001 → 43000001，430.1 → 43000001）、重命名科目并重新编号分录。
bank_to_journal	3	将 Norma 43 银行对账单转换为以 572 子科目为对方科目的日记账分录。按顺序应用规则，根据文本、正则表达式、AEB 概念或借贷方向将交易映射到对方科目；未匹配任何规则的交易会记入 555 并列出。
build_journal	2	将 Agent 编制的分录（发票、工资单、应计项目）写入任意一种格式。
bank_statement_csv	1	将 Norma 43 对账单转换为适用于 Xero（预编码模板）或 QuickBooks Online（3 列）的银行对账单 CSV。
validate_journal	1	执行 A3 和 ContaPlus 导入时的检查：分录平衡、每行有借方或贷方（不能两者都有）、PGC 组、财政年度、科目位数混用。
resize_account、detect_format、pricing、credits_balance	0	免费辅助工具。

输出文件以 content 和 content_base64 形式返回。Base64 版本采用 Windows-1252 编码和 CRLF 换行符（CSV 使用带 BOM 的 UTF-8），这是这些程序导入所需的格式。

计费方式如下：

• 会被拒绝的文件（不平衡、无法读取、缺少列）会在扣除任何积分之前被拒绝。
• 扣除积分后发生的故障会退还积分。

格式和来源

• A3：“Enlace contable de entrada. Descripción de registros”（Wolters Kluwer）。记录类型 0，格式 5（512 字节）和格式 4（256 字节）。读取时会跳过发票记录（类型 1、2 和 9），并在警告中报告。
• ContaPlus：“Protocolo de comunicación de programas de gestión con ContaPlus”（Sage，2023）。写入 Asien、Fecha、SubCta、Contra、Concepto、Documento、MonedaUso=2、EuroDebe 和 EuroHaber。固定宽度 ASCII 变体（32 个字段）采用与开源 BulmaGés 导出器相同的布局。
• QuickBooks Desktop IIF：GENERAL JOURNAL 交易（以制表符分隔的 !TRNS/!SPL/!ENDTRNS）。借方为正数，贷方为负数，因此 TRNS 金额等于其 SPL 行金额之和的负值。其他 IIF 列表（科目、客户）会跳过，并在警告中报告。
• QuickBooks Online：“Import journal entries” CSV，包含 Journal No., Journal Date, Account Name, Debits, Credits, Description, Name。
• Xero：“Import a manual journal” 模板（*Narration, *Date, Description, *AccountCode, *TaxRate, *Amount、跟踪）。Narration 和 Date 相同的行构成一笔日记账。xero_tax_rate 会将 TaxRate 设置为该组织中使用的名称（英国为 No VAT，澳大利亚为 BAS Excluded，新西兰为 No GST，美国为 Tax Exempt）。
• QuickBooks 和 Xero 的日期遵循 date_style：mdy（QuickBooks 默认）、dmy（Xero 默认）或 iso。金额使用小数点，逗号始终按千位分隔符读取。它们的科目使用名称或代码，因此会依据各自的科目表验证，而非依据 PGC。使用 account_map 可在与 A3/ContaPlus 互相转换时映射科目。
• CSV：系统会自动检测西班牙语和英语列名（fecha、cuenta、debe、haber、importe+d/h……），也可通过 column_map 指定。没有分录编号的文件会通过累积各行直至平衡的方式分组为分录。

安装

你只需要 KeyFlint 许可证（LIC-...）。网关 URL、公钥和结账链接均有默认值。

Claude Desktop，一键安装： 从最新版本下载 contabridge-mcp-X.Y.Z.mcpb，双击并粘贴许可证。无需终端，也无需 JSON。

Claude Code：

claude mcp add contabridge -e KEYFLINT_LICENSE=LIC-... -- uvx contabridge-mcp

Cursor、Windsurf、Claude Desktop（JSON）：

{
  "mcpServers": {
    "contabridge": {
      "command": "uvx",
      "args": ["contabridge-mcp"],
      "env": { "KEYFLINT_LICENSE": "LIC-..." }
    }
  }
}

可选项：KEYFLINT_URL、KEYFLINT_PUBLIC_KEYS（未设置时从网关获取并缓存到 ~/.keyflint/keyring.json）、KEYFLINT_CHECKOUT_URL。

托管模式：CONTABRIDGE_TRANSPORT=http contabridge-mcp --http（每个请求均需许可证，Authorization: Bearer LIC-...）。

调优：CONTABRIDGE_PRICES（convert_journal=3,bank_to_journal=5）、CONTABRIDGE_MAX_BYTES。

视觉卡片（MCP Apps）

在 Claude、ChatGPT、VS Code 和 Goose 中，每个付费工具和 credits_balance 都会在聊天中呈现为交互式卡片：显示带充值进度条和购买按钮的额度余额，或结果摘要（关键数据、问题、表格预览和扣除的额度）。它是 ui://contabridge/card.html 资源，独立运行且不访问网络。其他客户端仍会收到与之前相同的 JSON。

Claude 技能

skills/contabridge/SKILL.md（打包在 distribution/contabridge-skill.zip 中）会告知 Agent 应使用哪个工具、应询问哪种账号长度，以及如何保存文件。

测试

pip install -e '.[test]' && pytest

测试使用虚拟 KeyFlint 网关和本地签名的许可证，因此无需联网。A3 和 ContaPlus 布局均会按照官方规范逐项检查。

许可证

Business Source License 1.1。源码可用；生产环境使用需要 KeyFlint 许可证（或必须用于非商业用途）。每个版本在发布四年后转为 Apache 2.0。请参阅 LICENSE。