mcpField
F
FacturX API

FacturX API

ローカル
github.com/facturxapiその他01 日前に更新
リポジトリ

FacturX API について

FacturX APIは、電子請求書やFactur-Xを扱うエージェント向けのMCPサーバーです。FacturX APIを通じて、事前シミュレーション、PDF/A-3変換、検証、EN16931ルールの検索を提供し、stdioとHTTPに対応します。

主な機能

  1. 01請求書処理のシミュレーション
  2. 02請求書をFactur-X PDF/A-3に変換
  3. 03請求書ファイルの検証
  4. 04EN16931ルールとフィールドの検索

活用シーン

  1. 01変換前に請求書の準備状況を確認
  2. 02請求書をPDF/A-3に変換
  3. 03請求書の検証エラーを確認
  4. 04ルールやコードに関連するフィールドを検索

MCP 対応

FacturX APIの操作をMCPツールとして公開し、事前シミュレーション、変換、検証、エラーやルールの説明を提供します。stdioとStreamable HTTPのトランスポートに対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "com-facturxapi": {
      "command": "uvx",
      "args": [
        "facturx-mcp"
      ],
      "env": {
        "FACTURX_API_KEY": "<FACTURX_API_KEY>",
        "FACTURX_BASE_URL": "<FACTURX_BASE_URL>"
      }
    }
  }
}
起動コマンドuvx facturx-mcp
設定が必要な環境変数
FACTURX_API_KEYシークレットFacturX API key (free Sandbox key at https://facturxapi.com/api-key)
FACTURX_BASE_URLAPI base URL

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
pypifacturx-mcp0.1.2

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

facturx-mcp

FacturX API の公式 MCP サーバーです。エージェント（Claude、Codex、Cursor など）は、統合コードを書かずに、シミュレーション、Factur-X PDF/A-3 への変換、ファイルの検証、EN16931 ルールの説明を行えます。facturx-api SDK を基盤としており、stdio と HTTP のトランスポートに対応しています。

バージョン 0.1.1、PyPI で公開：pip install facturx-mcp。公式 MCP クライアント（Python SDK）でテスト済みです。Claude Code、Codex、Cursor ではまだテストされていません（「実証済みの内容」を参照）。

インストール

pip install facturx-mcp                        # installe aussi facturx-api
export FACTURX_API_KEY=…   # clé Sandbox gratuite : https://facturxapi.com/api-key
# FACTURX_BASE_URL est facultatif à partir de 0.1.2 (production par défaut) ; obligatoire en 0.1.1
facturx-mcp                                   # stdio (défaut)
facturx-mcp --transport streamable-http --port 8765   # HTTP : http://127.0.0.1:8765/mcp

MCP クライアントでの stdio サーバーの一般的な宣言（mcpServers 形式、市販クライアントでは未テスト）：

{"mcpServers": {"facturx": {"command": "facturx-mcp",
  "env": {"FACTURX_API_KEY": "…"}}}}

ツール

ツール機能コスト
facturx_dry_run(invoice, validation_target?, output?)シミュレーション。ready は generationReadiness を参照します無料
facturx_convert(invoice, out_dir, validation_target?, output?, idempotency_key?)factur-x.pdf / .xml を書き込み、パス、サイズ、sha256、検証対象を返します請求書 1 件
facturx_validate(file_path, validation_target?)検証レポートの要約（最初の 10 件のエラー）処理対象の請求書
facturx_explain_error(code_or_rule)ルール（BR-…）、BT、または JSON パスに関連する公開統合契約のフィールド無料、キー不要

ツールの説明では、エージェントに呼び出すタイミング、返される内容、コストが発生するかどうかを伝えます。API エラーは is_error の結果となり、API が送信した status、code、api_message、request_id、idempotency_key を含む Error executing tool <nom>: {"error": {...}} というテキストが返されます。自動再試行はありません（api#2111）。公開 API エラーコードレジストリはまだ存在しません（api#2089）。そのため、facturx_explain_error は説明を作り出すのではなく、その旨を伝えます。

実証済みの内容（2026/11/06）

  • オフラインテスト 6 件（facturx-api と mcp をインストールした状態で PYTHONPATH=src python -m unittest discover -s tests を実行）。外部への接続は禁止されています。
  • 公式 MCP クライアント（Python SDK mcp 2.3.0、ClientSession）から、staging（release 900685311ea7）に対して facturx-mcp を stdio で起動。テスト用 sandbox キーを使用、16:02Z。完全なトレースは traces/stdio-staging-full-path.json にあります：
facturx_explain_error BR-CO-15 -> totals.net (BT-109), totals.tax (BT-110), … depuis GET /api/v1/integration-contract
facturx_dry_run  -> ready=true, generationReadiness ready (request f51f89da-69df-4eea-bf8f-0da1a3e57163)
facturx_convert  -> target verified en16931, xml 4584 o sha256 f332975e…e03c, pdf 20624 o
facturx_validate -> valid=true, validationStatus=valid, profile EN16931, 0 erreur
  • 同じサーバーを streamable HTTP で実行（16:03Z）：tools/list、facturx_explain_error BT-1、facturx_dry_run は成功しました。無効なキーを使用した場合、facturx_dry_run は invalid_api_key と API メッセージをそのまま含む is_error を返します（traces/http-staging-*.json）。
  • トレースにもサーバーログにもキーが含まれていないことを確認済みです。

未実証の内容：Claude Code、Codex、Cursor からの試用（創設者のセッションから実施予定）；xml_cii、署名付き URL、実際の 409/503；MCP ディレクトリへの登録申請（創設者による作業）。

mcp-name: com.facturxapi/mcp

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。