Skip to content

Commit ebe8a6b

Browse files
cdeustclaude
andcommitted
fix(ci): import the tool surface late in the host verifier (#597)
The derivation at module scope pulled the MCP SDK through the registries, and the mcp-host-config job installs the three host CLIs with no Python dependencies: "ModuleNotFoundError: No module named 'mcp'" took the job down, and CI Green with it. That job verifies lean profiles only, which never need the bounds. full_tool_bounds() moves to mcp_server/tool_surface.py, where the surface knowledge already lives, and the verifier keeps a thin wrapper importing it inside the function. The wrapper also keeps that script at 292 lines, under the 300-line cap it would otherwise have crossed. A new test imports the script with `mcp` blocked in sys.meta_path and asserts it still imports; I reproduced the failing condition that way before fixing it. ADR-1077 says why the late import is load-bearing. Full suite: 8772 passed, 8 skipped. The verifier passes its six cases. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH
1 parent c710439 commit ebe8a6b

5 files changed

Lines changed: 70 additions & 20 deletions

File tree

‎docs/adr/ADR-1077-the-advertised-tool-count-is-read-from-the-registries.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ A literal that is right for a while, then wrong, and only caught when it drifts
2626

2727
`mcp_server/tool_surface.py` reads the surface from the registry modules themselves: `standalone_tool_names()` is the union of their `SCHEMAS` maps minus the three gated names, and `UPSTREAM_TOOL_NAMES` holds those three. It imports registries only, never the server, so a caller pays no MCP startup for a count.
2828

29-
`scripts/verify_mcp_hosts.py` derives its bounds from that module rather than stating them. The remaining copies are prose for humans, and the doc-claim gate already cross-checks them against the pinned test name.
29+
`scripts/verify_mcp_hosts.py` derives its bounds from that module rather than stating them, through a thin `full_tool_bounds()` that imports it late. The late import is load-bearing: reading the registries pulls the MCP SDK, and the `mcp-host-config` CI job installs the three host CLIs with no Python dependencies and verifies lean profiles only. A module-scope import broke that job, and a test now imports the script with `mcp` blocked to keep it importable without the SDK. The remaining copies are prose for humans, and the doc-claim gate already cross-checks them against the pinned test name.
3030

3131
## Consequences
3232

‎mcp_server/tool_surface.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,16 @@ def standalone_tool_names() -> frozenset[str]:
5353
names.update(registry.SCHEMAS)
5454
names.update(set(tool_registry_ingest.SCHEMAS) - UPSTREAM_TOOL_NAMES)
5555
return frozenset(names)
56+
57+
58+
def full_tool_bounds() -> tuple[int, int]:
59+
"""How many tools a full profile may advertise: without, then with upstreams.
60+
61+
The host-contract verifier used to state these as literals and one went
62+
stale through a whole count move (ADR-1066), failing only three tools
63+
later. It now reads them here, inside a function, because importing this
64+
module pulls the MCP SDK and the `mcp-host-config` CI job installs the
65+
host CLIs without it.
66+
"""
67+
standalone = len(standalone_tool_names())
68+
return standalone, standalone + len(UPSTREAM_TOOL_NAMES)

‎scripts/verify_mcp_hosts.py‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -41,23 +41,23 @@
4141
)
4242

4343
from mcp_server.tool_profiles import LEAN_TOOL_NAMES # noqa: E402
44-
from mcp_server.tool_surface import ( # noqa: E402
45-
UPSTREAM_TOOL_NAMES,
46-
standalone_tool_names,
47-
)
4844

4945

5046
CLIENTS = ("claude-code", "gemini-cli", "codex-cli")
5147
PROFILES: tuple[Literal["full", "lean"], ...] = ("full", "lean")
5248
STORAGE_SELECTIONS: tuple[Literal["sqlite", "auto"], ...] = ("sqlite", "auto")
53-
# The floor is what this tree registers without an upstream, read from the
54-
# registries themselves rather than copied: a literal here went stale when
55-
# the count moved 52 -> 54 (ADR-1066) and only failed the build three tools
56-
# later, when it moved to 57 (issue #597).
49+
50+
5751
# source: ADR-0788
5852
# The correction is recorded as ADR number 1077.
59-
MIN_FULL_TOOL_COUNT = len(standalone_tool_names())
60-
MAX_FULL_TOOL_COUNT = MIN_FULL_TOOL_COUNT + len(UPSTREAM_TOOL_NAMES)
53+
def full_tool_bounds() -> tuple[int, int]:
54+
"""The surface's own bounds, imported late: the mcp-host-config job runs
55+
without the MCP SDK and verifies lean profiles only."""
56+
from mcp_server.tool_surface import ( # noqa: PLC0415 — see docstring
57+
full_tool_bounds as surface_bounds,
58+
)
59+
60+
return surface_bounds()
6161

