ledgerbackup

ledgerbackup

ledgerbackup は、ホスト型の Boxkite MCP サーバーへの小規模なローカルブリッジです。このサーバーは、Boxkite アカウントに接続された組織（Xero、Sage、Reckon、または QuickBooks）の会計データをバックアップしてエクスポートします。組織の一覧を取得し、1つの組織のデータの読み取り専用エクスポートを開始してから、ステータス、マニフェスト、ファイルとオブジェクトの対応付けを追跡し、完成した ZIP の署名付きダウンロード URL が利用可能になるまで確認します。

このブリッジは会計データを保持しません。ライブエンドポイントから取得した内容をそのままローカルで提供し、上流サーバーのツール一覧を公開します。また、各ツール呼び出しを上流に転送し、結果を変更せずに返します。

ツール

• list_organisations — 認証済みの Boxkite アカウントに接続された会計組織を一覧表示します。引数はありません。
• start_export — 1つの組織のデータの読み取り専用エクスポートを開始します。必須：organisationId（list_organisations から取得）。上流の説明によると、エクスポートの費用は組織ごとに $39 です。支払いが未完了の場合、レスポンスのステータスは awaiting_payment となり、Stripe のチェックアウト URL が返されます。同じ呼び出しを繰り返すと、2件目を作成したり課金したりせず、既存のエクスポートが返されます。通常、エクスポートには数時間かかります。
• list_exports — 単発のエクスポートを新しい順に一覧表示します。必要に応じて organisationId で絞り込めます。副作用はなく、エクスポートを開始したり、課金したりすることはありません。
• get_export_status — 1件のエクスポートの状態（queued | running | ready | failed）、進捗状況、および次回のポーリング時期を返します。必須：exportId。
• get_export_manifest — 進行中のエクスポートに現時点で含まれる内容を確認します。fileOffset と fileLimit でページ分割できます。必須：exportId。
• get_export_mapping — 進行中のエクスポートについて、検出された各ファイルと、それが表す会計オブジェクトとの対応付けを取得します。同じ方法でページ分割できます。必須：exportId。
• get_download_url — 完了したエクスポート ZIP の有効期間の短い署名付き URL を返します。この URL はエクスポートの7日間の保持期間内に有効です。必須：exportId。

設定

• BOXKITE_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://app.getboxkite.com/mcp です。（この上書き用フックは、この再構築で独自に追加したものとして明記しています。）
• BOXKITE_API_KEY（任意）— 設定すると、すべての上流リクエストに Boxkite API キーを含む X-API-Key: <key> ヘッダーが付与されます。設定されていない場合、キーのヘッダーは送信されません。Authorization ヘッダーは一切送信されません。（この転送機能も、この再構築で独自に追加したものとして明記しています。元のインターフェースはキーなしで取得したものです。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーミング可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name ledgerbackup）を送り、次に notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送信します。上流が initialize への応答で Mcp-Session-Id ヘッダーを返した場合、その値はセッションの後続リクエストすべてに付与され、プロセスの存続中は同じセッションが再利用されます。応答は通常の JSON として届く場合と、サーバー送信イベントとして届く場合があり、どちらも読み取られます。

上流からの成功結果は、上流が設定した isError フラグを含め、内容がそのまま返されます。失敗（JSON-RPC エラー、2xx 以外のステータス、読み取れない応答、または完了できないリクエスト）は、テキストが ledgerbackup error: で始まる isError 結果として返されます（この表示方法は、この再構築で独自に追加したものとして明記しています）。

CLI

各ツールは、JSON 引数文字列を1つ受け取るサブコマンドとしても利用できます。

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.