fix(schema): align reserved _meta prefix rule with spec docs#2758
Merged
kurtisvg merged 1 commit intoMay 21, 2026
Merged
Conversation
The MetaObject JSDoc (the schema source of truth) and the basic
specification described structurally different rules for which `_meta`
key prefixes are reserved for MCP, and classified the same prefixes
oppositely.
schema.ts required a trailing label after the keyword ("zero or more
labels, followed by modelcontextprotocol or mcp, followed by any
label"), so `io.modelcontextprotocol/` — the prefix used for every
mandatory per-request field (protocolVersion, clientInfo,
clientCapabilities, logLevel, subscriptionId) — was NOT reserved under
the source of truth, leaving the protocol's own namespace open to
collision. The docs used a reverse-DNS "second label" rule that did
reserve it.
Adopt the docs' rule and example set verbatim in the JSDoc (and the
reverse-DNS recommendation), then regenerate schema.json and
schema.mdx so all three documents state one identical rule with one
identical example set.
kurtisvg
approved these changes
May 21, 2026
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.
Problem
The reserved-
_meta-prefix rules in the schema and the basic specification were structurally different and classified the same prefixes oppositely.schema/draft/schema.ts(source of truth): "Any prefix consisting of zero or more labels, followed bymodelcontextprotocolormcp, followed by any label, is reserved." Examples were forward-DNS:modelcontextprotocol.io/,mcp.dev/,api.modelcontextprotocol.org/,tools.mcp.com/.docs/specification/draft/basic/index.mdx(docs): "Any prefix where the second label ismodelcontextprotocolormcpis reserved." Examples were reverse-DNS:io.modelcontextprotocol/,dev.mcp/,org.modelcontextprotocol.api/,com.mcp.tools/.Because the schema rule required a trailing label after the keyword,
io.modelcontextprotocol/was not reserved under the source of truth — yet that is the prefix used for every mandatory per-request field (io.modelcontextprotocol/protocolVersion,/clientInfo,/clientCapabilities,/logLevel,/subscriptionId). The protocol's own namespace was left open to third-party squatting/collision. Conversely,modelcontextprotocol.io/andmcp.dev/were reserved only by the schema, anddev.mcp/only by the docs. Two implementers building a_meta-key validator from the two documents would produce incompatible, mutually-rejecting validators, and neither would protect the spec's own keys.Fix
The schema is brought in line with the docs. The
MetaObjectJSDoc now uses the docs' rule and example set:io.modelcontextprotocol/,dev.mcp/,org.modelcontextprotocol.api/,com.mcp.tools/), including thecom.example.mcp/-is-NOT-reserved clarification.schema.jsonandschema.mdxwere regenerated vianpm run generate:schema. All three documents now state one identical rule with one identical example set, and the protocol's ownio.modelcontextprotocol/namespace is reserved.Validation
npm run generate:schema— regenerated JSON + MDX.npm run check:schema— passes for the changed files. (One pre-existing, unrelated failure remains in draft:ReadResourceResult/file-resource-contents.jsonis missingcacheScope/ttlMs; not touched by this PR.)npm run format— no further changes.