feat(health): implement unified health status across all interfaces

Complete implementation of the unified health status feature (012):

## Backend (already committed)
- HealthStatus struct with level, admin_state, summary, detail, action
- CalculateHealth() function in internal/health/calculator.go
- Health field added to contracts.Server

## CLI
- Updated upstream list to use health.level for status emoji
- Added action hints column showing CLI commands for fixes
- Distinct indicators for disabled/quarantined admin states

## Tray App
- Updated getServerStatusDisplay() to use unified health status
- Health-based status indicators (green/orange/red/paused/locked)
- Added restart action menu items based on health.action

## Web UI
- ServerCard.vue uses health.level for badge color
- Added action buttons (Login, Restart, Enable, Approve, View Logs)
- HealthStatus TypeScript interface in contracts.ts

## Dashboard
- X servers need attention banner for degraded/unhealthy servers
- Quick-fix action buttons in banner
- Filters out disabled/quarantined from attention list

## Documentation
- Updated CLAUDE.md with health status documentation
- Added HealthStatus schema to oas/swagger.yaml
- Created followup doc for verify-oas-coverage.sh issues

All 44 tasks complete.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: technicalpickles

CLAUDE.md

@@ -522,6 +522,41 @@ open "http://127.0.0.1:8080/ui/?apikey=your-api-key"
 - **REST API** requires authentication - API key is always enforced (auto-generated if not provided)
 - **Secure by default**: Empty or missing API keys trigger automatic generation and persistence to config
 
+### Unified Health Status
+
+All server responses include a `health` field that provides consistent status information across all interfaces (CLI, web UI, tray, MCP tools):
+
+```json
+{
+  "health": {
+    "level": "healthy|degraded|unhealthy",
+    "admin_state": "enabled|disabled|quarantined",
+    "summary": "Human-readable status summary",
+    "detail": "Additional context about the status",
+    "action": "login|restart|enable|approve|view_logs|"
+  }
+}
+```
+
+**Health Levels**:
+- `healthy`: Server is connected and functioning normally
+- `degraded`: Server has warnings (e.g., OAuth token expiring soon)
+- `unhealthy`: Server has errors or is not functioning
+
+**Admin States**:
+- `enabled`: Normal operation
+- `disabled`: User disabled the server
+- `quarantined`: Server pending security approval
+
+**Actions**: Suggested remediation action for the current state. Empty when no action is needed.
+
+**Configuration**: Token expiry warning threshold can be configured:
+```json
+{
+  "oauth_expiry_warning_hours": 24
+}
+```
+
 ## JavaScript Code Execution
 
 The `code_execution` tool enables orchestrating multiple upstream MCP tools in a single request using sandboxed JavaScript (ES5.1+).

cmd/mcpproxy/upstream_cmd.go

@@ -700,24 +700,3 @@ func runUpstreamBulkAction(action string, force bool) error {
 
 	return nil
 }
-
-// formatDurationShort formats a duration into a short human-readable string for table display
-func formatDurationShort(d time.Duration) string {
-	if d < 0 {
-		return "expired"
-	}
-
-	days := int(d.Hours() / 24)
-	hours := int(d.Hours()) % 24
-
-	if days > 30 {
-		return fmt.Sprintf("%dd", days)
-	} else if days > 0 {
-		return fmt.Sprintf("%dd %dh", days, hours)
-	} else if hours > 0 {
-		return fmt.Sprintf("%dh", hours)
-	} else {
-		minutes := int(d.Minutes())
-		return fmt.Sprintf("%dm", minutes)
-	}
-}

docs/followups/2025-12-11-verify-oas-coverage-script.md

