Add mcp.types as a permanent alias for mcp_types

Merged
MA
4mo ago
+467-364

Restores import mcp.types as a permanent alias that mirrors the mcp_types package.

Motivation and Context

import mcp.types as types is the most common v1 idiom (it's in the v1 README and nearly every example), and in v2 it fails with ModuleNotFoundError: No module named 'mcp.types' — which reads as a broken install rather than a migration step. #2973 removed the module without a shim.

This adds src/mcp/types.py, which star-re-exports mcp_types, so every name is the same object and all four v1 idioms work again: import mcp.types as types, from mcp.types import X, from mcp import types, and import mcp followed by mcp.types.Tool (the package init binds the submodule, as v1's did). It ships as a permanent alias, not a deprecation shim — no warning, no v3 removal — and mcp.types is a package with a version submodule mirroring mcp_types.version the same way, so from mcp.types.version import LATEST_MODERN_VERSION works too:

  • A deprecation is a permanent commitment (a future removal) spent on a transient goal (the migration wave); the second break would cost every user again for no functional gain, since a star re-export can't drift.
  • The v1 spelling is baked into years of tutorials and generated code; making it work permanently absorbs that instead of fighting it forever.
  • It's a genuinely nice types-only namespace (types.TextContent(...), one import). And the two spellings map to a real packaging rule, not a preference: every distribution whose modules you import should be a declared dependency, and mcp exact-pins mcp-types so declaring it independently is pointless-to-harmful. So: depend on mcp → import mcp.types (one declared dependency, one import root); depend only on mcp-types → import mcp_types.

The examples and docs now follow that rule. The third commit sweeps every example, snippet, and docs tutorial (~145 files, a mechanical mcp_types → mcp.types substitution best reviewed as its own commit) so SDK-user code no longer models the transitive-import leak; the hl_lines highlights that the import reordering shifted were remapped, and the migration guide, What's New, and installation docs restate the rule.

Of v1's 212 top-level names, 173 resolve unchanged. The 22 genuinely removed ones (Content, ResourceReference, Cursor, the *Type unions, the TASK_* constants, …) raise an AttributeError from module __getattr__ that names the replacement on attribute access. AttributeError (per PEP 562) rather than a smuggled ImportError so hasattr() and getattr(x, name, default) still take their fallback path — probing code in v1/v2-straddling libraries doesn't crash. The tradeoff is that from mcp.types import <removed> falls back to CPython's generic "cannot import name", which is still fail-fast. The remaining 17 "gone" names were stdlib/pydantic imports (Any, BaseModel, datetime, …) that leaked out of v1's import block and were never API.

Import cost is a wash and the alias itself is free. Cold-import benchmarks (median of 15 subprocesses): v1 mcp.types ≈ 374ms vs v2 mcp_types ≈ 391ms marginal over pydantic — both dominated by building ~150 pydantic models. The alias body adds ~250µs, and nothing at all unless imported. No regression versus v1 either: v1's mcp/__init__ imported the whole client/server stack, so v1's import mcp.types always paid for the full package — exactly as it does now — while mcp_types is the strictly cheaper path v2 makes newly possible.

The module is excluded from the generated API reference; the migration guide and What's New pages are updated to match.

How Has This Been Tested?

New tests in tests/test_types.py prove the full mirror by identity across every exported name, the replacement-naming AttributeError, the preserved hasattr/getattr(default) contract for removed names, plain AttributeError for unknown names, and that from mcp.types import <removed> still raises. Also driven end-to-end from a fresh process at the package boundary: all four import idioms (silent, all 211 names identical objects), removed-name access, hasattr/getattr(default) fallbacks, and from mcp.types import *. Full suite: 100% coverage, strict-no-cover clean.

Breaking Changes

None — this softens an existing v2 break. Documented in docs/migration.md.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

Two suppressions, both stating intent rather than hiding an error: a per-file-ignores entry for the wildcard import (F403) and a file-level # pyright: reportWildcardImportFromLibrary=false, since mirroring the whole mcp_types namespace is the point of the file and mcp-types is a separate distribution.

Open question for reviewers: mcp.shared.version was removed in the same PR (#2973) and could get an identical sibling alias → mcp_types.version. Left out to keep this focused; happy to add.

AI Disclaimer