GeezerVison

Adds a deprecated mcp.server.fastmcp import path so the single most common line in v1 code, from mcp.server.fastmcp import FastMCP, resolves again on v2 (with an MCPDeprecationWarning) instead of raising ModuleNotFoundError, and makes MCPServer's constructor keyword-only after name.

Motivation and Context

from mcp.server.fastmcp import FastMCP is the first line of nearly every v1 server, and of most tutorial and LLM-generated code, so it's row 1 of the migration guide's "changes almost every project hits" table. For decorator-built servers the rename is genuinely most of the port: the README-shaped v1 quickstart (FastMCP("Demo") + @mcp.tool() / @mcp.resource() / @mcp.prompt() + mcp.run()) runs unmodified on v2 given only the class alias. This is the one v1 name where the alias alone rescues real programs, which is the line for shimming it — mcp.types and McpError stay hard breaks because an alias there saves nobody.

Scope is deliberately narrow:

• Package init only. FastMCP, Context, Image, Audio, Icon (v1's exact __all__) resolve to the v2 objects; mcp.server.fastmcp.server, .prompts.base, etc. still raise ModuleNotFoundError, since nothing beneath them is behaviour-equivalent.
• The warning is honest. It says this is not just a rename (default server name, transport params off the constructor, sync handlers on a worker thread) and links the guide. MCPDeprecationWarning subclasses UserWarning, so it shows without -W. Removed in v3.
• from mcp.server import FastMCP is not restored (v1 exported it there too): that needs a module-level __getattr__ on mcp.server, which loosens static checking of every from mcp.server import ... for all downstream users.
• No API-reference page — the doc generator skips deprecated shim modules.

The keyword-only constructor closes the one hazard the shim would otherwise make silent. v2 inserted title/description ahead of instructions, so a v1 FastMCP("Demo", "You answer questions about the weather.") used to run without complaint and land the instructions in title; with the import erroring, users at least met the guide first. Now that the import warns and continues, that call raises TypeError instead — for shim users and mechanical-rename users alike, matching what the lowlevel Server already does. The migration guide's constructor section is rewritten from "silently misassigns" to "raises".

How Has This Been Tested?

• New tests/server/test_fastmcp.py: the import warns with the replacement named, and the five re-exports are the v2 objects (FastMCP is MCPServer, v1 __all__ preserved). Full suite: ./scripts/test at 100% coverage, strict-no-cover clean; pyright 0 errors.
• Ran an unmodified v1 README-shaped server end-to-end through the old import against an in-process Client: tool call, resource template, and prompt all round-trip; the warning is attributed to the user's own import line (stacklevel correct) and fires once per process.
• Probed the edges: from mcp.server.fastmcp.prompts import base → ModuleNotFoundError; positional FastMCP('Demo', 'instructions') → the TypeError quoted in the guide; python -W error::UserWarning -c 'import mcp.server.fastmcp' → raises the warning cleanly by category; from mcp.server import FastMCP → still ImportError.
• Regenerated docs/api/ before and after: no fastmcp page either way.

Breaking Changes

• MCPServer(...) no longer accepts title, description, instructions, website_url, icons, version, auth_server_provider, or token_verifier positionally — pass them by keyword (the migration guide already recommended this; the signature now enforces it). Documented in docs/migration.md.
• The new import path is additive (previously it did not exist), gated behind a deprecation warning.

Types of changes

• 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

_{AI Disclaimer}