InvoiceXML

InvoiceXML MCP Server

InvoiceXML API を AI エージェントに公開する Model Context Protocol サーバーです。Factur-X、ZUGFeRD、XRechnung、UBL / CII、Peppol BIS Billing 3.0 に対応しています。

同じコードベースを、起動時に 1 つの環境変数で選択する 2 種類のデプロイ形態で実行できます。

モード	実行者	認証
セルフホスト	独自のマシンまたはサーバー上で実行	環境変数または appsettings.json に設定する単一の API キー
ホスト型	InvoiceXML 独自のインフラストラクチャ上で実行	invoicexml.com に対する OAuth 2.1 + Dynamic Client Registration

どちらも同じバイナリを実行し、異なるのは構成だけです。このリポジトリはプラットフォームに依存せず、ホスティングの場所や方法については関知しません。

アーキテクチャ

+----------------------+   ProjectReference   +----------------------+
|  InvoiceXml.Mcp.Core | -------------------> |  InvoiceXml.Mcp.Host |
|  (SDK: client+tools) |                      |  (the deployable)    |
+----------------------+                      +----------------------+

InvoiceXml.Mcp.Core は、トランスポートに依存しない小規模な SDK です。

• IInvoiceXmlClient — 公開 REST API を利用する型付きクライアント
• HttpInvoiceXmlClient — 唯一の実装。IHttpClientFactory から HttpClient を受け取ります
• InvoiceXmlClientOptions — ベース URL、タイムアウト（認証なし）
• AddInvoiceXmlMcpCore(IServiceCollection, IConfiguration) — DI エントリーポイント。IHttpClientBuilder を返すため、ホストは DelegatingHandler として認証を追加できます

SDK が認証情報を扱うことはありません。ホストが HTTP パイプラインを通じて認証情報を適用します。この分離により、同じコードベースで両方のデプロイモードに対応できます。

InvoiceXml.Mcp.Host は ASP.NET Core 10 アプリです。

• 起動時に Mcp:AuthMode（ApiKey または OAuth）を読み込みます
• AddHostAuth(...) を通じて、対応する DelegatingHandler を Core の HTTP クライアントに接続します
• POST / に MCP エンドポイント、GET / にユーザー向けのウェルカムページ、/health にヘルスチェックを提供します

認証モードの追加は、AuthExtensions.cs に分岐を 1 つ追加し、Auth/<Mode>/ に小さなフォルダーを作成するだけです。ツールの追加は、[McpServerTool] クラスを 1 つ作成するだけです。それ以外に変更はありません。

リポジトリの構成

invoicexml-mcp/
├── src/
│   ├── InvoiceXml.Mcp.Core/              # the SDK: client, models, tools
│   │   ├── Enums/  Interfaces/  Models/  Options/  Services/  Tools/  Extensions/
│   └── InvoiceXml.Mcp.Host/              # the deployable host
│       ├── Auth/{ApiKey,OAuth}/          # the two auth modes
│       ├── Configuration/
│       ├── Program.cs
│       └── appsettings.json              # safe defaults, no secrets
├── tests/
│   ├── InvoiceXml.Mcp.Core.Tests/
│   └── InvoiceXml.Mcp.Host.Tests/
├── Directory.Build.props                 # repo-wide MSBuild defaults
├── Directory.Packages.props              # Central Package Management
├── global.json                           # pins the .NET SDK
└── InvoiceXml.Mcp.slnx

ローカルでの実行

.NET 10 SDK と InvoiceXML API キーが必要です。

# 1. Provide your API key (pick one):

# A. dotnet user-secrets (recommended — kept outside the repo)
dotnet user-secrets --project src/InvoiceXml.Mcp.Host set "Mcp:ApiKey:Value" "your-key"

# B. environment variable
$env:INVOICEXML_API_KEY = "your-key"

# 2. Run
dotnet run --project src/InvoiceXml.Mcp.Host

