dVeracity Semantic API

dVeracity Semantic MCP サーバー

MCP 対応の AI エージェント（Claude Code、Cursor、カスタムエージェント）ならどれでも、dVeracity Semantic API（検証済み排出量ナレッジグラフ（Open Footprint / PPDM / OGMP-methane）に対する自然言語クエリ）とVaaS 標準検証を、従量制で利用できます。

前提条件

1. api-tier サブスクリプション：https://dveracity.com/pricing
2. API キー（dvrc_…）：POST /api/v1/api-keys（またはダッシュボード）
3. 従量制の呼び出しに必要な API クレジット：POST /api/v1/vaas/credits/purchase

機械可読なサービス契約は GET /api/v1/semantic/manifest（公開、認証不要）にあります。

インストール

このディレクトリから：npm install

Claude Code

claude mcp add dveracity \
  -e DVERACITY_API_KEY=dvrc_yourkey \
  -- node /path/to/dVE/mcp/semantic-mcp/index.js

汎用 MCP JSON 設定（Cursor など）

{
  "mcpServers": {
    "dveracity": {
      "command": "node",
      "args": ["/path/to/dVE/mcp/semantic-mcp/index.js"],
      "env": { "DVERACITY_API_KEY": "dvrc_yourkey" }
    }
  }
}

オプション：DVERACITY_API_URL で API のベース URL を上書きできます（デフォルトは本番環境です）。

KERI モード — 検証済みエージェント ID（任意）

エージェントがdVeracity Agent Authorization クレデンシャル（その法的事業体が発行する ACDC で、法的事業体の vLEI に連鎖しています。elm/docs/VLEI_AGENT_TOKENS_DESIGN.md を参照）を保持している場合は、次のように設定します。

DVERACITY_KERI_AID=<the agent's AID (credential issuee)>
DVERACITY_KERI_PRESENTATION=/path/to/agent-credential.cesr   # self-contained CESR

その後、サーバーは検証可能なプレゼンテーション（チャレンジ → 交換 → 1 時間のセッション。透過的に更新）によってエージェントを認証し、すべての呼び出しに X-Keri-Session を付加します。API キーは引き続き課金を担い、KERI セッションは検証済み IDを付与します。これにより、すべての従量制呼び出しが dVeracity の監査証跡でエージェントの AID と法的事業体の LEI に関連付けられます。keri_identity ツール（無料）で有効な ID を確認できます。スコープが拒否された場合（たとえば、クレデンシャルに semantic:query が含まれていない場合）、付与されているスコープを示す、対処可能なエラーが表示されます。Signify ベースのノンス署名は、今後の拡張として計画されています。

ツール

ツール	費用	機能
semantic_query	クレジット	検証済み排出量ナレッジグラフに対する自然言語の質問
semantic_templates	無料	対応しているクエリテンプレートのカタログ
credits_balance	無料	クレジット残高
list_standards	無料	VaaS が検証できる標準
validate_data	クレジット	対応している標準に照らしてペイロードを検証
keri_identity	無料	KERI モードが設定されている場合の、このエージェントの検証済み vLEI ID

Open Footprint canonical model

Open Footprint 標準に基づくアプリケーションの構築に使用する設計時ツールです。 モデルの参照は無料で、料金が発生するのは最後のチェックのみです。

ツール	費用	機能
ofp_models	無料	モデルのドメイン（openfootprint b60a24e 時点で9つ）と、DDL が公開されているデータベースの方言
ofp_search_entities	無料	名前、説明、またはフィールドで正規エンティティ（b60a24e 時点で262件）を検索します
ofp_entity	無料	エンティティ1件の全情報（フィールド、型、キー、リレーションシップ、物理テーブル）
ofp_sectors	無料	各ステータスを含む業界セクター
ofp_sector	無料	参照アーティファクトを含むセクター1件
ofp_policies	無料	セクターの Rego ガードレール、または明示的な「公開なし」
compliance_policies	有料プラン	承認済みの規制コンプライアンスポリシー（規制から抽出したルールで、管理者が承認済み）。ドラフトは含まれません
compliance_policy	有料プラン	承認済みポリシー1件（Rego、抽出されたルール、入力、由来）
ofp_validate	クレジット	ペイロードをモデル、および必要に応じてセクターのガードレールに照らしてチェックします
ofp_semantics	無料	O-DEF セマンティックコード。他のシステムのフィールドをモデルに対応付けるために使用します
ofp_semantic_code	無料	1つのコードを持つ正規フィールド。コネクタに必要な逆引き情報です
ofp_model_provenance	無料	このデプロイメントが提供する標準のスナップショット

