Canonical model & snapshots

Artifacts from five different tools arrive in five different shapes. The point of the canonical model is that after indexing, there is only one shape.

The canonical manifest

Reindexing creates a canonical capability manifest for each item: the normalized identity (type, tool, name, slug, description), activation and enrichment fields, and what the artifact provides/requires. Whatever the source format — YAML frontmatter, TOML, JSON config — the manifest is the common language the rest of the system (conversion, compatibility, hydration, packs) reasons about.

fetch_capability({ "id": "pdf-extraction" })

The response includes the original item fields plus manifest and snapshot when available. The dashboard shows lightweight file flags for scripts, assets/references, and snapshot coverage.

Snapshots

A snapshot records the artifact’s file tree: a tree hash for the whole artifact and a per-file classification (primary file, script, asset, metadata). Local snapshots carry both a sha256 and a git blob hash (gitSha) per file.

That dual hashing is what makes upstream verification cheap: comparing a local artifact against its GitHub source takes one tree-listing API call — git blob hashes line up directly, no file downloads. See Upstream provenance & drift.

Comparing snapshots across bases

Upstream snapshots are tree listings on the gitSha basis (no sha256, no content). Raw tree_hash strings from snapshots with different bases are not comparable — drift computation harmonizes them and drops an incomparable latest rather than mis-reporting.

Why one row per artifact

The registry stores one row per artifact (path-unique), with cross-tool duplicates collapsed at search time — one result, all locations noted. Config files that define many things (an .mcp.json with five servers) expand to many records with stable synthetic paths, so every server/hook is individually searchable, convertible, and trackable.