#!/usr/bin/env python3 """Project the server-only advertised capabilities of one MCP revision from the canonical inventory. Story 3.1 AT-13 artifact step. The expectation for a revision is derived **only** from the `protocol` block of `docs/capability-inventory.json` (accepted SPEC `remaining-ac-spec.md` section 5, rules 1-4): 1. take the effective entry for the era (`default` merged with `per_revision[era]`, rule O2); 2. include it only when `kind in {capability, extension}` AND `role = server` AND `status = supported` AND the era is listed in the entry's `revisions[]`; client/both/method/notification entries are neutral completeness inputs and are never projected; 3. deep-merge the `advertised` fragments of every included entry; a conflicting top-level capabilities key is rejected; 4. the result is exactly the era's `capabilities` object. The producer never calls the MCP server, never imports the registry and never reads a captured server response: era-vs-era, self-snapshot and capture-of-server-output-as-expectation are forbidden. The frozen payload is the canonical serialization of that object: compact UTF-8 (`:`/`,` separators), object keys sorted byte-lexicographically, no trailing newline. The audit provenance (inventory digest, projection rule id and the participating identity triples) lives in a separate sidecar file and is never byte-compared with the endpoint. """ from __future__ import annotations import argparse import hashlib import json import sys from pathlib import Path from typing import Any REVISION_ORDER = ("2026-07-28", "2025-11-25") PROJECTION_RULE = "remaining-ac-spec.md#5-server-only-projection-rules-1-4" ADVERTISABLE_KINDS = frozenset({"capability", "extension"}) # Rule O1 (accepted SPEC section 5), the same policy the validator applies: exactly these fields may be # redeclared per revision. The structural identity and the applicability scope are resolved from the # default record, so a forbidden `surface`/`revisions` override is a bounded rejection instead of a # silently narrowed eligibility scope (G5). OVERRIDE_ALLOWED_FIELDS = frozenset( { "status", "applicability", "role", "reason", "fallback", "evidence_target", "owner", "requirement", "subfeatures", "open_subfeatures", "advertised", } ) # The pinned wire types of the advertisement leaves this projection emits # (`reviewed-inputs/2026-07-28-schema.ts`: `ServerCapabilities.tools.listChanged?: boolean`). An array # leaf used to be written into the frozen artifact, i.e. a fragment the pinned type does not allow (G4). PINNED_LEAF_TYPES: dict[str, type] = { "tools.listChanged": bool, } # The reviewed `subfeatures`/`open` accounting of the two pinned revision schemas # (`surface-inventory.md` sections 3-4 of the accepted SPEC, rule U3): the sub-keys the pinned schema # declares for a capability and whether the pinned value is an open map. The standalone producer is an # artifact oracle of its own, so it rejects a self-declared sub-key that legitimized an advertised leaf # the pinned schema does not declare (`tools.subfeatures = ["invented"]` + # `advertised = {"tools": {"invented": true}}` used to be projected for both eras, H2). REVIEWED_SUBFEATURE_BASIS: dict[tuple[str, str, str], tuple[tuple[str, ...], bool]] = { ("2026-07-28", "server", "experimental"): ((), True), ("2026-07-28", "server", "logging"): ((), False), ("2026-07-28", "server", "completions"): ((), False), ("2026-07-28", "server", "prompts"): (("listChanged",), False), ("2026-07-28", "server", "resources"): (("subscribe", "listChanged"), False), ("2026-07-28", "server", "tools"): (("listChanged",), False), ("2026-07-28", "server", "extensions"): ((), True), ("2026-07-28", "client", "experimental"): ((), True), ("2026-07-28", "client", "roots"): ((), False), ("2026-07-28", "client", "sampling"): (("context", "tools"), False), ("2026-07-28", "client", "elicitation"): (("form", "url"), False), ("2026-07-28", "client", "extensions"): ((), True), ("2025-11-25", "server", "experimental"): ((), True), ("2025-11-25", "server", "logging"): ((), False), ("2025-11-25", "server", "completions"): ((), False), ("2025-11-25", "server", "prompts"): (("listChanged",), False), ("2025-11-25", "server", "resources"): (("subscribe", "listChanged"), False), ("2025-11-25", "server", "tools"): (("listChanged",), False), ("2025-11-25", "server", "tasks"): (("list", "cancel", "requests.tools.call"), False), ("2025-11-25", "client", "experimental"): ((), True), ("2025-11-25", "client", "roots"): (("listChanged",), False), ("2025-11-25", "client", "sampling"): (("context", "tools"), False), ("2025-11-25", "client", "elicitation"): (("form", "url"), False), ("2025-11-25", "client", "tasks"): ( ("list", "cancel", "requests.sampling.createMessage", "requests.elicitation.create"), False, ), } def advertisement_key(kind: Any, surface: Any) -> Any: """The top-level `capabilities` key an advertisable surface declares its fragment under (spec 5/A1). A capability declaration advertises under its own surface name; a capability extension advertises under the `extensions` key (e.g. `io.modelcontextprotocol/tasks` -> `extensions`). Any other top-level key is not the pinned advertisement of the declaring surface and is rejected instead of being merged into the era payload. """ if kind == "extension": return "extensions" return surface class ProjectionError(Exception): """The inventory cannot be projected for the requested revision.""" def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--inventory", type=Path, required=True) parser.add_argument("--revision", required=True, choices=list(REVISION_ORDER)) parser.add_argument("--frozen", type=Path, required=True) parser.add_argument("--provenance", type=Path, required=True) return parser.parse_args() def reject_nonstandard_json_constant(name: str) -> None: """`NaN`/`Infinity` are JavaScript-only constants, never part of a JSON artifact (G4). `json.loads` accepts them by default and `json.dumps` writes them back, so the bounded oracle used to emit an unparseable frozen payload. """ raise ProjectionError(f"inventory carries the non-standard JSON constant {name!r}") def load_inventory(path: Path) -> tuple[dict[str, Any], str]: try: payload_bytes = path.read_bytes() except OSError as error: # pragma: no cover - defensive raise ProjectionError(f"inventory is unreadable: {path}: {error}") from error digest = hashlib.sha256(payload_bytes).hexdigest() try: document = json.loads( payload_bytes.decode("utf-8"), parse_constant=reject_nonstandard_json_constant ) except (UnicodeDecodeError, json.JSONDecodeError) as error: raise ProjectionError(f"inventory is not valid UTF-8 JSON: {path}") from error if not isinstance(document, dict): raise ProjectionError("inventory must be a JSON object") return document, digest def effective(entry: dict[str, Any], era: str) -> dict[str, Any]: """Shallow per-field merge `default` + `per_revision[era]` (accepted SPEC rule O2). Only the rule O1 allowed fields are merged: the structural identity/applicability scope always resolves from the default record, exactly as in the validator. """ merged = {key: value for key, value in entry.items() if key != "per_revision"} overrides = entry.get("per_revision", {}) if isinstance(overrides, dict): override = overrides.get(era, {}) if isinstance(override, dict): merged.update( { key: value for key, value in override.items() if key in OVERRIDE_ALLOWED_FIELDS } ) return merged def check_override_policy(entry: dict[str, Any], surface: Any, era: str) -> None: """Rule O1 for one entry: only the allowed fields may be redeclared, per era (G5). A standalone negative must hold even when no validator ran before, so a forbidden `revisions` override is rejected here rather than silently narrowing the eligibility scope and producing an empty artifact. """ overrides = entry.get("per_revision") if overrides is None: return if not isinstance(overrides, dict): raise ProjectionError( f"per_revision of {surface!r} must be an object for {era}: {overrides!r}" ) for revision, override in overrides.items(): if not isinstance(override, dict): raise ProjectionError( f"per_revision/{revision} of {surface!r} must be an object for {era}: {override!r}" ) for key in override: if key not in OVERRIDE_ALLOWED_FIELDS: raise ProjectionError( f"per-revision override field {key!r} of {surface!r} for {revision} is not " f"allowed by rule O1 (observed while projecting {era})" ) def check_subfeature_basis(resolved: dict[str, Any], era: str) -> None: """H2/U3 + J2: the declared `subfeatures`/`open_subfeatures` of one effective record are reviewed. The producer is a standalone artifact oracle: a self-declared sub-key that legitimizes an advertised leaf the pinned revision schema does not declare must be rejected here as well, even when no validator ran before, and the reviewed open maps / per-era differences stay accepted. The check runs for every capability record of the document (advertisable or not), so a document that misdeclares a client-side row is not silently projectable either. J2: the type of that accounting is not deferred to the projected-entry checks (F8), which only ever see a supported server row eligible for the requested era. A wrong-typed `subfeatures` (e.g. `null` or `[{}]`) or `open_subfeatures` (e.g. `"false"`) on a client, truthfully deferred or applicability-skipped capability made the standalone oracle exit 0 and write the frozen payload and the provenance sidecar while the validator rejected the same document. Every capability record is therefore type-checked before its declaration is compared with the reviewed basis; the comparison itself stays limited to the reviewed per-era rows, and a declaration absent from the record is still handled by the projected-entry checks. """ if resolved.get("kind") != "capability": return surface = resolved.get("surface") role = resolved.get("role") if not isinstance(surface, str) or not isinstance(role, str): return declared = resolved.get("subfeatures") if "subfeatures" in resolved and ( not isinstance(declared, list) or not all(isinstance(item, str) for item in declared) ): raise ProjectionError( f"subfeatures of {surface!r} must be an array of strings for {era}: {declared!r}" ) open_flag = resolved.get("open_subfeatures") if "open_subfeatures" in resolved and not isinstance(open_flag, bool): raise ProjectionError( f"open_subfeatures of {surface!r} must be a boolean for {era}: {open_flag!r}" ) expected = REVIEWED_SUBFEATURE_BASIS.get((era, role, surface)) if expected is None: return expected_keys, expected_open = expected if not isinstance(declared, list): # The type contract of a projected entry is enforced separately (F8). return unexpected = sorted(set(declared) - set(expected_keys)) if unexpected: raise ProjectionError( f"the declared subfeatures {unexpected} of {surface!r} are not part of the reviewed " f"pinned {era} basis {list(expected_keys)}" ) missing = sorted(set(expected_keys) - set(declared)) if missing: raise ProjectionError( f"the reviewed pinned {era} basis of {surface!r} declares {list(expected_keys)}; missing " f"from subfeatures: {missing}" ) if isinstance(open_flag, bool) and open_flag is not expected_open: raise ProjectionError( f"open_subfeatures of {surface!r} must be {str(expected_open).lower()} in the pinned " f"{era} revision, observed {open_flag!r}" ) def required_text(value: Any, field: str, era: str) -> str: """One projected entry field must be a non-empty string; anything else is a bounded rejection. The producer is a standalone CLI oracle: a malformed kind/subfeature/map must produce a deterministic `PROJECTION_REJECTED` diagnostic instead of an unhandled `TypeError` (F8). """ if not isinstance(value, str) or not value: raise ProjectionError(f"{field} of a projected entry must be a non-empty string for {era}: {value!r}") return value def leaf_items(node: dict[str, Any], prefix: str = "") -> list[tuple[str, Any]]: """Leaf paths with the value that terminates each path (G4).""" items: list[tuple[str, Any]] = [] for key, value in node.items(): path = f"{prefix}.{key}" if prefix else key if isinstance(value, dict) and value: items.extend(leaf_items(value, path)) else: items.append((path, value)) return items def project(capabilities: Any, era: str) -> tuple[dict[str, Any], list[dict[str, str]]]: if not isinstance(capabilities, list): raise ProjectionError("protocol.capabilities must be an array") merged: dict[str, Any] = {} participating: list[dict[str, str]] = [] for entry in capabilities: if not isinstance(entry, dict): raise ProjectionError("protocol.capabilities entries must be objects") # Rule O1 first, for every entry: a forbidden/unknown per-revision override makes the document # unprojectable even when the entry is not advertisable (G5). check_override_policy(entry, entry.get("surface"), era) resolved = effective(entry, era) # F8: every field this projection reads is type-checked before it is used, so a malformed # kind/subfeature/map is a bounded rejection instead of an unhandled interpreter error. kind = resolved.get("kind") if not isinstance(kind, str) or not kind: raise ProjectionError( f"kind of a protocol.capabilities entry must be a non-empty string for {era}: {kind!r}" ) if kind not in ADVERTISABLE_KINDS: continue role = resolved.get("role") if not isinstance(role, str) or not role: raise ProjectionError( f"role of a protocol.capabilities entry must be a non-empty string for {era}: {role!r}" ) # H2: the declared per-era subfeature accounting of every capability record is compared with the # reviewed pinned basis before the advertisable filter, so a misdeclared row can never be # projected (and never silently skipped) either. check_subfeature_basis(resolved, era) if role != "server": continue status = resolved.get("status") if not isinstance(status, str) or not status: raise ProjectionError( f"status of a protocol.capabilities entry must be a non-empty string for {era}: " f"{status!r}" ) if status != "supported": continue # Eligibility is read from the *default* applicability scope, before any merge (rule O1: an # override may never move the window), exactly as the validator resolves it. revisions = entry.get("revisions") if not isinstance(revisions, list) or not all(isinstance(item, str) for item in revisions): raise ProjectionError( f"revisions of one advertisable entry must be an array of revision strings for {era}: " f"{revisions!r}" ) if era not in revisions: continue surface = required_text(resolved.get("surface"), "surface", era) fragment = resolved.get("advertised") if not isinstance(fragment, dict) or not fragment: raise ProjectionError( f"supported server {kind} {surface!r} must carry a non-null " f"advertised fragment for {era}" ) declared = resolved.get("subfeatures") if not isinstance(declared, list) or not all(isinstance(item, str) for item in declared): raise ProjectionError( f"subfeatures of {surface!r} must be an array of strings for {era}: {declared!r}" ) declared_keys = set(declared) open_flag = resolved.get("open_subfeatures") if not isinstance(open_flag, bool): raise ProjectionError( f"open_subfeatures of {surface!r} must be a boolean for {era}: {open_flag!r}" ) open_map = open_flag expected_key = advertisement_key(kind, surface) for top_key, value in fragment.items(): if top_key != expected_key: raise ProjectionError( f"advertised top-level key {top_key!r} does not belong to the declaring surface " f"{surface!r} (expected {expected_key!r}) for {era}" ) if not isinstance(value, dict): raise ProjectionError( f"advertised fragment {top_key!r} of {surface!r} must be a JSON object for {era}" ) if top_key in merged: raise ProjectionError( f"conflicting top-level advertised key {top_key!r} while projecting {era}" ) for leaf, leaf_value in leaf_items(value): if not open_map and leaf not in declared_keys: raise ProjectionError( f"advertised leaf {leaf!r} of {surface!r} is not declared by subfeatures for {era}" ) pinned = PINNED_LEAF_TYPES.get(f"{top_key}.{leaf}") if pinned is not None and type(leaf_value) is not pinned: raise ProjectionError( f"advertised leaf {leaf!r} of {surface!r} must be a {pinned.__name__} in the " f"pinned revision for {era}: {leaf_value!r}" ) merged[top_key] = value participating.append( {"role": str(resolved.get("role")), "kind": str(resolved.get("kind")), "surface": str(surface)} ) return merged, participating def canonical_bytes(payload: dict[str, Any]) -> bytes: """Compact UTF-8, sorted keys, no trailing newline (accepted SPEC section 5). `allow_nan=False` is the backstop of the strict parse: a non-standard JSON constant may never be serialized into the frozen artifact (G4). """ return json.dumps( payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False ).encode("utf-8") def main() -> int: args = parse_args() try: document, digest = load_inventory(args.inventory) protocol = document.get("protocol") if not isinstance(protocol, dict): raise ProjectionError("inventory has no protocol block") projected, participating = project(protocol.get("capabilities"), args.revision) except ProjectionError as error: sys.stderr.write(f"error[PROJECTION_REJECTED] /protocol: {error}\n") return 1 except (TypeError, ValueError) as error: # A malformed input shape that the explicit field checks above did not name: the CLI still # answers with a deterministic bounded rejection instead of an unhandled interpreter error. sys.stderr.write( f"error[PROJECTION_REJECTED] /protocol: malformed projection input: {error}\n" ) return 1 frozen_bytes = canonical_bytes(projected) provenance = { "revision": args.revision, "inventory_path": str(args.inventory), "inventory_sha256": digest, "rule": PROJECTION_RULE, "projection_inputs": participating, "note": ( "Sidecar provenance only. Never compared byte-for-byte with the endpoint; the payload " "oracle is the sibling .frozen.json file." ), } args.frozen.parent.mkdir(parents=True, exist_ok=True) args.provenance.parent.mkdir(parents=True, exist_ok=True) args.frozen.write_bytes(frozen_bytes) args.provenance.write_text(json.dumps(provenance, indent=2) + "\n", encoding="utf-8") print( f"projected {args.revision}: top_level_keys={len(projected)} " f"bytes={len(frozen_bytes)} sha256={hashlib.sha256(frozen_bytes).hexdigest()}" ) return 0 if __name__ == "__main__": raise SystemExit(main())