What

Follow-ups from the review of #2973 (the review comment) — the items #2973 itself didn't pick up before it merged. Two of them are invisible to every check that ran green on that PR, because neither the docs build nor the publish path runs in PR CI.

Key changes

The published API reference (PR-introduced by #2973, no CI sees it). docs/hooks/gen_ref_pages.py derives the mkdocstrings identifier from the path relative to src/, which for the new package yields ::: mcp-types.mcp_types.* — and griffe resolves modules by walking the filesystem, not importlib, so it happily collects the hyphenated directory as a namespace package. The result is a green mkdocs build --strict that publishes the entire type system under the heading mcp-types.mcp_types (a dotted path that is a syntax error to import) while every existing link to /api/mcp/types/* 404s. Fixed by deriving each module's identifier from its own package root, adding src/mcp-types to the mkdocs paths: list and to the deploy-docs.yml trigger filter (which only listed src/mcp/**), and dropping the mkdocs watch: package list rather than extending it.

The publish path. The release job uploads both distributions in one trusted-publishing step. A partial upload — say, the mcp-types trusted publisher isn't configured yet, or PyPI hiccups on one project — used to be unrecoverable from the workflow alone, because re-running it failed on the files that had already landed. skip-existing: true makes a re-run skip whatever is already on PyPI and upload the rest, so a partial failure is fixed by re-running the job.

Development Status classifier. #2975 set mcp to 5 - Production/Stable but left src/mcp-types/pyproject.toml at 3 - Alpha, and the two distributions are published in lockstep with an exact == pin — so their PyPI metadata would contradict each other, immutably. mcp-types now matches, and RELEASE.md records that the classifier is permanently 5 - Production/Stable and is not part of any release.

A CI check for the package's headline contract. Nothing today fails if mcp_types grows an import httpx: tests, pyright, and ruff all run in the one workspace venv, which always has the full SDK dependency closure installed, so the import just resolves and everything stays green — the breakage only surfaces for the first user who installs mcp-types into a clean environment. A new step in the pre-commit job exercises the contract directly: uv run --isolated --no-project --with ./src/mcp-types resolves only the package's declared dependencies into an empty environment and imports every module, so a stray import of the SDK or anything from its stack is a ModuleNotFoundError and a red, blocking check (the pre-commit job is a hard gate; the test matrix is continue-on-error). Also moves tests/shared/test_version.py to tests/types/ to mirror its source module.

Docs. The migration guide's headline "After (v2)" example, from mcp import Tool, CallToolResult, raises ImportError — CallToolResult was never in mcp.__all__. Swapped for Resource, which is. Also: name mcp_types.version as the home of the protocol-version constants (they're not in mcp_types.__all__ and the section never said where they went), link the new API reference from the section about the move, correct "depends only on pydantic" to also name typing-extensions, and point schema/README.md at the new codegen output path.

Contributor docs. [project].dependencies becoming dynamic means uv add <runtime-pkg> on the root project now fails (and with a misleading build-backend traceback that never points at the real edit site), so AGENTS.md's "Installation: uv add <package>" gets the exception. RELEASE.md now covers the two-distribution release and the trusted-publisher precondition.

Not done here, deliberately

• Required before the next release tag, and not expressible in code: the mcp-types PyPI project (currently owned by Kludex alone, vs dsp/jspahrsummers/maxisbey on mcp) needs a Trusted Publisher matching mcp's — this repository, workflow publish-pypi.yml, environment release — plus the same owners. Without it the upload is rejected; the new step ordering bounds the blast radius to "nothing publishes" instead of "pip install mcp breaks", but it doesn't make the release succeed.
• Recommended follow-up: an mkdocs build --strict job in PR CI is the mechanism that would have caught the gen_ref_pages bug (and its whole class) before merge. Left out of this PR because the build fetches three external objects.inv inventories, so it adds a real external-flakiness surface to every PR — that tradeoff deserves its own decision.
• mcp_types.version is now load-bearing public API under a name that reads like "the package's version". Renaming (or re-exporting the registry from the top level) is free until the first mcp-types release and not after; raised on Split protocol types into a standalone mcp-types package #2973 and intentionally not decided unilaterally here.

Verification

• gen_ref_pages.py executed against the tree: 97 pages, zero hyphenated identifiers, all six mcp_types.* ones resolve via griffe with the new paths; mkdocs build --strict exits 0 with api/mcp and api/mcp_types both emitted.
• The standalone check was run verbatim, with a negative control: the isolated environment contains only mcp-types plus its declared closure (anyio, httpx, starlette, and mcp are all absent from it), and all six mcp_types modules import.
• pypa/gh-action-pypi-publish at the pinned ref accepts skip-existing.
• Targeted coverage on the new test: 100% with branch coverage, 0 partial; strict-no-cover clean; the full pre-commit suite (ruff, pyright strict, markdownlint, the uv.lock check) passes.

AI Disclaimer

This PR was developed with the assistance of Claude. The changes and the verification above were reviewed.

_{AI Disclaimer}