Skip to content

Add StatusReporter abstraction for vMCP runtime status reporting #2854

@JAORMX

Description

@JAORMX

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

Implementation Environment Behavior
K8sReporter Kubernetes Updates VirtualMCPServer/status subresource
LogReporter CLI/local Logs status periodically
NoopReporter Testing No-op

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    apiItems related to the APIenhancementNew feature or requestgoPull requests that update go codekubernetesItems related to KubernetesoperatorvmcpVirtual MCP Server related issues

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions