FatturaPA / SDI

Name: FatturaPA / SDI
Author: MaurizioLisanti

ローカル

github.com/MaurizioLisanti金融データ04 週間前に更新

リポジトリ

FatturaPA / SDI について

FatturaPA / SDIは、イタリアの電子請求書を扱うPython開発者やAIチーム向けのベータ版MCPサーバーです。解析、異常検出、VAT確認、レポート、SDIエラー検索のツールを備えますが、構造検証には既知の制限があり、SDI検証の代用にはなりません。

主な機能

01XMLから請求書データを抽出
02XML構造とイタリアVAT番号の確認
03VIES経由でEU VAT番号を検証
04請求書の異常を検出
05複数請求書のレポート作成
06SDIエラーをオフライン検索

活用シーン

01仕入先、顧客、明細情報の抽出
02請求書処理時のVAT番号確認
03複数請求書の異常と統計を確認
04ネットワークなしでSDIエラーコードを検索

MCP 対応

このMCPサーバーは、FatturaPA請求書の解析、VAT番号の確認、異常検出、レポート作成、SDIエラー検索を行う7つのツールを提供します。ファイルの読み取り先は設定済みの許可ルートに制限され、請求書XMLを直接渡すこともできます。

設定

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

mcp.json · 共通設定

{
  "mcpServers": {
    "mauriziolisanti-fatturapa": {
      "command": "uvx",
      "args": [
        "fatturapa-mcp-server"
      ],
      "env": {
        "FATTURAPA_ALLOWED_ROOTS": "<FATTURAPA_ALLOWED_ROOTS>"
      }
    }
  }
}

起動コマンドuvx fatturapa-mcp-server

設定が必要な環境変数

FATTURAPA_ALLOWED_ROOTSFolders the server may read invoices from (';' separated on Windows, ':' elsewhere). If unset, file reads are refused and XML must be passed as text.

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

パッケージ

pypifatturapa-mcp-server0.3.2stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

パラメーター	型	必須	説明
file_path	any	いいえ
xml_content	string	いいえ

詳細

fatturapa-mcp-server

英語

問題

FatturaPA を統合するすべてのプロジェクトは、同じ検証、解析、SDI エラー処理を一から再実装しています。その結果、同じ作業の繰り返しに何週間も費やし、隠れたバグが発生し、標準化も進みません。

解決策

1 行でインストールできる 7 つの AI ツール — ドキュメントの解析、受信した請求書の異常検知、複数請求書のレポート作成、VIES によるイタリアおよび EU の VAT 確認、XML の構造チェック、オフラインでの SDI エラー検索に対応します。

ステータス：ベータ版です。 検証結果を信頼する前に、既知の制限事項をご確認ください。

対象ユーザー

イタリアの電子請求書システムに取り組んでおり、プロジェクトごとに FatturaPA のコンプライアンスを一から再実装することなく Claude を統合したい Python 開発者と AI チームが対象です。

これは何ですか？

人間のための MCP（Model Context Protocol）サーバーです。イタリアの電子請求書（FatturaPA）および SDI（Sistema di Interscambio）システムを扱うための、すぐに使える 7 つのツールを AI アシスタントに提供します。複雑な設定は不要です。

ツール

ツール	入力	機能
`validate_invoice`	`xml_content`	XML が整形式であり、FatturaPA のルート構造を備えているかを確認します。⚠️ 完全なスキーマ検証にはまだ対応していません — 既知の制限事項をご覧ください
`extract_invoice_data`	`xml_content`	有効な FatturaPA ドキュメントから、供給元、顧客、金額、明細項目、メタデータを抽出します
`lookup_sdi_error`	`error_code`	SDI エラーコードの説明、カテゴリ、解決のヒントを返します（オフライン）。⚠️ テーブルを公式リストに合わせて調整中です — 既知の制限事項をご覧ください
`check_piva`	`piva`	公式の MEF チェックサムアルゴリズムを使用して、イタリアの P.IVA（VAT 番号）を検証します — ネットワーク呼び出しはありません
`verify_piva_vies`	`country_code`, `vat_number`	ライブの VIES REST API に照会し、EU の VAT 番号を検証します。サービス停止時も適切に動作します
`find_invoice_anomalies`	`xml_content`	FatturaPA XML ドキュメントの異常を検出します：合計の不一致、VAT の誤り、未来の日付、無効な P.IVA、受取人の欠落、明細項目の不備、負の金額、支払い情報の欠落
`generate_invoice_report`	`xml_contents`	複数の FatturaPA XML ドキュメントを集約し、統計、供給元／顧客別の内訳、異常の概要を含む単一のレポートを作成します

クイックスタート

オプション A — uvx（インストール不要）

uvx fatturapa-mcp-server

オプション B — pip

