MCP 응답을 v1 봉투로 통일 (primaryMatch 제거)

search_menu/fetch_menu_raw/health 응답을 우리 v1 봉투(agent/trace_id/ok/elapsed_ms/error)로 통일. results는 {rank,menu_id,menu_name,menu_path,similarity}. 담당자 rule-v1의 primaryMatch는 의미 불일치(우리는 임베딩 quality, 담당자는 확정매칭)로 제거. tool 이름(search_menu/fetch_menu_raw/health)은 게이트웨이 호출용 유지. agentHint는 유효 카테고리면 필터 적용. 로컬 e2e 검증 완료. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

mcp_server.py

@@ -128,21 +128,23 @@ def _strip_scr(menu_id) -> str:
 
 
 # ════════════════════════════════════════════════════════════════════════════
-# Tool) health — 상태 / 버전 / 데이터 건수 / 엔진 버전
+# Tool) health — 상태(liveness/readiness) / 버전 / 데이터 건수 (v1 봉투)
 # ════════════════════════════════════════════════════════════════════════════
 @mcp.tool()
 def health() -> dict:
-    """서버 상태, 빌드 버전, 참조 데이터 건수, 사용 가능한 검색 엔진 버전을 반환한다."""
+    """서버 상태(liveness/readiness)·버전·참조 데이터 건수·엔진을 v1 봉투로 반환한다."""
+    started = time.time()
     try:
         engine = _get_engine()
         stats = engine.vectorstore.get_stats()
-        return {"status": "ok", "version": AGENT_VERSION,
-                "dataCount": stats.get("total_menus", 0),
-                "engines": [ENGINE_VERSION]}
+        return _envelope({"status": "ok", "live": True, "ready": True,
+                          "menu_count": stats.get("total_menus", 0),
+                          "engine": ENGINE_VERSION}, None, started)
     except Exception as e:
         logger.exception("health 실패")
-        return {"status": "error", "version": AGENT_VERSION,
-                "dataCount": 0, "engines": [], "error": str(e)}
+        return _envelope({"status": "error", "live": True, "ready": False},
+                         None, started, ok=False,
+                         error=_err("ENGINE_NOT_READY", "검색엔진 미준비", str(e)))
 
 
 # ════════════════════════════════════════════════════════════════════════════
