Kontor MCP

Kontor MCP

AI エージェントのための、主権を確保した電子請求書ツールキットです。 公式 XRechnung／EN 16931 検証、ZUGFeRD の読み込みと出力に対応し、100 % オフライン、API キーは不要です。

Kontor MCP は、AI アシスタント（Claude Desktop、Claude Code、あらゆる MCP クライアント）がドイツ／EU の電子請求書（EN 16931 準拠の XRechnung および ZUGFeRD／Factur-X）を扱えるようにする、ローカルでオフライン動作するツールボックスです。請求書（XML 単体または PDF に埋め込まれた XML）の読み取り、公式の KoSIT／EN 16931 ルールブックに照らした検証、難解なエラーのドイツ語または英語での説明、有効な請求書（XML または ZUGFeRD PDF/A-3）の作成、形式間の変換、さらにどの法的義務が適用されるかを事業者に伝えることができます。核となる約束は主権の確保です。クラウドも API キーもネットワーク呼び出しも実行時の Java もなく、テストで実証されています。

重要な理由：2025 年以降、ドイツのすべての事業者は電子請求書を受領できなければならず、2027／2028 年からは発行も求められます。電子請求書とは PDF ではなく、検証済みの XML です。ルールに違反すると、仕入税額控除を受けられなくなる可能性があります。請求書には個人情報や銀行情報が含まれるため、請求書が保存されている場所、つまりお使いのマシン上で、公共部門の受領者が使用するものと同じルールセットで検証するべきです。

kontor サーバーを使う Claude Desktop：検証 → BR-DE-15（Leitweg-ID が不足）と修正のヒント · ZUGFeRD PDF の解析 · BR-DE-18 の説明。MP4

v1.0 — 8 ツール · 4 リソースファミリー · 3 プロンプト · KoSIT 準拠性 89/89 を CI ゲートとして適用 · veraPDF と Mustang で検証済みの ZUGFeRD PDF/A-3 出力 · stdio および Streamable HTTP（ベアラー認証）· Docker イメージ（amd64/arm64）· リファレンスクライアント kontor-agent · Official MCP Registry に登録済み。npx、Docker、またはソースからインストールできます。

Why

• 近似ではなく、公式ルールを使用。 KoSIT XRechnung Schematron と CEN EN 16931 ルールを変更せずに実行します（XSLT/SEF にコンパイルし、Saxon-JS で実行）。KoSIT シナリオモデルを使い、公共部門の受領者と同じ判定を行います。公式バリデーターと照合した結果は、ファイルごとに実証されています。
• 設計段階から主権を確保。 純粋な TypeScript/WASM で、実行時の Java もネットワーク呼び出しもありません。保存もログ記録も行わず、請求書がある場所で動作します。
• エージェント向けに設計。 すべてのツールは、構造化コンテンツと読みやすい概要の両方を返します。検出結果には DE／EN の説明、該当するビジネス用語、修正のヒントが含まれます。生成では正直な結果を返し（valid は実際の判定であり、決めつけません）。
• ZUGFeRD の入出力に対応。 あらゆる ZUGFeRD／Factur-X PDF から埋め込み XML を読み取れます。veraPDF と Mustang の検証に合格する factur-x.xml を含む PDF/A-3 請求書を作成できます。

5 分で始めるクイックスタート

Node ≥ 20 が必要です。ルール、スキーマ、コードリスト、フォントなど、すべて npm パッケージに含まれています。実行時のダウンロードや Java は不要です。

インストール方法	コマンド
npx（設定不要の stdio）	npx -y @kontor-mcp/server
Docker（Streamable HTTP、トークンが必要）	docker run -d -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN=… ghcr.io/dashankanadeeshandesilva/kontor-mcp
リファレンスクライアント	npx -y -p @kontor-mcp/client kontor-agent audit invoice.xml
ソースから	git clone … && pnpm install && pnpm build → node packages/server/dist/bin.js

Claude Desktop —「Settings」→「Developer」→「Edit Config」の順に選択し、終了（⌘Q）してから再度開きます。

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

