Unified Health Status: Consistent server health across CLI, tray, web UI, and MCP tools

[technicalpickles]

Problem Statement

MCPProxy currently displays inconsistent server health status across its four interfaces:

1. CLI reads oauth_status and shows "Token Expired"
2. Tray only checks HTTP connectivity and shows "Healthy"
3. Web UI may show different status based on its own interpretation
4. MCP Tools (upstream_servers list) return raw connection state fields without unified health interpretation

This leads to user confusion when the same server shows different states in different interfaces. LLMs interacting via MCP tools must interpret raw fields (connection_status.state, enabled, quarantined, oauth_status) and calculate health themselves, leading to inconsistent conclusions.

Additionally, when servers have issues, users often don't know what action to take to resolve them.

Proposed Solution

Implement a single source of truth for server health calculated in the backend, with consistent display across all four interfaces:

1. Unified Health Status Model

Each server will have a health field with:

• Level: healthy (green), degraded (yellow), unhealthy (red)
• Admin State: enabled, disabled, quarantined - separate from health
• Summary: Human-readable status message (e.g., "Connected (5 tools)", "Token expiring in 45m")
• Action: Suggested fix (login, restart, enable, approve, view_logs)

2. Consistent Display

Interface	Before	After
CLI	Multiple fields to interpret	Single emoji + summary + action hint
Tray	Basic connectivity	Full health with colored status
Web UI	Varies	Colored badge + action button
MCP Tools	Raw fields	Nested health object

3. Actionable Guidance

Every unhealthy or degraded state will include a suggested action:

• Token expired → "auth login --server=X"
• Connection refused → "upstream restart X"
• Quarantined → "Approve in Web UI"

User Stories

1. Consistent Status: Users see identical health status across all interfaces
2. Actionable Guidance: Users know exactly what command/button to use to fix issues
3. OAuth Visibility: Token expiration visible in tray/web (not just CLI)
4. Admin State Clarity: Disabled/quarantined shown as intentional states, not errors
5. LLM Support: LLMs can determine server health from a single MCP tool call

Technical Approach

• Backend calculates health once in GetAllServers() using deterministic priority rules
• All interfaces consume the same HealthStatus struct
• No breaking changes - health field is additive to existing responses

Follow-up

A PR will follow with the complete specification and implementation plan in specs/012-unified-health-status/.

---

Related Design: docs/designs/2025-12-10-unified-health-status.md