Health & Readiness Checks

# Liveness probe (lightweight, no I/O)
curl http://localhost:3001/healthz

# Readiness probe (probes dependencies, returns catalog hash)
curl http://localhost:3001/readyz

# Legacy endpoint (alias for /healthz)
curl http://localhost:3001/health

{
  "status": "ok",
  "server": { "name": "my-server", "version": "1.0.0" },
  "runtime": {
    "platform": "linux",
    "runtime": "node",
    "deployment": "standalone",
    "env": "production"
  },
  "uptime": 3600.5
}

{
  "status": "ready",
  "totalLatencyMs": 45,
  "catalog": {
    "toolsHash": "a1b2c3d4e5f6...",
    "toolCount": 12,
    "resourceCount": 3,
    "promptCount": 2,
    "skillCount": 1,
    "agentCount": 0
  },
  "probes": {
    "session-store": { "status": "healthy", "latencyMs": 12 },
    "remote:payment-svc": { "status": "healthy", "latencyMs": 25 }
  }
}

@FrontMcp({
  info: { name: 'my-server', version: '1.0.0' },
  apps: [MyApp],
  health: {
    probes: [
      {
        name: 'postgres',
        async check() {
          const start = Date.now();
          await pool.query('SELECT 1');
          return { status: 'healthy', latencyMs: Date.now() - start };
        },
      },
      {
        name: 'external-api',
        async check() {
          const res = await fetch('https://api.example.com/ping', {
            signal: AbortSignal.timeout(2000),
          });
          return { status: res.ok ? 'healthy' : 'unhealthy' };
        },
      },
    ],
  },
})

interface HealthProbeResult {
  status: 'healthy' | 'degraded' | 'unhealthy';
  latencyMs?: number;
  details?: Record<string, unknown>;
  error?: string;
}

@FrontMcp({
  health: {
    enabled: true,              // default: true
    healthzPath: '/healthz',    // custom liveness path
    readyzPath: '/readyz',      // custom readiness path
    includeDetails: false,      // omit per-probe details (default: true in dev, false in prod)
    readyz: {
      enabled: true,            // auto-determined by runtime when omitted
      timeoutMs: 5000,          // per-probe timeout (default: 5000ms)
    },
    probes: [],                 // custom probes
  },
})

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: mcp-server
          livenessProbe:
            httpGet:
              path: /healthz
              port: 3001
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /readyz
              port: 3001
            initialDelaySeconds: 10
            periodSeconds: 15
            timeoutSeconds: 5

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:3001/healthz || exit 1

# Compare catalog hash across replicas
curl -s http://replica-1:3001/readyz | jq .catalog.toolsHash
curl -s http://replica-2:3001/readyz | jq .catalog.toolsHash

@FrontMcp({
  health: { enabled: false },
})