feat: add health check endpoint for container orchestration (#198)

## Summary

Implements a basic health check endpoint (`/health`) for the MCP server
to support container orchestration systems like Kubernetes and Docker
Compose.

## Changes

- ✅ Add `/health` endpoint using FastMCP's custom_route decorator
- ✅ Health check handler returns server status, timestamp, and version
info
- ✅ Transport-aware registration (only enabled for HTTP/SSE transports)
- ✅ Comprehensive unit and integration tests
- ✅ Updated Docker container test to verify health endpoint

## Implementation Details

### Health Check Response Format
```json
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "server": {
    "name": "quilt-mcp-server",
    "version": "1.0.0",
    "transport": "http"
  }
}
```

### Transport Compatibility
- **HTTP/SSE/Streamable-HTTP**: Health endpoint registered at `/health`
- **stdio**: No HTTP endpoints (maintains compatibility)

## Testing

- [x] Unit tests for health check handler
- [x] Integration tests for FastMCP registration
- [x] Docker container test validates health endpoint
- [x] All existing tests pass

## Documentation

Complete specification documents created in
`spec/197-add-health-checks/`:
- `01-requirements.md` - User stories and acceptance criteria
- `02-analysis.md` - Current state analysis
- `03-specifications.md` - Desired end state
- `04-phases.md` - Implementation roadmap

## Future Phases

This PR implements Phase 1 of the health check feature. Future
enhancements:
- Phase 2: Component health integration (AWS, Athena, packages)
- Phase 3: Advanced endpoints (/readiness, /liveness)
- Phase 4: Docker HEALTHCHECK and Kubernetes probe support

Fixes #197

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

Co-Authored-By: Claude <[email protected]>

Author: drernie

CHANGELOG.md

@@ -6,6 +6,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.14] - 2025-09-24
+
+### Added
+
+- **Health Check Endpoint**: Basic health monitoring for container orchestration (#197)
+  - New `/health` endpoint returning server status, timestamp, and version info
+  - Transport-aware registration (only enabled for HTTP/SSE/streamable-http transports)
+  - Comprehensive test coverage for health check functionality
+  - Foundation for future enhancements (component health, readiness/liveness probes)
+
+### Changed
+
+- **Docker Integration Tests**: Enhanced to verify health check endpoint availability
+  - Tests now validate both `/mcp` and `/health` endpoints
+  - Ensures health check responses include proper server metadata
+
 ## [0.6.13] - 2025-09-22
 
 ### Added

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quilt-mcp"
-version = "0.6.13"
+version = "0.6.14"
 description = "Secure MCP server for accessing Quilt data with JWT authentication"
 readme = "README.md"
 requires-python = ">=3.11"

spec/197-add-health-checks/01-requirements.md

@@ -0,0 +1,164 @@
+# Health Check Endpoints Requirements
+
+**Issue Reference**: GitHub Issue #197 - Add Health Checks to MCP Server
+**Branch**: `197-add-health-checks`
+**Status**: Requirements Analysis
+
+## Problem Statement
+
+The Quilt MCP server currently lacks standardized health check endpoints that are essential for container orchestration, monitoring systems, and production deployments. While internal health check functionality exists in the codebase (via `error_recovery.health_check_with_recovery()`), there is no exposed HTTP endpoint that external systems can use to monitor server health status.
+
+This creates challenges for:
+1. Container orchestration platforms (Kubernetes, Docker Compose) that need health probes
+2. Load balancers and reverse proxies requiring health check endpoints
+3. Monitoring and alerting systems that track service availability
+4. DevOps workflows that need to verify deployment success
+
+## User Stories
+
+### US1: Container Orchestration Health Probes
+
+**As a** DevOps engineer deploying the MCP server in Kubernetes or Docker Compose
+**I want** standardized health check endpoints (`/health`, `/readiness`, `/liveness`)
+**So that** the orchestration system can automatically restart unhealthy containers and route traffic only to ready instances
+
+**Acceptance Criteria:**
+1. `/health` endpoint returns HTTP 200 with JSON status when server is healthy
+2. `/health` endpoint returns HTTP 503 with error details when server is unhealthy
+3. `/readiness` endpoint indicates when server is ready to accept MCP requests
+4. `/liveness` endpoint indicates when server process is running and responsive
+5. All endpoints work across HTTP, SSE, and stdio transport modes
+6. Health check endpoints do not require MCP authentication
+7. Response format follows standard health check conventions
+
+### US2: Monitoring and Alerting Integration
+
+**As a** Site Reliability Engineer monitoring production MCP deployments
+**I want** detailed health status information with component-level diagnostics
+**So that** I can set up accurate alerts and quickly identify the root cause of issues
+
+**Acceptance Criteria:**
+1. Health endpoints return structured JSON with overall status and component details
+2. Component-level status includes: authentication, AWS connectivity, Athena, package operations
+3. Response includes timing information for performance monitoring
+4. Degraded states are clearly distinguished from healthy and unhealthy states
+5. Health responses include actionable recovery recommendations when issues are detected
+6. Response format is consistent and machine-parseable
+
+### US3: Load Balancer Health Checks
+
+**As a** Infrastructure engineer configuring load balancers for MCP server deployment
+**I want** lightweight health check endpoints with configurable response formats
+**So that** the load balancer can efficiently route traffic to healthy instances without impacting server performance
+
+**Acceptance Criteria:**
+1. `/health/simple` endpoint returns minimal response (HTTP status only) for efficiency
+2. Health checks complete within 1-2 seconds under normal conditions
+3. Health check endpoints have minimal resource overhead
+4. Support for custom health check timeouts via query parameters
+5. Health checks work reliably during high server load
+6. No side effects on MCP tool operations from health check requests
+
+### US4: Development and Debugging Support
+
+**As a** developer working on the MCP server or troubleshooting client issues
+**I want** detailed diagnostic information accessible via health endpoints
+**So that** I can quickly identify configuration problems and verify system components
+
+**Acceptance Criteria:**
+1. `/health/detailed` endpoint provides comprehensive diagnostic information
+2. Diagnostic data includes: transport mode, tool registration status, AWS configuration
+3. Error details include specific failure messages and suggested fixes
+4. Health endpoints work in all transport modes (stdio, http, sse)
+5. Diagnostic information helps differentiate client vs server issues
+6. Response format is human-readable for manual debugging
+
+### US5: CI/CD Pipeline Integration
+
+**As a** DevOps engineer managing automated deployments
+**I want** reliable health check endpoints for deployment validation
+**So that** CI/CD pipelines can automatically verify successful deployments before promoting to production
+
+**Acceptance Criteria:**
+1. Health endpoints are available immediately after server startup
+2. Health status accurately reflects server readiness for MCP requests
+3. Health checks integrate with existing Docker container health probe configurations
+4. Consistent behavior across different deployment environments
+5. Health check failures provide actionable information for automated remediation
+6. Support for health check retries with configurable intervals
+
+## Numbered Acceptance Criteria
+
+1. **HTTP Transport Compatibility**: Health check endpoints MUST work when server is running in HTTP transport mode (`FASTMCP_TRANSPORT=http`)
+
+2. **Cross-Transport Support**: Health check functionality MUST be accessible across all transport modes (stdio, HTTP, SSE, streamable-http)
+
+3. **Standard Endpoint Structure**:
+   - `/health` - General health status (default)
+   - `/health/simple` - Minimal response for load balancers
+   - `/health/detailed` - Comprehensive diagnostics for debugging
+   - `/readiness` - Kubernetes-style readiness probe
+   - `/liveness` - Kubernetes-style liveness probe
+
+4. **Response Format Standardization**: All health endpoints MUST return JSON with consistent schema including:
+   - `status`: "healthy" | "degraded" | "unhealthy"
+   - `timestamp`: ISO 8601 timestamp
+   - `components`: Object with component-level status
+   - `message`: Human-readable status description
+
+5. **Performance Requirements**:
+   - Health checks MUST complete within 2 seconds under normal load
+   - Health checks MUST NOT impact MCP tool operation performance
+   - Memory overhead for health checks MUST be minimal (<10MB)
+
+6. **Error Handling**: Health endpoints MUST return appropriate HTTP status codes:
+   - 200: Healthy/Ready
+   - 503: Service Unavailable (unhealthy/not ready)
+   - 500: Internal server error during health check
+
+7. **Component Health Monitoring**: Health checks MUST validate core components:
+   - Authentication status (Quilt login state)
+   - AWS connectivity (STS, S3, Athena)
+   - MCP tool registration and availability
+   - Transport layer functionality
+
+8. **Container Integration**: Health endpoints MUST work with Docker health check directives and container orchestration health probes
+
+9. **No Authentication Required**: Health check endpoints MUST NOT require MCP protocol authentication or Quilt login
+
+10. **Graceful Degradation**: Health endpoints MUST function even when some server components are failing
+
+## Success Metrics
+
+1. **Availability**: Health check endpoints respond successfully >99.9% of the time
+2. **Response Time**: 95th percentile response time <1 second for simple health checks
+3. **Accuracy**: Health status correctly reflects actual server state >99% of the time
+4. **Integration Success**: Successfully integrates with at least 2 container orchestration platforms
+5. **Zero False Negatives**: Healthy endpoints never report unhealthy status when server is actually functional
+
+## Open Questions
+
+1. **Endpoint Naming Convention**: Should we follow Kubernetes convention (`/healthz`, `/readyz`) or HTTP standard (`/health`, `/status`)?
+
+2. **Authentication Requirement**: Should detailed health endpoints require any form of authentication to prevent information disclosure?
+
+3. **Caching Strategy**: Should health check results be cached to reduce overhead, and if so, for how long?
+
+4. **Custom Health Checks**: Should there be a way for users to register custom health checks for their specific deployment requirements?
+
+5. **Metrics Integration**: Should health endpoints also expose Prometheus-style metrics, or keep that separate?
+
+6. **Transport-Specific Behavior**: Should health check behavior differ between stdio and HTTP transports, or remain identical?
+
+7. **Failure Thresholds**: What should be the criteria for marking individual components or overall system as unhealthy vs degraded?
+
+8. **Recovery Actions**: Should health endpoints support triggering automatic recovery actions (like cache clearing or reconnection attempts)?
+
+## Dependencies and Constraints
+
+- **Existing Code**: Must integrate with existing `error_recovery.health_check_with_recovery()` functionality
+- **FastMCP Framework**: Must work within FastMCP server architecture and routing
+- **Transport Compatibility**: Must function across all supported transport modes
+- **Docker Integration**: Must be compatible with existing Docker container configuration
+- **Performance**: Must not significantly impact existing MCP tool performance
+- **Backward Compatibility**: Must not break existing server functionality or client connections