Skip to content

Commit 1f3c7ff

Browse files
cdeustclaude
andauthored
fix: expose 13 handler-declared params dropped by hand-written MCP wrappers (#559) (#567)
* fix: expose 13 handler-declared params dropped by hand-written MCP wrappers (#559) FastMCP derives each tool's client-visible inputSchema from the registered wrapper function's own signature (tool_registry_*.py), not from the handler's schema["inputSchema"] dict. 13 of 54 tools had drifted: the handler declared a parameter (used in its own body) that the wrapper never forwarded, making it silently unreachable over MCP, including recall(tags_any=["archival"]) (host protocol) and remember(is_global=True) (cortex-remember-global skill). Root cause fix, not a patch. Widened tests_py/handlers/test_tool_schema_parity.py from a remember/wiki_write-only guard with omission lists to a universal check over every registered tool (mcp.list_tools()), asserting handler inputSchema properties equal wrapper params in both directions, with no per-tool omission list (the only structural exception is the documented rooted-agent_topic variant). Closed every gap by exposing the parameter on the wrapper with the handler schema's own type/default and forwarding it. Verified each one is actually read in the handler body before adding it, so none is a no-op forward. wiki_write's title/summary/body are the one exception: declared on the handler's own inputSchema but never consumed by wiki_write.handler() (grepped, confirmed dead). Exposed anyway since the parity contract is wrapper-vs-handler-schema, not handler completeness; documented at the wrapper as pre-existing, out-of-blast-radius debt. tool_registry_memory.py exceeded the 300-line file cap, and one wrapper briefly exceeded the 40-line method cap once its signature carried every property recall.py declares. Split the maintenance/diagnostics tools (no external caller, verified by grep) into tool_registry_memory_maintenance.py, and factored a shared _do_recall delegate so neither the rooted nor unrooted wrapper's own body exceeds the cap. Regenerated .craftsmanship-baseline.json to prune the now-fixed file-size entry; no new entries added. Added tests_py/handlers/test_recall_remember_wrapper_reachability.py. It calls the REGISTERED recall/remember tools via mcp.call_tool (not the handler directly) and proves tags_any/is_global reach the handler's args dict. Confirmed fail-before/pass-after for both new test files against a3b3a79. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * fix: remove dead title/summary/body from wiki_write's own contract (#559 follow-up) Review caught that exposing a wrapper parameter the handler silently drops is the same contract lie as #559 in the other direction. Grepped the whole repo (tests, skills/cortex-wiki-author, docs/mcp-tools.md, docs/api-reference.md, curate_wiki_serialize.py's authoring prompt, scripts/, hooks/): nothing anywhere passes title/summary/body to wiki_write; every real caller already uses content. The handler schema was the one lying, not the wrapper. Removed title/summary/body from wiki_write's inputSchema and from the tool_registry_wiki.py wrapper. Corrected content's description, which falsely claimed it was "used when structured fields (title/summary/body) are not provided" -- content is unconditionally required and wiki_write.handler() never reads those three keys. The universal parity test now holds for wiki_write with no exception. Re-audited every other parameter exposed in the original #559 commit, grep-confirmed each is read in its handler body (see PR body table with file:line citations) -- none is a repeat of this defect. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * test(parity): an unmapped registered tool fails instead of being skipped (#559) A registered tool with no handler schema entry has no contract its client-visible parameters can be checked against; skipping it silently would reopen the exact gap #559 closes. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * test(parity): check every tool on a server with all upstream gates open (#559) CI has no ai-architect codebase server, so ingest_codebase and change_impact were not registered there and the hardcoded gated set ({ingest_prd}) failed. Building the server under test with register_all(codebase=True, prd=True), as tests_py/test_main.py does, makes the check identical on every machine and covers the gated tools' parity too, with no exception list. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent e382a6e commit 1f3c7ff

12 files changed

Lines changed: 523 additions & 308 deletions

‎.craftsmanship-baseline.json‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
2-
"$comment": "Generated by `python scripts/check_craftsmanship.py --write-baseline`. Do NOT add an entry by hand to silence a new violation \u2014 that is gaming the ratchet, not maintaining it (CLAUDE.md \u00a7 Code Style). Regenerate only after confirming every new entry is pre-existing debt, not something this PR just introduced. Every entry removed here must correspond to a violation actually fixed in the code.",
3-
"generated": "2026-08-10",
2+
"$comment": "Generated by `python scripts/check_craftsmanship.py --write-baseline`. Do NOT add an entry by hand to silence a new violation \u2014 that is gaming the ratchet, not maintaining it (docs/agent-guidance.md \u00a7 Code Style). Regenerate only after confirming every new entry is pre-existing debt, not something this PR just introduced. Every entry removed here must correspond to a violation actually fixed in the code.",
3+
"generated": "2026-09-15",
44
"violations": [
55
{
66
"file": "benchmarks/_repro.py",
@@ -4732,11 +4732,6 @@
47324732
"kind": "method-size",
47334733
"detail": "safe_handler"
47344734
},
4735-
{
4736-
"file": "mcp_server/tool_registry_memory.py",
4737-
"kind": "file-size",
4738-
"detail": "exceeds 300-line cap"
4739-
},
47404735
{
47414736
"file": "mcp_server/tool_registry_memory.py",
47424737
"kind": "method-size",

‎mcp_server/__main__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
tool_registry_ingest,
4141
tool_registry_manage,
4242
tool_registry_memory,
43+
tool_registry_memory_maintenance,
4344
tool_registry_nav,
4445
tool_registry_wiki,
4546
)
@@ -95,6 +96,7 @@ def merged_schemas() -> dict[str, dict]:
9596
return {
9697
**tool_registry_core.SCHEMAS,
9798
**tool_registry_memory.SCHEMAS,
99+
**tool_registry_memory_maintenance.SCHEMAS,
98100
**tool_registry_manage.SCHEMAS,
99101
**tool_registry_nav.SCHEMAS,
100102
**tool_registry_advanced.SCHEMAS,
@@ -109,6 +111,7 @@ def register_all(mcp: MCPServer, *, codebase: bool, prd: bool) -> None:
109111
source: ADR-0093"""
110112
tool_registry_core.register(mcp)
111113
tool_registry_memory.register(mcp)
114+
tool_registry_memory_maintenance.register(mcp)
112115
tool_registry_manage.register(mcp)
113116
tool_registry_nav.register(mcp)
114117
tool_registry_advanced.register(mcp)

‎mcp_server/handlers/wiki_write.py‎

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -96,9 +96,10 @@
9696
"content": {
9797
"type": "string",
9898
"description": (
99-
"Raw markdown content. Used when structured fields "
100-
"(title/summary/body) are not provided. Markdown is preserved "
101-
"verbatim."
99+
"Raw markdown content, the final page body. Required — "
100+
"render it yourself (e.g. via wiki_adr for ADRs) before "
101+
"calling this tool; wiki_write does not render from "
102+
"structured fields. Markdown is preserved verbatim."
102103
),
103104
},
104105
"mode": {
@@ -111,22 +112,6 @@
111112
"default": "create",
112113
"examples": ["create", "append"],
113114
},
114-
"title": {
115-
"type": "string",
116-
"description": "Page title (used when rendering from template).",
117-
"examples": ["Recall regression triaged 2026-04-12"],
118-
},
119-
"summary": {
120-
"type": "string",
121-
"description": (
122-
"One-paragraph summary placed near the top of the rendered page."
123-
),
124-
"examples": ["FlashRank ONNX cache divergence; clearing fixed it."],
125-
},
126-
"body": {
127-
"type": "string",
128-
"description": "Main markdown body inserted into the template.",
129-
},
130115
"tags": {
131116
"type": "array",
132117
"description": (

‎mcp_server/tool_registry_advanced.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,12 @@ async def tool_curate_wiki(
6464
min_avg_heat: float = 0.3,
6565
recent_only: bool = True,
6666
memory_pool_size: int = 500,
67+
include_coverage: bool = True,
68+
coverage_jobs_max: int = 4,
69+
include_reauthor: bool = True,
70+
reauthor_jobs_max: int = 3,
71+
report_uncited_deliberate: bool = False,
72+
uncited_deliberate_limit: int = 20,
6773
) -> dict[str, Any]:
6874
"""Return structured authoring jobs for the in-session LLM to author."""
6975
return await safe_handler(
@@ -75,6 +81,12 @@ async def tool_curate_wiki(
7581
"min_avg_heat": min_avg_heat,
7682
"recent_only": recent_only,
7783
"memory_pool_size": memory_pool_size,
84+
"include_coverage": include_coverage,
85+
"coverage_jobs_max": coverage_jobs_max,
86+
"include_reauthor": include_reauthor,
87+
"reauthor_jobs_max": reauthor_jobs_max,
88+
"report_uncited_deliberate": report_uncited_deliberate,
89+
"uncited_deliberate_limit": uncited_deliberate_limit,
7890
},
7991
tool_name="curate_wiki",
8092
)

‎mcp_server/tool_registry_ingest.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ async def tool_ingest_codebase(
6363
output_dir: str | None = None,
6464
language: str = "auto",
6565
force_reindex: bool = False,
66+
ingest_docs: bool = True,
6667
ctx: Context | None = None,
6768
) -> dict[str, Any]:
6869
"""Ingest upstream codebase analysis into Cortex.
@@ -87,6 +88,7 @@ async def tool_ingest_codebase(
8788
"output_dir": output_dir,
8889
"language": language,
8990
"force_reindex": force_reindex,
91+
"ingest_docs": ingest_docs,
9092
"top_symbols": None,
9193
"top_processes": None,
9294
},

‎mcp_server/tool_registry_manage.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,8 @@ async def tool_validate_memory(
8484
base_dir: str | None = None,
8585
staleness_threshold: float = 0.5,
8686
dry_run: bool = False,
87+
after_id: int = 0,
88+
url_check_limit: int = 10,
8789
) -> dict[str, Any]:
8890
"""Validate memories against current filesystem state."""
8991
return await safe_handler(
@@ -95,6 +97,8 @@ async def tool_validate_memory(
9597
"base_dir": base_dir or "",
9698
"staleness_threshold": staleness_threshold,
9799
"dry_run": dry_run,
100+
"after_id": after_id,
101+
"url_check_limit": url_check_limit,
98102
},
99103
tool_name="validate_memory",
100104
)
@@ -108,13 +112,15 @@ def _register_rate_memory(mcp: MCPServer) -> None:
108112
async def tool_rate_memory(
109113
memory_id: int,
110114
useful: bool,
115+
query: str | None = None,
111116
) -> dict[str, Any]:
112117
"""Rate a memory as useful or not to update metamemory confidence."""
113118
return await safe_handler(
114119
rate_memory.handler,
115120
{
116121
"memory_id": memory_id,
117122
"useful": useful,
123+
"query": query,
118124
},
119125
tool_name="rate_memory",
120126
)
@@ -152,13 +158,15 @@ def _register_anchor(mcp: MCPServer) -> None:
152158
async def tool_anchor(
153159
memory_id: int,
154160
reason: str | None = None,
161+
is_global: bool = False,
155162
) -> dict[str, Any]:
156163
"""Mark a memory as compaction-resistant (heat=1.0)."""
157164
return await safe_handler(
158165
anchor.handler,
159166
{
160167
"memory_id": memory_id,
161168
"reason": reason or "",
169+
"is_global": is_global,
162170
},
163171
tool_name="anchor",
164172
)

0 commit comments

Comments
 (0)