broker

README

Tracks upstream MCP servers

Documentation

Overview

Package broker tracks upstream MCP servers and manages the relationship from clients to upstream

Index

• type CapabilitiesValidation
• type ConnectionStatus
• type MCPBroker
  • func NewBroker(logger *slog.Logger, opts ...Option) MCPBroker
• type OAuthProtectedResource
• type Option
  • func WithEnforceToolFilter(enforce bool) Option
  • func WithInvalidToolPolicy(policy mcpv1alpha1.InvalidToolPolicy) Option
  • func WithManagerTickerInterval(interval time.Duration) Option
  • func WithTrustedHeadersPublicKey(key string) Option
• type ProtectedResourceHandler
  • func (prh *ProtectedResourceHandler) Handle(w http.ResponseWriter, r *http.Request)
• type ProtocolValidation
• type ServerValidationStatus
• type StatusHandler
  • func NewStatusHandler(broker MCPBroker, logger slog.Logger) *StatusHandler
  • func (h *StatusHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type StatusResponse
• type ToolConflict

Types

type CapabilitiesValidation

type CapabilitiesValidation struct {
	IsValid             bool     `json:"isValid"`
	HasToolCapabilities bool     `json:"hasToolCapabilities"`
	ToolCount           int      `json:"toolCount"`
	MissingCapabilities []string `json:"missingCapabilities"`
}

CapabilitiesValidation represents the capabilities validation results

type ConnectionStatus

type ConnectionStatus struct {
	IsReachable    bool   `json:"isReachable"`
	Error          string `json:"error,omitempty"`
	HTTPStatusCode int    `json:"httpStatusCode,omitempty"`
}

ConnectionStatus represents the connection health of an MCP server

type MCPBroker

type MCPBroker interface {

	// Returns tool annotations for a given tool name
	ToolAnnotations(serverID config.UpstreamMCPID, tool string) (mcp.ToolAnnotation, bool)

	// Returns server info for a given tool name
	GetServerInfo(tool string) (*config.MCPServer, error)

	// MCPServer gets an MCP server that federates the upstreams known to this MCPBroker
	MCPServer() *server.MCPServer

	//RegisteredServers returns the map of registered servers
	RegisteredMCPServers() map[config.UpstreamMCPID]*upstream.MCPManager

	// GetVirtualSeverByHeader returns a virtual server definition based on a header where the header is the namespaced/name of the virtual server resource
	GetVirtualSeverByHeader(namespaceName string) (config.VirtualServer, error)

	// ValidateAllServers performs comprehensive validation of all registered servers and returns status
	ValidateAllServers() StatusResponse

	// HandleStatusRequest handles HTTP status endpoint requests
	HandleStatusRequest(w http.ResponseWriter, r *http.Request)

	// Shutdown closes any resources associated with this Broker
	Shutdown(ctx context.Context) error

	config.Observer
}

MCPBroker manages a set of MCP servers and their sessions

func NewBroker

func NewBroker(logger *slog.Logger, opts ...Option) MCPBroker

NewBroker creates a new MCPBroker accepts optional config functions such as WithEnforceToolFilter

type OAuthProtectedResource

type OAuthProtectedResource struct {
	ResourceName           string   `json:"resource_name"`
	Resource               string   `json:"resource"`
	AuthorizationServers   []string `json:"authorization_servers"`
	BearerMethodsSupported []string `json:"bearer_methods_supported"`
	ScopesSupported        []string `json:"scopes_supported"`
}

OAuthProtectedResource represents the OAuth protected resource response

type Option

type Option func(mb *mcpBrokerImpl)

Option configures a broker instance

func WithEnforceToolFilter

func WithEnforceToolFilter(enforce bool) Option

WithEnforceToolFilter defines enforceToolFilter setting and is intended for use with the NewBroker function

func WithInvalidToolPolicy

func WithInvalidToolPolicy(policy mcpv1alpha1.InvalidToolPolicy) Option

WithInvalidToolPolicy sets the policy for handling upstream tools with invalid schemas

func WithManagerTickerInterval

func WithManagerTickerInterval(interval time.Duration) Option

WithManagerTickerInterval sets the interval for MCP manager backend health checks

func WithTrustedHeadersPublicKey

func WithTrustedHeadersPublicKey(key string) Option

WithTrustedHeadersPublicKey defines the public key used to verify signed headers and is intended for use with the NewBroker function

type ProtectedResourceHandler

type ProtectedResourceHandler struct {
	Logger *slog.Logger
}

ProtectedResourceHandler is the HTTP handler for the oauth protectected resource config

func (*ProtectedResourceHandler) Handle

func (prh *ProtectedResourceHandler) Handle(w http.ResponseWriter, r *http.Request)

Handle handles the /.well-known/oauth-protected-resource endpoint

type ProtocolValidation

type ProtocolValidation struct {
	IsValid          bool   `json:"isValid"`
	SupportedVersion string `json:"supportedVersion"`
	ExpectedVersion  string `json:"expectedVersion"`
}

ProtocolValidation represents the MCP protocol version validation results

type ServerValidationStatus

type ServerValidationStatus struct {
	ID                     string                 `json:"id"`
	Name                   string                 `json:"name"`
	ToolPrefix             string                 `json:"toolPrefix"`
	ConnectionStatus       ConnectionStatus       `json:"connectionStatus"`
	ProtocolValidation     ProtocolValidation     `json:"protocolValidation"`
	CapabilitiesValidation CapabilitiesValidation `json:"capabilitiesValidation"`
	ToolConflicts          []ToolConflict         `json:"toolConflicts"`
	LastValidated          time.Time              `json:"lastValidated"`
}

ServerValidationStatus contains the validation status of a single MCP server

type StatusHandler

type StatusHandler struct {
	// contains filtered or unexported fields
}

StatusHandler handles HTTP requests to the status endpoint

func NewStatusHandler

func NewStatusHandler(broker MCPBroker, logger slog.Logger) *StatusHandler

NewStatusHandler creates a new status handler for HTTP status endpoints

func (*StatusHandler) ServeHTTP

func (h *StatusHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler interface

type StatusResponse

type StatusResponse struct {
	Servers          []upstream.ServerValidationStatus `json:"servers"`
	OverallValid     bool                              `json:"overallValid"`
	TotalServers     int                               `json:"totalServers"`
	HealthyServers   int                               `json:"healthyServers"`
	UnHealthyServers int                               `json:"unHealthyServers"`
	ToolConflicts    int                               `json:"toolConflicts"`
	Timestamp        time.Time                         `json:"timestamp"`
}

StatusResponse contains the overall validation status of all servers

type ToolConflict

type ToolConflict struct {
	ToolName      string   `json:"toolName"`
	PrefixedName  string   `json:"prefixedName"`
	ConflictsWith []string `json:"conflictsWith"`
}

ToolConflict represents a tool name conflict between servers