Fix docs/release follow-ups from the mcp-types package split

- gen_ref_pages.py: derive each module identifier from its own package
  root, so the API reference emits `mcp_types.*` instead of the
  unimportable `mcp-types.mcp_types.*`. Add `src/mcp-types` to the mkdocs
  paths/watch lists and to the deploy-docs trigger filter.
- publish-pypi.yml: build the two distributions into separate directories
  and publish `mcp-types` before `mcp`, so a failed dependency upload can
  never leave `mcp` published with an unsatisfiable exact pin.
  `skip-existing` only on the mcp-types step, so a re-run recovers from a
  partial publish without muting a duplicate `mcp` upload.
- mcp-types: ship a real LICENSE file instead of the sdist-only
  force-include, so the wheel carries License-File in every build mode.
- tests: add a static check that every `mcp_types` module imports only the
  standard library and the dependencies `src/mcp-types/pyproject.toml`
  declares; move test_version.py to mirror its source module.
- docs: the migration guide taught `from mcp import CallToolResult`, which
  raises ImportError (`CallToolResult` is not in `mcp.__all__`) -- use
  `Resource`. Name `mcp_types.version` as the home of the protocol-version
  constants, link the new API reference, correct the "depends only on
  pydantic" wording, and point schema/README.md at the new codegen path.
- AGENTS.md / RELEASE.md: document that the root project's runtime
  dependencies are dynamic and live in the uv-dynamic-versioning hook
  table, and that a release now publishes both distributions.

Author: maxisbey

.github/workflows/deploy-docs.yml

