[BUG] skillspector[mcp] resolves to mcp 2.x, which removed mcp.server.fastmcp — server fails to start with a misleading "requires the optional 'mcp' dependency" error

[tohir-dev]

Summary

The mcp extra declares mcp>=1.2.0 with no upper bound. The mcp SDK published 2.0.0 on 2026-07-28, and it no longer provides mcp.server.fastmcp. Any fresh skillspector[mcp] install now resolves to mcp 2.x, so skillspector mcp fails the moment a client initializes — and the error it raises points at the wrong cause.

Reproduction

uv tool install --force -p 3.12 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
# resolves mcp==2.0.0 — install reports success

The install succeeds and skillspector mcp --help renders normally, so nothing looks wrong yet. Driving an MCP initialize over stdio returns:

Error: The MCP server requires the optional 'mcp' dependency. Install it with:
pip install 'skillspector'

mcp is in fact installed. In the same environment:

importlib.util.find_spec("mcp")                 # -> OK
importlib.util.find_spec("mcp.server.fastmcp")  # -> None

Root cause

pyproject.toml:

[project.optional-dependencies]
mcp = [
    "mcp>=1.2.0",
]

src/skillspector/mcp_server.py (L40 under TYPE_CHECKING, L143-149 at runtime):

try:
    from mcp.server.fastmcp import FastMCP
except ModuleNotFoundError as exc:
    raise ModuleNotFoundError(
        "The MCP server requires the optional 'mcp' dependency. "
        "Install it with: pip install 'skillspector[mcp]'"
    ) from exc

The except ModuleNotFoundError branch cannot distinguish "the extra was never installed" from "the extra is installed but the submodule moved". Under mcp 2.x it hits the second case and reports the first, so the message instructs the user to install a package that is already present at the requested version.

Impact

• Every new skillspector[mcp] install since 2026-07-28 gets a non-functional MCP server.
• The failure is quiet at install time. The README's claude mcp add skillspector -- skillspector mcp registers without complaint; the server only dies when an agent first initializes it, which makes it easy to mis-diagnose as a client or transport problem rather than a dependency resolution one.
• The misleading message sends users toward reinstalling the extra, which re-resolves to mcp 2.x and reproduces the same failure.

Environment

• skillspector 2.5.1 (a818f50f541ab2bbb4751e3c2490778f7a1b7c2b)
• Python 3.12.13, uv 0.11.8, macOS (arm64)
• Broken with mcp 2.0.0; works with mcp 1.29.0

Workaround

Constraining the SDK to 1.x resolves it — initialize then succeeds and scan_skill is exposed as expected:

uv tool install --force -p 3.12 --with 'mcp<2' 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

Suggested fix

1. Bound the extra to the supported major version, e.g. mcp>=1.2.0,<2, until the 2.x FastMCP entry point is supported.
2. Optionally, make the except branch distinguish the two failure modes — e.g. check whether mcp itself imports before claiming the extra is missing — so an incompatible-version failure reports itself as one.