fix(recall): align handler output with declared outputSchema (#46)

Three drifts between mcp_server/handlers/recall.py's outputSchema and
its handler implementation made every recall MCP call fail with
``Output validation error: 'memories' is a required property``:

  1. Key names — handler returned ``results``/``total``/``query_intent``
     while the schema required ``memories``/``count``/``intent``.
  2. Intent enum — schema allowed 6 values but core.query_intent.QueryIntent
     defines 11. Any query falling back to QueryIntent.GENERAL ("general")
     would have failed enum validation even after the key rename.
  3. Early return — the ``if not args or not args.get("query")`` branch
     returned ``{"results": [], "total": 0}``, missing the
     schema-required ``memories`` key entirely.

Fix:

  • _handler_impl returns the schema-aligned ``memories``/``count``/
    ``intent`` keys AND keeps ``results``/``total``/``query_intent`` as
    back-compat aliases for one minor release.
  • Early return now includes the schema-required keys plus the
    back-compat ones, so even no-query calls validate.
  • outputSchema enum broadened to match QueryIntent's full set
    (added: instruction, event_order, summarization, preference, general)
    so the classifier's GENERAL fallback no longer fails MCP validation.

Two new tests prove the fix:
  • test_issue_46_schema_aligned_keys — early-return + empty-query paths
    carry the required keys.
  • test_issue_46_intent_in_schema_enum — every public string constant on
    QueryIntent must be in the broadened schema enum.

Reported by @darval. Verified locally; the broken pre-existing
test_recall_stored_memory unrelated to this fix (fails due to
sqlite_compat missing ``heat`` column — separate sweep).

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

Author: cdeust

mcp_server/handlers/recall.py

@@ -58,13 +58,24 @@
             },
             "intent": {
                 "type": "string",
+                # source: mcp_server/core/query_intent.py::QueryIntent — every
+                # value the classifier can emit must be in this enum or MCP
+                # output validation rejects the response. Previously the
+                # schema was narrower than the classifier's range, so any
+                # query falling back to QueryIntent.GENERAL ("general")
+                # failed validation. Issue #46.
                 "enum": [
                     "temporal",
                     "causal",
                     "semantic",
                     "entity",
                     "knowledge_update",
                     "multi_hop",
+                    "instruction",
+                    "event_order",
+                    "summarization",
+                    "preference",
+                    "general",
                 ],
                 "description": "Classified query intent that drove the signal-weight profile.",
             },
@@ -262,7 +273,16 @@ def _track_recall_replay(results: list[dict], store: Any) -> None:
 async def _handler_impl(args: dict[str, Any] | None = None) -> dict[str, Any]:
     """Retrieve memories: pg_recall base + production enrichments."""
     if not args or not args.get("query"):
-        return {"results": [], "total": 0}
+        # Issue #46: even the early-return must satisfy the outputSchema's
+        # required keys (`memories`). The legacy `results`/`total` are
+        # kept for back-compat with consumers that haven't migrated yet.
+        return {
+            "memories": [],
+            "count": 0,
+            "intent": "semantic",
+            "results": [],
+            "total": 0,
+        }
 
     query = args["query"]
     domain, directory = args.get("domain"), args.get("directory")
@@ -315,11 +335,21 @@ async def _handler_impl(args: dict[str, Any] | None = None) -> dict[str, Any]:
 
     intent_info = classify_query_intent(query)
     intent = intent_info.get("intent", QueryIntent.GENERAL)
+    # Issue #46: align the response with the declared outputSchema while
+    # preserving the legacy keys (`results`/`total`/`query_intent`) for
+    # consumers that already migrated to them. The schema enum was
+    # broadened to include every QueryIntent value so the classifier's
+    # `general` fallback no longer fails validation.
     return {
+        "memories": results,
+        "count": len(results),
+        "intent": str(intent),
+        # Back-compat aliases — drop after one minor release once consumers
+        # migrate to the schema-aligned key names.
         "results": results,
         "total": len(results),
-        "low_signal_dropped": low_signal_dropped,
         "query_intent": intent,
+        "low_signal_dropped": low_signal_dropped,
         "dispatch_tier": "pg",
         "signals": {},
         "enhancements": build_enhancements(query, intent, "pg", settings),

tests_py/handlers/test_recall.py

@@ -55,6 +55,60 @@ def test_empty_query_returns_empty(self):
         result = asyncio.run(recall_handler({"query": ""}))
         assert result["results"] == []
 
+    def test_issue_46_schema_aligned_keys(self):
+        """Issue #46: every recall response must satisfy the MCP outputSchema.
+
+        Schema requires: ``memories`` (array). Strictly enforced by Claude
+        Code's MCP host, which would otherwise reject the response with
+        ``Output validation error: 'memories' is a required property``.
+
+        Back-compat aliases (``results``/``total``/``query_intent``) stay
+        for one minor release so existing consumers don't break.
+        """
+        # Early-return path (no query)
+        result = asyncio.run(recall_handler(None))
+        assert "memories" in result, "issue #46: schema requires 'memories' key"
+        assert "count" in result, "issue #46: schema declares 'count'"
+        assert "intent" in result, "issue #46: schema declares 'intent'"
+        assert result["memories"] == []
+        assert result["count"] == 0
+        # Back-compat aliases still present
+        assert "results" in result and "total" in result
+
+        # Empty-query path
+        result = asyncio.run(recall_handler({"query": ""}))
+        assert "memories" in result
+        assert result["memories"] == []
+        assert "intent" in result
+
+    def test_issue_46_intent_in_schema_enum(self):
+        """Issue #46 drift 2: any string the classifier emits must be in
+        the schema's intent enum, or MCP validation rejects it. Verify
+        the early-return uses an enum-valid value and that the broadened
+        enum includes every QueryIntent constant (so the GENERAL fallback
+        no longer fails)."""
+        from mcp_server.core.query_intent import QueryIntent
+        # The schema's broadened enum should include EVERY public string
+        # constant on QueryIntent so the classifier can't produce an
+        # out-of-enum value.
+        schema_enum = {
+            "temporal", "causal", "semantic", "entity", "knowledge_update",
+            "multi_hop", "instruction", "event_order", "summarization",
+            "preference", "general",
+        }
+        for attr in dir(QueryIntent):
+            if attr.startswith("_") or attr != attr.upper():
+                continue
+            value = getattr(QueryIntent, attr)
+            if isinstance(value, str):
+                assert value in schema_enum, (
+                    f"QueryIntent.{attr}={value!r} missing from recall "
+                    f"outputSchema enum — would fail MCP validation"
+                )
+        # Early-return uses a schema-valid intent
+        result = asyncio.run(recall_handler(None))
+        assert result["intent"] in schema_enum
+
     def test_recall_stored_memory(self):
         # Store a memory first
         asyncio.run(