From 8b893ae1f1e029273b5c70857def8858a7b9852e Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Sat, 25 Apr 2026 10:15:32 -0400 Subject: [PATCH] docs: recommend namespaced subkeys inside publisher-provided (#1197) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Adds a short "Recommended: Namespaced Subkeys" subsection to `official-registry-requirements.md`, documenting the reverse-DNS subkey convention for `publisher-provided` metadata with one worked example - Explicitly notes this is not enforced, to avoid churning the ~15 existing flat-key examples elsewhere in the docs Closes #477 ## Test plan - [ ] Render the file on GitHub and verify the new subsection appears right after the `Publisher-Provided Metadata` size-limit note 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) --- .../official-registry-requirements.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/reference/server-json/official-registry-requirements.md b/docs/reference/server-json/official-registry-requirements.md index ec456cc..e03b659 100644 --- a/docs/reference/server-json/official-registry-requirements.md +++ b/docs/reference/server-json/official-registry-requirements.md @@ -69,6 +69,28 @@ When publishing to the official registry, **only data under the specific key `io **Size limit:** The publisher-provided extension is limited to 4KB (4096 bytes) of JSON. If the marshaled JSON exceeds this limit, publishing will fail with an error indicating the actual size. +#### Recommended: Namespaced Subkeys + +When your `publisher-provided` metadata gets large or comes from multiple sources (e.g. GitHub-specific hints alongside your own CI tool's metadata), grouping keys under reverse-DNS subkeys is a useful convention to avoid accidental collisions: + +```jsonc +{ + "_meta": { + "io.modelcontextprotocol.registry/publisher-provided": { + "com.github": { + "serverDisplayName": "My Server" + }, + "io.example.ci-publisher": { + "tool": "ci-publisher", + "version": "1.0.0" + } + } + } +} +``` + +This is **not enforced**; flat keys work fine for simple cases, and existing examples in this repo use the flat form. Use the namespaced form when organizing metadata from more than one source. + ### Registry API Metadata vs server.json Metadata The `_meta` field in `server.json` is **different** from the `_meta` field returned in registry API responses: