band-sdk[claude_sdk] 3.0.0 installs mcp 2.x and cannot import ClaudeSDKAdapter

[nir-singher-band]

band-sdk[claude_sdk]==3.0.0 resolves mcp 2.x, and band/integrations/mcp/engine.py imports mcp.server.fastmcp, which mcp 2.x removed. A fresh install of the extra cannot import its own adapter.

Reproduction

uv venv --python 3.12 /tmp/probe
uv pip install --python /tmp/probe "band-sdk[claude_sdk]==3.0.0"
/tmp/probe/bin/python -c "from band.adapters import ClaudeSDKAdapter"

File ".../band/integrations/mcp/engine.py", line 35, in <module>
    from mcp.server.fastmcp import FastMCP
ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where
FastMCP was renamed to MCPServer ... or pin 'mcp<2' to keep running v1 code.

Resolved versions: band-sdk 3.0.0, claude-agent-sdk 0.2.145, mcp 2.1.1.

Cause

Every other mcp consumer in pyproject.toml is capped, with a comment explaining exactly this:

desktop:  "mcp>=1.28.1,<2"
opencode: "mcp>=1.28.1,<2"   # 2.x drops the lowlevel Server decorator registration
letta:    "mcp>=1.28.1,<2"
acp:      "mcp>=1.28.1,<2"

claude_sdk declares only claude-agent-sdk>=0.1.81. claude-agent-sdk allows mcp<3, so the resolver takes 2.1.1 and nothing constrains it back down. The extra does not import mcp directly, but band.adapters.claude_sdk reaches band/integrations/mcp/engine.py on the import path, so the missing cap is still fatal.

Suggested fix

Add "mcp>=1.28.1,<2" to the claude_sdk extra, matching the other four. If the intent is to support mcp 2.x, engine.py needs the MCPServer rename and all five caps can lift together.

Why this keeps recurring

Same class of defect as two already fixed in this line, both of which also only surfaced on a fresh resolve rather than in a warm dev environment:

• agent-client-protocol<0.11 was pinned in our test harness until 3.0.0 declared agent-client-protocol>=0.11.0.
• mcp<2 was needed for desktop/opencode/letta/acp before those caps landed.

An install-only CI job per extra (create venv, install the extra alone, import the adapter it enables) would catch all three without needing a working model provider. Our docs test harness carries a local mcp<2 pin for the claude_sdk group as a workaround; we would rather drop it than document a transitive pin for readers.