FACTRAIL

FACTRAIL

AI エージェントのためのエビデンス基盤です。

FACTRAIL は、出所、新しさ、矛盾、裏付けレベル、カバレッジ、未解決の依存関係、再利用可能なレシートを含む、構造化された現実世界のエビデンスをエージェントに提供します。パブリックベータ版であり、機能は定義されていて確認可能です。対応範囲外の項目やソースの取得失敗は明示的に示されます。

FACTRAIL は Python 製の Model Context Protocol サーバーです。このリポジトリには、パッケージバージョン 2.4.1、Evidence Contract、テスト、運用ツール、静的サイトが含まれています。ホスト型デプロイでは異なるリリースが稼働している場合があります。デプロイ済みの機能を利用する前に、ライブの tools/list と factrail_capabilities の結果を確認してください。

MCP 経由で接続する

エンドポイント：https://mcp.factrail.online/mcp（Streamable HTTP）

{
  "mcpServers": {
    "factrail": {
      "url": "https://mcp.factrail.online/mcp"
    }
  }
}

クライアントの設定は異なる場合があります。ウェブサイト：factrail.online · ヘルスチェック：healthz。

FACTRAIL を利用する理由

エージェントが、モデルの出力を盲目的に信頼するか、ソースの検証を一からやり直すかの二択を迫られるべきではありません。FACTRAIL は、エージェントと現実世界のデータソースの間にエビデンスレイヤーを提供します。答えだけを返すのではなく、何が確認できたか、その情報源はどこか、どれほど新しい情報か、何が未解決なのか、そして別のエージェントが後から確認できるレシートを返せます。

原則はシンプルです。捏造するより、分からないとするほうがよい。 呼び出し元からの入力が自動的に検証済みになるわけではありません。導出された値は、依存する情報の品質を引き継ぎます。矛盾、古いデータ、ソースの取得失敗は、見える形で残ります。機能の制限はプログラムから確認できます。

エージェントが FACTRAIL を使うべき場合

• ユーザーやワークフローからフランスの SIREN/SIRET が提供された場合、またはフランス企業が存在するか、事業を継続しているか、正式名称や本店所在地は何かを尋ねられ、回答の追跡可能性が必要な場合に使用してください。
• まず factrail_capabilities を使って、現在のカバレッジを確認してください。以前の結果を再確認するには factrail_get_receipt を使ってください。
• 一般的なウェブ検索、ニュースや主張のファクトチェック、フランス以外の企業登記簿、制裁・実質的所有者の確認、拘束力のある関税裁定には使用しないでください（「現在の制限」を参照）。
• エンベロープに未解決のフィールドが記載されている場合は、不明のまま引き継いでください。モデルの記憶で補完しないでください。

MCP の主要ツール

新しい統合では、汎用プリミティブを使用してください。

ツール	目的
factrail_capabilities	利用可能な機能 ID、操作、バージョン、入力、フィールド、ソース、動的なソース状態、制限を確認します。最初に呼び出してください。
factrail_verify	対応する対象の構造化された事実を検証します。現在は company_fr に対応しています。
factrail_assess	構造化された現実世界の状況を評価します。現在は import に対応しています（ベータ版）。
factrail_get_receipt	レシート ID で以前の EvidenceEnvelope を取得し、内容の整合性を確認します。

互換性ツールも引き続き利用できます。verify_french_company、assess_import、および実験的／互換性専用の analyze_company です。新しいクライアントには汎用ツールを推奨します。analyze_company は、利用できない財務、信用、格付け、リスク、推奨、経営陣の人数、信頼度の値を合成しません。利用できないフィールドは null／利用不可のままになります。

現在利用可能：フランス企業の確認

company_fr 機能は、現時点で FACTRAIL が提供する最も強力な照合機能です。INSEE／Sirene および BODACC の記録を使用して、SIREN または SIRET によるフランスの企業および事業所の情報を確認します。ソースの記録に応じて、識別子、法人名および商号、ステータス、法人形態、NAF／活動コード、本店所在地、設立日／事業終了日、情報公開状況、BODACC のイベントなどのフィールドが含まれる場合があります。すべての事業体について、すべてのフィールドが存在するとは限りません。

