toolgraph 0.0.1__tar.gz → 0.1.0__tar.gz

{toolgraph-0.0.1 → toolgraph-0.1.0}/.gitignore

@@ -15,6 +15,7 @@ wheels/
 
 # Agent session logs
 .swarm/
+.dev-trio/
 
 # macOS / local git worktrees
 .DS_Store

{toolgraph-0.0.1 → toolgraph-0.1.0}/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 All notable changes to Toolgraph are documented here.
 
+## 0.1.0 - 2026-09-10
+
+Second alpha. Upgrading from `0.0.1` takes three things: the MCP SDK 2.x, one
+new field for anything caching MCP responses, and — if you generated a
+quickstart with `0.0.1` — a regenerated server script. Read **Upgrading from
+0.0.1** below before installing.
+
+### Upgrading from 0.0.1
+
+`toolgraph example init` copies a quickstart out of the package, so a
+quickstart generated by `0.0.1` holds its own copy of the demo MCP server —
+one that imports `mcp.server.fastmcp`. Upgrading that environment installs MCP
+2.x and the copied server stops importing, so the next `toolgraph crawl`
+fails. Updating the package does not touch a directory it already wrote, and
+`example init` refuses an existing destination on purpose.
+
+To migrate one, generate a fresh quickstart beside it and move your own work
+across:
+
+```bash
+toolgraph example init quickstart-0.1.0
+# Keep your authored governance and your database; take the new server script.
+cp quickstart/governance.yaml quickstart-0.1.0/governance.yaml
+cp -R quickstart/.toolgraph   quickstart-0.1.0/.toolgraph
+```
+
+`servers.yaml` records the interpreter that generated it, so regenerating from
+the upgraded environment already points at the right one; check it only if you
+generated from somewhere else. Re-run `toolgraph crawl`, then
+`toolgraph ingest-manifest`, to confirm.
+
+Verified end to end against the published `0.0.1`: a quickstart it generated
+crawls cleanly on `0.0.1`, fails on the next crawl once the environment holds
+`0.1.0`, and returns the same eligibility verdicts after these steps.
+
+### Added
+
+- `examples/policy_propose_from_observed.py` reads a window of observed gateway
+  usage and prints a reviewable `governance.yaml` grant proposal. It never
+  writes governance. Repository-only — it is not part of the distribution — and
+  deliberately narrow: it requires an envelope declaring the governance digest
+  it was recorded against and refuses a mismatch, refuses an export with no
+  envelope unless `--unverified-provenance` is given, proposes a removal only
+  from an explicit zero-call row, and accepts only fully qualified timestamps
+  with an explicit UTC offset. Digest equality shows what the export declared,
+  not where its rows came from; issue #89 tracks what a real binding needs.
+
+### Changed
+
+- **Breaking:** requires the MCP SDK 2.x (`mcp>=2.1.1,<3`). Environments pinned
+  to `mcp` 1.x can no longer install this package, because 2.x removed
+  `mcp.server.fastmcp` and renamed every model field from camelCase to
+  snake_case. The MCP *wire* format is unchanged, so a client that only speaks
+  the protocol needs no change; that is not the same as no change for anything
+  written against the Python SDK, caching responses, or reading exception text.
+- An unexpected exception raised by a toolgraph tool body no longer puts its
+  message on the wire. Only errors raised deliberately as `ContractError` (for
+  example an unknown selector profile) are forwarded; the rest keep the SDK's
+  generic text, so an internal failure cannot disclose filesystem paths, query
+  bodies or credential-shaped values. Argument-validation failures still echo
+  the caller's own input, as the MCP SDK intends.
+- **Breaking:** an MCP response whose read could not be bracketed by a stable
+  graph state now carries `graph_generation: null` and
+  `graph_state_verified: false` instead of the generation read afterwards.
+  Labelling such a result with a generation it was never read at let a verdict
+  from before a permission change be cached under the generation that changed
+  it, while the tool documentation tells callers to cache per generation.
+  Successful reads gain `graph_state_verified: true`, so the absence of a
+  guarantee is never inferred from a missing field. Null is not self-enforcing
+  — `None` is a usable cache key — so the obligation to skip the cache and to
+  attribute nothing to a graph state is the consumer's; ADR-0004 and the README
+  state it, and a consumer that turns eligibility into an authorization
+  decision should reject or retry such a response.
+
 ## 0.0.1 - 2026-09-09
 
 Initial public alpha release.

