fix(handlers): remember/recall/get_telemetry return dict not str (issue #17)

PSGSupport reported strict MCP clients (Claude Code tool runtime)
rejecting these three handlers with "structured_content must be a
dict or None. Got str". The DB writes happened but FastMCP rejected
the response before delivery to the client.

Root cause: mcp_server/tool_error_handler.py:safe_handler used to wrap
every handler return value in json.dumps(...) and return the JSON
string. FastMCP 2.x validates structured content against the declared
output_schema and rejects non-dict returns. Three handlers
(remember, recall, get_telemetry) declare output_schema and so failed;
others without output_schema worked because FastMCP auto-wraps strings
when no schema is declared.

The fix returns the dict directly from safe_handler (with a defensive
{} fallback for None). All tool registry signatures updated from
-> str to -> dict to match.

Liskov: every MCP handler now uniformly returns dict (or None) per
the output_schema contract. Added a contract-enforcement test in
tests_py/server/test_handler_contract.py that asserts the invariant
across all registered tools, so future handlers can't silently
regress this.

Also pinned the dict-not-str contract in:
- tests_py/handlers/test_get_telemetry.py (new file)
- tests_py/handlers/test_remember.py (TestRememberReturnsDict class)
- tests_py/handlers/test_recall.py (TestRecallReturnsDict class)
- tests_py/integration/test_cold_start.py (TestToolErrorHandler updates)

Verification: 16 new/updated tests pass; full handlers + server +
cold_start sweep stays green (355 passed).

Closes #17.

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

Author: cdeust

mcp_server/tool_error_handler.py

@@ -9,18 +9,25 @@
     DB methods) run on a worker thread instead of blocking the event
     loop
 
+Issue #17 (PSGSupport): handlers that declare ``output_schema`` were
+rejected by FastMCP with ``structured_content must be a dict or None.
+Got str: '{...}'`` because this wrapper used to ``json.dumps`` the
+result before returning. FastMCP 2.x validates the return shape
+against the declared schema and rejects strings. Fix: return the
+dict directly. The handler contract IS dict-or-None (Liskov: every
+``mcp__cortex__*`` handler now uniformly satisfies the same interface).
+
 Usage in tool registries:
     from mcp_server.tool_error_handler import safe_handler
 
-    async def tool_remember(...) -> str:
+    async def tool_remember(...) -> dict:
         result = await safe_handler(remember.handler, {...}, tool_name="remember")
         return result
 """
 
 from __future__ import annotations
 
 import asyncio
-import json
 from typing import Any, Callable, Coroutine
 
 _DB_SETUP_GUIDE = (
@@ -107,8 +114,8 @@ async def safe_handler(
     handler_fn: Callable[..., Coroutine[Any, Any, dict]],
     args: dict[str, Any],
     tool_name: str | None = None,
-) -> str:
-    """Call a handler and return JSON, catching errors gracefully.
+) -> dict[str, Any]:
+    """Call a handler and return its dict, catching errors gracefully.
 
     When ``tool_name`` is provided:
       * The call is gated by the per-tool admission semaphore (Phase 5
@@ -124,9 +131,15 @@ async def safe_handler(
     event loop without admission (backward-compat for code paths not
     yet migrated).
 
-    On success: returns json.dumps(result).
-    On DB errors: returns a friendly setup guide.
-    On other errors: returns error type + message (no traceback).
+    Contract (issue #17 — Liskov enforcement across all MCP handlers):
+      precondition: ``handler_fn`` is an async callable returning a dict.
+      postcondition: returns a ``dict[str, Any]``. Never a JSON string.
+                     FastMCP 2.x validates structured content against
+                     the declared ``output_schema`` and rejects strings.
+
+    On success: returns the handler's dict verbatim.
+    On DB errors: returns a friendly setup-guide dict.
+    On other errors: returns an error-type/message dict (no traceback).
     """
     try:
         if tool_name:
@@ -147,7 +160,13 @@ async def safe_handler(
             )
         else:
             result = await handler_fn(args)
-        return json.dumps(result, indent=2, default=str)
+        # Defensive: every handler must already return a dict per its
+        # ``output_schema``. If a handler regresses to None we surface
+        # an empty dict so FastMCP's structured-content validator does
+        # not reject the response.
+        if result is None:
+            return {}
+        return result
     except Exception as exc:
         error_type, message = _classify_error(exc)
         if tool_name:
