vmcp

type Backend struct {
	// ID is the unique identifier for this backend.
	ID string

	// Name is the human-readable name.
	Name string

	// BaseURL is the backend's MCP server URL.
	BaseURL string

	// TransportType is the MCP transport protocol.
	TransportType string

	// HealthStatus is the current health state.
	HealthStatus BackendHealthStatus

	// AuthConfig contains the typed authentication configuration for this backend.
	// The actual authentication is handled by OutgoingAuthRegistry interface.
	// If nil, the backend requires no authentication.
	AuthConfig *authtypes.BackendAuthStrategy

	// AuthConfigRef is the name of the MCPExternalAuthConfig resource (if any).
	// This field is populated during backend discovery and is useful for
	// debugging and status reporting.
	// +optional
	AuthConfigRef string

	// Metadata stores additional backend information.
	Metadata map[string]string
}

type BackendClient interface {
	// CallTool invokes a tool on the backend MCP server.
	// The meta parameter contains _meta fields from the client request that should be forwarded to the backend.
	// Returns the complete tool result including _meta field from the backend response.
	CallTool(
		ctx context.Context, target *BackendTarget, toolName string, arguments map[string]any, meta map[string]any,
	) (*ToolCallResult, error)

	// ReadResource retrieves a resource from the backend MCP server.
	// Returns the complete resource result including _meta field.
	ReadResource(ctx context.Context, target *BackendTarget, uri string) (*ResourceReadResult, error)

	// GetPrompt retrieves a prompt from the backend MCP server.
	// Returns the complete prompt result including _meta field.
	GetPrompt(ctx context.Context, target *BackendTarget, name string, arguments map[string]any) (*PromptGetResult, error)

	// ListCapabilities queries a backend for its capabilities.
	// Returns tools, resources, and prompts exposed by the backend.
	ListCapabilities(ctx context.Context, target *BackendTarget) (*CapabilityList, error)
}

type BackendHealthStatus string

type BackendRegistry interface {
	// Get retrieves a backend by ID.
	// Returns nil if the backend is not found.
	// This method is safe for concurrent reads.
	//
	// Example:
	//   backend := registry.Get(ctx, "github-mcp")
	//   if backend == nil {
	//       return fmt.Errorf("backend not found")
	//   }
	Get(ctx context.Context, backendID string) *Backend

	// List returns all registered backends.
	// The returned slice is a snapshot and safe to iterate without additional locking.
	// Order is not guaranteed unless specified by the implementation.
	//
	// Example:
	//   backends := registry.List(ctx)
	//   for _, backend := range backends {
	//       fmt.Printf("Backend: %s\n", backend.Name)
	//   }
	List(ctx context.Context) []Backend

	// Count returns the number of registered backends.
	// This is more efficient than len(List()) for large registries.
	Count() int
}

type BackendTarget struct {
	// WorkloadID is the unique identifier for the backend workload.
	WorkloadID string

	// WorkloadName is the human-readable name of the workload.
	WorkloadName string

	// BaseURL is the base URL for the backend's MCP server.
	// For local deployments: http://localhost:PORT
	// For Kubernetes: http://service-name.namespace.svc.cluster.local:PORT
	BaseURL string

	// TransportType specifies the MCP transport protocol.
	// Supported: "stdio", "http", "sse", "streamable-http"
	TransportType string

	// OriginalCapabilityName is the original name of the capability (tool/resource/prompt)
	// as known by the backend. This is used when forwarding requests to the backend.
	//
	// When conflict resolution renames capabilities, this field preserves the original name:
	// - Prefix strategy: "fetch" → "fetch_fetch" (OriginalCapabilityName="fetch")
	// - Priority strategy: usually unchanged (OriginalCapabilityName="tool_name")
	// - Manual strategy: "fetch" → "custom_name" (OriginalCapabilityName="fetch")
	//
	// If empty, the resolved name is used when forwarding to the backend.
	//
	// IMPORTANT: Do NOT access this field directly when forwarding requests to backends.
	// Use GetBackendCapabilityName() method instead, which handles both renamed and
	// non-renamed capabilities correctly. Direct access can lead to incorrect behavior
	// when capabilities are not renamed (OriginalCapabilityName will be empty).
	//
	// Example (WRONG):
	//   client.CallTool(ctx, target, target.OriginalCapabilityName, args) // BUG: fails when empty
	//
	// Example (CORRECT):
	//   client.CallTool(ctx, target, target.GetBackendCapabilityName(toolName), args)
	OriginalCapabilityName string

	// AuthConfig contains the typed authentication configuration for this backend.
	// The actual authentication is handled by OutgoingAuthRegistry interface.
	// If nil, the backend requires no authentication.
	AuthConfig *authtypes.BackendAuthStrategy

	// SessionAffinity indicates if requests from the same session
	// must be routed to this specific backend instance.
	SessionAffinity bool

	// HealthStatus indicates the current health of the backend.
	HealthStatus BackendHealthStatus

	// Metadata stores additional backend-specific information.
	Metadata map[string]string
}

