sources

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 10, 2025 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package sources provides interfaces and implementations for retrieving MCP registry data from various external sources.

The package defines the SourceHandler interface which abstracts the process of validating source configurations and fetching registry data from external sources such as ConfigMaps, HTTP endpoints, Git repositories, or external registries.

Architecture:

  • SourceHandler: Interface for fetching and validating registry data
  • StorageManager: Interface for persisting registry data to ConfigMaps
  • SourceDataValidator: Validates and parses registry data in different formats
  • FetchResult: Strongly-typed result containing Registry instances with metadata

Current implementations:

  • ConfigMapSourceHandler: Retrieves registry data from Kubernetes ConfigMaps Supports both ToolHive and Upstream registry formats with format validation
  • ConfigMapStorageManager: Persists Registry data to Kubernetes ConfigMaps

Future implementations may include:

  • URLSourceHandler: HTTP/HTTPS endpoints
  • GitSourceHandler: Git repositories
  • RegistrySourceHandler: External registries

The package provides a factory pattern for creating appropriate source handlers based on the source type configuration, and uses strongly-typed Registry instances throughout for type safety.

Index

Constants

View Source 
const (
	// ConfigMapStorageDataKey is the key used to store registry data in ConfigMaps by the storage manager
	ConfigMapStorageDataKey = "registry.json"
	// RegistryStorageComponent is the component label for the registry storage
	RegistryStorageComponent = "registry-storage"

	// StorageTypeConfigMap identifies the ConfigMap storage manager implementation
	StorageTypeConfigMap = "configmap"
)
View Source 
const (
	// ConfigMapSourceDataKey is the default key used for registry data in ConfigMap sources
	ConfigMapSourceDataKey = "registry.json"
)
View Source 
const (
	// DefaultRegistryDataFile is the default file name for the registry data in Git sources
	DefaultRegistryDataFile = "registry.json"
)

Variables

This section is empty.

Functions

func EmptyJSON 

func EmptyJSON(format string) []byte

EmptyJSON returns empty JSON object/array based on format

func InvalidJSON 

func InvalidJSON() []byte

InvalidJSON returns intentionally malformed JSON for testing error cases

Types

type APISourceHandler added in v0.4.1 

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

APISourceHandler handles registry data from API endpoints It detects the format (ToolHive vs Upstream) and delegates to the appropriate handler

func NewAPISourceHandler added in v0.4.1 

func NewAPISourceHandler() *APISourceHandler

NewAPISourceHandler creates a new API source handler

func (*APISourceHandler) CurrentHash added in v0.4.1 