pip install fatturapa-mcp-server
fatturapa-mcp-server

Claude Desktop の設定

以下のブロックを Claude Desktop の設定ファイルに追加します：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"],
      "env": { "FATTURAPA_ALLOWED_ROOTS": "/path/to/your/invoices" }
    }
  }
}

FATTURAPA_ALLOWED_ROOTS には、サーバーが読み取りを許可されるフォルダーのみを指定します（macOS/Linux では :、Windows では ; 区切り）。この設定がない場合、すべての file_path による読み取りは拒否され、ドキュメントは xml_content として渡す必要があります。これは意図的な仕様です。サーバーは、信頼できないドキュメントを読み取る AI エージェントによって操作されます。

Claude Desktop を再起動すると、ツールパネルに新しいツールが 7 つ表示されます。

既知の制限事項（v0.3.2）

合成請求書を使用して、公式の AdE スキーマ（FatturaPA v1.2.3）に照らした監査を行ったところ、以下の点が見つかりました。これらは次回以降のリリースで修正予定です。それまでは、次の点にご注意ください。

validate_invoice は構造のみを検証します。 同梱の XSD ファイルはスタブです。未知の書類種別（TD99）、無効な通貨（EURO）、または必須ブロックの欠落がある請求書でも、valid: true と報告されます。SDI 検証の代わりとして使用しないでください。
lookup_sdi_error：複数のコードの説明が公式リストと異なり（例：00001 は「無効なファイル名」）、一部のコードが欠落しています。
バッチ（ロット）：ファイルに複数の請求書が含まれる場合、完全に分析されるのは最初の請求書だけです。
エンコーディング：ISO-8859-1 / windows-1252 と宣言された XML が正しくデコードされない場合があります。
.p7m 署名付きファイルはまだサポートされていません。先に XML を抽出してください。
レポート：クレジットノート（TD04）が減算ではなく加算されます。異なる通貨間の合計も合算されます。
金額は浮動小数点数として返されます。

現在、確実に機能するのは、整合性チェック（合計、VAT、P.IVA チェックサム、日付）、フェイルクローズ方式のファイルアクセス、XXE 保護、サービス停止時の VIES の劣化動作です。

変更履歴／リリース履歴

Wave	ツール／機能	リリース
Wave 1	`validate_invoice`、`extract_invoice_data`、`lookup_sdi_error`、`check_piva`、`verify_piva_vies`	v0.1.0
Wave 2	PyPI 公開、CI/CD、セキュリティ監査、完全なテストカバレッジ	v0.1.0
Wave 3	コンテキスト伝播、構造化ログ、進捗レポート、roots ベースのセキュアなファイルアクセス	v0.1.x
Wave 4	`find_invoice_anomalies`、`generate_invoice_report`	v0.2.0

v0.3.2 の統計： 7 個のツール · 181 件のテスト · カバレッジ 95％（サーバー起動を含む）

このプロジェクトが示すもの

mypy による厳格な型付けを備え、Python 3.11、3.12、3.13 でテスト済みの MCP サーバー
自動セキュリティ監査 — bandit + pip-audit
最低 80％のカバレッジを保証（現在、181 件のテストで 95％）
フェイルクローズ方式のファイルシステムアクセス：明示的に設定されない限り、読み取りは拒否されます
PyPI で公開済み — どこでも 1 行でインストール可能
イタリア語／英語のバイリンガル対応 — イタリア国内および国際市場向けに構築

監査可能な設計

このリポジトリのすべての機能は、統制されたマルチエージェントのパイプラインを通じて構築されました。計画、実行、レビューをそれぞれ別の役割として分け、各役割に権限を明示し、その間に厳格な品質ゲートを設けています。

coord/ ディレクトリに監査証跡があります。タスクごとに 1 件の引き継ぎ記録を作成し、変更したファイルとその理由、実行したコマンドと PASS／FAIL の出力、行った仮定とその検証方法、未解決のリスクを記録しています。15 件の引き継ぎ記録が、上記の 4 つの開発段階を網羅しています。

電子請求書、税務データ、コンプライアンスなどの規制対象業務では、システムが機能することを示すのと同じくらい、どのように構築されたかを示せることが重要です。この方法論については、agentic-dev-pipeline に別途記載されています。

プロジェクトのステータス

ベータ版。 公式スキーマに照らして検証した合成 FatturaPA 文書でテスト済みですが、まだ本番環境では使用されていません。既知の制限事項を参照してください。より広範なエコシステムの一部です：fatturapa-mcp-server → sdi-ops-monitor

開発環境のセットアップ

git clone https://github.com/MaurizioLisanti/fatturapa-mcp-server
cd fatturapa-mcp-server

# Install the package and all dev dependencies
make install        # pip install -e ".[dev]"

# Run the full quality gate (lint + typecheck + tests + security)
make check