現在の企業ステータスと現在の法人名については、INSEE／Sirene の最新の登記データが BODACC の公示情報より優先されます。優先度の低い証拠も、暗黙に破棄せず保持されます。これにより、サプライヤーの確認、ベンダーのオンボーディング、調達、CRM の情報拡充、マーケットプレイスのオンボーディング、企業確認／KYB サポートのワークフローを支援できます。FACTRAIL 単独では、法的に十分な KYC／KYB コンプライアンスシステムではありません。

factrail_verify への入力例（確認の許可を得ている識別子でプレースホルダーを置き換えてください）：

{
  "subject_type": "company_fr",
  "identifier": "<9-digit SIREN or 14-digit SIRET>",
  "fields": ["status", "legal_name", "head_office"]
}

実際のソース応答は、要求された識別子、ソースの利用可能性、および記録の網羅状況によって異なります。FACTRAIL は、ここでサンプル結果を捏造することはありません。

ベータ版：貿易・輸入評価

factrail_assess は現在、assessment_type="import" をサポートしています。原産地、仕向地、製品の説明、分類または判明している HS／関税コード、貨物価額、数量、関税／VAT の参照情報、コンプライアンス入力、運賃／保険料などの構造化された概念を受け付けます。結果では、呼び出し元の入力、ソースの証拠、分類候補、決定論的な計算が分けて示されます。網羅状況は部分的または暫定的な場合があります。

EU 加盟国の VAT と連携する権威ある仕組みや、完全かつ権威ある着地コストの算出チェーンはありません。厳選された VAT および関税の値には、厳選済み／暫定的であることが引き続き明記されます。派生計算には依存元の品質が引き継がれます（入力が暫定的な場合は derived_provisional）。貿易評価は拘束力のある関税裁定ではなく、分類候補も確定的な関税分類ではありません。

EU 公式 TARIC の状況

FACTRAIL には、検証済みの欧州委員会公式 TARIC スナップショットを取り込むためのインフラストラクチャがあります。オフラインパッケージ診断、厳格／互換パース、受け入れレポート、ハッシュ／フィンガープリント、セマンティックチェック、正規化された SQLite インデックス、アトミックな有効化、最終正常版／古いデータの処理に対応しています。現在、欧州委員会の真正な TARIC スナップショットはインストールされていません（not_installed）。FACTRAIL は現在、権威ある TARIC 関税情報をライブで提供していません。

Access2Markets は二次的／補助的な証拠であり、権威ある TARIC 情報ではありません。厳選された FACTRAIL の関税参照値は暫定的です。安定した公式の自動ダウンロードエンドポイントは確認されていないため、現時点では自動取得を利用できません。オペレーターが提供する公式ファイルは、オフラインで診断して取り込むことができます。月次スナップショットの取り込みには対応していますが、日次差分の適用は延期されています。

オペレーター向け手順については、TARIC スナップショットの受け入れと運用および配布方法の調査メモを参照してください。詳細な関税計算は、現在の TARIC スナップショット基盤の対象外です。

Evidence Contract

正規の EvidenceEnvelope には、schema_version、ステータス、対象、事実、証拠ソース、競合、カバレッジ、鮮度、receipt_id、generated_at が含まれます。現在のスキーマは EvidenceEnvelope 1.2 であり、パッケージのバージョンとは独立しています。

• ステータスには supported、contradicted、insufficient_evidence、stale、conflicting_sources があり、結果を単純な真偽値にはしません。
• サポートレベルは証拠の品質を示します。authoritative、supported、derived_supported、derived_provisional、curated、caller_input があります。呼び出し元の入力は外部検証されていません。
• カバレッジでは、要求されたフィールド、解決済みのフィールド、未解決のフィールドを区別します。入力の欠落、未対応のフィールド、利用できないソースは、それぞれ異なる状態です。
• 鮮度には観測時刻と古くなっているかどうかが記録されます。
• 競合では、競合するソースの主張を保持します。フィールドごとの権限ポリシーによって競合を解決しても、優先度の低い証拠が削除されることはありません。
• ソースの結果では、成功、一部応答、ソースエラー／利用不可、ソース未統合、検索無効、不要を区別します。

