Description

Add a platform-agnostic StatusReporter interface to enable vMCP runtime to report operational status. This enables real-time status updates from the running vMCP binary rather than controller-inferred status.

Background

Currently, VirtualMCPServer CRD status is populated by the controller via static queries at reconcile time. The vMCP runtime has no way to report actual operational state (backend health, tool counts, connectivity). This leads to stale status information.

Proposed Design

Interface (pkg/vmcp/status/reporter.go)

type Reporter interface {
    Report(ctx context.Context, status *RuntimeStatus) error
    Start(ctx context.Context, interval time.Duration) error
    Stop()
}

type RuntimeStatus struct {
    Phase             string               // Ready, Degraded, Failed
    Message           string
    Backends          []BackendHealthReport
    TotalToolCount    int
    HealthyBackends   int
    UnhealthyBackends int
    LastDiscoveryTime time.Time
}

Implementations

Factory

func NewReporter(name, namespace string) (Reporter, error) {
    if rt.IsKubernetesRuntime() {
        return NewK8sReporter(name, namespace)
    }
    return NewLogReporter(name), nil
}

Implementation

New Files

• pkg/vmcp/status/reporter.go - Interface
• pkg/vmcp/status/types.go - RuntimeStatus types
• pkg/vmcp/status/k8s_reporter.go - K8s implementation
• pkg/vmcp/status/log_reporter.go - Logging implementation
• pkg/vmcp/status/factory.go - Platform detection factory

Modified Files

• pkg/vmcp/server/server.go - Accept and use StatusReporter
• cmd/vmcp/app/commands.go - Create reporter based on environment
• cmd/thv-operator/controllers/virtualmcpserver_deployment.go - Add VMCP_NAME/VMCP_NAMESPACE env vars

RBAC Updates

vMCP ServiceAccount needs status update permission:

- apiGroups: ["toolhive.stacklok.dev"]
  resources: ["virtualmcpservers/status"]
  verbs: ["get", "update", "patch"]

Design Principles

• Platform-agnostic: Interface works for K8s and CLI
• Loose coupling: Runtime imports only CRD types, not controller code
• Graceful degradation: K8s reporter errors fall back to logging
• Non-blocking: Status reporting in background goroutine

Acceptance Criteria

• Reporter interface defined with Start/Stop/Report methods
• K8sReporter updates VirtualMCPServer status subresource
• LogReporter logs status for CLI environments
• Factory detects runtime environment
• vMCP server integrates StatusReporter
• RBAC rules added for status updates
• Unit tests for all implementations
• Integration test for K8s status updates