個別のターゲット：

make test           # pytest with coverage (fail-under 80 %)
make lint           # ruff check + ruff format --check
make typecheck      # mypy --strict
make security       # bandit -ll + pip-audit
make format         # auto-fix formatting and imports

MCP Inspector

MCP Inspector を使うと、ローカルの Web UI からツールを対話的に呼び出せます。開発時に便利です。

npx @modelcontextprotocol/inspector uvx fatturapa-mcp-server
# Open http://localhost:5173 in your browser

イタリア語

課題

FatturaPA を統合するすべてのプロジェクトで、同じ SDI の検証、解析、エラー処理のロジックを一から再実装しています。その結果、同じ作業を何週間も繰り返し、隠れたバグが発生し、標準化も行われません。

解決策

1 行でインストールできる 7 つの AI ツール — ドキュメントの解析、受信した請求書の異常検出、複数請求書レポート、VIES によるイタリアおよび欧州の VAT 番号の確認、XML の構造チェック、オフラインでの SDI エラー検索に対応します。

ステータス：ベータ版です。 検証結果に依存する前に、既知の制限をお読みください。

対象ユーザー

イタリアの電子請求書システムに携わり、プロジェクトごとに FatturaPA のコンプライアンスを一から再実装することなく Claude を統合したい Python 開発者や AI チームです。

このプロジェクトについて

イタリアの電子請求書（FatturaPA）および Sistema di Interscambio（SDI）を扱うための、すぐに利用できる 7 つのツールを AI アシスタントに提供する MCP（Model Context Protocol）サーバーです。

利用可能なツール

ツール	入力	機能
`validate_invoice`	`xml_content`	XML が整形式であり、FatturaPA のルート構造を持つことを確認します。⚠️ スキーマに対する完全な検証にはまだ対応していません — 既知の制限を参照してください
`extract_invoice_data`	`xml_content`	有効な FatturaPA ドキュメントから、サプライヤー、顧客、金額、明細行、メタデータを抽出します
`lookup_sdi_error`	`error_code`	SDI エラーコードの説明、カテゴリ、解決方法のヒントを返します（オフライン）。⚠️ テーブルは公式リストとの整合性を調整中です — 既知の制限を参照してください
`check_piva`	`piva`	MEF 公式チェックサムアルゴリズムを使用してイタリアの VAT 番号を検証します — ネットワーク接続は不要です
`verify_piva_vies`	`country_code`, `vat_number`	リアルタイムで VIES REST API に照会し、EU の VAT 番号を検証します。サービスに接続できない場合は、機能を縮小して応答します
`find_invoice_anomalies`	`xml_content`	FatturaPA XML ドキュメントの異常を検出します：不整合な合計額、誤った VAT、未来の日付、無効な VAT 番号、宛先の欠落、不完全な明細行、負の金額、支払い情報の欠落
`generate_invoice_report`	`xml_contents`	複数の FatturaPA XML ドキュメントを、統計、サプライヤー／顧客の概要、異常分析を含む 1 つのレポートにまとめます

クイックスタート

オプション A — uvx（インストール不要）

uvx fatturapa-mcp-server

オプション B — pip

pip install fatturapa-mcp-server
fatturapa-mcp-server

Claude Desktop の設定

以下のブロックを Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"],
      "env": { "FATTURAPA_ALLOWED_ROOTS": "C:\\percorso\\delle\\fatture" }
    }
  }
}

FATTURAPA_ALLOWED_ROOTS は、サーバーが読み取り可能なフォルダーのみを指定します（Windows では ;、macOS/Linux では : で区切ります）。この変数を設定しない場合、file_path による読み取りはすべて拒否され、請求書は xml_content として渡す必要があります。信頼できないドキュメントを読み取る AI エージェントがサーバーを操作するため、意図的にこのようにしています。

Claude Desktop を再起動すると、7 つのツールがツールパネルに表示されます。

既知の制限（v0.3.2）

合成請求書を使用して、AdE の公式スキーマ（FatturaPA v1.2.3）に対する監査を実施したところ、以下の点が明らかになりました。これらは今後のリリースで修正予定です。

validate_invoice は構造のみを検証します。 同梱の XSD はスタブです。存在しない書類種別（TD99）、無効な通貨（EURO）、または必須ブロックが欠けた請求書でも、valid: true になります。SDI による検証の代わりにはなりません。
lookup_sdi_error：一部の説明が公式リストと一致せず（例：00001 は「ファイル名が無効」）、一部のコードが欠けています。
ロット：ファイルに複数の請求書が含まれている場合、完全に解析されるのは最初の請求書のみです。
エンコーディング：ISO-8859-1／windows-1252 と宣言された XML が、正しくデコードされない場合があります。
.p7m：署名済みファイルはまだサポートされていません。先に XML を抽出してください。
レポート：クレジットノート（TD04）が差し引かれず、加算されます。異なる通貨の合計も加算されます。
金額は float として返されます。

現在、すでに堅牢な機能：整合性チェック（合計、VAT、P.IVA チェックサム、日付）、フェイルクローズ方式のファイルアクセス、XXE 対策、VIES サービスが応答しない場合の処理。

変更履歴／リリース履歴

Wave	ツール／機能	リリース
Wave 1	`validate_invoice`、`extract_invoice_data`、`lookup_sdi_error`、`check_piva`、`verify_piva_vies`	v0.1.0
Wave 2	PyPI 公開、CI/CD、セキュリティ監査、完全なカバレッジ	v0.1.0
Wave 3	コンテキストの伝播、構造化ログ、進捗報告、roots による安全なファイルアクセス	v0.1.x
Wave 4	`find_invoice_anomalies`、`generate_invoice_report`	v0.2.0

v0.3.2 の統計： 7 ツール · 181 テスト · カバレッジ 95％、サーバー起動分を含む

技術的に示す内容

mypy による厳密な型付けを備えた MCP サーバー。Python 3.11、3.12、3.13 でテスト済み
自動セキュリティ監査 — bandit + pip-audit
最低カバレッジ 80％を保証（現在、181 テストで 95％）
フェイルクローズ方式のファイルシステムアクセス：明示的な設定がない限り、読み取りは拒否されます
PyPI で公開 — 1 行でどこにでもインストール可能
IT／EN のバイリンガル対応 — イタリアおよび国際市場向け

設計段階からのトレーサビリティ

このリポジトリの各機能は、管理されたマルチエージェントパイプラインを通じて構築されています。プランナー、実行者、レビュアーを別々の役割とし、それぞれに明示された権限を設け、各フェーズの間に必須の品質ゲートを配置しています。

coord/ フォルダーは監査証跡です。タスクごとに 1 つのハンドオフを記録し、変更したファイルとその理由、実行したコマンドと PASS／FAIL の結果、行った仮定とその検証方法、未解決のリスクを記載しています。上記の 4 つの開発ウェーブを、15 件のハンドオフで網羅しています。

電子請求書、税務データ、コンプライアンスといった規制対象分野の業務では、システムが動作することを示すのと同じくらい、システムがどのように構築されたかを示せることが重要です。この手法については、agentic-dev-pipeline で別途文書化しています。

プロジェクトのステータス

ベータ版。 公式スキーマと照合して検証した FatturaPA の合成請求書でテスト済みですが、まだ本番環境では使用されていません。既知の制限を参照してください。より広範なエコシステムの一部です：fatturapa-mcp-server → sdi-ops-monitor

開発環境のセットアップ

git clone https://github.com/MaurizioLisanti/fatturapa-mcp-server
cd fatturapa-mcp-server

# Installa il pacchetto e tutte le dipendenze di sviluppo
make install        # pip install -e ".[dev]"

# Esegui il quality gate completo (lint + typecheck + test + security)
make check

個別のターゲット：

make test           # pytest con coverage (fail-under 80 %)
make lint           # ruff check + ruff format --check
make typecheck      # mypy --strict
make security       # bandit -ll + pip-audit
make format         # correzione automatica formattazione e import

MCP Inspector

MCP Inspector を使うと、ローカルの Web UI からツールを対話的に呼び出せます。開発時に便利です：

npx @modelcontextprotocol/inspector uvx fatturapa-mcp-server
# Aprire http://localhost:5173 nel browser

ライセンス / ライセンス

MIT

Markdown 対応

ログインしてコメント

基本情報

作者: MaurizioLisanti
言語: python
バージョン: 0.3.2
トランスポート: stdio
掲載日: 2026年10月1日
最終更新: 4 週間前
公式 Registry: io.github.MaurizioLisanti/fatturapa-mcp-server

問題を報告

MCP は初めてですか？

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

入門ガイドを読む

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

FatturaPA / SDI

FatturaPA / SDI について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

fatturapa-mcp-server

英語

問題

解決策

対象ユーザー

これは何ですか？

ツール

クイックスタート

Claude Desktop の設定

既知の制限事項（v0.3.2）

変更履歴／リリース履歴

このプロジェクトが示すもの

監査可能な設計

プロジェクトのステータス

開発環境のセットアップ

MCP Inspector

関連プロジェクト

イタリア語

課題

解決策

対象ユーザー

このプロジェクトについて

利用可能なツール

クイックスタート

Claude Desktop の設定

既知の制限（v0.3.2）

変更履歴／リリース履歴

技術的に示す内容

設計段階からのトレーサビリティ

プロジェクトのステータス

開発環境のセットアップ

MCP Inspector

関連プロジェクト

ライセンス / ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？