Red-evidence: naalp-mcp-hook (MCP framework-hook adapter)¶
Mutation-survival evidence for naalp_mcp_hook/mcp_hook.py's property ("keep MCP
annotations OPAQUE -- never decode/parse annotation contents to derive a decision"). Produced by
actually editing naalp_mcp_hook/mcp_hook.py (never naalp_kit/binding.py or
impl/python/naalp/*, both out of scope and already separately graded), confirming the named
test flips RED for the stated reason, then restoring the file from a .bak copy (never
git checkout -- this tree is uncommitted), clearing __pycache__
(PYTHONDONTWRITEBYTECODE=1 set for every run), and re-running the full 35-test suite GREEN.
Baseline / reverted file hash for naalp_mcp_hook/mcp_hook.py (SHA-256), confirmed identical
before the mutation and after the revert:
Run command (from the repo root, invoking the real installed Python interpreter for this
platform -- on Windows the Microsoft-Store python/python3 execution-alias stubs resolve
ahead of a real install on PATH and hang, so invoke the actual interpreter binary directly
rather than the bare python command):
M1 -- annotations-stay-opaque-never-decoded (test_effect_is_never_derived_from_annotation_hints)¶
Mutated: two sites, both required for the mutation to have any real effect (a single-site mutation that references a never-populated attribute would be a no-op, not a genuine defect):
list_tools()-- stash the RAW, decodedtypes.ToolAnnotationsobject per tool name (not just its opaque content id), the first step toward reading a hint's boolean value:
result = await super().list_tools(*args, **kwargs)
for tool in result.tools:
cid = annotations_content_id(tool.annotations)
if cid is not None:
self._naalp_annotation_cids[tool.name] = cid
+ # MUTATION M1 (red-evidence, naalp-mcp-hook): stash the raw, DECODED annotations
+ # object too -- the opacity violation call_tool's mutation below reads from.
+ if not hasattr(self, "_naalp_raw_annotations"):
+ self._naalp_raw_annotations = {}
+ self._naalp_raw_annotations[tool.name] = tool.annotations
return result
call_tool()-- when the effect is otherwise unclassified, read the stashed annotations object'sreadOnlyHintboolean VALUE and derive an effect from it -- exactly thenaalp-mcp-bridge-style decode this module's own opacity guarantee forbids:
effect = self._classify_effect(name, args_dict)
+ # MUTATION M1 (red-evidence, naalp-mcp-hook): decode the tool's cached annotations the
+ # way naalp-mcp-bridge does, and derive effect from a hint's boolean VALUE -- the exact
+ # opacity violation this module exists to forbid.
+ if effect is None:
+ _ann_obj = getattr(self, "_naalp_raw_annotations", {}).get(name)
+ if _ann_obj is not None and _ann_obj.readOnlyHint:
+ effect = policy.READ_ONLY
RED, confirmed:
FAILED ecosystem/naalp-mcp-hook/tests/test_mcp_hook.py::test_effect_is_never_derived_from_annotation_hints
assert read_only_hinted_call.effect == policy.DESTRUCTIVE # SAME, despite the opposite hint
E assert 0 == 3
E + where 0 = <naalp.envelope.Object object at 0x...>.effect
E + and 3 = policy.DESTRUCTIVE
1 failed, 34 passed
With the mutation in place, a tool whose real MCP ToolAnnotations carried readOnlyHint=True
(and destructiveHint=False) resolved to a signed, VERIFIED N-AALP object with effect ==
READ_ONLY (0) instead of the fail-closed DESTRUCTIVE (3) default -- i.e. the mutated adapter
DID successfully decode the annotation's boolean hint and let it steer a real authorization-grade
field, precisely the behavior this module exists to forbid (and precisely what naalp-mcp-bridge
correctly does, for its OWN, different job, via naalp.mcp.map_annotations_to_effect). Every
other test in the file was unaffected (34 of 35 tests still passed, including
test_payload_never_contains_raw_annotation_hint_text, which targets a DIFFERENT opacity facet
-- the payload's literal bytes -- and was never touched by this mutation) -- this mutation
targets only the effect-derivation path a genuine annotation decode would reach.
Reverted: the file was restored from its .bak copy (never git checkout -- this tree is
uncommitted), __pycache__ cleared, hash re-confirmed
64152cd304d5c1038e99c9818b76ce4879ca9670f37150ff1b0bccdf7e7c6f8d.
GREEN, confirmed: 35/35 tests pass.
Why this mutation, and why the target stays inside naalp_mcp_hook/¶
Every cryptographic, encoding, and authorization operation call_tool/list_tools reaches
(naalp_kit.binding.sign_action/verify_action/authorize_action, and beneath those the real
Part-1 core -- naalp.ez, naalp.envelope, naalp.cbor.content_id, naalp.policy.Grant.
authorize_object) is already-graded, untouched by this task, and carries its own red-evidence
elsewhere. What naalp_mcp_hook/mcp_hook.py adds, and therefore
what this mutation targets, is entirely this module's OWN new code: whether a real MCP tool's real
ToolAnnotations object is ever read for its semantic CONTENT. This is the one property that
distinguishes this module from the pre-existing ecosystem/naalp-mcp-bridge and is the reason it
is a DISTINCT adapter rather than an extension of that library -- a governance
kit that silently decodes what it promises to keep opaque would defeat the specific design
guarantee ("even against an unmodified third-party server") this module exists to provide.
Environment note (verified against the currently installed package, not memory)¶
The official mcp package, version 1.27.1, was already installed in this session's Python
environment (confirmed via pip show mcp: Author: Anthropic, PBC) and used directly for this
module and its test suite -- a real mcp.server.fastmcp.FastMCP server, a real
mcp.ClientSession subclass (NaalpGovernedClientSession), and real mcp.types.ToolAnnotations
objects, connected over real anyio memory-object streams
(mcp.shared.memory.create_client_server_memory_streams, the same in-process transport the MCP
SDK's own test suite uses) with a real initialize() handshake.
Cross-checked THIS session against the current PyPI release (pypi.org/pypi/mcp/json): the
latest release line is 2.1.1 (released 2026-08-24), "a major rework of the SDK... to support
the 2026-07-28 MCP specification." Installed into an isolated venv (never touching the
environment's 1.27.1 install, which another local tool depends on) purely to confirm the hook
point this module relies on -- mcp.client.session.ClientSession.call_tool, a plain overridable
async def instance method -- is stable across the rework (2.1.1 adds keyword-only extras for
new elicitation/task features; this module forwards *args, **kwargs through them unexamined,
so it is unaffected by the addition). Confirmed by reading mcp/client/session.py and
mcp/shared/session.py in both versions, and by grepping the installed package tree for
"middleware"/"interceptor": the MCP Python SDK has no separate client-side plugin/middleware
registry (unlike ADK's BasePlugin); ordinary subclassing of ClientSession IS the SDK's own
extensibility mechanism for this purpose, confirmed real and stable across the current major
version boundary.