（ソースをチェックアウトした場合は、代わりに "command": "node", "args": ["/absolute/path/to/kontor-mcp/packages/server/dist/bin.js"] を使用してください。）

**Claude Code:**

```sh
claude mcp add kontor -- npx -y @kontor-mcp/server

サンプル請求書を監査してみましょう。 Claude に次のように尋ねます。

/absolute/path/to/kontor-mcp/packages/server/samples/broken-missing-buyer-reference.xml を監査してください。有効ですか？

判定結果（invalid）、検出事項 BR-DE-15（買い手の参照情報／Leitweg-ID の不足）とその説明および修正のヒント、再計算された合計額と VAT の内訳、さらに根拠を添えた reject（却下）の推奨が返されます。次に、ZUGFeRD PDF を試してみましょう。

/absolute/path/to/kontor-mcp/packages/server/samples/generated-zugferd-en16931.pdf には何が含まれていますか？

（必要であれば XML ファイルを直接添付できます。PDF はローカルパスで指定してください。Claude Desktop は PDF のバイトデータを MCP サーバーに渡しません。）

チャットクライアントを使わない場合は、MCP Inspector をヘッドレスで利用できます。

npx @modelcontextprotocol/inspector@latest --cli node packages/server/dist/bin.js \
  --method tools/call --tool-name audit_invoice \
  --tool-arg file_path=$PWD/packages/server/samples/broken-missing-buyer-reference.xml --tool-arg lang=en

kontor-agent CLI — リファレンスクライアントです。audit は LLM 不要で、accept/review/reject に対応する 0/1/2 を返します。chat はすべてのツール呼び出しを表示する Anthropic エージェントループです（ANTHROPIC_API_KEY が必要です）。

node packages/client/dist/bin.js audit packages/server/samples/broken-missing-buyer-reference.xml --lang en
node packages/client/dist/bin.js chat -m "Prüfe $PWD/packages/server/samples/valid-zugferd-en16931.pdf"
node packages/client/dist/bin.js --url http://127.0.0.1:3333/mcp --token "$KONTOR_AUTH_TOKEN" tools   # against Docker / HTTP

Docker / Streamable HTTP — リモートエージェントやコンテナ向けに、同じサーバーを HTTP 経由で利用できます（トークンが必要です。ポートはループバックに公開し、TLS はリバースプロキシで設定してください）。

docker build -t kontor-mcp .              # multi-stage, non-root, ~70 MB, amd64 + arm64
docker run -d -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN="$(openssl rand -hex 24)" kontor-mcp
curl -s http://127.0.0.1:3333/healthz     # {"ok":true,"name":"kontor-mcp",...}

または、cp .env.example .env && docker compose up -d を実行します（ルートファイルシステムは読み取り専用で、./invoices が /data にマウントされます）。設定項目とセキュリティ対策については、packages/server/README.md と SECURITY.md を参照してください。

ツール

ツール	機能
parse_invoice	フォーマット（UBL / CII · EN 16931 · XRechnung のバージョンとバリアント · ZUGFeRD プロファイル）を検出し、EN 16931 のセマンティックモデルを返します
validate_invoice	XSD + 公式の EN 16931 / XRechnung Schematron（KoSIT シナリオ）+ Kontor の妥当性チェックを行い、説明付きの検出事項とともに valid / valid_with_warnings / invalid を返します
audit_invoice	買掛金管理向けの一括処理です。ヘッダー情報、VAT の内訳、判定結果、グループ化された検出事項、根拠付きの accept / review / reject を返します。known_invoice_numbers による重複検出はステートレスです
generate_invoice	構造化データから XRechnung 3.0 (UBL) または ZUGFeRD 2.3 / Factur-X PDF/A-3（target: zugferd-pdf、プロファイルは EN16931 / BASIC / EXTENDED）を生成します。小数計算に安全な金額処理、内部検証、自動修正の内容を報告する機能を備えています
convert_invoice	ZUGFeRD PDF → XML、セマンティックモデルを介した UBL ↔ CII 変換（変換後に検証し、損失を正確に報告）、自己完結型 HTML プレビューを提供します
check_obligations	ドイツの電子請求書義務に関する判定ツリー（B2B/B2G/B2C、2025 → 2028 年の移行、免除）を、主要な法的根拠とともに提示します
explain_rule	任意の BR-* / BR-DE-* / KONTOR-* ルール ID について、公式テキスト、説明、影響を受ける業務用語、修正のヒントを返します
list_capabilities	フォーマット、同梱されている標準のバージョン、KB の統計情報、法的情報の lastVerified、インベントリ、ソブリンティに関する声明を返します

リソース：kontor://samples/{name}、kontor://reference/rules、kontor://reference/codelists/{list}、kontor://reference/cheatsheet。プロンプト：audit-incoming-invoice、draft-supplier-rejection、create-invoice-interview。入力と規約を含む完全なリファレンスについては、packages/server/README.md を参照してください。

主権性 — そして、それを証明する方法

主張	証明
実行時にネットワーク接続を行わない	すべてのルールセット、スキーマ、コードリスト、法的事実は、出所情報とチェックサムとともに@kontor-mcp/rulesに同梱されています。これを証明するのがsovereignty.test.tsです。すべてのツール、リソース、プロンプトの実行中、外部への通信経路（ソケット、DNS、TLS、http/https、fetch）をすべて遮断して記録し、試行がゼロであることを確認します。また、静的スキャンでは、受信HTTPホスト以外でのネットワークインポートを許可しません。CIでは、--network noneコンテナ内で完全な監査も実行します。SECURITY.mdを参照してください。
Javaなし、ネイティブコードなし	Schematronはビルド時にコンパイルされ、Saxon-JSで実行されます。XSDにはxmllint-wasm、PDFにはpdf-libを使用します。Javaは、CIでの開発時オラクル（KoSIT validator、veraPDF、Mustang）にのみ使用します。
保存もログ記録も行わない	サーバーはステートレスです。請求書の内容がログに記録されることはありません（KONTOR_LOG_PAYLOADSはデフォルトでオフです）。
判定結果は公式のものと一致する	docs/CONFORMANCE.md：公式XRechnungテストスイートの89ファイルすべてについて、KoSIT validatorと判定結果および検出内容が一致しており、CIの実行ごとに再検証されます。
PDFは実際のPDF/A-3です	生成されるサンプルはすべてCIで再生成され、veraPDF（PDF/A-3b、違反ゼロ）およびMustang CLI（PDF/A + XMP + プロファイルXSD + EN 16931ルール）で検証されます。

アーキテクチャ

flowchart LR
  subgraph client [MCP client]
    A[Claude Desktop / Claude Code / kontor-agent]
  end
  A -- stdio / Streamable HTTP --> S

  subgraph server ["@kontor-mcp/server"]
    S[tools · resources · prompts<br/>Zod schemas, structuredContent + text]
  end

  subgraph core ["@kontor-mcp/core (MCP-free library)"]
    D[detect] --> P[parse → EN 16931 model]
    P --> V[validate: XSD → Schematron → plausibility]
    P --> G[generate / convert / preview]
    G --> Z[ZUGFeRD PDF/A-3 assembly]
    V --> AU[audit → verdict + recommendation]
    O[obligations decision tree]
  end

  subgraph rules ["@kontor-mcp/rules (bundled, checksummed)"]
    R1[XSDs UBL 2.1 / CII D16B]
    R2[EN 16931 + XRechnung Schematron as SEF]
    R3[rule knowledge base DE/EN]
    R4[code lists · legal timeline · fonts + ICC]
  end

  S --> core
  core --> rules

検証パイプライン：レイヤー1 XSD（xmllint-wasm）→ レイヤー2 公式Schematron（Saxon-JS、KoSITシナリオ選択と重大度のオーバーライド）→ レイヤー3 Kontorの妥当性チェック（KONTOR-PLAUS-*：小数の再計算、VAT税率、IBAN/BIC、Leitweg-IDのチェックデジット、日付、重複 — 公式判定結果は決して変更しません）。金額計算にはdecimal.jsのみを使用します。すべてのXML解析では、DTDと外部エンティティを無効にしています。

適合性

項目	参照先	結果（2026-08-25）
検証の判定結果と検出内容	KoSIT validator 1.6.3、XRechnung 3.0.2テストスイート（86ファイル）+ Kontorフィクスチャ（3件）	判定結果および検出内容の一致 89/89
生成されたZUGFeRD PDF	veraPDF 1.30.2（PDF/A-3b）	6/6 PASS、違反ゼロ
生成されたZUGFeRD PDF	Mustang CLI 2.26.0（PDF/A + XMP + Factur-XプロファイルXSD + EN 16931）	6/6 valid（EN 16931、BASIC、EXTENDED × DE/EN）
生成されたXRechnung	独自のパイプライン（上記のオラクルと同一）、ランダム入力50件	50/50が有効かつ妥当

詳細、コマンド、記録済みレポート：docs/CONFORMANCE.md。

パッケージ

パッケージ	目的
@kontor-mcp/core	MCPに依存しないライブラリ：検出、解析、検証、監査、生成、変換、ZUGFeRD PDF
@kontor-mcp/rules	同梱された標準関連アーティファクト（XSD、コンパイル済みSchematron、コードリスト、法令の時系列、PDFアセット）+ ルールナレッジベース
@kontor-mcp/server	ツール、リソース、プロンプトを公開するMCPサーバー（stdioおよびBearer認証付きStreamable HTTP、Dockerイメージ）
@kontor-mcp/client	kontor-agent — MCPクライアントのリファレンス実装CLI：toolsによるイントロスペクション、スクリプト実行可能なaudit <file>（LLMなし、終了コードあり）、ツール呼び出しのトレースを含むAnthropicエージェントループのchat。stdioまたはHTTPに対応

FAQ

これは法律または税務に関する助言ですか？ いいえ。Kontor は、公開されている標準とその根拠資料に基づく法的タイムラインに照らして、形式面および技術面のチェック結果を報告します。判断はご自身で行ってください。すべての回答にこの免責事項が記載されています。

XRechnung 3.0.2／2025年のルールに対応していますか？ はい。XRechnung 3.0.2、Schematron 2.5.0、validator configuration 2026-01-31、EN 16931 1.3.16 に対応しています。バージョンは固定されており、list_capabilities に一覧表示されます。

読み書きできる ZUGFeRD プロファイルはどれですか？ 読み取り：MINIMUM、BASIC WL、BASIC、EN 16931、EXTENDED、XRECHNUNG（XMP からプロファイルを取得）。書き込み：EN 16931（デフォルト）、BASIC、EXTENDED — BASIC で省略される内容については D-042 を参照してください。

Claude Desktop から PDF を送れますか？ ローカルパスを指定してください。デスクトップアプリは添付された PDF のバイトデータを MCP サーバーに渡しません。XML の添付ファイルはどちらの方法でも使用できます。

KoSIT のバリデーターは Java なのに、なぜ Java を使わないのですか？ 主権性とインストールのしやすさのためです。Schematron はビルド時に一度コンパイルされ、TypeScript（Saxon-JS）で実行されます。Java ツールは、同等性を証明するための CI でのみオラクルとして使用します。

Windows に対応していますか？ はい。CI では Node 20 と 22 を使用し、Ubuntu、macOS、Windows で全テストスイートを実行します。

開発

pnpm install
pnpm build
pnpm -r test
pnpm lint
pnpm artifacts        # fetch pinned third-party artefacts for the oracles (dev only)
pnpm oracle --diff …  # KoSIT parity (Java 17+)
pnpm check:zugferd    # regenerate samples, veraPDF + Mustang (Java + veraPDF)

PR を作成する前に CONTRIBUTING.md をお読みください。セキュリティ上の問題は SECURITY.md に従って報告してください。

ドキュメント

• 製品要件 · 実装計画 · 決定ログ
• 適合性 · ビジネス用語のカバレッジ · 成果物の来歴
• v0.1 Claude Desktop の検証

ライセンス

Apache-2.0 — 同梱のサードパーティコンポーネントについては LICENSE と NOTICE を参照してください（KoSIT artefacts Apache-2.0、EN 16931 artefacts EUPL-1.2、Liberation Fonts OFL 1.1、ICC sRGB profile）。