@@ -0,0 +1,60 @@
+# Follow-up: verify-oas-coverage.sh Script Issues
+
+**Date**: 2025-12-11
+**Related Feature**: 012-unified-health-status
+**Priority**: Low (script works but output is misleading)
+
+## Issue
+
+The `scripts/verify-oas-coverage.sh` script has issues that cause misleading output:
+
+1. **Endpoint prefix mismatch**: The script extracts routes without the `/api/v1` prefix, but the OAS file documents them with the full path. This causes false "missing" reports.
+
+2. **Uppercase artifact**: The sed command `\U\1` uppercases the HTTP method but also adds a "U" prefix to the path (e.g., `UGet /config` instead of `GET /config`).
+
+3. **Coverage calculation is incorrect**: Shows "Coverage: 100%" even when listing 37 "missing" endpoints because the comparison logic doesn't properly match routes.
+
+## Example Output (Problematic)
+
+```
+❌ Missing OAS documentation for:
+  UDelete /{name}
+  UGet /config
+  ...
+
+📊 Coverage Statistics:
+  Total endpoints:     37
+  Documented:          37
+  Missing:             37
+  Coverage:            100.0%    <-- This is wrong
+```
+
+## Root Cause
+
+The route extraction from Go files captures relative paths like `/config`, but the OAS file documents them as `/api/v1/config`. The comparison fails to match these.
+
+## Fix Applied (Partial)
+
+Fixed the bash syntax error where inline comments appeared after backslash line continuations (lines 45-47). This was causing "command not found" errors.
+
+## Remaining Work
+
+1. Update the sed pattern to not add "U" prefix to paths
+2. Either:
+   - Add `/api/v1` prefix to extracted routes, OR
+   - Strip `/api/v1` prefix from OAS paths for comparison
+3. Fix the coverage calculation logic
+
+## Verification Steps
+
+```bash
+# Run the script and verify:
+# 1. No "command not found" errors
+# 2. Routes show as "GET /api/v1/config" not "UGet /config"
+# 3. Coverage percentage matches actual missing count
+./scripts/verify-oas-coverage.sh
+```
+
+## Files Affected
+
+- `scripts/verify-oas-coverage.sh`

frontend/src/components/ServerCard.vue

@@ -10,16 +10,14 @@
           </p>
         </div>
 
-        <!-- Status indicator -->
+        <!-- Status indicator using unified health status -->
         <div
           :class="[
             'badge badge-sm flex-shrink-0',
-            server.connected ? 'badge-success' :
-            server.connecting ? 'badge-warning' :
-            'badge-error'
+            statusBadgeClass
           ]"
         >
-          {{ server.connected ? 'Connected' : server.connecting ? 'Connecting' : 'Disconnected' }}
+          {{ statusText }}
         </div>
       </div>
 
@@ -65,39 +63,58 @@
         <span class="text-xs">Server is quarantined</span>
       </div>
 
-      <!-- Actions -->
+      <!-- Actions - uses unified health.action when available -->
       <div class="card-actions justify-end space-x-2">
+        <!-- Primary action button based on health.action -->
         <button
-          v-if="server.quarantined"
+          v-if="healthAction === 'approve'"
           @click="unquarantine"
           :disabled="loading"
           class="btn btn-sm btn-warning"
         >
           <span v-if="loading" class="loading loading-spinner loading-xs"></span>
-          Unquarantine
+          Approve
         </button>
 
-        <!-- Restart button only for stdio servers (HTTP servers use Login/Reconnect) -->
         <button
-          v-if="!server.connected && server.enabled && !isHttpProtocol"
-          @click="restart"
+          v-if="healthAction === 'enable'"
+          @click="enableServer"
           :disabled="loading"
-          class="btn btn-sm btn-outline"
+          class="btn btn-sm btn-primary"
         >
           <span v-if="loading" class="loading loading-spinner loading-xs"></span>
-          Restart
+          Enable
         </button>
 
         <button
-          v-if="needsOAuth"
+          v-if="healthAction === 'login'"
           @click="triggerOAuth"
           :disabled="loading"