@@ -9,6 +9,7 @@ on:
       - docs/**
       - mkdocs.yml
       - src/mcp/**
+      - src/mcp-types/**
       - scripts/build-docs.sh
       - pyproject.toml
       - uv.lock

.github/workflows/publish-pypi.yml

@@ -28,8 +28,8 @@ jobs:
 
       - name: Build
         run: |
-          uv build --package mcp
-          uv build --package mcp-types
+          uv build --package mcp-types -o dist/types
+          uv build --package mcp -o dist/mcp
 
       - name: Upload artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -56,5 +56,18 @@ jobs:
           name: release-dists
           path: dist/
 
-      - name: Publish package distributions to PyPI
+      # The `mcp` wheel exact-pins `mcp-types`, so the dependency must publish
+      # first: if its upload fails, nothing `mcp`-named has been uploaded yet and
+      # `pip install mcp` keeps resolving to the previous release. `skip-existing`
+      # lets a re-run after a failed `mcp` upload get past the already-published
+      # `mcp-types`; the `mcp` step omits it so a duplicate upload still fails loudly.
+      - name: Publish mcp-types to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          packages-dir: dist/types
+          skip-existing: true
+
+      - name: Publish mcp to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          packages-dir: dist/mcp

AGENTS.md

@@ -18,7 +18,12 @@
 ## Package Management
 
 - ONLY use uv, NEVER pip
-- Installation: `uv add <package>`
+- Installation: `uv add <package>`. Exception: the root project's runtime
+  dependencies are dynamic (the published `mcp` wheel exact-pins `mcp-types`),
+  so `uv add` cannot edit them — add the requirement to
+  `[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies` in
+  `pyproject.toml` by hand, then run `uv lock`. Dependency groups, extras, and
+  the example packages still take plain `uv add`.
 - Running tools: `uv run --frozen <tool>`. Always pass `--frozen` so uv doesn't
   rewrite `uv.lock` as a side effect.
 - Cross-version testing: `uv run --frozen --python 3.10 pytest ...` to run

RELEASE.md

@@ -2,7 +2,9 @@
 
 ## Bumping Dependencies
 
-1. Change dependency version in `pyproject.toml`
+1. Change the dependency version in `pyproject.toml`. The root `mcp` project's
+   runtime dependencies are dynamic and live under
+   `[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`.
 2. Upgrade lock with `uv lock --resolution lowest-direct`
 
 ## Major or Minor Release
@@ -21,6 +23,14 @@ The package version will be set automatically from the tag.
 v2 pre-releases are cut from `main` with a PEP 440 pre-release tag: `v2.0.0aN`
 for alphas, later `bN`/`rcN` for betas and release candidates.
 
+A release publishes two distributions, `mcp` and `mcp-types`, at the same
+version, and the `mcp` wheel exact-pins `mcp-types`. Before the first release
+that includes both, the `mcp-types` PyPI project must be given the same
+trusted publisher as `mcp` (this repository, workflow `publish-pypi.yml`,
+environment `release`) and the same owners — without it the `mcp-types`
+upload is rejected. The publish workflow uploads `mcp-types` first so that a
+failed upload stops the job before anything `mcp`-named has been published.
+
 1. Check the full test matrix is green on the release commit. The matrix runs
    with `continue-on-error`, so a green workflow run does not mean the tests
    passed — check the individual jobs.

docs/hooks/gen_ref_pages.py

@@ -9,27 +9,32 @@
 root = Path(__file__).parent.parent.parent
 src = root / "src"
 
-for path in sorted(src.rglob("*.py")):
-    module_path = path.relative_to(src).with_suffix("")
-    doc_path = path.relative_to(src).with_suffix(".md")
-    full_doc_path = Path("api", doc_path)
-
-    parts = tuple(module_path.parts)
-
-    if parts[-1] == "__init__":
-        parts = parts[:-1]
-        doc_path = doc_path.with_name("index.md")
-        full_doc_path = full_doc_path.with_name("index.md")
-    elif parts[-1].startswith("_"):
-        continue
-
-    nav[parts] = doc_path.as_posix()
-
-    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        ident = ".".join(parts)
-        fd.write(f"::: {ident}")
-
-    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+# `src/mcp-types` is a distribution directory, not an import package, so each
+# package's dotted module path is taken relative to its own parent: deriving it
+# from `src/` would emit the unimportable `mcp-types.mcp_types.*`.
+for package in (src / "mcp", src / "mcp-types" / "mcp_types"):
+    base = package.parent
+    for path in sorted(package.rglob("*.py")):
+        module_path = path.relative_to(base).with_suffix("")
+        doc_path = path.relative_to(base).with_suffix(".md")
+        full_doc_path = Path("api", doc_path)
+
+        parts = tuple(module_path.parts)
+
+        if parts[-1] == "__init__":
+            parts = parts[:-1]
+            doc_path = doc_path.with_name("index.md")
+            full_doc_path = full_doc_path.with_name("index.md")
+        elif parts[-1].startswith("_"):
+            continue
+
+        nav[parts] = doc_path.as_posix()
+
+        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+            ident = ".".join(parts)
+            fd.write(f"::: {ident}")
+
+        mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
 
 with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file:
     nav_file.writelines(nav.build_literate_nav())

docs/migration.md

@@ -212,10 +212,11 @@ The WebSocket transport has been removed: `mcp.client.websocket.websocket_client
 ### `mcp.types` moved to the `mcp-types` package
 
 The protocol wire types now live in a standalone distribution, `mcp-types`, imported as
-`mcp_types`. It depends only on `pydantic`, so code that just needs to (de)serialize MCP
-traffic can install it without the full SDK. The `mcp` package depends on `mcp-types` and
+`mcp_types`. Its only runtime dependencies are `pydantic` and `typing-extensions`, so code
+that just needs to (de)serialize MCP traffic can install it without the full SDK. The `mcp` package depends on `mcp-types` and
 continues to re-export the type names at the top level, so `from mcp import Tool` is
-unchanged. Only the `mcp.types` submodule and `mcp.shared.version` were removed.
+unchanged. Only the `mcp.types` submodule and `mcp.shared.version` were removed. The
+package's API reference is at [`mcp_types`](api/mcp_types/index.md).
 
 **Why:** keeping the wire types in their own package lets tooling and lightweight clients
 depend on the protocol schema without pulling in `httpx`, `starlette`, `uvicorn`, and the
@@ -224,18 +225,18 @@ rest of the server/transport stack.
 **Before (v1):**
 
 ```python
-from mcp.types import Tool, CallToolResult
+from mcp.types import Tool, Resource
 from mcp.shared.version import LATEST_PROTOCOL_VERSION
 ```
 
 **After (v2):**
 
 ```python
-from mcp_types import Tool, CallToolResult
+from mcp_types import Tool, Resource
 from mcp_types.version import LATEST_PROTOCOL_VERSION
 
-# Top-level re-exports are unchanged:
-from mcp import Tool, CallToolResult
+# Names `mcp` already re-exported at the top level are unchanged:
+from mcp import Tool, Resource
 ```
 
 ### Removed type aliases and classes
@@ -813,7 +814,7 @@ async def my_tool(ctx: Context[MyLifespanState]) -> str: ...
 
 ### Version constants
 
-`SUPPORTED_PROTOCOL_VERSIONS` is deprecated — it's now the union of `HANDSHAKE_PROTOCOL_VERSIONS` (initialize-handshake versions) and `MODERN_PROTOCOL_VERSIONS` (per-request-envelope versions). If you were using it to mean "versions the initialize handshake accepts", switch to `HANDSHAKE_PROTOCOL_VERSIONS`. Named scalars derived from these tuples are now exported alongside them — `LATEST_HANDSHAKE_VERSION`, `LATEST_MODERN_VERSION`, `OLDEST_SUPPORTED_VERSION` — so prefer those over indexing the tuples directly.
+`SUPPORTED_PROTOCOL_VERSIONS` is deprecated — it's now the union of `HANDSHAKE_PROTOCOL_VERSIONS` (initialize-handshake versions) and `MODERN_PROTOCOL_VERSIONS` (per-request-envelope versions). If you were using it to mean "versions the initialize handshake accepts", switch to `HANDSHAKE_PROTOCOL_VERSIONS`. Named scalars derived from these tuples are now exported alongside them — `LATEST_HANDSHAKE_VERSION`, `LATEST_MODERN_VERSION`, `OLDEST_SUPPORTED_VERSION` — so prefer those over indexing the tuples directly. All of these live in `mcp_types.version` (previously `mcp.shared.version`): `from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS`.
 
 ### `ProgressContext` and `progress()` context manager removed
 

mkdocs.yml

@@ -103,6 +103,7 @@ markdown_extensions:
 
 watch:
   - src/mcp
+  - src/mcp-types
 
 plugins:
   - search
@@ -117,7 +118,7 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
-          paths: [src]
+          paths: [src, src/mcp-types]
           options:
             relative_crossrefs: true
             members_order: source

schema/README.md

@@ -3,7 +3,8 @@
 JSON Schema files for each protocol version the SDK has a wire-shape surface
 package for, vendored from the [spec repository] at the commit recorded in
 `PINNED.json`. `scripts/gen_surface_types.py` reads these to regenerate
-`src/mcp/types/v<version>/__init__.py`; CI runs the generator with `--check`.
+`src/mcp-types/mcp_types/v<version>/__init__.py`; CI runs the generator with
+`--check`.
 
 To bump: drop the new `schema.json` here as `<protocol-version>.json`, update
 the matching entry in `PINNED.json` (commit + sha256), and run

src/mcp-types/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anthropic, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/mcp-types/pyproject.toml

@@ -47,8 +47,5 @@ vcs = "git"
 style = "pep440"
 bump = true
 
-[tool.hatch.build.targets.sdist.force-include]
-"../../LICENSE" = "LICENSE"
-
 [tool.hatch.build.targets.wheel]
 packages = ["mcp_types"]