graphify-mcp fails to start on a default install: unpinned mcp extra resolves to 2.x, which removed mcp.types.AnyUrl #2291

Summary

On a clean uv tool install "graphifyy[mcp]" (v0.9.29), graphify-mcp cannot start:

ImportError: cannot import name 'AnyUrl' from 'mcp.types'
  File ".../graphify/serve.py", line 1116, in _build_server
    from mcp.types import AnyUrl

The mcp extra is declared unpinned in pyproject.toml:

mcp = ["mcp", "starlette>=1.3.1"]

so a fresh resolve picks up mcp==2.0.0, which no longer re-exports AnyUrl from mcp.types
(confirmed: hasattr(mcp.types, "AnyUrl") is False at mcp==2.0.0, pydantic==2.13.4).

Why this is easy to miss

The failure is invisible to every cheap check. After the broken install:

• graphify-mcp is installed and is on PATH
• graphify-mcp --help prints full usage and exits 0
• the CLI (graphify query / path / explain) works perfectly

Only an actual stdio JSON-RPC handshake surfaces it. Three states are otherwise indistinguishable:

no [mcp] extra   ModuleNotFoundError: No module named 'mcp'
mcp 2.x          ImportError: cannot import name 'AnyUrl' from 'mcp.types'
mcp<2            initialize OK -> {'name': 'graphify', 'version': '1.29.0'}, 10 tools

Because --help exits 0, a setup script or CI step that checks for the binary will report the MCP
server as healthy while it is completely non-functional.

Reproduce

uv tool install "graphifyy[mcp]" --force        # resolves mcp==2.0.0
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | graphify-mcp graphify-out/graph.json
# -> ImportError: cannot import name 'AnyUrl' from 'mcp.types'

Workaround

uv tool install "graphifyy[mcp]" --with "mcp<2"

Verified working: handshake completes and ten tools register — query_graph, get_node,
get_neighbors, get_community, god_nodes, graph_stats, shortest_path, list_prs,
get_pr_impact, triage_prs.

Suggested fix

Pin the extra to the supported major, e.g.:

mcp = ["mcp>=1,<2", "starlette>=1.3.1"]

...or import AnyUrl from pydantic directly, which is where it originates and which is already a
transitive dependency — that would make serve.py work across both mcp majors.

A smoke check that performs a real initialize + tools/list handshake (rather than --help) would
also catch this class of breakage in CI, since the symptom is a working binary in front of a dead
server.

Environment

Thanks for graphify — the graph-first workflow measurably cut our agents' context per question and
search-call count, which is exactly why we wanted the persistent server rather than the per-call CLI
cold load.