cvd-mcp

{
  "sku": "WIDGET-PRO",
  "unit_price_usd": 4800.00
}

{
  "status": "refused",
  "reason": "context_expired",
  "disclosure": "…last validated 14 days
   ago… The accountable steward is
   Ana Souza; contact them to revalidate."
}

flowchart LR
    A["agent calls<br/>guarded tool"] --> B{"age =<br/>now − last_validated"}
    B -->|"age ≤ freshness_slo"| C["✅ FRESH<br/>answer, unchanged"]
    B -->|"age > freshness_slo"| D{"decay_policy<br/>.on_violation"}
    D -->|refuse_with_disclosure| E["🛑 refusal that<br/>names the steward"]
    D -->|warn| F["⚠️ answers,<br/>but flagged"]
    D -->|escalate_to_steward| G["📣 routed to<br/>escalation target"]
    D -->|"unknown policy"| E

{
  "steward": "Ana Souza (Head of Pricing Operations)",
  "source_of_record": "SAP ERP price list PL-2026-Q3",
  "freshness_slo": "P7D",
  "last_validated": "2026-07-15T09:00:00Z",
  "decay_policy": {
    "on_violation": "refuse_with_disclosure",
    "fallback": "escalate_to_steward"
  }
}

pip install -e .            # core — zero dependencies, Python ≥ 3.9
pip install -e ".[mcp]"     # + official MCP Python SDK, for the example server
pip install -e ".[dev]"     # + pytest

from cvd import ContextValidity, DecayPolicy, cvd_guard

pricing_cv = ContextValidity(
    steward="Ana Souza (Head of Pricing Operations)",
    source_of_record="SAP ERP price list PL-2026-Q3",
    freshness_slo="P7D",
    last_validated="2026-07-15T09:00:00Z",
    decay_policy=DecayPolicy(on_violation="refuse_with_disclosure"),
)

@cvd_guard(pricing_cv)
def get_enterprise_price(sku: str) -> dict:
    return {"sku": sku, "unit_price_usd": 4800.00}

from cvd import evaluate, ContextExpired

decision = evaluate(pricing_cv)          # Decision(freshness, allowed, action, age, slo, …)

@cvd_guard(pricing_cv, raise_on_expired=True)
def get_price(sku: str) -> dict: ...     # raises ContextExpired, carrying the Decision

from mcp.server.fastmcp import FastMCP
from cvd import cvd_guard

mcp = FastMCP("pricing-context-server")

@mcp.tool()
@cvd_guard(PRICING_CV)
def get_enterprise_price(sku: str) -> dict:
    ...

pip install -e ".[mcp]"
python -m cvd.mcp_server

=== 2. STALE — past the 7-day window (age: 14 days) ===
freshness      : STALE
allowed        : False
action         : refuse
tool result    : {
  "status": "refused",
  "reason": "context_expired",
  "disclosure": "This context derives from SAP ERP price list PL-2026-Q3 and has
    exceeded its freshness SLO of P7D: it was last validated 14 days ago, on
    2026-07-15T09:00:00Z. The accountable steward is Ana Souza (Head of Pricing
    Operations); contact them to revalidate."
}

CVD demo — fail loud, not fail confident
manifest: examples/pricing_context.json

=== 1. FRESH — within the 7-day window (age: 2 days) ===
now            : 2026-07-17T09:00:00+00:00
last_validated : 2026-07-15T09:00:00Z
freshness_slo  : P7D
freshness      : FRESH
allowed        : True
action         : answer
tool result    : {
  "sku": "WIDGET-PRO",
  "unit_price_usd": 4800.0,
  "currency": "USD"
}

=== 2. STALE — past the 7-day window (age: 14 days) ===
now            : 2026-07-29T09:00:00+00:00
last_validated : 2026-07-15T09:00:00Z
freshness_slo  : P7D
freshness      : STALE
allowed        : False
action         : refuse
tool result    : {
  "status": "refused",
  "reason": "context_expired",
  "disclosure": "This context derives from SAP ERP price list PL-2026-Q3 and has exceeded its freshness SLO of P7D: it was last validated 14 days ago, on 2026-07-15T09:00:00Z. The accountable steward is Ana Souza (Head of Pricing Operations); contact them to revalidate.",
  "escalate_to": null
}

Lacerda, K. (2026). The Agent Steward: Context Provenance and Temporal Validity
as a Missing Governance Dimension in Multi-Agent Enterprise Ecosystems.
Zenodo. https://doi.org/10.5281/zenodo.21660205