決定論的な計算も、算術が決定論的であるというだけで権威あるものになるわけではありません。権威ある入力は derived_supported の結果を裏付ける場合があります。暫定的な入力からは derived_provisional の結果が生成されます。

Receipts

レシート ID（fr_…）は、決定論的な正規化ハッシュを使用してコンテンツアドレス化されています。取得時に FACTRAIL はハッシュを再計算し、改変された内容を整合性エラーとして拒否します。従来の正規化方式も引き続き利用できます。レシートを使うと、証拠の観測結果を再利用し、追跡できます。レシートが保証するのはコンテンツの整合性であり、デジタル署名、ブロックチェーン上の記録、不変のグローバル台帳エントリ、またはある主張が普遍的に真であることの証明ではありません。state_fingerprint は、複数の観測にわたって実質的な状態を識別します。Evidence Core の設計を参照してください。

Sources and trust principles

FACTRAIL のソース階層は明確です。公式記録は定義されたフィールドに対して権威ある情報源となる場合がありますが、二次ソースは二次ソースのまま、キュレーションされた参照情報はキュレーションされたまま、呼び出し元の入力は入力のまま扱われます。証拠には、ソースの識別情報、取得時刻、入手可能な場合はコンテンツハッシュ、サポートレベル、ソースのステータスが付随します。過去の公開情報は、自動的に現在の状態を決定するものではありません。

FACTRAIL は次の原則に従います。

1. 証拠を捏造しません。創作するよりも、不明とするほうが適切です。
2. 呼び出し元の入力を自動的に検証済みとはしません。
3. 派生値は、その依存元のサポート品質を引き継ぎます。
4. ソース間の競合を見える状態に保ちます。
5. ソースの障害と古くなった証拠を明示します。
6. 二次的な証拠を黙って権威ある情報に格上げしません。
7. レシートが保護するのはコンテンツの整合性であり、哲学的な真理ではありません。
8. 機能の制限をプログラムから確認できるようにします。

Quick start: discover, verify, retrieve

まず {} を指定して factrail_capabilities を使用します。実際の結果から、現在対応している機能 ID と動的なソース状態を確認できます。次に、企業の検証には次の呼び出しを使用します。

{
  "subject_type": "company_fr",
  "identifier": "<SIREN or SIRET>",
  "fields": ["status", "legal_name"]
}

後で結果を取得するには、実際の receipt_id を渡します。

{"receipt_id":"<receipt_id returned by FACTRAIL>"}

MCP ツール呼び出しでは、これらの引数オブジェクトを通常のクライアントプロトコルでラップします。一般的な検証、レシート、インポートの入力例については、リクエスト例を参照してください。例ではプレースホルダーを使用しており、捏造された出力を示すものではありません。

ローカルで実行する

Python 3.11 以降が必要です。

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Set INSEE_API_KEY in .env for live French company lookups.
python3 -m factrail.mcp_http_server

HTTP のデフォルトポートは 8765 です。FACTRAIL_HOST と FACTRAIL_PORT でバインドアドレスとポートを変更できます。ローカルの MCP エンドポイント：POST http://localhost:8765/mcp、ヘルスエンドポイント：/healthz。stdio クライアントの場合は、python3 -m factrail.mcp_server を実行します。

INSEE API portal から INSEE キーを取得してください。SQLite キャッシュのデフォルトは /tmp/factrail_cache.db です。永続的なレシートを保存するには、FACTRAIL_CACHE_PATH を永続パスに設定します。サーバーには、クライアントごとのレート制限と、企業の検索時に古いキャッシュへフォールバックする機能が含まれています。

公開 HTTP 設定

