All 7 built-in MCP servers fail to import on mcp>=2.0 (FastMCP renamed); `mcp>=1.27.0` is unbounded

[sknob3l]

Description

get-physics-done declares mcp>=1.27.0 with no upper bound. mcp 2.0 renamed FastMCP to MCPServer and moved the module, so on any fresh install today pip resolves mcp 2.1.1 and all seven built-in MCP servers fail to import:

from mcp.server.fastmcp import FastMCP   # gpd/mcp/servers/*.py
ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Affected modules (every server GPD ships):

• gpd/mcp/servers/verification_server.py
• gpd/mcp/servers/state_server.py
• gpd/mcp/servers/conventions_server.py
• gpd/mcp/servers/patterns_server.py
• gpd/mcp/servers/protocols_server.py
• gpd/mcp/servers/errors_mcp.py
• gpd/mcp/servers/skills_server.py

The console entry points (gpd-mcp-verification, etc.) fail the same way.

The failure is silent at install time. npx -y get-physics-done --claude --local reports success (✓ 24 agents, 71 commands) and writes a .mcp.json listing all seven servers. Nothing in the installer or in gpd doctor surfaces that none of them can start. The first sign is the runtime failing to connect them.

First mcp 2.x release on PyPI was 2026-06-11, so this affects new installs from around that date onward. Existing installs with a pre-2.0 mcp already in the venv are unaffected until something upgrades it.

gpd --version and the rest of the local CLI still work — this is scoped to the MCP layer.

Steps to Reproduce

Clean-room, no prior GPD install:

python3.14 -m venv cleanroom
./cleanroom/bin/pip install "get-physics-done==1.2.2"
./cleanroom/bin/pip list | grep -iE "^(mcp|get-physics-done) "
#   get-physics-done  1.2.2
#   mcp               2.1.1

for s in verification_server state_server conventions_server patterns_server \
         protocols_server errors_mcp skills_server; do
  ./cleanroom/bin/python -c "import gpd.mcp.servers.$s" 2>&1 | tail -1
done
# 7/7 -> ModuleNotFoundError: No module named 'mcp.server.fastmcp'

./cleanroom/bin/gpd-mcp-verification
# same ModuleNotFoundError

Confirming the cause is the unbounded pin — in the same venv:

./cleanroom/bin/pip install "mcp<2"     # resolves 1.29.1
for s in verification_server state_server conventions_server patterns_server \
         protocols_server errors_mcp skills_server; do
  ./cleanroom/bin/python -c "import gpd.mcp.servers.$s" 2>&1 | tail -1
done
# 7/7 import cleanly, no output

Expected Behavior

A fresh npx -y get-physics-done install produces MCP servers that import and start, or the installer fails loudly / warns when the resolved mcp is incompatible.

Two fixes, not mutually exclusive:

1. Bound the dependency — mcp>=1.27.0,<2 in pyproject.toml. Verified above to restore all seven servers with no other change.
2. Migrate to the 2.x API — from mcp.server.mcpserver import MCPServer, per the migration guide. Note gpd/mcp/servers/__init__.py:tighten_registered_tool_contracts also reaches into mcp._tool_manager and mcp.list_tools, which will need attention in a 2.x port.

Separately, it may be worth having gpd doctor import-check the servers it registers, so a broken MCP layer is reported at install time rather than discovered at runtime.

Runtime

Claude Code

GPD Version

1.2.2 (installed via npx -y get-physics-done --claude --local)

Operating System

macOS 15 (Darwin 25.6.0, Apple Silicon), Python 3.14.2 (Homebrew), Node v22.22.0

Relevant Logs

$ ./cleanroom/bin/gpd-mcp-verification
Traceback (most recent call last):
  ...
  File ".../gpd/mcp/servers/verification_server.py", line 19, in <module>
    from mcp.server.fastmcp import FastMCP
  File ".../mcp/server/fastmcp.py", line 16, in <module>
    raise ModuleNotFoundError(_MESSAGE, name=__name__)
ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where
FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and
other APIs changed; see the migration guide at
https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver
or pin 'mcp<2' to keep running v1 code.

Metadata from the installed distribution:

$ grep -i "requires-dist: mcp" get_physics_done-1.2.2.dist-info/METADATA
Requires-Dist: mcp>=1.27.0