@@ -172,51 +174,54 @@ def search_menu(
     Returns:
         {version, query, results:[{id, menuName, path}], primaryMatch, [debug]}.
     """
+    started = time.time()
     if not query or not query.strip():
-        return {"version": ENGINE_VERSION, "query": query, "results": [],
-                "primaryMatch": False, "error": "query가 비어있음"}
+        return _envelope({"query": query, "result_count": 0, "results": []},
+                         None, started, ok=False,
+                         error=_err("BAD_REQUEST", "query가 비어있음"))
     try:
         from core.agent import run_agent
         limit = max(1, min(int(limit), 30))
+        # agentHint가 유효 카테고리면 필터로, 아니면 자체 카테고리 감지 사용
+        cat = agentHint if agentHint in CATEGORIES else None
         with _quiet_stdout():   # run_agent 내부 print → stderr (stdout 오염 방지)
-            result = run_agent(query=query, top_n=limit, use_hyde=True)
+            result = run_agent(query=query, top_n=limit,
+                               category_filter=cat, use_hyde=True)
         hits = result.get("search_results", [])
 
         results = []
-        for r in hits:
+        for i, r in enumerate(hits, 1):
             item = {
-                "id": _strip_scr(r.get("menu_id", "")),
-                "menuName": r.get("menu_name", ""),
-                "path": r.get("menu_path", ""),
+                "rank": i,
+                "menu_id": r.get("menu_id", ""),
+                "menu_name": r.get("menu_name", ""),
+                "menu_path": r.get("menu_path", ""),
+                "similarity": round(r.get("similarity", 0.0), 4),
             }
             if verbose:
-                item["score"] = round(r.get("similarity", 0.0), 4)
-                item["matchType"] = ENGINE_VERSION
+                item["category"] = r.get("category")
                 item["keywords"] = r.get("keywords", [])
             results.append(item)
 
-        out = {
-            "version": ENGINE_VERSION,
-            "query": query,
-            "results": results,
-            "primaryMatch": result.get("is_satisfactory", False),
-        }
+        payload = {"query": query, "result_count": len(results), "results": results}
+        if verbose:
+            payload["detected_category"] = result.get("detected_category")
+            payload["intent"] = result.get("intent")
+            payload["quality_score"] = round(result.get("quality_score", 0.0), 4)
         if debug:
-            out["debug"] = {
-                "keywords": [query.strip()],
-                "traces": [{
-                    "toolName": "hydeSearch",
-                    "input": {"query": query,
-                              "refinedQuery": result.get("refined_query", query)},
-                    "output": [{"id": _strip_scr(r.get("menu_id", "")),
-                                "path": r.get("menu_path", "")} for r in hits],
-                }],
+            payload["debug"] = {
+                "refined_query": result.get("refined_query", query),
+                "retry_count": result.get("retry_count", 0),
+                "rewrite_history": result.get("rewrite_history", []),
+                "detected_category": result.get("detected_category"),
+                "intent": result.get("intent"),
             }
-        return out
+        return _envelope(payload, None, started)
     except Exception as e:
         logger.exception("search_menu 실패")
-        return {"version": ENGINE_VERSION, "query": query, "results": [],
-                "primaryMatch": False, "error": str(e)}
+        return _envelope({"query": query, "result_count": 0, "results": []},
+                         None, started, ok=False,
+                         error=_err("INTERNAL", "검색 중 오류", str(e)))
 
 
 # ════════════════════════════════════════════════════════════════════════════
@@ -229,15 +234,17 @@ def fetch_menu_raw() -> dict:
     외부에서 참조 데이터 전체를 받아 검색 결과를 대조 검증하는 용도.
 
     Returns:
-        {version, count, menus:[원본 메뉴 dict, ...]}.
+        v1 봉투 + count + menus:[원본 메뉴 dict, ...].
     """
+    started = time.time()
     try:
         menus = _get_raw_menus()
-        return {"version": ENGINE_VERSION, "count": len(menus),
-                "menus": list(menus.values())}
+        return _envelope({"count": len(menus), "menus": list(menus.values())},
+                         None, started)
     except Exception as e:
         logger.exception("fetch_menu_raw 실패")
-        return {"version": ENGINE_VERSION, "count": 0, "menus": [], "error": str(e)}
+        return _envelope({"count": 0, "menus": []}, None, started, ok=False,
+                         error=_err("INTERNAL", "조회 오류", str(e)))
 
 
 # ════════════════════════════════════════════════════════════════════════════

test_mcp_http.py

@@ -16,7 +16,7 @@ def _show(label, result):
     txt = result.content[0].text if result.content else "{}"
     try:
         obj = json.loads(txt)
-        print(f"\n[{label}] {json.dumps(obj, ensure_ascii=False)[:120]}")
+        print(f"\n[{label}] ok={obj.get('ok')} elapsed={obj.get('elapsed_ms')}ms trace={obj.get('trace_id','')[:8]}")
         return obj
     except Exception:
         print(f"\n[{label}] {txt[:150]}")
@@ -32,13 +32,13 @@ async def main():
             print("=== tools/list ===")
             for t in tools.tools:
                 print(f"  - {t.name}")
-            _show("health", await session.call_tool("health", {}, read_timeout_seconds=TO))
+            r = _show("health", await session.call_tool("health", {}, read_timeout_seconds=TO))
+            print(f"    status={r.get('status')} menu_count={r.get('menu_count')} engine={r.get('engine')}")
             r = _show("search_menu(SOXL 주가)", await session.call_tool(
                 "search_menu", {"query": "SOXL 주가", "limit": 3, "verbose": True},
                 read_timeout_seconds=TO))
-            print(f"    version={r.get('version')} primaryMatch={r.get('primaryMatch')}")
             for it in r.get("results", []):
-                print(f"    - id={it['id']} {it['menuName']} | {it['path']}  score={it.get('score')}")
+                print(f"    {it['rank']}. {it['menu_name']} | {it['menu_path']}  sim={it.get('similarity')}")
             r = _show("fetch_menu_raw()", await session.call_tool(
                 "fetch_menu_raw", {}, read_timeout_seconds=TO))
             print(f"    count={r.get('count')} (첫 메뉴: {(r.get('menus') or [{}])[0].get('menu_path')})")