|
| 1 | +# OpenAPI 3.1 Additions for Unified Health Status |
| 2 | +# This file documents the new HealthStatus schema and its integration |
| 3 | +# into existing endpoints. Merge into oas/swagger.yaml during implementation. |
| 4 | + |
| 5 | +openapi: 3.1.0 |
| 6 | +info: |
| 7 | + title: MCPProxy Unified Health Status API Additions |
| 8 | + version: 1.0.0 |
| 9 | + description: | |
| 10 | + Schema definitions and endpoint changes for the unified health status feature. |
| 11 | + This provides consistent health information across CLI, tray, web UI, and MCP tools. |
| 12 | +
|
| 13 | +components: |
| 14 | + schemas: |
| 15 | + # New schema: HealthStatus |
| 16 | + HealthStatus: |
| 17 | + type: object |
| 18 | + required: |
| 19 | + - level |
| 20 | + - admin_state |
| 21 | + - summary |
| 22 | + properties: |
| 23 | + level: |
| 24 | + type: string |
| 25 | + enum: |
| 26 | + - healthy |
| 27 | + - degraded |
| 28 | + - unhealthy |
| 29 | + description: | |
| 30 | + Health level indicating server readiness: |
| 31 | + - healthy: Server is ready and functioning normally |
| 32 | + - degraded: Server works but needs attention soon (e.g., token expiring) |
| 33 | + - unhealthy: Server is broken and cannot be used until fixed |
| 34 | + example: "healthy" |
| 35 | + |
| 36 | + admin_state: |
| 37 | + type: string |
| 38 | + enum: |
| 39 | + - enabled |
| 40 | + - disabled |
| 41 | + - quarantined |
| 42 | + description: | |
| 43 | + Administrative state of the server: |
| 44 | + - enabled: Server is active and participating in tool discovery |
| 45 | + - disabled: Server is intentionally turned off by the user |
| 46 | + - quarantined: Server is pending security review before activation |
| 47 | + example: "enabled" |
| 48 | + |
| 49 | + summary: |
| 50 | + type: string |
| 51 | + maxLength: 100 |
| 52 | + description: | |
| 53 | + Human-readable status message suitable for display in all interfaces. |
| 54 | + Examples: "Connected (5 tools)", "Token expiring in 45m", "Connection refused" |
| 55 | + example: "Connected (5 tools)" |
| 56 | + |
| 57 | + detail: |
| 58 | + type: string |
| 59 | + description: | |
| 60 | + Optional longer explanation providing additional context for debugging. |
| 61 | + May include technical details not shown in the summary. |
| 62 | + example: "Last error: connection refused at 10.0.0.1:3000" |
| 63 | + |
| 64 | + action: |
| 65 | + type: string |
| 66 | + enum: |
| 67 | + - "" |
| 68 | + - login |
| 69 | + - restart |
| 70 | + - enable |
| 71 | + - approve |
| 72 | + - view_logs |
| 73 | + description: | |
| 74 | + Suggested action to resolve the issue: |
| 75 | + - "" (empty): No action needed (healthy state) |
| 76 | + - login: OAuth authentication required |
| 77 | + - restart: Server needs to be restarted |
| 78 | + - enable: Server is disabled and should be enabled |
| 79 | + - approve: Server is quarantined and needs security approval |
| 80 | + - view_logs: Check server logs for more details |
| 81 | + example: "" |
| 82 | + |
| 83 | + # Modified schema: Server (showing health field addition) |
| 84 | + Server: |
| 85 | + type: object |
| 86 | + description: | |
| 87 | + Upstream MCP server configuration and status. |
| 88 | + Now includes a unified health field. |
| 89 | + properties: |
| 90 | + # ... existing properties (id, name, url, protocol, etc.) ... |
| 91 | + |
| 92 | + health: |
| 93 | + $ref: '#/components/schemas/HealthStatus' |
| 94 | + description: | |
| 95 | + Unified health status calculated by the backend. |
| 96 | + Always populated for API responses; all interfaces should use this |
| 97 | + for consistent status display instead of calculating from raw fields. |
| 98 | +
|
| 99 | +# Endpoint changes documentation (for reference) |
| 100 | +paths: |
| 101 | + /api/v1/servers: |
| 102 | + get: |
| 103 | + summary: List all upstream servers |
| 104 | + description: | |
| 105 | + Returns all configured upstream MCP servers with their current status. |
| 106 | +
|
| 107 | + **Change in this feature**: Each server in the response now includes a |
| 108 | + `health` field containing the unified health status. Clients should use |
| 109 | + this field for status display instead of interpreting raw connection fields. |
| 110 | + responses: |
| 111 | + '200': |
| 112 | + description: List of servers with health status |
| 113 | + content: |
| 114 | + application/json: |
| 115 | + schema: |
| 116 | + type: object |
| 117 | + properties: |
| 118 | + servers: |
| 119 | + type: array |
| 120 | + items: |
| 121 | + $ref: '#/components/schemas/Server' |
| 122 | + stats: |
| 123 | + type: object |
| 124 | + description: Aggregated server statistics |
| 125 | + example: |
| 126 | + servers: |
| 127 | + - id: "abc123" |
| 128 | + name: "github" |
| 129 | + protocol: "http" |
| 130 | + enabled: true |
| 131 | + connected: true |
| 132 | + tool_count: 5 |
| 133 | + health: |
| 134 | + level: "healthy" |
| 135 | + admin_state: "enabled" |
| 136 | + summary: "Connected (5 tools)" |
| 137 | + action: "" |
| 138 | + - id: "def456" |
| 139 | + name: "slack" |
| 140 | + protocol: "http" |
| 141 | + enabled: true |
| 142 | + connected: true |
| 143 | + oauth_status: "expiring" |
| 144 | + tool_count: 10 |
| 145 | + health: |
| 146 | + level: "degraded" |
| 147 | + admin_state: "enabled" |
| 148 | + summary: "Token expiring in 45m" |
| 149 | + action: "login" |
| 150 | + - id: "ghi789" |
| 151 | + name: "filesystem" |
| 152 | + protocol: "stdio" |
| 153 | + enabled: true |
| 154 | + connected: false |
| 155 | + last_error: "connection refused" |
| 156 | + health: |
| 157 | + level: "unhealthy" |
| 158 | + admin_state: "enabled" |
| 159 | + summary: "Connection refused" |
| 160 | + action: "restart" |
| 161 | + - id: "jkl012" |
| 162 | + name: "new-server" |
| 163 | + protocol: "http" |
| 164 | + enabled: true |
| 165 | + quarantined: true |
| 166 | + health: |
| 167 | + level: "healthy" |
| 168 | + admin_state: "quarantined" |
| 169 | + summary: "Quarantined for review" |
| 170 | + action: "approve" |
| 171 | + stats: |
| 172 | + total_servers: 4 |
| 173 | + connected_servers: 2 |
| 174 | + quarantined_servers: 1 |
| 175 | + |
| 176 | +# MCP Protocol Changes (documentation only - not OpenAPI) |
| 177 | +# The MCP upstream_servers tool with operation: list will include the same |
| 178 | +# health field structure in its response for LLM consumption. |
0 commit comments