@@ -160,17 +179,13 @@ async def safe_handler(
                 )
             except Exception:
                 pass
-        return json.dumps(
-            {
-                "error": error_type,
-                "message": message,
-                "hint": (
-                    "If this persists, check that PostgreSQL is running "
-                    "and DATABASE_URL is set correctly."
-                )
-                if error_type not in ("missing_extension", "database_not_connected")
-                else None,
-            },
-            indent=2,
-            default=str,
-        )
+        return {
+            "error": error_type,
+            "message": message,
+            "hint": (
+                "If this persists, check that PostgreSQL is running "
+                "and DATABASE_URL is set correctly."
+            )
+            if error_type not in ("missing_extension", "database_not_connected")
+            else None,
+        }

mcp_server/tool_registry_advanced.py

@@ -39,7 +39,7 @@ async def tool_sync_instructions(
         max_insights: int = 10,
         min_heat: float = 0.3,
         dry_run: bool = False,
-    ) -> str:
+    ) -> dict:
         """Push top memory insights into CLAUDE.md."""
         return await safe_handler(
             sync_instructions.handler,
@@ -63,7 +63,7 @@ async def tool_create_trigger(
         trigger_condition: str,
         trigger_type: str = "keyword",
         target_directory: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Create a prospective memory trigger."""
         return await safe_handler(
             create_trigger.handler,
@@ -89,7 +89,7 @@ async def tool_add_rule(
         scope: str = "global",
         scope_value: str | None = None,
         priority: int = 0,
-    ) -> str:
+    ) -> dict:
         """Add a neuro-symbolic rule to the memory store."""
         return await safe_handler(
             add_rule.handler,
@@ -114,7 +114,7 @@ async def tool_get_rules(
         scope: str | None = None,
         rule_type: str | None = None,
         include_inactive: bool = False,
-    ) -> str:
+    ) -> dict:
         """List active neuro-symbolic rules."""
         return await safe_handler(
             get_rules.handler,
@@ -137,7 +137,7 @@ async def tool_get_project_story(
         domain: str | None = None,
         period: str = "week",
         max_chapters: int = 5,
-    ) -> str:
+    ) -> dict:
         """Generate a period-based autobiographical narrative."""
         return await safe_handler(
             get_project_story.handler,
@@ -160,7 +160,7 @@ async def tool_assess_coverage(
         directory: str | None = None,
         domain: str | None = None,
         stale_days: int = 14,
-    ) -> str:
+    ) -> dict:
         """Evaluate knowledge coverage completeness."""
         return await safe_handler(
             assess_coverage.handler,

mcp_server/tool_registry_core.py

@@ -46,7 +46,7 @@ async def tool_query_methodology(
         cwd: str | None = None,
         project: str | None = None,
         first_message: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Returns cognitive profile for the current domain."""
         return await safe_handler(
             query_methodology.handler,
@@ -68,7 +68,7 @@ async def tool_detect_domain(
         cwd: str | None = None,
         project: str | None = None,
         first_message: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Lightweight domain classification."""
         return await safe_handler(
             detect_domain_handler.handler,
@@ -89,7 +89,7 @@ def _register_rebuild_profiles(mcp: FastMCP) -> None:
     async def tool_rebuild_profiles(
         domain: str | None = None,
         force: bool = False,
-    ) -> str:
+    ) -> dict:
         """Full rescan of all session data to rebuild methodology profiles."""
         return await safe_handler(
             rebuild_profiles.handler,
@@ -106,7 +106,7 @@ def _register_list_domains(mcp: FastMCP) -> None:
         name="list_domains",
         **tool_kwargs(list_domains.schema),
     )
-    async def tool_list_domains() -> str:
+    async def tool_list_domains() -> dict:
         """Overview of all detected cognitive domains."""
         return await safe_handler(list_domains.handler, {}, tool_name="list_domains")
 
@@ -125,7 +125,7 @@ async def tool_record_session_end(
         keywords: list[str] | None = None,
         cwd: str | None = None,
         project: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Incremental profile update after a session ends."""
         return await safe_handler(
             record_session_end.handler,
@@ -150,7 +150,7 @@ def _register_get_methodology_graph(mcp: FastMCP) -> None:
     )
     async def tool_get_methodology_graph(
         domain: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Returns methodology map as graph data for 3D visualization."""
         return await safe_handler(
             get_methodology_graph.handler,
@@ -175,7 +175,7 @@ async def tool_query_workflow_graph(
         depth: int | None = None,
         domain: str | None = None,
         limit_nodes: int | None = None,
-    ) -> str:
+    ) -> dict:
         """Return a typed subgraph of the unified workflow graph."""
         return await safe_handler(
             query_workflow_graph.handler,
@@ -198,7 +198,7 @@ def _register_open_visualization(mcp: FastMCP) -> None:
     )
     async def tool_open_visualization(
         domain: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Launch the 3D methodology constellation map in the browser."""
         return await safe_handler(
             open_visualization.handler,
@@ -216,7 +216,7 @@ async def tool_explore_features(
         mode: str,
         domain: str | None = None,
         compare_domain: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Explore interpretability features."""
         return await safe_handler(
             explore_features.handler,

mcp_server/tool_registry_ingest.py

@@ -31,7 +31,7 @@ async def tool_ingest_codebase(
         output_dir: str | None = None,
         language: str = "auto",
         force_reindex: bool = False,
-    ) -> str:
+    ) -> dict:
         """Ingest upstream codebase analysis into Cortex.
 
         No caps. Pulls every Function/Method/Struct/process the upstream
@@ -61,7 +61,7 @@ async def tool_change_impact(
         head: str = "HEAD",
         expand_impact: bool = False,
         apply_heat_bump: bool = False,
-    ) -> str:
+    ) -> dict:
         """Report memories affected by a commit's code changes (ADR-0046 P4)."""
         return await safe_handler(
             change_impact.handler,
@@ -87,7 +87,7 @@ async def tool_ingest_prd(
         title: str | None = None,
         validate: bool = False,
         domain: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Ingest a PRD document into Cortex."""
         return await safe_handler(
             ingest_prd.handler,

mcp_server/tool_registry_manage.py

@@ -40,7 +40,7 @@ async def tool_forget(
         memory_id: int,
         soft: bool = False,
         force: bool = False,
-    ) -> str:
+    ) -> dict:
         """Delete or soft-delete a memory by ID."""
         return await safe_handler(
             forget.handler,
@@ -65,7 +65,7 @@ async def tool_validate_memory(
         base_dir: str | None = None,
         staleness_threshold: float = 0.5,
         dry_run: bool = False,
-    ) -> str:
+    ) -> dict:
         """Validate memories against current filesystem state."""
         return await safe_handler(
             validate_memory.handler,
@@ -89,7 +89,7 @@ def _register_rate_memory(mcp: FastMCP) -> None:
     async def tool_rate_memory(
         memory_id: int,
         useful: bool,
-    ) -> str:
+    ) -> dict:
         """Rate a memory as useful or not to update metamemory confidence."""
         return await safe_handler(
             rate_memory.handler,
@@ -111,7 +111,7 @@ async def tool_seed_project(
         domain: str | None = None,
         max_file_size_kb: int = 64,
         dry_run: bool = False,
-    ) -> str:
+    ) -> dict:
         """Bootstrap memory from an existing codebase."""
         return await safe_handler(
             seed_project.handler,
@@ -133,7 +133,7 @@ def _register_anchor(mcp: FastMCP) -> None:
     async def tool_anchor(
         memory_id: int,
         reason: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Mark a memory as compaction-resistant (heat=1.0)."""
         return await safe_handler(
             anchor.handler,
@@ -156,7 +156,7 @@ async def tool_backfill_memories(
         min_importance: float = 0.35,
         dry_run: bool = False,
         force_reprocess: bool = False,
-    ) -> str:
+    ) -> dict:
         """Auto-import prior Claude Code conversations into memory."""
         return await safe_handler(
             backfill_memories.handler,
@@ -184,7 +184,7 @@ async def tool_codebase_analyze(
         incremental: bool = True,
         dry_run: bool = False,
         domain: str | None = None,
-    ) -> str:
+    ) -> dict:
         """Analyze codebase and store structure as memories."""
         return await safe_handler(
             codebase_analyze.handler,