grapharc[mcp] shipped broken: an unbounded pin, and a package that could not be imported without it

Two defects, one found by the other.

`grapharc/mcp/server.py` builds on `mcp.server.fastmcp`, which exists in the
mcp 1.x line and was removed in 2.0 — and the extra said `mcp>=1.2`. So every
fresh `pip install 'grapharc[mcp]'` resolved to 2.0.0 and could not import the
server at all, while `uv.lock` held development on 1.28 and kept every local
test green. The ceiling is explicit now: raising it means porting off FastMCP,
which should be a diff someone writes rather than a resolver accident.

CI reported that as "in the source tree but not in the wheel:
['grapharc.mcp.driver', 'grapharc.mcp.server']", which was not true — both were
in the wheel. `pkgutil.walk_packages` imports a package to walk into it, and
`grapharc/mcp/__init__.py` eagerly imported the SDK-backed module, so any
environment without a working extra made the whole subpackage unwalkable and it
read as missing. `grapharc/slack/__init__.py` already documents the right
posture; `driver.py` needs no SDK. The three SDK-backed names resolve on first
access now, so `import grapharc.mcp` works without the extra and
`from grapharc.mcp import build_server` still works with it.

130 modules import from a clean `[all]` wheel.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Shashankss1205

grapharc/mcp/__init__.py

@@ -7,9 +7,35 @@
 
 `grapharc mcp` is the entry point; `build_server` is the library surface a
 test drives directly.
+
+**The extra is imported lazily**, the same posture `grapharc.slack` takes: only
+`server.py` needs the MCP SDK, `driver.py` needs nothing beyond grapharc's core
+dependencies, and importing this package must not require either. Eagerly
+importing `server` here made `grapharc.mcp` unimportable in any environment
+without the extra — which is every environment the packaging check builds, so a
+whole subpackage read as missing from the wheel it was actually in.
+
+`build_server` and `serve_stdio` therefore resolve on first attribute access
+(PEP 562), and `from grapharc.mcp import build_server` still works.
 """
 
+from typing import Any
+
 from grapharc.mcp.driver import DriverError
-from grapharc.mcp.server import FORBIDDEN_TOOL_WORDS, build_server, serve_stdio
 
 __all__ = ["FORBIDDEN_TOOL_WORDS", "DriverError", "build_server", "serve_stdio"]
+
+_DEFERRED = frozenset({"FORBIDDEN_TOOL_WORDS", "build_server", "serve_stdio"})
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve the SDK-backed names on first use, not at import."""
+    if name in _DEFERRED:
+        from grapharc.mcp import server
+
+        return getattr(server, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

pyproject.toml

@@ -81,9 +81,14 @@ server = [
     "fastapi>=0.115",
     "uvicorn>=0.32",
 ]
-# MCP client (ROADMAP 3.5).
+# MCP client (ROADMAP 3.5). Upper-bounded on purpose: `grapharc/mcp/server.py`
+# builds on `mcp.server.fastmcp`, which exists in the 1.x line and was removed
+# in 2.0. `>=1.2` alone resolved to 2.0.0 for anyone installing fresh, so
+# `grapharc mcp` was broken on arrival while the lockfile kept development on
+# 1.28 and every local test green. Raising this ceiling means porting the
+# server off FastMCP, which is a change with a diff, not a resolver accident.
 mcp = [
-    "mcp>=1.2",
+    "mcp>=1.2,<2",
 ]
 # LadybugDB-backed claim store — grapharc/memory/ladybug_store.py imports this
 # one, unlike the `memory` extra above. The distribution is `real-ladybug`, not