dVeracity Semantic API

dVeracity Semantic MCP 服务

为任何支持 MCP 的 AI Agent（Claude Code、Cursor、自定义 Agent）提供按量计费的访问权限， 以调用 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 模式——已验证的 Agent 身份（可选）

如果 Agent 持有 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

随后，服务会通过可验证的声明来验证 Agent 身份 （质询 → 交换 → 1 小时会话，并自动续期），并在每次调用中附加 X-Keri-Session：API 密钥继续负责 计费，KERI 会话则添加 已验证的身份——每次按量计费的调用都会在 dVeracity 的审计跟踪中归属到 Agent AID 和法律实体 LEI。免费工具 keri_identity 会显示当前身份。权限范围拒绝（凭证未包含例如 semantic:query 的权限范围）会显示可操作的错误，并指出凭证所含的权限范围。基于 Signify 的随机数签名计划作为后续增强功能推出。

工具

工具	费用	功能
semantic_query	积分	通过自然语言查询已验证排放知识图谱
semantic_templates	免费	支持的查询模板目录
credits_balance	免费	剩余积分余额
list_standards	免费	VaaS 可用于验证的标准
validate_data	积分	根据受支持的标准验证负载
keri_identity	免费	配置 KERI 模式时，此 Agent 已验证的 vLEI 身份

Open Footprint 规范模型

用于基于 Open Footprint 标准构建应用的设计时工具。 读取模型免费；只有最后的检查会计费。

工具	费用	功能
ofp_models	免费	模型域（截至 openfootprint b60a24e 共九个），以及已发布 DDL 的数据库方言
ofp_search_entities	免费	按名称、描述或字段搜索规范实体（截至 b60a24e 共 262 个条目）
ofp_entity	免费	查看单个实体的完整信息：字段、类型、键、关系和物理表
ofp_sectors	免费	行业领域及各自的状态
ofp_sector	免费	单个行业领域及其参考资料
ofp_policies	免费	某行业领域的 Rego 护栏，或明确说明“未发布任何内容”
compliance_policies	付费方案	已批准的法规合规策略（从法规中提取并经管理员批准的规则）；不包含草稿
compliance_policy	付费方案	单个已批准策略：Rego、提取的规则、输入和来源信息
ofp_validate	积分	根据模型检查载荷，并可选地检查行业领域护栏
ofp_semantics	免费	O-DEF 语义代码，用于将其他系统的字段映射到模型
ofp_semantic_code	免费	哪些规范字段使用某个代码——连接器所需的反向查询
ofp_model_provenance	免费	此部署提供的是哪个标准快照

了解以下两种有意设计的行为，有助于你在基于这些工具构建应用前做好准备。

实体名称有歧义时会报错，而不会自动判定。 数十个实体名称（ofp_models 摘要会通过 ambiguousNameCount 报告数量） 在多个域中都有定义——Country 就出现在四个域中。未提供 domain 时，ofp_entity 会返回列出候选项的错误，而不是自行选择。知道域时， 请务必传入 domain。

语义代码的实用性各不相同。 大多数规范字段都带有 O-DEF 代码， 但多个字段共用的代码只是通用分类，映射到此类代码几乎无法说明任何问题。ofp_models 摘要会在 precision 下报告实际情况——preciseFieldThreshold（代码具有精确性而非通用性时所对应的 fieldCount 阈值）、fieldsOnPreciseCodes 和 preciseShareOfAnnotated。这些值取决于供应商提供的快照，而非本文档。每个代码都会附带其 fieldCount：映射前请先检查该值，并在 ofp_semantics 中传入该阈值作为 maxFieldCount，以仅查看精确代码。

“未发布任何内容”是一个答案，不是错误。 大多数行业领域只在分类体系中列出，并无参考实现；只有七个领域发布了策略护栏。对这类领域调用 ofp_policies 会返回 published: false 及原因，而 ofp_validate 会报告 policy.ran: false。这两种情况都表示未发布规则，绝不表示没有约束——仅检查结构的载荷并不代表它合规，不应如此描述。

第四种结果 unevaluable 表示该行业领域的规则已运行，但所有返回 false 的规则所读取的输入都不在载荷中（policy.missingInputs，例如 co2e_kg、direction、counterparty_industry）。这些是电子账本记录字段，而非 Open Footprint 规范字段名——ofp_policies 会在每个策略的 inputs 下列出这些字段。unevaluable 既不代表通过，也不代表违规，且 valid 为 null。

ofp_validate 检查什么，不检查什么

响应是一个约定，而非判定结果。每次调用都会通过两个列表报告检查目录：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 结果这三项时运行：会复现 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 只会检查记录本身的一致性，不会检查其他内容。它会从模型中解析三个输入——承载排放量角色的字段、… Factor Value（绝不会是 … Factor ID，后者是对因子的引用，而不是用于相乘的数值），以及 … CO2e … 结果；对于护栏所读取词汇表中的记录，则会从 quantity_value / emission_factor_value / co2e_kg 中解析。如果记录对同一输入项填写了多个值，就会报告 ambiguous_calculation_inputs，并放弃检查，而不是自行选择。验证引擎中的 CalculationAccuracy 和 ISO 14064 量化政策使用的 calc_tolerance 都采用 1% 的容差，因此这一关系在所有场景下的容差一致。它能捕获的是记录自身数值相乘后不符的情况。它不会说明该因子是否适用于此来源和时期（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 和读取的 三个 inputs），…… unknown_field 是针对单个字段的警告，且每个字段只会产生一条。
• unknown_field 警告带有 didYouMean：最多三个规范候选项，每个候选项都带有置信度 和该字段所携带的 O-DEF 代码。如果模型中没有合理匹配项，列表就为空——属于其他系统 的键仍然属于其他系统。schema.normalisations 会单独披露通过大小写和分隔符折叠 解析的键。
• advisories 包含对载荷而言属实、但与其有效性无关的发现。目前只有 deprecated_field：模型已弃用的字段，其严重性为 warning，并原样携带 modelDescription；如果模型指定了替代项，则还会带有 successor。如果模型没有 指定替代项，则会省略该键，而不是猜测。建议项不会改变 schemaValid，相同条目也会 出现在 schema.warnings 中。
• valid 已弃用（参见响应中的 deprecations）。在 0.5.x 系列中，它会保留 0.5.0 版本的含义，并且最早会在 0.6.0 中移除。请改为读取 schemaValid。

计费行为（面向 Agent）

计量计费的调用会在账户余额不足时返回 HTTP 402。服务端会将其作为工具错误返回， 提示 Agent 请其人工操作员购买额度或升级——Agent 应转达该消息并停止，不要重试。

测试

npm test（不联网；HTTP 层已存根处理）。

收录平台

• Smithery — 供 Smithery 工具箱用户一键添加
• Official MCP Registry — com.dveracity/semantic-mcp
• npm — @dveracity/semantic-mcp