構築前に知っておくべき、意図的に設計された動作が2つあります。

曖昧なエンティティ名は解決されず、エラーになります。 数十件のエンティティ名（ofp_models の概要では ambiguousNameCount として件数が報告されます）は、複数のドメインで定義されています。たとえば Country は4つのドメインにあります。domain を指定せずに ofp_entity を呼び出すと、いずれかを選ぶのではなく、候補を列挙したエラーが返されます。ドメインがわかっている場合は、domain を指定してください。

セマンティックコードの有用性にはばらつきがあります。 ほとんどの正規フィールドには O-DEF コードが付いていますが、多数のフィールドで共有されるコードは汎用的な分類であり、それに対応付けてもほとんど何も断定できません。ofp_models の概要では、実際の構成が precision の下に報告されます。これには、コードが汎用的ではなく精密とみなされる fieldCount の上限である preciseFieldThreshold、fieldsOnPreciseCodes、および preciseShareOfAnnotated が含まれます。これらはこのドキュメントではなく、ベンダー提供のスナップショットに従います。各コードには fieldCount が返されるため、対応付ける前に確認してください。また、精密なコードだけを表示するには、そのしきい値を maxFieldCount として ofp_semantics に渡してください。

「公開なし」も回答の一つであり、エラーではありません。 ほとんどのセクターは分類体系に名前が登録されていますが、参照実装はなく、ポリシーガードレールを公開しているのは7つだけです。そのようなセクターに対して ofp_policies を呼び出すと、理由とともに published: false が返され、ofp_validate は policy.ran: false を報告します。どちらも意味するのはルールが公開されていないということであり、制約がないということではありません。構造だけをチェックしたペイロードはコンプライアンスに適合しているとは限らず、そのように説明してはいけません。

4つ目の結果である unevaluable は、セクターのルールは実行されたものの、false となったすべてのルールが、ペイロードに含まれていない入力（policy.missingInputs。例：co2e_kg、direction、counterparty_industry）を参照していることを意味します。これらは e-ledger のレコードフィールドであり、正規の Open Footprint フィールド名ではありません。ofp_policies では、ポリシーごとに inputs の下に一覧表示されます。unevaluable は合格でも違反でもなく、valid は null です。

ofp_validate がチェックすること、しないこと

レスポンスは判定ではなく、チェック内容を示すものです。呼び出しのたびに、チェック一覧が2つのリストで報告されます。実行されたチェックを示す checked と、実行されなかったチェックを示す checks_not_run です。後者には reason と、通常は detail が含まれます。ペイロードについて説明する前に、両方を確認してください。

チェック	状態	実行されない場合に報告される理由
schema — 存在、主キー、型、宣言された制約	実行されます	entity_has_no_fields
value_range	モデルで範囲が宣言されている場合に実行されます。宣言された最小値または最大値を外れる数量は拒否されます。範囲を宣言するフィールドは、取り込まれるスナップショットによって異なるため、一部のエンティティでは実行され、ほかでは実行されません。呼び出しごとに checked と schema.coverage.constraintsDeclared を確認してください	no_range_declared、no_numeric_fields
unit_coherence	実行されません	not_implemented
calculation_reproducibility	レコードに数量、排出係数値、明示された CO2e 結果の3つがすべて含まれている場合に実行されます。quantity × factor = result が1％以内で再現され、自己矛盾するレコードは拒否されます	no_calculation_inputs、calculation_inputs_incomplete、ambiguous_calculation_inputs、calculation_inputs_unparseable
temporal_consistency	実行されます。有効期間の終了が開始より前の場合、拒否されます	no_validity_pair、validity_pair_incomplete、validity_values_unparseable
enum_membership	語彙でメンバーが公開されている場合に実行されます。形式が正しいキーが、存在しない参照先を指している場合、拒否されます	no_members_published、no_reference_field_supplied、reference_ids_unparseable
referential_integrity	実行されません。キーはパターンとメンバーのチェックのみを受け、ライブレコードとの照合は行われません	no_data_plane
factor_provenance	実行されません	not_implemented
materiality	実行されません	not_implemented
sector_policy	公開済みのガードレールがあるセクターでレコードタイプが対象となる場合に実行されます	no_sector_supplied、no_policy_published、policy_source_missing、policy_package_unparseable、not_applicable、unevaluable

