invoiceproof

invoiceproof

invoiceproof は、欧州の電子請求書を扱うサービスである、ホスト型 eInvoiceChecker MCP サーバーへのシンプルなローカルブリッジです。対応フォーマットを確認したり、渡された請求書を識別したり、内容を正規化された JSON として抽出したり、フォーマットの公式ルールセットに照らして検証したり、検出した決定論的なエラーを修正したり、ドキュメントを HTML または PDF としてレンダリングしたりできます。

このブリッジは請求書に関するロジックを持たず、それ自体で検証を行うこともありません。ライブエンドポイントからそのまま取得した上流サーバーのツール一覧をローカルで提供し、各ツール呼び出しを上流に転送して、結果を変更せずに返します。対応範囲は、XRechnung、ZUGFeRD、Factur-X、Peppol BIS、KSeF のほか、上流がサポートするその他のフォーマットや各国のルールセットにわたります。

ツール

必須フィールドが宣言されているツールはありません。請求書は content（XML テキスト）または content_base64（ZUGFeRD／Factur-X の PDF やその他のファイル）として渡します。どちらも、取得したスキーマでは任意です。

• list_supported_formats — サービスが対応するフォーマット、プロファイル、ルールセットと、各ツールの料金を確認します。引数はありません。
• detect_invoice — 請求書ファイルのフォーマット、構文、プロファイル／カスタマイズ、国別標準を識別します。検証前に行う、低コストな最初のステップです。
• parse_invoice — 請求書を正規化された JSON として抽出します。番号、日付、販売者、購入者、明細行、VAT 内訳、合計、支払い詳細が含まれます。
• fix_invoice — EN 16931 請求書の検証エラーを決定論的に修正します。空の要素、小数、日付やコードのフォーマット、仕様 ID が対象です。totals: true を指定すると、明細行を基に合計と VAT 内訳も再計算します。ファイルにないデータは values に指定でき、なお不足しているデータは needs_input に一覧表示されます。dry_run を指定すると、変更を適用せずに報告します。上流へのリクエスト数は 2 件として数えられます。
• validate_invoice — 識別されたフォーマットの公式ルールセットを実行し、失敗したルールをすべて ID、重大度、メッセージ、XPath とともに返します。kosit: false を指定すると、完全な KoSIT Schematron を省略し、スキーマとコアのみを対象とした高速なチェックを行います。
• render_invoice_html — 人が読みやすい請求書ドキュメントを HTML（A4 印刷レイアウト）で生成します。ラベルの言語は lang（en、de、fr、pl、nl、hr、es）で選択できます。
• render_invoice_pdf — 同じドキュメントを PDF として生成し、base64 リソースとして返します。選択できる lang は同じです。上流へのリクエスト数は 2 件として数えられます。
• my_usage — 接続に使用した API キーのプラン、月間クォータ、今月の使用状況、サブスクリプションの状態を確認します。無料です。引数はありません。

設定

• EINVOICECHECKER_API_KEY（任意）— 設定すると、すべての上流リクエストに Authorization: Bearer <key> が付与されます。設定されていない場合、認証ヘッダーは送信されず、上流の匿名ユーザー向けレート制限が適用されます。このクライアントでキーが必須になることはありません。
• EINVOICECHECKER_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://einvoicechecker.com/v1/mcp です。 （この上書き用フックは、この再構築で独自に追加したものであることを明記しています。）

転送の仕組み

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

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

CLI

各ツールは、JSON 引数文字列を 1 つ取るサブコマンドとしても実行できます（引数を取らないツールでは省略します）。

npx @reneturcios/invoiceproof list_supported_formats
npx @reneturcios/invoiceproof validate_invoice '{"content":"<Invoice>...</Invoice>"}'
npx @reneturcios/invoiceproof render_invoice_html '{"content":"<Invoice>...</Invoice>","lang":"de"}'
npx @reneturcios/invoiceproof --version

終了コード：成功時は 0、isError の結果が返された場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/invoiceproof mcp

MCP クライアントの設定：

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

API キーを指定して MCP サーバーを実行するには、このサーバーのクライアントの env ブロックに EINVOICECHECKER_API_KEY を追加します。

Docker

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

コンテナのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーとして動作し、それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはスタブ化された JSON-RPC アップストリームのみを使用して実行され、実際のネットワーク呼び出しは行いません。

ライセンス

MIT — LICENSE を参照してください。