func (h *APISourceHandler) CurrentHash(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (string, error)

CurrentHash returns the current hash of the API response

func (*APISourceHandler) FetchRegistry added in v0.4.1 

func (h *APISourceHandler) FetchRegistry(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*FetchResult, error)

FetchRegistry retrieves registry data from the API endpoint It auto-detects the format and delegates to the appropriate handler

func (*APISourceHandler) Validate added in v0.4.1 

func (*APISourceHandler) Validate(source *mcpv1alpha1.MCPRegistrySource) error

Validate validates the API source configuration

type ConfigMapSourceHandler 

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

ConfigMapSourceHandler handles registry data from Kubernetes ConfigMaps

func NewConfigMapSourceHandler 

func NewConfigMapSourceHandler(k8sClient client.Client) *ConfigMapSourceHandler

NewConfigMapSourceHandler creates a new ConfigMap source handler

func (*ConfigMapSourceHandler) CurrentHash 

func (h *ConfigMapSourceHandler) CurrentHash(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (string, error)

CurrentHash returns the current hash of the source data without performing a full fetch

func (*ConfigMapSourceHandler) FetchRegistry 

func (h *ConfigMapSourceHandler) FetchRegistry(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*FetchResult, error)

FetchRegistry retrieves registry data from the ConfigMap source

func (*ConfigMapSourceHandler) Validate 

func (*ConfigMapSourceHandler) Validate(source *mcpv1alpha1.MCPRegistrySource) error

Validate validates the ConfigMap source configuration

type ConfigMapStorageManager 

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

ConfigMapStorageManager implements StorageManager using Kubernetes ConfigMaps

func NewConfigMapStorageManager 

func NewConfigMapStorageManager(k8sClient client.Client, scheme *runtime.Scheme) *ConfigMapStorageManager

NewConfigMapStorageManager creates a new ConfigMap-based storage manager

func (*ConfigMapStorageManager) Delete 

func (s *ConfigMapStorageManager) Delete(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) error

Delete removes the storage ConfigMap

func (*ConfigMapStorageManager) Get 

func (s *ConfigMapStorageManager) Get(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*registry.Registry, error)

Get retrieves and parses registry data from a ConfigMap

func (*ConfigMapStorageManager) GetStorageReference 

func (s *ConfigMapStorageManager) GetStorageReference(mcpRegistry *mcpv1alpha1.MCPRegistry) *mcpv1alpha1.StorageReference

GetStorageReference returns a reference to the ConfigMap storage

func (*ConfigMapStorageManager) GetType added in v0.3.6 

func (*ConfigMapStorageManager) GetType() string

GetType returns the storage manager type

func (*ConfigMapStorageManager) Store 

func (s *ConfigMapStorageManager) Store(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry, reg *registry.Registry) error

Store saves a Registry instance to a ConfigMap

type DefaultSourceDataValidator 

type DefaultSourceDataValidator struct{}

DefaultSourceDataValidator is the default implementation of SourceValidator

func (*DefaultSourceDataValidator) ValidateData 

func (*DefaultSourceDataValidator) ValidateData(data []byte, format string) (*registry.Registry, error)

ValidateData validates raw data and returns a parsed Registry

type DefaultSourceHandlerFactory 

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

DefaultSourceHandlerFactory is the default implementation of SourceHandlerFactory

func (*DefaultSourceHandlerFactory) CreateHandler 

func (f *DefaultSourceHandlerFactory) CreateHandler(sourceType string) (SourceHandler, error)

CreateHandler creates a source handler for the given source type

type EnvVarDetail added in v0.4.1 

type EnvVarDetail struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
	Default     string `json:"default,omitempty"`
	Secret      bool   `json:"secret,omitempty"`
}

EnvVarDetail represents detailed environment variable information

type FetchResult 

type FetchResult struct {
	// Registry is the parsed registry data (replaces raw Data field)
	Registry *registry.Registry

	// Hash is the SHA256 hash of the serialized data for change detection
	Hash string

	// ServerCount is the number of servers found in the registry data
	ServerCount int

	// Format indicates the original format of the source data
	Format string
}

FetchResult contains the result of a fetch operation

func NewFetchResult 

func NewFetchResult(reg *registry.Registry, hash string, format string) *FetchResult

NewFetchResult creates a new FetchResult from a Registry instance and pre-calculated hash The hash should be calculated by the source handler to ensure consistency with CurrentHash

type GitSourceHandler added in v0.3.6 

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

GitSourceHandler handles registry data from Git repositories

func NewGitSourceHandler added in v0.3.6 

func NewGitSourceHandler() *GitSourceHandler

NewGitSourceHandler creates a new Git source handler

func (*GitSourceHandler) CurrentHash added in v0.3.6 

func (h *GitSourceHandler) CurrentHash(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (string, error)

CurrentHash returns the current hash of the source data after fetching the registry data

func (*GitSourceHandler) FetchRegistry added in v0.3.6 

func (h *GitSourceHandler) FetchRegistry(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*FetchResult, error)

FetchRegistry retrieves registry data from the Git repository

func (*GitSourceHandler) Validate added in v0.3.6 

func (*GitSourceHandler) Validate(source *mcpv1alpha1.MCPRegistrySource) error

Validate validates the Git source configuration

type ListServersResponse added in v0.4.1 

type ListServersResponse struct {
	Servers []ServerSummaryResponse `json:"servers"`
	Total   int                     `json:"total"`
}

ListServersResponse represents the servers list response from /v0/servers

type RegistryInfoResponse added in v0.4.1 

type RegistryInfoResponse struct {
	Version      string `json:"version"`
	LastUpdated  string `json:"last_updated"`
	Source       string `json:"source"`
	TotalServers int    `json:"total_servers"`
}

RegistryInfoResponse represents the registry information response from /v0/info

type ServerDetailResponse added in v0.4.1 

type ServerDetailResponse struct {
	Name          string                 `json:"name"`
	Description   string                 `json:"description"`
	Tier          string                 `json:"tier"`
	Status        string                 `json:"status"`
	Transport     string                 `json:"transport"`
	Tools         []string               `json:"tools"`
	EnvVars       []EnvVarDetail         `json:"env_vars,omitempty"`
	Permissions   map[string]interface{} `json:"permissions,omitempty"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`
	RepositoryURL string                 `json:"repository_url,omitempty"`
	Tags          []string               `json:"tags,omitempty"`
	Args          []string               `json:"args,omitempty"`
	Volumes       map[string]interface{} `json:"volumes,omitempty"`
	Image         string                 `json:"image,omitempty"`
}

ServerDetailResponse represents a server in detail API responses (full view)

type ServerSummaryResponse added in v0.4.1 

type ServerSummaryResponse struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Tier        string `json:"tier"`
	Status      string `json:"status"`
	Transport   string `json:"transport"`
	ToolsCount  int    `json:"tools_count"`
}

ServerSummaryResponse represents a server in list API responses (summary view)

type SourceDataValidator 

type SourceDataValidator interface {
	// ValidateData validates raw data and returns a parsed Registry
	ValidateData(data []byte, format string) (*registry.Registry, error)
}

SourceDataValidator is an interface for validating registry source configurations

func NewSourceDataValidator 

func NewSourceDataValidator() SourceDataValidator

NewSourceDataValidator creates a new default source validator

type SourceHandler 

type SourceHandler interface {
	// FetchRegistry retrieves data from the source and returns the result
	FetchRegistry(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*FetchResult, error)

	// Validate validates the source configuration
	Validate(source *mcpv1alpha1.MCPRegistrySource) error

	// CurrentHash returns the current hash of the source data without performing a full fetch
	CurrentHash(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (string, error)
}

SourceHandler is an interface with methods to fetch data from external data sources

type SourceHandlerFactory 

type SourceHandlerFactory interface {
	// CreateHandler creates a source handler for the given source type
	CreateHandler(sourceType string) (SourceHandler, error)
}

SourceHandlerFactory creates source handlers based on source type

func NewSourceHandlerFactory 

func NewSourceHandlerFactory(k8sClient client.Client) SourceHandlerFactory

NewSourceHandlerFactory creates a new source handler factory

type StorageError 

type StorageError struct {
	Operation string
	Registry  string
	Message   string
	Cause     error
}

StorageError represents an error that occurred during storage operations

func NewStorageError 

func NewStorageError(operation, mcpRegistry, message string, cause error) *StorageError

NewStorageError creates a new StorageError

func (*StorageError) Error 

func (e *StorageError) Error() string

func (*StorageError) Unwrap 

func (e *StorageError) Unwrap() error

type StorageManager 

type StorageManager interface {
	// Store saves a Registry instance to persistent storage
	Store(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry, reg *registry.Registry) error

	// Get retrieves and parses registry data from persistent storage
	Get(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*registry.Registry, error)

	// Delete removes registry data from persistent storage
	Delete(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) error

	// GetStorageReference returns a reference to where the data is stored
	GetStorageReference(mcpRegistry *mcpv1alpha1.MCPRegistry) *mcpv1alpha1.StorageReference

	// GetType returns the storage manager type as a string
	GetType() string
}

StorageManager defines the interface for registry data persistence

type TestRegistryBuilder 

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

TestRegistryBuilder provides a fluent interface for building test registry data

func NewTestRegistryBuilder 

func NewTestRegistryBuilder(format string) *TestRegistryBuilder

NewTestRegistryBuilder creates a new test registry builder for the specified format

func (*TestRegistryBuilder) BuildJSON 

func (b *TestRegistryBuilder) BuildJSON() []byte

BuildJSON returns the JSON representation of the built registry

func (*TestRegistryBuilder) BuildPrettyJSON 

func (b *TestRegistryBuilder) BuildPrettyJSON() []byte

BuildPrettyJSON returns the JSON representation with indentation for readability

func (*TestRegistryBuilder) ContainerServerCount 

func (b *TestRegistryBuilder) ContainerServerCount() int

ContainerServerCount returns the number of container servers only

func (*TestRegistryBuilder) Empty 

func (b *TestRegistryBuilder) Empty() *TestRegistryBuilder

Empty creates an empty registry with minimal required fields

func (*TestRegistryBuilder) GetRegistry 

func (b *TestRegistryBuilder) GetRegistry() *registry.Registry

GetRegistry returns the built registry (for ToolHive format only)

func (*TestRegistryBuilder) GetUpstreamData 

func (b *TestRegistryBuilder) GetUpstreamData() []registry.UpstreamServerDetail

GetUpstreamData returns the built upstream data (for Upstream format only)

func (*TestRegistryBuilder) RemoteServerCount 

func (b *TestRegistryBuilder) RemoteServerCount() int

RemoteServerCount returns the number of remote servers only (ToolHive format only)

func (*TestRegistryBuilder) ServerCount 

func (b *TestRegistryBuilder) ServerCount() int

ServerCount returns the number of servers (both container and remote for ToolHive format)

func (*TestRegistryBuilder) WithLastUpdated 

func (b *TestRegistryBuilder) WithLastUpdated(timestamp string) *TestRegistryBuilder

WithLastUpdated sets a custom last updated timestamp (ToolHive format only)

func (*TestRegistryBuilder) WithRemoteServer 

func (b *TestRegistryBuilder) WithRemoteServer(url string) *TestRegistryBuilder

WithRemoteServer adds a remote server with the given URL (only for ToolHive format)

func (*TestRegistryBuilder) WithRemoteServerName 

func (b *TestRegistryBuilder) WithRemoteServerName(name, url string) *TestRegistryBuilder

WithRemoteServerName adds a remote server with a specific name and URL

func (*TestRegistryBuilder) WithServer 

func (b *TestRegistryBuilder) WithServer(name string) *TestRegistryBuilder

WithServer adds a container server with the given name and default valid values

func (*TestRegistryBuilder) WithServerName 

func (b *TestRegistryBuilder) WithServerName(name string) *TestRegistryBuilder

WithServerName adds a server with a specific name

func (*TestRegistryBuilder) WithVersion 

func (b *TestRegistryBuilder) WithVersion(version string) *TestRegistryBuilder

WithVersion sets a custom version (ToolHive format only)

type ToolHiveAPIHandler added in v0.4.1 

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

ToolHiveAPIHandler handles registry data from ToolHive Registry API endpoints API Format: /v0/servers (list), /v0/servers/{name} (detail), /v0/info (metadata)

func NewToolHiveAPIHandler added in v0.4.1 

func NewToolHiveAPIHandler(httpClient httpclient.Client) *ToolHiveAPIHandler

NewToolHiveAPIHandler creates a new ToolHive API handler

func (*ToolHiveAPIHandler) CurrentHash added in v0.4.1 

func (h *ToolHiveAPIHandler) CurrentHash(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (string, error)

CurrentHash returns the current hash of the API response

func (*ToolHiveAPIHandler) FetchRegistry added in v0.4.1 

func (h *ToolHiveAPIHandler) FetchRegistry(ctx context.Context, mcpRegistry *mcpv1alpha1.MCPRegistry) (*FetchResult, error)

FetchRegistry retrieves registry data from the ToolHive API endpoint

func (*ToolHiveAPIHandler) Validate added in v0.4.1 

func (h *ToolHiveAPIHandler) Validate(ctx context.Context, endpoint string) error

Validate validates that the endpoint is a ToolHive registry

type UpstreamAPIHandler added in v0.4.1 

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

UpstreamAPIHandler handles registry data from upstream MCP Registry API endpoints API Format: /v0/servers (paginated list), /v0/servers/{name}/versions, /openapi.yaml Phase 2 implementation - currently validates format but does not fetch data

func NewUpstreamAPIHandler added in v0.4.1 

func NewUpstreamAPIHandler(httpClient httpclient.Client) *UpstreamAPIHandler

NewUpstreamAPIHandler creates a new upstream MCP Registry API handler

func (*UpstreamAPIHandler) CurrentHash added in v0.4.1 

func (*UpstreamAPIHandler) CurrentHash(_ context.Context, _ *mcpv1alpha1.MCPRegistry) (string, error)

CurrentHash returns the current hash of the API response Phase 2: Not yet implemented

func (*UpstreamAPIHandler) FetchRegistry added in v0.4.1 

func (*UpstreamAPIHandler) FetchRegistry(_ context.Context, _ *mcpv1alpha1.MCPRegistry) (*FetchResult, error)

FetchRegistry retrieves registry data from the upstream MCP Registry API endpoint Phase 2: Not yet implemented - will support pagination and format conversion

func (*UpstreamAPIHandler) Validate added in v0.4.1 

func (h *UpstreamAPIHandler) Validate(ctx context.Context, endpoint string) error

Validate validates that the endpoint is an upstream MCP Registry by checking /openapi.yaml for expected version and description

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.