Fix health endpoint to comply with MCP Gateway Spec v1.3.0 Section 8.1.1

[Copilot]

The /health endpoint returned a non-compliant response format with status: "ok", protocolVersion, and version fields instead of the spec-required status: "healthy|unhealthy", specVersion, gatewayVersion, and servers fields.

Changes

internal/server/unified.go:

• Added MCPGatewaySpecVersion = "1.3.0" constant
• Added ServerStatus struct with status and uptime fields
• Added GetServerStatus() method returning server health map
• Added StartTime field to Session for uptime tracking

internal/server/routed.go and internal/server/transport.go:

• Changed response status from "ok" to "healthy" (or "unhealthy" when servers error)
• Replaced protocolVersion with specVersion: "1.3.0"
• Renamed version to gatewayVersion
• Added servers field with server status map

internal/server/health_test.go:

• Updated assertions to verify spec-compliant response structure
• Changed response type from map[string]string to map[string]interface{}

Response Format

Before:

{
  "status": "ok",
  "protocolVersion": "2024-11-05",
  "version": "dev"
}

After:

{
  "status": "healthy",
  "specVersion": "1.3.0",
  "gatewayVersion": "dev",
  "servers": {
    "github": {
      "status": "running",
      "uptime": 0
    }
  }
}

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[compliance] Health Endpoint Non-Compliance with Specification Section 8.1.1</issue_title>
<issue_description>## Summary

The /health endpoint does not conform to the MCP Gateway Specification v1.3.0, Section 8.1.1. Despite PR #140 titled "update-health-endpoint", the endpoint response format does not match the required specification.

Specification Version: 1.3.0
Commit Reviewed: 2e8c29f
Severity: Critical (MUST violation)

---

Critical Issue: Incorrect Health Endpoint Response Format

Specification Requirement (Section 8.1.1)

Deep Link: https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#811-general-health-health

The specification REQUIRES the following response format:

{
  "status": "healthy" | "unhealthy",
  "specVersion": "string",
  "gatewayVersion": "string",
  "servers": {
    "server-name": {
      "status": "running" | "stopped" | "error",
      "uptime": 12345
    }
  }
}

Required Fields (per spec):

• ✅ status (string, Yes) - Overall gateway health status: "healthy" or "unhealthy"
• ❌ specVersion (string, Yes) - MCP Gateway Specification version (e.g., "1.3.0")
• ❌ gatewayVersion (string, Yes) - Gateway implementation version (e.g., "0.1.0")
• ❌ servers (object, Yes) - Map of server names to their health status

Current Implementation

Files:

• internal/server/routed.go:114-120
• internal/server/transport.go:162-168
• internal/server/server.go:53-58

Current Response:

{
  "status": "ok",
  "protocolVersion": "2024-11-05",
  "version": "dev"
}

Problems:

1. ❌ Returns "status": "ok" instead of "status": "healthy" or "status": "unhealthy"
2. ❌ Missing required field: specVersion (specification version like "1.3.0")
3. ❌ Returns version instead of required field: gatewayVersion
4. ❌ Missing required field: servers (server health status map)
5. ❌ Returns protocolVersion which is not part of the spec

Specification Quote

Requirements:

The gateway MUST include the following version information in the /health endpoint response:

1. specVersion: The version of this MCP Gateway Specification that the implementation conforms to. This field MUST use semantic versioning (MAJOR.MINOR.PATCH format).
2. gatewayVersion: The version of the gateway implementation itself. This field MUST use semantic versioning and represents the specific build or release version of the gateway software.

These version fields enable clients to:

• Verify specification compatibility
• Detect implementation versions for debugging
• Track deployment versions across environments
• Ensure feature availability based on specification version

Deep Link: https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#L680-L692

---

Impact

This non-compliance affects:

1. Client Compatibility: Clients expecting spec-compliant responses will fail to parse the health endpoint
2. Version Detection: Clients cannot determine which specification version the gateway implements
3. Server Monitoring: No visibility into individual server health status
4. Debugging: Missing version information makes troubleshooting difficult
5. Compliance Testing: Fails test cases T-HLT-006 through T-HLT-009

Related Test Requirements:

• T-HLT-006: Health response includes specVersion field
• T-HLT-007: Health response includes gatewayVersion field
• T-HLT-008: specVersion uses semantic versioning format
• T-HLT-009: gatewayVersion uses semantic versioning format

---

Root Cause

PR #140 was titled "update-health-endpoint" but appears to have not actually updated the response format to match specification v1.3.0. The endpoint implementation in routed.go, transport.go, and server.go all use the old response format.

---

Remediation Tasks

Task 1: Update Health Endpoint Response Format

Description: Modify all health endpoint handlers to return spec-compliant response

Files to Modify:

• internal/server/routed.go (lines 114-120)
• internal/server/transport.go (lines 162-168)
• internal/server/server.go (lines 53-58)

Required Changes:

1. Add specVersion field: Return the specification version (e.g., "1.3.0")
2. Rename version to gatewayVersion: Use the gateway implementation version
3. Remove protocolVersion field: Not part of the spec
4. Change status values: Use "healthy" or "unhealthy" instead of "ok"
5. Add servers field: Include map of server health status

Example Implementation:

healthHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.Sta...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes githubnext/gh-aw-mcpg#143

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.