feat(mcp): detect Connected-but-namespaces-missing attachment failures (Closes #708)

mcp_namespace_health.py

@@ -51,6 +51,14 @@ EOF_PATTERNS = (
     "eof",
 )
 
+ERROR_CONNECTED_NAMESPACES_MISSING = "mcp_connected_namespaces_missing"
+
+UNSAFE_FALLBACK_WARNING = (
+    "Workflow Safety Hard Stop (#708): Connected-but-namespaces-missing recovery must "
+    "NEVER use direct imports, Gitea API mutations, profile hopping, session-state "
+    "overrides, PID kills, or config mtime touches. Use client reconnect only."
+)
+
 SAFE_ENV_KEYS = (
     "GITEA_MCP_PROFILE",
     "GITEA_PROFILE_NAME",
@@ -60,6 +68,83 @@ SAFE_ENV_KEYS = (
 )
 
 
+def assess_connected_namespace_attachment(
+    *,
+    connected_servers: list[str] | tuple[str, ...] | set[str] | None = None,
+    attached_session_namespaces: list[str] | tuple[str, ...] | set[str] | None = None,
+    required_namespaces: list[str] | tuple[str, ...] | set[str] | None = None,
+) -> dict[str, Any]:
+    """Assess whether host-connected MCP servers have attached tool namespaces in the active session (#708).
+
+    Addresses the Connected-but-namespaces-missing defect: CLI/host status may report Connected
+    while the active LLM session tool surface exposes 0 attached tool namespaces.
+
+    Returns structured telemetry and detection details.
+    """
+    connected = [str(s).strip() for s in (connected_servers or []) if str(s).strip()]
+    attached = set(str(ns).strip() for ns in (attached_session_namespaces or []) if str(ns).strip())
+    req = [str(r).strip() for r in (required_namespaces or DEFAULT_NAMESPACES) if str(r).strip()]
+
+    proof: dict[str, dict[str, bool]] = {}
+    missing: list[str] = []
+
+    for s in connected:
+        is_attached = s in attached
+        proof[s] = {"connected": True, "attached": is_attached}
+        if not is_attached and s in req:
+            missing.append(s)
+
+    for r in req:
+        if r not in proof:
+            proof[r] = {"connected": r in connected, "attached": r in attached}
+            if r in connected and r not in attached and r not in missing:
+                missing.append(r)
+
+    attachment_healthy = len(missing) == 0 and len(connected) > 0
+    discovery_status = (
+        "namespaces_attached" if attachment_healthy
+        else ("connected_but_namespaces_missing" if len(connected) > 0 else "disconnected")
+    )
+
+    reasons: list[str] = []
+    remediation: list[str] = []
+    if missing:
+        reasons.append(
+            f"MCP server(s) {missing} report Connected at host/CLI layer but tool namespaces "
+            f"are missing from active session attached tools (Connected ≠ attached tools, #708)."
+        )
+        remediation.append(
+            "Reconnect the IDE/client MCP session to attach namespaces to the active session. "
+            "Do not use direct imports, CLI API mutations, profile hopping, or session file overrides."
+        )
+    elif not connected:
+        reasons.append("No MCP servers reported Connected.")
+        remediation.append("Start or reconnect Gitea MCP servers in client config.")
+    else:
+        reasons.append("All connected MCP server namespaces are attached to the active session.")
+
+    return {
+        "success": attachment_healthy,
+        "attachment_healthy": attachment_healthy,
+        "discovery_status": discovery_status,
+        "connected_servers": connected,
+        "attached_session_namespaces": list(attached),
+        "missing_namespaces": missing,
+        "proof_of_connected_vs_attached": proof,
+        "error_type": None if attachment_healthy else ERROR_CONNECTED_NAMESPACES_MISSING,
+        "reasons": reasons,
+        "remediation": remediation,
+        "exact_next_action": (
+            "Reconnect the IDE/client MCP session so tool namespaces attach to the active session. "
+            "Do not use direct imports, CLI API mutations, profile hopping, or session-state overrides."
+            if not attachment_healthy
+            else "None; session tool namespaces attached."
+        ),
+        "unsafe_fallback_policy": UNSAFE_FALLBACK_WARNING,
+    }
+
+
+
 def _as_list(value: Any) -> list[str] | None:
     if value is None:
         return None