どのチェックでも、基盤となる構造チェックをまったく実行できなかったことを示す schema_not_run が報告される場合があります。

calculation_reproducibility が確認するのは、レコード内で計算が自己完結しているかどうかだけです。入力となる3つの値はモデルから解決されます。具体的には、排出量測定の役割を持つフィールド、… Factor Value（数値ではなく係数への参照である … Factor ID は対象外）、および … CO2e … の結果です。ガードレールが参照する語彙内のレコードでは、quantity_value ／ emission_factor_value ／ co2e_kg から解決されます。レコードが同じスロットを複数回埋めている場合は ambiguous_calculation_inputs となり、チェックは値を選ばずに実行を見送ります。1％の許容差は、検証エンジンの CalculationAccuracy と ISO 14064 の定量化ポリシーで使用される calc_tolerance に基づいているため、どの環境でも許容差は同じです。このチェックで検出できるのは、レコード内の数値同士が計算結果と一致しない場合です。係数がこの排出源と期間に適切であるか（factor_provenance は引き続き未実行）、あるいは数量が申告された計量器に由来するか（データプレーンは引き続き未実行）を示すものではありません。計算が再現できたレコードは自己整合性があるだけで、検証済みではありません。

• schemaValid は構造チェックの判定結果です（構造チェックを実行できなかった場合は null）。
• assuranceLevel は達成した検証の深さを示します：schema-only、schema-and-value、 schema-value-and-policy、または full。各レベルには、その下位のすべてのチェックが必要です。 そのため、値チェックなしのガードレールは schema-only のままです。この段階は value_range（モデル自体が宣言する境界）によって判定されるため、境界がない状態で レコードが独自の算術を再現しても、schema-only と表示されます。その結果は checked に現れ、こちらのほうがより正確です。
• すべての違反と警告には severity（error | warning）が付与されます。ルール ID は 固定です：required_field_missing、pattern_mismatch、format_mismatch、 type_mismatch、primary_key_missing、enum_violation、value_range（bound： minimum | maximum を含む）、temporal_consistency、enum_membership、 calculation_reproducibility（expected、received、tolerance と、読み取った 3 つの inputs を含む）、… unknown_field はフィールドごとの警告であり、1 件のままです。
• unknown_field 警告には didYouMean が含まれます。候補は正規のものから最大 3 件で、 それぞれに信頼度と、そのフィールドが持つ O-DEF コードが付与されます。モデル内に 該当しそうなものがない場合、リストは空です。別のシステムに属するキーは、そのまま 別のシステムに属するキーとして扱われます。schema.normalisations には、大文字小文字 と区切り文字の統一によって解決されたキーが別途示されます。
• advisories には、ペイロードに関する事実ではあるものの、その妥当性には影響しない 検出結果が含まれます。現在は deprecated_field が該当します。これはモデルで廃止 されたフィールドで、severity は warning です。modelDescription がそのまま 含まれ、モデルが後継を指定している場合は successor も含まれます。モデルが代替を 指定していない場合、推測で補うのではなく、そのキーは含まれません。アドバイザリが schemaValid を変えることはなく、同じ項目は schema.warnings にも表示されます。
• valid は 非推奨 です（レスポンスの deprecations を参照）。0.5.x 系では 0.5.0 と同じ意味を維持し、削除は 0.6.0 以降になります。代わりに schemaValid を 参照してください。

課金の動作（エージェント向け）

従量課金の呼び出しでは、アカウントのクレジットが不足すると HTTP 402 が返されます。 サーバーはこれをツールエラーとして提示し、エージェントにクレジットの購入または アップグレードを人間の運用担当者に依頼するよう伝えます。エージェントはその メッセージを伝えて停止し、再試行してはいけません。

テスト

npm test（ネットワークは使用しません。HTTP レイヤーはスタブ化されています）。

掲載先

• Smithery — Smithery ツールボックスユーザー向けのワンクリック追加
• Official MCP Registry — com.dveracity/semantic-mcp
• npm — @dveracity/semantic-mcp