ledgerbackup

ledgerbackup

ledgerbackup 是一个小型本地桥接工具，可连接托管的 Boxkite MCP 服务。该服务会备份并导出与你的 Boxkite 账户关联的组织（Xero、Sage、Reckon 或 QuickBooks）的会计数据。它会列出这些组织，启动对某个组织数据的 只读导出，然后持续跟踪该导出的状态、清单和 文件到对象的映射，直到可以获取已完成 ZIP 文件的 签名下载 URL。

该桥接工具本身不存储会计数据。它会在本地提供上游服务的工具列表， 内容与从实时端点捕获的内容完全一致，并将每次工具调用转发到上游， 原样返回结果。

工具

• list_organisations — 列出已通过身份验证的 Boxkite 账户关联的会计组织。无需参数。
• start_export — 启动对某个组织数据的只读导出。必填参数：organisationId （来自 list_organisations）。根据上游描述，每个组织的导出费用为 39 美元： 如果款项尚未支付，响应状态为 awaiting_payment，并包含 Stripe 结账 URL；重复调用会返回现有导出， 而不会创建第二个导出或再次收费。一次典型的 导出需要数小时。
• list_exports — 列出一次性导出，按时间从新到旧排序，可选按 organisationId 筛选。 不会产生副作用：绝不会启动导出或收取费用。
• get_export_status — 报告某个导出的状态 （queued | running | ready | failed）、进度， 以及何时再次轮询。必填参数：exportId。
• get_export_manifest — 查看进行中的 导出目前包含的内容，可通过 fileOffset 和 fileLimit 分页。必填参数： exportId。
• get_export_mapping — 对于进行中的导出， 将每个已发现的文件映射到其代表的会计对象，分页方式相同。必填参数： exportId。
• get_download_url — 返回已完成导出 ZIP 文件的短期有效签名 URL，在导出的 7 天保留期内有效。必填参数： exportId。

配置

• BOXKITE_MCP_URL（可选）— 覆盖 上游端点。默认为 https://app.getboxkite.com/mcp。（此覆盖机制是本次重建自行添加并明确标注的内容。）
• BOXKITE_API_KEY（可选）— 设置后，每个上游请求都会携带 X-API-Key: <key> 标头，其中包含你的 Boxkite API 密钥。未设置时，不会发送密钥标头。 绝不会发送 Authorization 标头。（此转发机制也是本次重建自行添加并明确标注的内容；原始接口是在不带密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 为 2025-03-26， clientInfo name 为 ledgerbackup），然后发送 notifications/initialized 通知，接着发送携带调用方参数 （保持不变）的 tools/call 请求。上游以 Mcp-Session-Id 标头响应 initialize 时，该值会附加到会话的 后续每个请求中；该会话会在进程运行期间重复使用。响应可能以 普通 JSON 或服务器发送事件的形式返回；两种格式都会读取。

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

CLI

每个工具也可作为一个子命令使用，并接收一个 JSON 参数字符串：

npx @reneturcios/ledgerbackup list_organisations
npx @reneturcios/ledgerbackup start_export '{"organisationId":"org-123"}'
npx @reneturcios/ledgerbackup get_export_status '{"exportId":"exp-9"}'
npx @reneturcios/ledgerbackup get_download_url '{"exportId":"exp-9"}'
npx @reneturcios/ledgerbackup --version

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

MCP 服务

npx -y @reneturcios/ledgerbackup mcp

MCP 客户端配置：

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

Docker

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

容器的默认命令是 mcp，因此第一种形式会启动 stdio MCP 服务；其他参数则照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用桩接的 JSON-RPC 上游运行，不会发起实时网络调用。

License

MIT — see LICENSE.