{toolgraph-0.0.1 → toolgraph-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolgraph
-Version: 0.0.1
+Version: 0.1.0
 Summary: Graph-native MCP/tool registry, policy compiler, and impact analyzer
 Project-URL: Homepage, https://github.com/memtomem/toolgraph
 Project-URL: Repository, https://github.com/memtomem/toolgraph
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: cryptography>=50.0.0
 Requires-Dist: idna>=3.18
-Requires-Dist: mcp<2,>=1.28.1
+Requires-Dist: mcp<3,>=2.1.1
 Requires-Dist: neo4j<7,>=6.2
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic<3,>=2.7
@@ -493,7 +493,23 @@ server-qualified key. An unknown agent returns `agent_found: false`
 a typo'd agent is a context-construction error, not an empty catalog.
 
 MCP responses carry `graph_generation` (ADR-0004) so consumers can cache
-features per graph state with one integer comparison.
+features per graph state. Cache identity is the pair (`graph_instance_id`,
+`graph_generation`), not the integer alone: generations restart with the graph.
+
+A response also carries `graph_state_verified`. It is `true` when the read was
+bracketed by a stable graph state, and `false` when the graph moved under every
+retry — in which case all three state fields are null:
+
+```json
+{"graph_generation": null, "graph_instance_id": null,
+ "graph_state": null, "graph_state_verified": false}
+```
+
+An unverified response is still the answer to your question, but it must not be
+cached and must not be attributed to a graph state. Nothing enforces that for
+you: `null` is a usable dictionary key and two unverified responses compare
+equal on it. A consumer that turns eligibility into an authorization decision
+should reject or retry rather than proceed on one.
 
 If the graph backend is temporarily unavailable, every MCP tool returns
 `isError: true` with a typed `structuredContent` envelope instead of exposing
@@ -620,7 +636,7 @@ toolgraph/
   crawler/   connect to MCP servers (stdio + streamable-http), enumerate tools/resources
   graph/     Neo4j driver, schema/constraints, idempotent loader, governance/audit queries
   manifest/  parse + ingest authored governance (idempotent)
-  server/    FastMCP server exposing the queries as MCP tools
+  server/    MCP server exposing the queries as MCP tools
   cli.py     crawl / ingest-manifest / check-access / unsafe-tools / blast-radius /
              unmapped-tools / orphan-policies / unbacked-edges / drift /
              destructive-unsafeguarded / annotation-contradictions /

{toolgraph-0.0.1 → toolgraph-0.1.0}/README.md

@@ -456,7 +456,23 @@ server-qualified key. An unknown agent returns `agent_found: false`
 a typo'd agent is a context-construction error, not an empty catalog.
 
 MCP responses carry `graph_generation` (ADR-0004) so consumers can cache
-features per graph state with one integer comparison.
+features per graph state. Cache identity is the pair (`graph_instance_id`,
+`graph_generation`), not the integer alone: generations restart with the graph.
+
+A response also carries `graph_state_verified`. It is `true` when the read was
+bracketed by a stable graph state, and `false` when the graph moved under every
+retry — in which case all three state fields are null:
+
+```json
+{"graph_generation": null, "graph_instance_id": null,
+ "graph_state": null, "graph_state_verified": false}
+```
+
+An unverified response is still the answer to your question, but it must not be
+cached and must not be attributed to a graph state. Nothing enforces that for
+you: `null` is a usable dictionary key and two unverified responses compare
+equal on it. A consumer that turns eligibility into an authorization decision
+should reject or retry rather than proceed on one.
 
 If the graph backend is temporarily unavailable, every MCP tool returns
 `isError: true` with a typed `structuredContent` envelope instead of exposing
@@ -583,7 +599,7 @@ toolgraph/
   crawler/   connect to MCP servers (stdio + streamable-http), enumerate tools/resources
   graph/     Neo4j driver, schema/constraints, idempotent loader, governance/audit queries
   manifest/  parse + ingest authored governance (idempotent)
-  server/    FastMCP server exposing the queries as MCP tools
+  server/    MCP server exposing the queries as MCP tools
   cli.py     crawl / ingest-manifest / check-access / unsafe-tools / blast-radius /
              unmapped-tools / orphan-policies / unbacked-edges / drift /
              destructive-unsafeguarded / annotation-contradictions /

{toolgraph-0.0.1 → toolgraph-0.1.0}/pyproject.toml

@@ -28,7 +28,7 @@ dependencies = [
     "python-multipart>=0.0.31",
     "starlette>=1.3.1",
     "pydantic-settings>=2.14.2",
-    "mcp>=1.28.1,<2",
+    "mcp>=2.1.1,<3",
     "neo4j>=6.2,<7",
     "pydantic>=2.7,<3",
     "pyyaml>=6.0",

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/__init__.py

@@ -1,3 +1,3 @@
 """toolgraph — graph-native MCP/tool registry for advisory governance analysis."""
 
-__version__ = "0.0.1"
+__version__ = "0.1.0"

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/crawler/client.py

@@ -19,6 +19,23 @@ class PaginationLimitError(RuntimeError):
     """A server kept returning continuation cursors past MAX_LIST_PAGES."""
 
 
+def _page(cursor: str | None):
+    """Pagination params for a list call, or None for the first page.
+
+    mcp 2.x replaced the ``cursor=`` keyword with a params object. The SDK
+    treats "no params" and "params with a null cursor" as equivalent when
+    deciding a listing is complete, so returning None here is a matter of
+    sending the smaller request, not of correctness. The distinction that DOES
+    decide the loop is null versus ``""`` in the RESPONSE cursor, which the
+    caller below handles.
+    """
+    if cursor is None:
+        return None
+    from mcp.types import PaginatedRequestParams
+
+    return PaginatedRequestParams(cursor=cursor)
+
+
 def _annotation_fields(tool) -> dict:
     """Tool annotations as ToolRecord fields (ADR-0006).
 
@@ -30,15 +47,15 @@ def _annotation_fields(tool) -> dict:
     if ann is None:
         return {}
     return {
-        "read_only_hint": ann.readOnlyHint,
-        "destructive_hint": ann.destructiveHint,
-        "idempotent_hint": ann.idempotentHint,
-        "open_world_hint": ann.openWorldHint,
+        "read_only_hint": ann.read_only_hint,
+        "destructive_hint": ann.destructive_hint,
+        "idempotent_hint": ann.idempotent_hint,
+        "open_world_hint": ann.open_world_hint,
     }
 
 
 async def _list_all_tools(session) -> list[ToolRecord]:
-    """Drain ``list_tools`` pages until ``nextCursor`` is exhausted.
+    """Drain ``list_tools`` pages until ``next_cursor`` is exhausted.
 
     Without pagination, a server with more than one page silently drops
     tools on later pages — governance refs to them would then reject at
@@ -48,17 +65,17 @@ async def _list_all_tools(session) -> list[ToolRecord]:
     out: list[ToolRecord] = []
     cursor: str | None = None
     for _ in range(MAX_LIST_PAGES):
-        listed = await session.list_tools(cursor=cursor)
+        listed = await session.list_tools(params=_page(cursor))
         out.extend(
             ToolRecord(
                 name=t.name,
                 description=t.description,
-                input_schema=t.inputSchema,
+                input_schema=t.input_schema,
                 **_annotation_fields(t),
             )
             for t in listed.tools
         )
-        cursor = getattr(listed, "nextCursor", None)
+        cursor = getattr(listed, "next_cursor", None)
         if cursor is None:
             # Stop ONLY on None: an empty-string cursor is a valid opaque
             # continuation token in MCP and the SDK distinguishes "" from
@@ -72,21 +89,21 @@ async def _list_all_tools(session) -> list[ToolRecord]:
 
 
 async def _list_all_resources(session) -> list[ResourceRecord]:
-    """Drain ``list_resources`` pages until ``nextCursor`` is exhausted."""
+    """Drain ``list_resources`` pages until ``next_cursor`` is exhausted."""
     out: list[ResourceRecord] = []
     cursor: str | None = None
     for _ in range(MAX_LIST_PAGES):
-        listed = await session.list_resources(cursor=cursor)
+        listed = await session.list_resources(params=_page(cursor))
         out.extend(
             ResourceRecord(
                 uri=normalize_resource_uri(str(r.uri)),
                 name=r.name,
-                mime_type=r.mimeType,
+                mime_type=r.mime_type,
                 description=r.description,
             )
             for r in listed.resources
         )
-        cursor = getattr(listed, "nextCursor", None)
+        cursor = getattr(listed, "next_cursor", None)
         if cursor is None:
             # Stop ONLY on None: an empty-string cursor is a valid opaque
             # continuation token in MCP and the SDK distinguishes "" from
@@ -111,8 +128,8 @@ async def crawl_server(spec: ServerSpec) -> CrawlResult:
         )
 
         return CrawlResult(
-            server_name=spec.name or init.serverInfo.name,
-            server_version=init.serverInfo.version,
+            server_name=spec.name or init.server_info.name,
+            server_version=init.server_info.version,
             transport=spec.transport,
             endpoint=endpoint_label(spec),
             tools=tools,

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/crawler/transports.py

@@ -1,8 +1,9 @@
 """Open an MCP ClientSession over the right transport for a ServerSpec.
 
-Normalizes the transport differences the SDK exposes: stdio yields a 2-tuple
-``(read, write)`` while streamable-http yields a 3-tuple
-``(read, write, get_session_id)``. SSE is supported only as a deprecated fallback.
+Normalizes the transport differences the SDK exposes. Under mcp 2.x every
+transport yields the same 2-tuple ``(read, write)``; the session-id getter
+streamable-http used to return as a third element is gone. SSE is supported
+only as a deprecated fallback.
 
 Uses the preferred ``streamable_http_client``; since it takes headers via a
 custom httpx client rather than a ``headers=`` kwarg, we build one with the
@@ -42,7 +43,8 @@ async def open_session(spec: ServerSpec) -> AsyncIterator[ClientSession]:
                 http_client = await stack.enter_async_context(
                     create_mcp_http_client(headers=spec.headers)
                 )
-            read, write, _get_session_id = await stack.enter_async_context(
+            # mcp 2.x drops the session-id getter from the returned streams.
+            read, write = await stack.enter_async_context(
                 streamable_http_client(spec.url, http_client=http_client)
             )
 

toolgraph-0.1.0/toolgraph/errors.py

@@ -0,0 +1,26 @@
+"""Errors whose message is safe to hand back to a caller."""
+
+from __future__ import annotations
+
+
+class ContractError(ValueError):
+    """A caller-fixable violation of a documented contract.
+
+    The distinction is load-bearing at the MCP boundary. mcp 2.x masks the text
+    of an unexpected exception so an internal failure cannot leak filesystem
+    paths, query bodies or credential-shaped values to a client. That default is
+    right, and toolgraph keeps it for everything except the errors it raises
+    deliberately here.
+
+    A ContractError message is built only from values the caller supplied and
+    fixed constants -- "unknown profile 'production', expected one of [...]" --
+    so forwarding it is the answer the caller needs rather than a disclosure.
+
+    Raise this ONLY where that is true. Never use it to wrap a driver,
+    filesystem, or configuration failure: those carry text nobody audited, and
+    ``redact_text`` models URLs and a handful of credential labels, not
+    arbitrary confidential strings.
+
+    It subclasses ValueError so existing ``except ValueError`` callers and the
+    CLI's error handling keep working unchanged.
+    """

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/graph/driver.py

@@ -73,7 +73,7 @@ def _translating_backend_errors() -> Iterator[None]:
 def is_backend_unavailable(exc: BaseException) -> bool:
     """Whether *exc* was caused by a backend outage typed at the driver seam.
 
-    FastMCP wraps tool exceptions, so walk the chain. ``__context__`` is
+    MCPServer wraps tool exceptions, so walk the chain. ``__context__`` is
     followed only when Python did not suppress it: a deliberate
     ``raise ... from None`` while handling an outage is the author saying the
     outer error is the real one, and must not be reclassified as retryable.

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/graph/queries.py

@@ -58,19 +58,37 @@ def with_generation(fetch: Callable[[], dict], *, strict: bool = False) -> dict:
     Neo4j is read-committed rather than snapshot-isolated.  Reading the
     generation before and after the query and retrying on a change prevents a
     result from being labelled with a generation that committed midway
-    through it. MCP live queries keep their historical self-healing fallback
-    after retry exhaustion; persisted artifact producers pass ``strict=True``
-    so they fail instead of writing a potentially mislabelled artifact.
+    through it.
+
+    Persisted artifact producers pass ``strict=True`` and fail rather than
+    write a mislabelled artifact. A live query still returns its data after
+    retry exhaustion, because an answer under churn beats an error, but it
+    comes back with ``graph_generation: None`` and
+    ``graph_state_verified: False``. Stamping the generation read AFTERWARDS
+    labelled the result with a state it was never read at, and the MCP tools
+    tell callers to cache per generation -- so a verdict from before a
+    permission change could be cached under the very generation that changed
+    it.
+
+    Null does not enforce anything by itself: ``None`` is a usable dict key and
+    two unverified responses compare equal on it. What changes is that the
+    response no longer ASSERTS a state it never had, and says so in a field a
+    consumer can act on. The obligation to skip the cache is the consumer's;
+    ADR-0004 states it.
     """
     for attempt in range(_GENERATION_RETRIES):
         before = graph_generation()
         result = fetch()
         if graph_generation() == before:
-            return {**result, "graph_generation": before}
+            return {
+                **result,
+                "graph_generation": before,
+                "graph_state_verified": True,
+            }
         _bracket_backoff(attempt)
     if strict:
         raise RuntimeError("graph generation changed during every read attempt")
-    return {**result, "graph_generation": graph_generation()}
+    return {**result, "graph_generation": None, "graph_state_verified": False}
 
 
 def with_graph_state(
@@ -79,7 +97,12 @@ def with_graph_state(
     strict: bool = False,
     state_reader: Callable[[], GraphState] | None = None,
 ) -> dict:
-    """Return ``fetch`` bracketed by the collision-safe graph state token."""
+    """Return ``fetch`` bracketed by the collision-safe graph state token.
+
+    Same contract as ``with_generation``: an unbracketed read comes back with
+    every state field null and ``graph_state_verified: False`` rather than
+    carrying a token it was not read under.
+    """
     read_state = state_reader if state_reader is not None else graph_state
     for attempt in range(_GENERATION_RETRIES):
         before = read_state()
@@ -91,19 +114,17 @@ def with_graph_state(
                 "graph_generation": before.generation,
                 "graph_instance_id": before.instance_id,
                 "graph_state": token,
+                "graph_state_verified": True,
             }
         _bracket_backoff(attempt)
     if strict:
         raise RuntimeError("graph state changed during every read attempt")
-    current = read_state()
     return {
         **result,
-        "graph_generation": current.generation,
-        "graph_instance_id": current.instance_id,
-        "graph_state": {
-            "instance_id": current.instance_id,
-            "generation": current.generation,
-        },
+        "graph_generation": None,
+        "graph_instance_id": None,
+        "graph_state": None,
+        "graph_state_verified": False,
     }
 
 

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/graph/selector.py

@@ -21,6 +21,7 @@ consumer may never override a hard reject (NOT_GRANTED, violation, drifted).
 
 from __future__ import annotations
 
+from toolgraph.errors import ContractError
 from toolgraph.graph.driver import session
 from toolgraph.graph.queries import _deny_evidence_batch, agent_exists, resolve_tool_refs
 
@@ -164,7 +165,7 @@ def rank_features(agent: str, candidates: list[str]) -> dict:
     ``risk_score`` (see ``_risk_score`` for the fixed table).
     """
     if len(candidates) > MAX_CANDIDATES:
-        raise ValueError(
+        raise ContractError(
             f"{len(candidates)} candidates exceed the {MAX_CANDIDATES} limit"
         )
     if not agent_exists(agent):
@@ -274,7 +275,7 @@ def filter_features(ranked: dict, profile: str = DEFAULT_PROFILE) -> dict:
     graph evaluation twice inside the generation-retry bracket.
     """
     if profile not in PROFILES:
-        raise ValueError(
+        raise ContractError(
             f"unknown profile {profile!r} — expected one of {sorted(PROFILES)}"
         )
     agent = ranked["agent"]
@@ -336,7 +337,7 @@ def eligible_tools(
     ``eligible`` but may never resurrect a rejected row.
     """
     if profile not in PROFILES:
-        raise ValueError(
+        raise ContractError(
             f"unknown profile {profile!r} — expected one of {sorted(PROFILES)}"
         )
     return filter_features(rank_features(agent, candidates), profile)
@@ -348,7 +349,7 @@ def selection_explain(
     """Compact human-readable reasons for one (agent, tool) — a view over the
     same facts ``rank_features`` returns, for operators and end users."""
     if profile not in PROFILES:
-        raise ValueError(
+        raise ContractError(
             f"unknown profile {profile!r} — expected one of {sorted(PROFILES)}"
         )
     ranked = rank_features(agent, [tool])

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/quickstart/policy_gateway_server.py

@@ -2,19 +2,19 @@
 
 from __future__ import annotations
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 from mcp.types import ToolAnnotations
 
 
-def build() -> FastMCP:
-    server = FastMCP("policy-gateway")
+def build() -> MCPServer:
+    server = MCPServer("policy-gateway")
 
-    @server.tool(annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True))
+    @server.tool(annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True))
     def read_note(note_id: str) -> str:
         """Read a deterministic demo note."""
         return f"note:{note_id}"
 
-    @server.tool(annotations=ToolAnnotations(destructiveHint=True))
+    @server.tool(annotations=ToolAnnotations(destructive_hint=True))
     def publish_note(note_id: str, content: str) -> str:
         """Publish a demo note to the governed draft area."""
         return f"published:{note_id}:{len(content)}"

{toolgraph-0.0.1 → toolgraph-0.1.0}/toolgraph/server/app.py

@@ -4,18 +4,25 @@ it crawls. Thin wrappers over graph.queries — all logic lives there.
 Every response carries ``graph_generation`` (ADR-0004) so callers can cache
 graph-derived features and pin telemetry to a replayable graph state. The
 stamp lives HERE, not in the query layer — CLI output stays unchanged.
+
+``graph_generation`` is null, with ``graph_state_verified: false``, when the
+graph moved under every read attempt. The data is still the answer; what is
+missing is a state it was demonstrably read at. Such a response must not be
+cached and must not be attributed to a graph state — nothing enforces that on
+the consumer's behalf, so ADR-0004 states the obligation. A consumer turning
+eligibility into an authorization decision should reject or retry instead.
 """
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 import logging
 from typing import Any
 
-from mcp.server.fastmcp import FastMCP
-from mcp.server.fastmcp.exceptions import ToolError
-from mcp.types import CallToolResult, ContentBlock, TextContent, ToolAnnotations
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import CallToolResult, TextContent, ToolAnnotations
 
+from toolgraph.errors import ContractError
 from toolgraph.graph import queries, selector
 from toolgraph.graph.driver import is_backend_unavailable
 from toolgraph.redaction import redact_text
@@ -28,8 +35,8 @@ _BACKEND_UNAVAILABLE_MESSAGE = (
 )
 
 
-class _ToolgraphMCP(FastMCP):
-    """FastMCP server with a typed envelope for backend availability only."""
+class _ToolgraphMCP(MCPServer):
+    """MCPServer with a typed envelope for backend availability only."""
 
     def read_only_tool(self, name: str | None = None, **kwargs: Any):
         """Register a pure-read graph tool: safe to retry, no added side effect.
@@ -43,7 +50,7 @@ class _ToolgraphMCP(FastMCP):
         def decorator(fn):
             return self.tool(
                 name=name,
-                annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True),
+                annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
                 **kwargs,
             )(fn)
 
@@ -54,7 +61,7 @@ class _ToolgraphMCP(FastMCP):
 
         Read from the annotations the server actually advertises, so there is
         exactly one source of truth. A parallel registry could disagree with
-        the live registration — FastMCP keeps the *first* tool on a duplicate
+        the live registration — MCPServer keeps the *first* tool on a duplicate
         name, so a write tool could otherwise inherit a later read-only claim.
 
         Every failure path answers "no": an unknown tool, an unannotated tool,
@@ -70,7 +77,7 @@ class _ToolgraphMCP(FastMCP):
         try:
             for tool in await self.list_tools():
                 if tool.name == name:
-                    return bool(tool.annotations and tool.annotations.readOnlyHint)
+                    return bool(tool.annotations and tool.annotations.read_only_hint)
         except Exception:
             logger.warning(
                 "could not read retry safety for tool %r; reporting not retryable",
@@ -80,19 +87,30 @@ class _ToolgraphMCP(FastMCP):
         return False
 
     async def call_tool(
-        self, name: str, arguments: dict[str, Any]
-    ) -> Sequence[ContentBlock] | dict[str, Any] | CallToolResult:
+        self, name: str, arguments: dict[str, Any], context: Any = None
+    ) -> CallToolResult | Any:
+        # mcp 2.x threads a Context through and narrows the return to a typed
+        # result; 1.x returned a loose union the low-level server converted.
         try:
-            return await super().call_tool(name, arguments)
+            return await super().call_tool(name, arguments, context)
         except ToolError as exc:
             if not is_backend_unavailable(exc):
                 # The seam types every outage it covers, so reaching here means
-                # either a contract error or a driver exception that never
-                # passed the seam. FastMCP puts this message on the wire
-                # verbatim, and driver text can carry a connection URI, so it
-                # is scrubbed before it leaves. Ordinary contract text is
-                # unaffected; the cause is kept for server-side logs.
-                raise ToolError(redact_text(exc)) from exc
+                # either a contract error or an exception that never passed the
+                # seam.
+                #
+                # mcp 2.x masks unexpected exception text, and that default is
+                # kept. Only ContractError is forwarded: its message is built
+                # from caller-supplied values and fixed constants, so "unknown
+                # profile 'production'" reaches the caller who can act on it.
+                # Everything else re-raises untouched, which keeps the mask and
+                # preserves the SDK's crash-path logging for an
+                # UnexpectedToolError. redact_text models URLs and a few
+                # credential labels, not arbitrary confidential text, so it is
+                # a second line of defence here, not the reason this is safe.
+                if isinstance(exc.__cause__, ContractError):
+                    raise ToolError(redact_text(exc.__cause__)) from exc
+                raise
             payload: dict[str, Any] = {
                 "error_kind": "backend_unavailable",
                 "retryable": await self._is_retryable(name),
@@ -100,8 +118,8 @@ class _ToolgraphMCP(FastMCP):
             }
             return CallToolResult(
                 content=[TextContent(type="text", text=_BACKEND_UNAVAILABLE_MESSAGE)],
-                structuredContent=payload,
-                isError=True,
+                structured_content=payload,
+                is_error=True,
             )
 
 
@@ -267,7 +285,9 @@ def rank_features(agent: str, candidates: list[str]) -> dict:
     four annotation self-claims — plus the rule-based ``risk_score`` from the
     published fixed table. No relevance, no learning. ``agent_found: false``
     means selection should abort: context-construction error, not an empty
-    result. Cache per ``graph_generation``.
+    result. Cache on (``graph_instance_id``, ``graph_generation``), and never
+    when ``graph_state_verified`` is false — that read could not be bracketed
+    by a stable graph state, so it belongs to no state at all.
     """
     return _with_generation(lambda: selector.rank_features(agent, candidates))