From dac0982f6db8f391485d22f514e348cb8b86ea5a Mon Sep 17 00:00:00 2001 From: Ashwanthram K L <71945723+AshwanthramKL@users.noreply.github.com> Date: Fri, 24 Apr 2026 03:51:21 +0530 Subject: [PATCH] docs: signpost non-npm publishers to package-types from quickstart (#1192) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What Two targeted additions to `docs/modelcontextprotocol-io/quickstart.mdx`: 1. A `` 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](./package-types) before continuing. 2. The troubleshooting row for **"Registry validation failed for package"** previously named only npm's `mcpName` property in `package.json`. It now names all three current mechanisms (npm → `mcpName` in `package.json`; PyPI / NuGet → `mcp-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 `mcpName` property and nothing else. The cross-reference to `./package-types` only appears in the "Next Steps" footer, by which point a PyPI publisher has already gone through every step and hit a `400 Bad Request` at `mcp-publisher publish`: > `registry validation failed for package 0 (): PyPI package '' ownership validation failed. The server name 'io.github./' must appear as 'mcp-name: io.github./' in the package README` 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** - It does not propose changing the validation logic. - It does not duplicate content from `package-types.mdx` into the quickstart. - It does not add a separate PyPI-specific tutorial. The existing npm-flavored tutorial remains the canonical one; the note just tells non-npm readers which step is different. ## Verification - Change is docs-only; no build or test impact. - Link target `./package-types` is the same shape as the one already used in "Next Steps" of the same file. - Anchor `#step-1-add-verification-information-to-the-package` matches the existing heading's slug. ## Related - #531 — same validation error hit by another PyPI publisher; closed with a workaround but the quickstart wasn't updated. --- docs/modelcontextprotocol-io/quickstart.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/modelcontextprotocol-io/quickstart.mdx b/docs/modelcontextprotocol-io/quickstart.mdx index b33fc17..41bc8fc 100644 --- a/docs/modelcontextprotocol-io/quickstart.mdx +++ b/docs/modelcontextprotocol-io/quickstart.mdx @@ -9,6 +9,10 @@ sidebarTitle: "Quickstart: Publish a Server" This tutorial will show you how to publish an MCP server written in TypeScript to the MCP Registry using the official `mcp-publisher` CLI tool. + + If you are publishing a non-npm package (PyPI, NuGet, OCI, MCPB), the overall flow is identical, but the ownership-verification step in [Step 1](#step-1-add-verification-information-to-the-package) is different per package type. See [Package Types](./package-types) for the verification mechanism that applies to your package, then return here and follow the remaining steps. + + ## Prerequisites - **Node.js** — This tutorial assumes the MCP server is written in TypeScript. @@ -279,7 +283,7 @@ You should see your server's metadata in the search results JSON: | Error Message | Action | | --- | --- | -|"Registry validation failed for package"|Ensure your package includes the required validation information (e.g, `mcpName` property in `package.json`).| +|"Registry validation failed for package"|Ensure your package includes the required ownership-verification marker for its package type. For npm this is `mcpName` in `package.json`; for PyPI and NuGet it is an `mcp-name: ` line (or HTML comment) in the package README; for other types see [Package Types](./package-types).| |"Invalid or expired Registry JWT token"|Re-authenticate by running `mcp-publisher login github`.| |"You do not have permission to publish this server"|Your authentication method doesn't match your server's namespace format. With GitHub auth, your server name must start with `io.github.your-username/`.|