docs: signpost non-npm publishers to package-types from quickstart - #1192
Merged
rdimitrov merged 1 commit intoApr 23, 2026
Merged
Conversation
The quickstart is entirely npm-oriented (TypeScript example, npm publish, package.json mcpName marker). A publisher following it end-to-end for a PyPI, NuGet, OCI, or MCPB package will hit a 400 at 'mcp-publisher publish' because the ownership-verification step in Step 1 applies npm's mechanism. The correct per-package-type mechanism is already documented at ./package-types, but the quickstart doesn't link to it until 'Next Steps' at the very end. Two targeted changes so non-npm users don't have to debug it: 1. A <Note> at the top of the tutorial pointing them to Package Types before Step 1, with an explicit anchor to the verification step they'll need to adapt. 2. The 'Registry validation failed for package' troubleshooting row, which previously mentioned only npm's mcpName, now names the three current mechanisms (npm's mcpName, the README mcp-name marker for PyPI/NuGet, and a link to Package Types for the rest). This is motivated by filed issue modelcontextprotocol#531 and by recent publisher reports in the same spirit. No content is duplicated from package-types.mdx; this is purely navigational.
rdimitrov
approved these changes
Apr 23, 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.
What
Two targeted additions to
docs/modelcontextprotocol-io/quickstart.mdx:<Note>immediately after the tutorial's intro, telling PyPI / NuGet / OCI / MCPB publishers that the Step 1 ownership-verification mechanism differs for their package type and pointing them to Package Types before continuing.mcpNameproperty inpackage.json. It now names all three current mechanisms (npm →mcpNameinpackage.json; PyPI / NuGet →mcp-name: <server-name>line in the package README; other types → link to Package Types).+5 / -1 lines.
Why
The quickstart is the landing page for new publishers, but it's entirely TypeScript / npm-flavored — the Step 1 example shows npm's
mcpNameproperty and nothing else. The cross-reference to./package-typesonly appears in the "Next Steps" footer, by which point a PyPI publisher has already gone through every step and hit a400 Bad Requestatmcp-publisher publish:That specific error has tripped at least one other publisher (#531) and was what motivated this change. The ownership mechanism is correctly documented at
./package-types— the fix is purely to route people there before they publish, not to duplicate the content.What this change is not
package-types.mdxinto the quickstart.Verification
./package-typesis the same shape as the one already used in "Next Steps" of the same file.#step-1-add-verification-information-to-the-packagematches the existing heading's slug.Related
registry validation failed for package 0#531 — same validation error hit by another PyPI publisher; closed with a workaround but the quickstart wasn't updated.