type CapabilityList struct {
	// Tools available on this backend.
	Tools []Tool

	// Resources available on this backend.
	Resources []Resource

	// Prompts available on this backend.
	Prompts []Prompt

	// SupportsLogging indicates if the backend supports MCP logging.
	SupportsLogging bool

	// SupportsSampling indicates if the backend supports MCP sampling.
	SupportsSampling bool
}

type Condition = metav1.Condition

type ConflictResolutionStrategy string

type Content struct {
	// Type indicates the content type: "text", "image", "audio", "resource"
	Type string

	// Text is the content text (for TextContent)
	Text string

	// Data is the base64-encoded data (for ImageContent/AudioContent)
	Data string

	// MimeType is the MIME type (for ImageContent/AudioContent)
	MimeType string

	// URI is the resource URI (for EmbeddedResource)
	URI string
}

type DiscoveredBackend struct {
	// Name is the name of the backend MCPServer
	Name string `json:"name"`

	// URL is the URL of the backend MCPServer
	// +optional
	URL string `json:"url,omitempty"`

	// Status is the current status of the backend (ready, degraded, unavailable, unknown).
	// Use BackendHealthStatus.ToCRDStatus() to populate this field.
	// +optional
	Status string `json:"status,omitempty"`

	// AuthConfigRef is the name of the discovered MCPExternalAuthConfig (if any)
	// +optional
	AuthConfigRef string `json:"authConfigRef,omitempty"`

	// AuthType is the type of authentication configured
	// +optional
	AuthType string `json:"authType,omitempty"`

	// LastHealthCheck is the timestamp of the last health check
	// +optional
	LastHealthCheck metav1.Time `json:"lastHealthCheck,omitempty"`

	// Message provides additional information about the backend status
	// +optional
	Message string `json:"message,omitempty"`
}

type DynamicRegistry interface {
	BackendRegistry

	// Upsert adds or updates a backend atomically.
	// Idempotent - calling with the same backend multiple times is safe.
	// Increments Version() on every call.
	//
	// Parameters:
	//   - backend: The backend to add or update
	//
	// Returns:
	//   - error: Returns error if backend has empty ID
	//
	// Example:
	//   err := registry.Upsert(vmcp.Backend{
	//       ID: "github-mcp",
	//       Name: "GitHub MCP",
	//       BaseURL: "http://github-mcp.default.svc.cluster.local:8080",
	//   })
	Upsert(backend Backend) error

	// Remove deletes a backend by ID.
	// Idempotent - removing non-existent backends returns nil.
	// Increments Version() on every call.
	//
	// Parameters:
	//   - backendID: The ID of the backend to remove
	//
	// Returns:
	//   - error: Always returns nil (operation is always successful)
	//
	// Example:
	//   err := registry.Remove("github-mcp")
	Remove(backendID string) error

	// Version returns the current registry version.
	// Increments on every mutation (Upsert/Remove).
	// Used for cache invalidation in discovery manager.
	//
	// Returns:
	//   - uint64: Monotonic version counter
	//
	// Example:
	//   version := registry.Version()
	//   // Cache entries tagged with this version
	Version() uint64
}

type HealthChecker interface {
	// CheckHealth checks if a backend is healthy and responding.
	// Returns the current health status and any error encountered.
	CheckHealth(ctx context.Context, target *BackendTarget) (BackendHealthStatus, error)
}

type Phase string

type Prompt struct {
	// Name is the prompt name (may conflict with other backends).
	Name string

	// Description describes the prompt.
	Description string

	// Arguments are the prompt parameters.
	Arguments []PromptArgument

	// BackendID identifies the backend that provides this prompt.
	BackendID string
}

type PromptArgument struct {
	// Name is the argument name.
	Name string

	// Description describes the argument.
	Description string

	// Required indicates if the argument is mandatory.
	Required bool
}

type PromptGetResult struct {
	// Messages is the concatenated prompt text from all messages.
	Messages string

	// Description is an optional description of the prompt.
	Description string

	// Meta contains protocol-level metadata from the backend (_meta field).
	// This includes progressToken, trace context, and custom backend metadata.
	// Per MCP specification, this field is optional and may be nil.
	Meta map[string]any
}

type Resource struct {
	// URI is the resource URI (should be globally unique).
	URI string

	// Name is a human-readable name.
	Name string

	// Description describes the resource.
	Description string

	// MimeType is the resource's MIME type (optional).
	MimeType string

	// BackendID identifies the backend that provides this resource.
	BackendID string
}

type ResourceReadResult struct {
	// Contents is the concatenated resource data.
	// When a resource has multiple contents (text or blob), they are concatenated
	// directly without separators. Text contents are converted to bytes, blob contents
	// are base64-decoded before concatenation.
	Contents []byte

	// MimeType is the content type of the resource.
	MimeType string

	// Meta contains protocol-level metadata from the backend (_meta field).
	// NOTE: Due to MCP SDK limitations, resources/read handlers cannot forward _meta
	// because they return []ResourceContents directly, not a result wrapper.
	// This field is preserved for future SDK improvements but may be nil.
	Meta map[string]any
}

type RoutingTable struct {
	// Tools maps tool names to their backend targets.
	// After conflict resolution, tool names are unique.
	Tools map[string]*BackendTarget

	// Resources maps resource URIs to their backend targets.
	Resources map[string]*BackendTarget

	// Prompts maps prompt names to their backend targets.
	Prompts map[string]*BackendTarget
}

type Status struct {
	Phase              Phase               `json:"phase"`
	Message            string              `json:"message,omitempty"`
	Conditions         []Condition         `json:"conditions,omitempty"`
	DiscoveredBackends []DiscoveredBackend `json:"discoveredBackends,omitempty"`
	BackendCount       int                 `json:"backendCount,omitempty"`
	ObservedGeneration int64               `json:"observedGeneration,omitempty"`
	Timestamp          time.Time           `json:"timestamp"`
}

type Tool struct {
	// Name is the tool name (may conflict with other backends).
	Name string

	// Description describes what the tool does.
	Description string

	// InputSchema is the JSON Schema for tool parameters.
	InputSchema map[string]any

	// OutputSchema is the JSON Schema for tool output (optional).
	// Per MCP specification, this describes the structure of the tool's response.
	OutputSchema map[string]any

	// BackendID identifies the backend that provides this tool.
	BackendID string
}

type ToolCallResult struct {
	// Content is the tool output (text, image, etc.)
	// This is the array of content items returned by the backend.
	Content []Content

	// StructuredContent is structured output (preferred for composite tools and workflows).
	// If the backend MCP server provides StructuredContent, it is used directly.
	// Otherwise, this is populated by converting the Content array to a map:
	//   - First text item: key="text"
	//   - Additional text items: key="text_1", "text_2", etc.
	//   - Image items: key="image_0", "image_1", etc.
	// This allows templates to access fields via {{.steps.stepID.output.text}}.
	// Note: No JSON parsing is performed - backends must provide structured data explicitly.
	StructuredContent map[string]any

	// IsError indicates if the tool call failed.
	IsError bool

	// Meta contains protocol-level metadata from the backend (_meta field).
	// This includes progressToken, trace context, and custom backend metadata.
	// Per MCP specification, this field is optional and may be nil.
	Meta map[string]any
}