-          class="btn btn-sm btn-outline"
+          class="btn btn-sm btn-primary"
         >
           <span v-if="loading" class="loading loading-spinner loading-xs"></span>
           Login
         </button>
 
+        <button
+          v-if="healthAction === 'restart'"
+          @click="restart"
+          :disabled="loading"
+          class="btn btn-sm btn-primary"
+        >
+          <span v-if="loading" class="loading loading-spinner loading-xs"></span>
+          Restart
+        </button>
+
+        <router-link
+          v-if="healthAction === 'view_logs'"
+          :to="`/servers/${server.name}?tab=logs`"
+          class="btn btn-sm btn-primary"
+        >
+          View Logs
+        </router-link>
+
+        <!-- Logout button (only when connected with OAuth) -->
         <button
           v-if="canLogout"
           @click="triggerLogout"
@@ -178,6 +195,52 @@ const isHttpProtocol = computed(() => {
   return props.server.protocol === 'http' || props.server.protocol === 'streamable-http'
 })
 
+// Unified health status computed properties
+const statusBadgeClass = computed(() => {
+  const health = props.server.health
+  if (health) {
+    // Use admin_state for disabled/quarantined, otherwise use health level
+    switch (health.admin_state) {
+      case 'disabled':
+        return 'badge-neutral' // gray
+      case 'quarantined':
+        return 'badge-secondary' // purple-ish
+      default:
+        // Use health level
+        switch (health.level) {
+          case 'healthy':
+            return 'badge-success'
+          case 'degraded':
+            return 'badge-warning'
+          case 'unhealthy':
+            return 'badge-error'
+          default:
+            return 'badge-ghost'
+        }
+    }
+  }
+  // Fallback to legacy logic
+  if (props.server.connected) return 'badge-success'
+  if (props.server.connecting) return 'badge-warning'
+  return 'badge-error'
+})
+
+const statusText = computed(() => {
+  const health = props.server.health
+  if (health) {
+    return health.summary || health.level
+  }
+  // Fallback to legacy logic
+  if (props.server.connected) return 'Connected'
+  if (props.server.connecting) return 'Connecting'
+  return 'Disconnected'
+})
+
+// Suggested action from health status
+const healthAction = computed(() => {
+  return props.server.health?.action || ''
+})
+
 const needsOAuth = computed(() => {
   // Don't show Login button if server is disabled
   if (!props.server.enabled) return false
@@ -305,6 +368,26 @@ async function toggleEnabled() {
   }
 }
 
+async function enableServer() {
+  loading.value = true
+  try {
+    await serversStore.enableServer(props.server.name)
+    systemStore.addToast({
+      type: 'success',
+      title: 'Server Enabled',
+      message: `${props.server.name} has been enabled`,
+    })
+  } catch (error) {
+    systemStore.addToast({
+      type: 'error',
+      title: 'Enable Failed',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    })
+  } finally {
+    loading.value = false
+  }
+}
+
 async function restart() {
   loading.value = true
   try {

frontend/src/types/contracts.ts

@@ -8,6 +8,14 @@ export interface APIResponse<T = any> {
   error?: string;
 }
 
+export interface HealthStatus {
+  level: 'healthy' | 'degraded' | 'unhealthy';
+  admin_state: 'enabled' | 'disabled' | 'quarantined';
+  summary: string;
+  detail?: string;
+  action?: 'login' | 'restart' | 'enable' | 'approve' | 'view_logs' | '';
+}
+
 export interface Server {
   id: string;
   name: string;
@@ -37,6 +45,7 @@ export interface Server {
   oauth_status?: 'authenticated' | 'expired' | 'error' | 'none'; // OAuth authentication status
   token_expires_at?: string; // ISO date string when OAuth token expires
   user_logged_out?: boolean; // True if user explicitly logged out (prevents auto-reconnection)
+  health?: HealthStatus; // Unified health status calculated by the backend
 }
 
 export interface OAuthConfig {