docs: reconcile mkdocs site with spec + ADRs (MCP drift) - #62
Merged
Conversation
The mkdocs docs under docs/ mirror the spec (specification/ai-catalog.md + adr/0001..0016). Several pages had drifted from the current spec, mostly around MCP. Bring them back into line: - Server Card URLs: drop /.well-known/mcp/server-card.json in favor of the /mcp/server-card form used by the spec examples (ADR-0011: the well-known convention is for the AI Catalog, not the Server Card). - Attestation objects: remove the invalid `mediaType` field (ADR-0014 removed mediaType from Attestation; the object has only type/uri + optional digest/size/description). - OCI mapping table + MCP section: rename the entry's `mediaType` to `type` (ADR-0014) and reframe "MCP Registry mapping"/server.json as "MCP servers" referencing MCP Server Cards (matches the spec's "Mapping to MCP Servers" appendix). - Trust Manifest identity: correct the binding rule from "must match the entry identifier" to "authority/trust domain MUST align with the publisher domain segment of the identifier" (spec Identity section). - creating-a-catalog known-types table: add application/agent-card+json and application/agent-skills+gzip to fully mirror the spec known types. - specification.md mappings bullet: MCP Registry server.json -> MCP servers (via MCP Server Cards). Verified: `mkdocs build --strict` succeeds; all edited JSON blocks are well-formed; no internal anchors broken by the header rename. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Keep the one-line style of the original; correct only the claim (trust-domain alignment with the publisher domain, not exact match). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tadasant
marked this pull request as ready for review
July 8, 2026 21:19
mindpower
approved these changes
Jul 8, 2026
tadasant
pushed a commit
that referenced
this pull request
Jul 9, 2026
Resolves the specification/ai-catalog.md conflict with the base branch's Server-Card-centric MCP mapping rewrite (PR #53) and mkdocs reconciliation (PR #62). Base main already added the authoritative-source guidance to the MCP mapping-appendix description/version rows, so those now-redundant edits are dropped. This branch's genuinely-additive contribution is preserved and re-applied onto the base structure: - authoritative-source guidance on the description and version *field definitions* (base still had bare one-liners there) - a new "Resolving an Artifact's Description" consumer-resolution section - the Claude Plugins appendix description row aligned to match Spec-internal anchor links use the build-tool slugify form (#resolving-an-artifact-s-description) to match base's convention; ADR cross-links keep the GitHub form, consistent with ADR-0016. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
The mkdocs documentation site under
docs/is meant to mirror and simplify the specification (specification/ai-catalog.md+ the ADRs inadr/). Several pages had drifted from the current spec — mostly around MCP — describing an older model. This PR brings the docs back into line with the spec. No spec or ADR files are changed; onlydocs/. Where the docs and the spec disagreed, the docs were treated as wrong and corrected to match the spec.Inconsistencies found & fixed
index.md,getting-started.md,guides/creating-a-catalog.md(×2),guides/organizing-catalogs.md(×2),examples/minimal-catalog.md,examples/multi-protocol-agent.md,examples/nested-catalogs.md— 9 URLs…/.well-known/mcp/server-card.json…/mcp/server-card(the form the spec examples use).well-knownconvention is for the AI Catalog, not the Server Card; spec examples never put the card under.well-knownguides/adding-trust.md(×5),examples/multi-protocol-agent.md(×1)"mediaType": …fieldmediaTypewas removed from the Attestation object; it has onlytype/uri(required) + optionaldigest/size/description(spec "Attestation Object")guides/serving-your-catalog.md(OCI table)artifactTypeset to the entry'smediaTypetypemediaType→type); matches the spec's OCI mapping table verbatim.artifactTypeitself is a real OCI field and is kept.guides/serving-your-catalog.md(§ heading + body)server.jsonentries map naturally… each MCP server becomes an entry withmediaType: application/mcp-server-card+json"type: application/mcp-server-card+json,url→ the card)server.json-based)specification.md(mappings list)server.json, and Claude Code Plugins"guides/adding-trust.md(identityfield)identity… Must match the containing entry'sidentifier." (asserted exact-string match)identifier(a one-line correction, kept in the docs' simple style)guides/creating-a-catalog.md(known-typetable)application/agent-card+jsonandapplication/agent-skills+gziptypefieldNot changed (deliberately)
/.well-known/ai-catalog.json— still correct and kept; ADR-0011 only makes it OPTIONAL (a SHOULD-register convention), and the docs already present link-relation discovery as the primary mechanism with well-known as fallback.artifactTypein the OCI-mapping context — a legitimate OCI field, retained.type-is-a-media-type framing — consistent with the spec's own Design Goal ("declare its artifact type using a media type"), so left as-is.