ブラウザーで GET http://localhost:5004/ にアクセスするとウェルカムページが表示されます。MCP エンドポイントは POST http://localhost:5004/、GET /health は { "status": "ok" } を返します。

構成

{
  // Required in OAuth mode. The public origin where this MCP server is reachable.
  // Used in the protected-resource metadata response.
  "McpUri": "https://mcp.example.com",

  "InvoiceXml": {
    "BaseUrl": "https://api.invoicexml.com",   // override for staging / local
    "Timeout": "00:01:40"
  },

  "Mcp": {
    "AuthMode": "ApiKey",                       // "ApiKey" | "OAuth"
    "ApiKey": {
      "Value": ""                               // ApiKey mode: NEVER commit a real key
    },
    "OAuth": {
      "AuthorizationServer": "https://invoicexml.com",
      "ScopesSupported": [ "api_token.read" ]
    },
    "FileInput": {                              // limits for the URL-fetch input mode
      "MaxFileSizeBytes": 5242880,
      "FetchTimeout": "00:00:30"
    }
  }
}

環境変数での指定方法（ネストには二重アンダースコアを使用）：

変数	対応する設定
INVOICEXML_API_KEY	Mcp:ApiKey:Value（簡易エイリアス）
Mcp__ApiKey__Value	Mcp:ApiKey:Value
Mcp__AuthMode	Mcp:AuthMode（ApiKey または OAuth）
Mcp__OAuth__AuthorizationServer	Mcp:OAuth:AuthorizationServer
McpUri	McpUri（ルートレベル）
InvoiceXml__BaseUrl	InvoiceXml:BaseUrl

OAuth モード

Mcp:AuthMode=OAuth の場合、ホストは静的 API キーの受け付けを停止し、代わりに以下を行います。

1. Bearer トークンのない POST / に対して、WWW-Authenticate: Bearer resource_metadata="…" を含む 401 を返します。
2. MCP クライアントに認可サーバーとして invoicexml.com を示す GET /.well-known/oauth-protected-resource を提供します。
3. 受信した Bearer トークンを、すべての送信 InvoiceXML API 呼び出しにそのまま転送します（トークンの有効性の正本は API です。MCP サーバーはトークンをローカルで検証しません）。

MCP クライアントが行う一連の処理：

client → MCP  POST /                           → 401 + resource_metadata
client → /.well-known/oauth-protected-resource → { authorization_servers: [invoicexml.com] }
client → invoicexml.com/.well-known/oauth-authorization-server
                                               → { authorize, token, register endpoints }
client → invoicexml.com/oauth/register         → client_id + client_secret  (DCR)
client → invoicexml.com/oauth/authorize        → user consents, gets code
client → invoicexml.com/oauth/token            → access_token  (= user's API key)
client → MCP  POST /  + Authorization: Bearer  → 200, tool call flows through

デプロイ

ホストは標準的な ASP.NET Core アプリです。.NET サービスを実行する方法（systemd、コンテナー、PaaS など）で実行できます（このリポジトリでは特定の方法を指定していません）。

dotnet publish src/InvoiceXml.Mcp.Host -c Release -o ./publish
# then run ./publish/InvoiceXml.Mcp.Host on your host

ホスト上で環境変数を使って構成します（シークレットは決してコミットしないでください）。

• ASPNETCORE_ENVIRONMENT=Production
• Mcp__AuthMode=ApiKey（または OAuth）
• Mcp__ApiKey__Value=… / INVOICEXML_API_KEY=…（ApiKey モード）
• McpUri=https://your-public-url および Mcp__OAuth__AuthorizationServer=https://invoicexml.com（OAuth モード）

リバースプロキシまたはロードバランサーで TLS を終端し、ホストの HTTP ポートに転送します。サーバーはステートレスなので、ロードバランサーの背後で複数のインスタンスを実行できます。

ライセンス

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