{
  "markdown": "# dVeracity Semantic MCP server\n\n[![smithery badge](https://smithery.ai/badge/ajvdvoort/dveracity)](https://smithery.ai/servers/ajvdvoort/dveracity)\n\nGives any MCP-capable AI agent (Claude Code, Cursor, custom agents) metered access\nto the **dVeracity Semantic API** — natural-language queries over the\nverified-emissions knowledge graph (Open Footprint / PPDM / OGMP-methane) — and\n**VaaS** standards validation.\n\n## Prerequisites\n\n1. An **api-tier subscription**: https://dveracity.com/pricing\n2. An **API key** (`dvrc_…`): `POST /api/v1/api-keys` (or the dashboard)\n3. API **credits** for metered calls: `POST /api/v1/vaas/credits/purchase`\n\nThe machine-readable service contract lives at `GET /api/v1/semantic/manifest`\n(public, no auth).\n\n## Install\n\nFrom this directory: `npm install`\n\n### Claude Code\n\n```bash\nclaude mcp add dveracity \\\n  -e DVERACITY_API_KEY=dvrc_yourkey \\\n  -- node /path/to/dVE/mcp/semantic-mcp/index.js\n```\n\n### Generic MCP JSON config (Cursor, etc.)\n\n```json\n{\n  \"mcpServers\": {\n    \"dveracity\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/dVE/mcp/semantic-mcp/index.js\"],\n      \"env\": { \"DVERACITY_API_KEY\": \"dvrc_yourkey\" }\n    }\n  }\n}\n```\n\nOptional: `DVERACITY_API_URL` overrides the API base URL (defaults to prod).\n\n### KERI mode — verified agent identity (optional)\n\nIf the agent holds a **dVeracity Agent Authorization credential** (an ACDC issued\nby its Legal Entity, chained to the Legal Entity's vLEI — see\n`elm/docs/VLEI_AGENT_TOKENS_DESIGN.md`), set:\n\n```\nDVERACITY_KERI_AID=<the agent's AID (credential issuee)>\nDVERACITY_KERI_PRESENTATION=/path/to/agent-credential.cesr   # self-contained CESR\n```\n\nThe server then authenticates the agent by verifiable presentation\n(challenge → exchange → 1-hour session, refreshed transparently) and attaches\n`X-Keri-Session` to every call: the API key keeps carrying **billing**, the KERI\nsession adds **verified identity** — every metered call is attributed to the\nagent AID and Legal Entity LEI in dVeracity's audit trail. The `keri_identity`\ntool (free) shows the active identity. Scope denials (a credential that doesn't\ncarry e.g. `semantic:query`) surface as actionable errors naming the carried\nscopes. Signify-based nonce signing is a planned enhancement.\n\n## Tools\n\n| Tool | Cost | What it does |\n|---|---|---|\n| `semantic_query` | credits | Natural-language question over the verified-emissions knowledge graph |\n| `semantic_templates` | free | Catalog of supported query templates |\n| `credits_balance` | free | Remaining credit balance |\n| `list_standards` | free | Standards VaaS can validate against |\n| `validate_data` | credits | Validate a payload against a supported standard |\n| `keri_identity` | free | This agent's verified vLEI identity, when KERI mode is configured |\n\n### Open Footprint canonical model\n\nDesign-time tools for building an application on the Open Footprint standard.\nReading the model is free; only the check at the end is metered.\n\n| Tool | Cost | What it does |\n|---|---|---|\n| `ofp_models` | free | The eight model domains, and which database dialects have published DDL |\n| `ofp_search_entities` | free | Search 239 canonical entities by name, description or field |\n| `ofp_entity` | free | One entity in full: fields, types, keys, relationships, physical table |\n| `ofp_sectors` | free | Industry sectors, each with a status |\n| `ofp_sector` | free | One sector, with its reference artifacts |\n| `ofp_policies` | free | A sector's Rego guardrails, or an explicit \"none published\" |\n| `ofp_validate` | credits | Check a payload against the model and, optionally, sector guardrails |\n| `ofp_semantics` | free | O-DEF semantic codes, for aligning another system's fields onto the model |\n| `ofp_semantic_code` | free | Which canonical fields carry one code — the reverse lookup a connector needs |\n| `ofp_model_provenance` | free | Which snapshot of the standard this deployment serves |\n\nTwo behaviours are deliberate and worth knowing before you build against them.\n\n**Ambiguous entity names fail rather than resolve.** 48 of the 239 entity names\nare defined in more than one domain — `Country` is in four. `ofp_entity` without\na `domain` returns an error listing the candidates instead of picking one. Pass\n`domain` whenever you know it.\n\n**Semantic codes vary wildly in usefulness.** 660 of 813 canonical fields carry an\nO-DEF code, but the distribution is skewed: one generic code covers 255 fields.\nOnly about 16% sit on a code shared by ten fields or fewer. Every code is\nreturned with its `fieldCount` — check it before aligning to one, and pass\n`maxFieldCount: 10` to `ofp_semantics` to see only the precise ones.\n\n**\"Nothing published\" is an answer, not an error.** Most sectors are named in the\ntaxonomy but have no reference implementation, and only seven publish policy\nguardrails. `ofp_policies` on such a sector returns `published: false` with a\nreason, and `ofp_validate` reports `policy.ran: false`. Both mean *no rules are\npublished*, never *there are no constraints* — a payload checked for structure\nalone is not a compliant one, and should not be described as one.\n\nA fourth outcome, `unevaluable`, means the sector's rules ran but every rule that came back false reads an input the payload does not carry (`policy.missingInputs`, e.g. `co2e_kg`, `direction`, `counterparty_industry`). Those are e-ledger record fields, not canonical Open Footprint field names — `ofp_policies` lists them per policy under `inputs`. Unevaluable is neither a pass nor a breach, and `valid` is `null`.\n\n### What `ofp_validate` checks, and what it does not\n\nThe response is a contract, not a verdict. Every call reports the check\ncatalogue in two lists: `checked` (what ran) and `checks_not_run` (what did not,\neach with a `reason` and usually a `detail`). Read both before describing a\npayload as anything.\n\n| Check | Status in 0.5.x | Reason reported |\n|---|---|---|\n| `schema` — presence, primary key, types, declared constraints | runs | — |\n| `value_range` | not run: the model declares no numeric range on any field | `no_range_declared` |\n| `unit_coherence` | not run | `not_implemented` |\n| `temporal_consistency` | not run: an inverted validity period passes | `not_implemented` |\n| `referential_integrity` | not run: foreign keys are pattern-checked, never resolved | `no_data_plane` |\n| `factor_provenance` | not run | `not_implemented` |\n| `materiality` | not run | `not_implemented` |\n| `sector_policy` | runs when a sector with published guardrails covers the record type | `no_sector_supplied`, `no_policy_published`, `not_applicable`, `unevaluable` |\n\n- `schemaValid` is the structural verdict (`null` if the structural check could not run).\n- `assuranceLevel` names the depth earned: `schema-only`, `schema-and-value`,\n  `schema-value-and-policy` or `full`. Each level needs every check beneath it,\n  so guardrails without a value check is still `schema-only`.\n- Every violation and warning carries `severity` (`error` | `warning`). Rule ids\n  are stable: `required_field_missing`, `pattern_mismatch`, `format_mismatch`,\n  `type_mismatch`, `primary_key_missing`, `enum_violation`, … `unknown_field` is a\n  per-field warning and stays one.\n- `valid` is **deprecated** (see `deprecations` in the response). It keeps its\n  0.5.0 meaning through the 0.5.x line and is removed no earlier than 0.6.0.\n  Read `schemaValid` instead.\n\n## Billing behavior (for agents)\n\nMetered calls return an **HTTP 402** when the account is out of credits. The\nserver surfaces this as a tool error that tells the agent to ask its **human\noperator** to purchase credits or upgrade — agents should relay that message and\nstop, not retry.\n\n## Test\n\n`npm test` (no network; the HTTP layer is stubbed).\n\n## Where it is listed\n\n- [Smithery](https://smithery.ai/servers/ajvdvoort/dveracity) — one-click add for Smithery toolbox users\n- [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=dveracity) — `com.dveracity/semantic-mcp`\n- [npm](https://www.npmjs.com/package/@dveracity/semantic-mcp) — `@dveracity/semantic-mcp`\n",
  "bytes": 8067,
  "sha": "6c6f107aeae1db2a2ea4d67ea33119a5590950f5a691fc8d3caf9dd71658add8",
  "repo_slug": "d-veracity/semantic-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_dveracity_semantic_mcp_1f2d89cb/readme"
}