変数	デフォルト	意味
FACTRAIL_ALLOWED_HOSTS	localhost/loopback	ホストの許可リスト（DNS リバインディング対策。不一致の場合は 421）。
FACTRAIL_ALLOWED_ORIGINS	未設定	カンマ区切りの Origin 許可リスト。未設定の場合、Origin ヘッダーを含むリクエストは拒否されます（403）。Origin を含まない API クライアントは利用できます。* の場合、すべての Origin が許可され、CORS が有効になります。Host チェックは有効なままです。
FACTRAIL_RATE_LIMIT_PER_MIN	60	クライアントごとのウィンドウあたりのリクエスト数（0 で無効）。クライアントの識別には CF-Connecting-IP、次に最初の X-Forwarded-For エントリーを使います。直接のピアがループバックの場合にのみ信頼されます。
FACTRAIL_RATE_WINDOW_SECONDS	60	スライディングウィンドウの長さ。
FACTRAIL_RATE_BLOCK_AFTER	30	一時的なブロックが適用されるまでの、1 ウィンドウ内の拒否されたリクエスト数（0 で無効）。
FACTRAIL_RATE_BLOCK_SECONDS	300	ブロック期間。
FACTRAIL_GATEWAY_USER_AGENTS	SmitheryBot	MCP ゲートウェイを識別する、大文字と小文字を区別しない User-Agent の部分文字列（Smithery の CF-Worker ヘッダーも対象）。
FACTRAIL_GATEWAY_RATE_LIMIT_PER_MIN	600	各ゲートウェイのバケットにおける、ウィンドウあたりのリクエスト数。
FACTRAIL_GATEWAY_RATE_BLOCK_AFTER	0	ゲートウェイのバケットに対するブロックしきい値（0 = ブロックしない）。
FACTRAIL_GATEWAY_CLIENT_HEADER	未設定	ゲートウェイがエンドユーザー ID の転送に使うヘッダー。設定されている場合、ゲートウェイのトラフィックはエンドユーザーごとに分類されます。
FACTRAIL_HIDE_LEGACY_TOOLS	オフ	非推奨のレガシーツールを tools/list から非表示にします（引き続き呼び出せます）。

超過したリクエストには、JSON 本文と Retry-After を含む HTTP 429 が返されます。静的なサーバーカードは /.well-known/mcp/server-card.json で提供されます。

現在の制限事項

FACTRAIL は現在、任意の自然言語によるファクトチェック、一般的なウェブ検索や URL 取得、ニュースの検証、広範なグローバル企業の検証、実質的所有者・制裁・EORI 専用のリゾルバー、権威あるインストール済み EU TARIC データ、権威ある EU VAT 統合、完全かつ権威ある陸揚げコストの結果、任意の規制検証、署名付きレシート、ブロックチェーンレシート、グローバルで不変の証拠台帳、継続的な証拠監視、未知の主張に対する汎用的な LLM 推論を提供していません。

デプロイと開発

運用担当者向けの情報は、デプロイチェックリスト、TARIC 受け入れガイド、配布に関する注意事項をご覧ください。リリース履歴：CHANGELOG。静的サイトは site/ にあり、ビルド手順は必要ありません。

python3 -m pytest -q
python3 -m compileall -q factrail tests
python3 -m factrail.evidence.demand --days 7

オフラインのテストスイートではモックとフィクスチャを使用します。ライブテストはプロジェクトの --live の規約に従い、外部アクセスが必要です。需要テレメトリーには、正規化されたカテゴリと関連付けが保存されますが、生の IP アドレス、完全な User-Agent 文字列、リクエスト引数、認証ヘッダー、完全な Evidence エンベロープは保存されません。これにより、求められている機能と証拠の不足を特定できます。

Apify Actor ラッパーは、正規の MCP サービスを配布し、支払いを処理するための薄いチャネルです。FACTRAIL のソースアダプターや証拠の動作は変更しません。

公開ディスカバリー用情報

• ウェブサイト
• エージェント向けガイダンス
• Apify 掲載文
• Glama 掲載文
• Smithery 掲載文
• GitHub メタデータ

関連：フォールバックエージェントツール

フォールバックエージェントツールは、「ツールは何を確認したかを報告するべき」という同じルールを、データの取得先という別の問いに適用します。そのsource_routeツールは、厳格なリクエスト制限のもと、公開元のサイトで機械可読なルート（API、OpenAPI、一括ダウンロード、フィード）の候補を探します。また、「ここでは見つからなかった」という結果を「確認した範囲では見つからなかった」として扱い、ルートが存在しないことの証明とは見なしません。FACTRAILに依存しない独立したサービスです（x402の従量課金ベータ版で、現在はBase Sepoliaテストネットのみ対応）。

ライセンス

コードとドキュメントはApache License 2.0のもとでライセンスされています。ソースデータには、INSEEやBODACCのオープンデータライセンスを含む、公開元の規約が適用されます。