6262

6363
def _result(
@@ -110,11 +110,13 @@ def _verify_tool_surface(
110110
raise ContractError(
111111
f"{case.label}: lean surface drifted; missing={missing}, extra={extra}"
112112
)
113-
elif not MIN_FULL_TOOL_COUNT <= len(tools) <= MAX_FULL_TOOL_COUNT:
114-
raise ContractError(
115-
f"{case.label}: discovered {len(tools)} full tools; expected "
116-
f"{MIN_FULL_TOOL_COUNT}..{MAX_FULL_TOOL_COUNT}"
117-
)
113+
else:
114+
minimum, maximum = full_tool_bounds()
115+
if not minimum <= len(tools) <= maximum:
116+
raise ContractError(
117+
f"{case.label}: discovered {len(tools)} full tools; expected "
118+
f"{minimum}..{maximum}"
119+
)
118120
if "memory_stats" not in tool_names:
119121
raise ContractError(f"{case.label}: memory_stats was not discovered")
120122
return len(tools)

‎tests_py/test_tool_surface.py‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,12 @@ def test_the_upstream_names_are_exactly_the_gated_ones() -> None:
3434

3535

3636
def test_the_host_contract_bounds_follow_the_surface() -> None:
37-
from scripts.verify_mcp_hosts import MAX_FULL_TOOL_COUNT, MIN_FULL_TOOL_COUNT
37+
from scripts.verify_mcp_hosts import full_tool_bounds
3838

39-
assert MIN_FULL_TOOL_COUNT == len(standalone_tool_names())
40-
assert MAX_FULL_TOOL_COUNT == MIN_FULL_TOOL_COUNT + len(UPSTREAM_TOOL_NAMES)
39+
minimum, maximum = full_tool_bounds()
40+
41+
assert minimum == len(standalone_tool_names())
42+
assert maximum == minimum + len(UPSTREAM_TOOL_NAMES)
4143

4244

4345
def test_the_docker_smoke_floor_follows_the_surface() -> None:
@@ -50,3 +52,36 @@ def test_the_docker_smoke_floor_follows_the_surface() -> None:
5052

5153
assert match, "docker_smoke.sh no longer declares MIN_TOOL_COUNT as expected"
5254
assert int(match.group(1)) == len(standalone_tool_names())
55+
56+
57+
def test_the_verifier_imports_without_the_mcp_sdk() -> None:
58+
"""The mcp-host-config CI job installs the host CLIs, not the SDK.
59+
60+
Importing `mcp_server.tool_surface` at module scope pulled the SDK
61+
through the registries and broke that job (issue #597).
62+
"""
63+
import subprocess
64+
import sys
65+
import textwrap
66+
67+
probe = textwrap.dedent("""
68+
import sys
69+
class Blocker:
70+
def find_module(self, name, path=None):
71+
blocked = name == "mcp" or name.startswith("mcp.")
72+
return self if blocked else None
73+
def load_module(self, name):
74+
raise ImportError(name)
75+
sys.meta_path.insert(0, Blocker())
76+
sys.path.insert(0, ".")
77+
import importlib
78+
importlib.import_module("scripts.verify_mcp_hosts")
79+
print("imported")
80+
""")
81+
82+
result = subprocess.run(
83+
[sys.executable, "-c", probe], capture_output=True, text=True
84+
)
85+
86+
assert result.returncode == 0, result.stderr
87+
assert "imported" in result.stdout

‎wiki/adr/cortex/1077-the-advertised-tool-count-is-read-from-the-registries.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ A literal that is right for a while, then wrong, and only caught when it drifts
2424

2525
`mcp_server/tool_surface.py` reads the surface from the registry modules themselves: `standalone_tool_names()` is the union of their `SCHEMAS` maps minus the three gated names, and `UPSTREAM_TOOL_NAMES` holds those three. It imports registries only, never the server, so a caller pays no MCP startup for a count.
2626

27-
`scripts/verify_mcp_hosts.py` derives its bounds from that module rather than stating them. The remaining copies are prose for humans, and the doc-claim gate already cross-checks them against the pinned test name.
27+
`scripts/verify_mcp_hosts.py` derives its bounds from that module rather than stating them, through a thin `full_tool_bounds()` that imports it late. The late import is load-bearing: reading the registries pulls the MCP SDK, and the `mcp-host-config` CI job installs the three host CLIs with no Python dependencies and verifies lean profiles only. A module-scope import broke that job, and a test now imports the script with `mcp` blocked to keep it importable without the SDK. The remaining copies are prose for humans, and the doc-claim gate already cross-checks them against the pinned test name.
2828

2929
## Consequences
3030

0 commit comments

Comments
 (0)