billparse

billparse

請求書は PDF、スキャン画像、スマートフォンで撮影した写真として届きますが、そこに記載された数値は、最終的にどこかで使える形にする必要があります。billparse は、ホスト型 InvoiceParserPro MCP サービスにつなぐ小規模なローカルブリッジです。請求書文書を渡すと、文書をスプレッドシートに変換したり、計算が合っているかを確認したり、内容を構造化データとして抽出したり、すでに送信した文書の出力を取得したりできます。

解析はすべてローカルマシン以外で行われます。このパッケージは、キャプチャしたツール定義を使って tools/list にローカルで応答し、すべての tools/call をストリーミング可能な HTTP の JSON-RPC セッション経由でホスト型サービスに転送します。サービスから返された内容は変更せずに返します。

ツール

4 つのツールはすべて、指定した文書に対して動作します。読み取り用の 3 つのツールでは、次の 3 つの形式のいずれかで請求書を渡せます。file_url（サービスがダウンロードできる https リンク）、file_base64（ファイルのバイト列を base64 エンコードしたもの。file_name は任意）、または file（クライアント添付のファイルオブジェクト。添付ファイルに対応するクライアント向け）です。

• invoice_to_excel — 請求書を読み取り、ヘッダー項目と明細行を返します。Excel（.xlsx）ファイルと CSV ファイルのダウンロードリンクも返します。キャプチャした説明によると、リンクはサインインなしで 60 分間有効です。また、処理された文書の job_id を返します。
• check_invoice — 請求書の計算が合っているかを検証します。各明細の数量と単価の積、明細と小計の整合性、印字された税率と税額の整合性、小計と税額の合計と総額の整合性を確認します。1 行の判定結果と、見つかったすべての問題を請求書に記載された数値を引用して返します。
• extract_invoice_data — 請求書の内容を構造化された JSON として抽出します。販売元と顧客、請求書番号と日付、PO 番号、通貨、小計、割引、送料、税額と総額、税の明細、すべての明細項目に加え、全体および各フィールドの信頼度を返します。
• get_result — 以前の呼び出しで返された job_id を指定すると、その請求書で利用できるスプレッドシートのリンク、計算チェック、抽出データを取得します。同じ文書を再度送信して処理回数を重ねるのではなく、すでに送信した文書から別の出力を取得したい場合に使います。

このツール群では、購入、サブスクリプションの開始、チェックアウト、API キーの作成は行いません。入力するのは、ユーザー自身の文書です。

インストールと実行

npm 経由で MCP サーバーとして実行する場合：

npx -y @reneturcios/billparse mcp

MCP クライアントの設定：

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

コンテナとして実行する場合：

docker run -i ghcr.io/cloudcorprecords/billparse
docker run --rm ghcr.io/cloudcorprecords/billparse get_result '{"job_id":"job-123"}'

CLI

1 つのバイナリで、コマンドラインと MCP サーバーの両方を利用できます。各ツールはサブコマンドとして実行し、そのツールの引数を単一の JSON 文字列で指定します。

billparse invoice_to_excel '{"file_url":"https://example.com/invoice-1042.pdf"}'
billparse check_invoice '{"file_base64":"...","file_name":"invoice-1042.pdf"}'
billparse extract_invoice_data '{"file_url":"https://example.com/invoice-1042.pdf"}'
billparse get_result '{"job_id":"job-123"}'
billparse --version

終了コード：転送した呼び出しが成功した場合は 0、上流の結果がエラーの場合は 1、不明なサブコマンドや不正な JSON 引数など、使い方に問題がある場合は 2 です。

設定

• INVOICEPARSERPRO_MCP_URL — 上流エンドポイントを上書きします。デフォルトは固定されたホスト型エンドポイント https://api.invoiceparserpro.com/mcp です。（この上書き用変数は、この再ビルドで追加された再構成要素です。）
• INVOICEPARSERPRO_API_KEY — 設定すると、その値がすべてのリクエストで Authorization: Bearer <value> ヘッダーとして上流に送信されます。設定されていない場合、キーのヘッダーは一切送信されません。これは、ツール群のキャプチャ時にキーなしで動作していた状態に合わせています。（変数名と Bearer 形式は再構成要素です。ホスト型サービスのレジストリ記録には Authorization ヘッダーが記載されていますが、パッケージで使う環境変数名は固定されていません。）

上流の障害（サービスからの JSON-RPC エラー、2xx 以外の応答、読み取れない本文、またはリクエスト自体の失敗）は、テキストが billparse error: で始まるエラー結果として呼び出し元に報告されます。

転送の仕組み

最初に転送される呼び出しでセッションが開始されます。initialize リクエスト（プロトコルバージョン 2025-03-26）に続いて、notifications/initialized 通知が送信され、その後に tools/call が実行されます。サービスが initialize リクエストに Mcp-Session-Id ヘッダーを付けて応答した場合、その値は以降のすべてのリクエストに引き継がれ、プロセスの残りの期間は同じセッションが再利用されます。応答は、通常の JSON またはサーバー送信イベントのどちらでも受け付けます。成功した結果は、isError フラグやサービスが含める追加フィールドも含めて、そのまま受け渡されます。

開発

npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev     # run the CLI from source

テストスイートでは、提供されるツールの一覧を記録された各ツールと照合し、セッションのハンドシェイクと再利用をテストします。また、キーのヘッダーに関する両方の分岐を確認し、引数が変更されずに上流へ渡され、結果が変更されずに返されることを検証します。

ライセンス

MIT — LICENSE を参照してください。著作権 (c) 2026 Rene Turcios。