fix(mcp): report the real import failure, not a missing extra

[CameronBrooks11]

netspec-mcp caught ImportError and printed netspec-mcp needs the mcp extra: pip install 'kicad-netspec[mcp]' whatever the cause. ModuleNotFoundError is a subclass of ImportError, so under mcp 2.x the message was wrong in the one way that matters: the extra is installed, and the user was told to install it.

This is piece 1 of the two in #35. Piece 2 — the FastMCP → MCPServer migration, and whether the rest of the API netspec uses moved with it — is untouched here, and so is the mcp>=1.27,<2 pin. #33 widens that pin to <3; this change does not depend on that decision and does not pre-empt it. It does change what #33 would look like if merged: instead of an entry point that blames a missing extra, a user on 2.x gets upstream's migration message, so the pin question is visible rather than disguised.

The three cases

Measured in three fresh venvs, kicad-netspec installed from this branch.

mcp 2.1.1 installed. Before:

$ netspec-mcp
netspec-mcp needs the mcp extra: pip install 'kicad-netspec[mcp]'
$ echo $?
4

After:

$ netspec-mcp
netspec-mcp could not import the MCP server API. The mcp package itself is installed, so the extra is not absent; netspec does not know more than that. The import said:

    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.
$ echo $?
4

mcp absent — unchanged, before and after:

$ netspec-mcp
netspec-mcp needs the mcp extra: pip install 'kicad-netspec[mcp]'
$ echo $?
4

Incomplete install — mcp 1.30.0 with pydantic-settings uninstalled. After:

$ netspec-mcp
netspec-mcp could not import the MCP server API. The mcp package itself is installed, so the extra is not absent; netspec does not know more than that. The import said:

    ModuleNotFoundError: No module named 'pydantic_settings'
$ echo $?
4

The message says only what the lookup established. An earlier revision of this branch said "this is not a missing dependency: the mcp package is installed", which denied a missing dependency in the same breath as printing one — a categorical claim about the whole dependency tree from resolving one name in it. It was also the wrong steer: pip install 'kicad-netspec[mcp]' re-resolves the missing transitive dependency and repairs that install (measured), so the denial argued against the one thing that works.

The change

_diagnose_import_failure(exc, *, mcp_installed) decides between the two messages. main() supplies the observation as importlib.util.find_spec("mcp") is not None.

find_spec is a design preference, not a necessity: the exception's own name attribute would also separate the reachable cases, and both discriminators agree on all three. Measured:

case	exc.name	find_spec("mcp") is None
mcp 2.1.1 installed	'mcp.server.fastmcp'	False
mcp absent	'mcp'	True
mcp 1.30.0, pydantic-settings removed	'pydantic_settings'	False

find_spec is preferred because "is the package there" is the question being asked, and asking it directly does not depend on an error attribute keeping its shape across upstream versions. It is a better way to learn the same thing, not the only way.

Exit stays 4 in every case. Exit 4 was already the right outcome — netspec could not run, which says nothing about a design (D10). The reason was the fabricated part.

Tests

tests/test_mcp_import_failure.py, deliberately not gated on the mcp extra — three of its four tests construct their own exceptions and need no mcp, and a module-level gate would take them with it on a contributor machine without the extra:

• an absent package still says to install the extra
• a moved symbol does not mention the extra, and carries upstream's text through verbatim
• an incomplete install is not told that nothing is missing
• through main(), against the real find_spec: exit 4, upstream's text on stderr, no kicad-netspec[mcp] in it — the one test that reads the environment, and the only one that skips without the extra

tests/test_mcp.py is unchanged; its gate is still right for the MCP surface it covers, and still fails loudly in CI.

No decision in docs/DECISIONS.md moves. D7's pin, D10's exit 4, and D18's tool surface are all as they were.

Closes #35.

[github-actions]

Connectivity unchanged

tests/fixtures/good_ldo.kicad_sch

_{design sha256:36f119b0091afd2449fcd8cc92856510f5eda0d95156ad096fc1272a39cff90e}

Connectivity unchanged.

tests/fixtures/polcap_rail_correct.kicad_sch

_{design sha256:60a7ddcc8a14c5b7c1269e499974c219ce6e3e3b53f22c734099aeb749c4b4b1}

Connectivity unchanged.

_{Reported by netspec — KiCad's own netlist, not a guess.}