registry

type BaseProvider struct {
	// GetRegistryFunc is a function that fetches the registry data
	// This allows different providers to implement their own data fetching logic
	GetRegistryFunc func() (*Registry, error)
}

type BaseServerMetadata struct {
	// Name is the identifier for the MCP server, used when referencing the server in commands
	// If not provided, it will be auto-generated from the registry key
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// Description is a human-readable description of the server's purpose and functionality
	Description string `json:"description" yaml:"description"`
	// Tier represents the tier classification level of the server, e.g., "Official" or "Community"
	Tier string `json:"tier" yaml:"tier"`
	// Status indicates whether the server is currently active or deprecated
	Status string `json:"status" yaml:"status"`
	// Transport defines the communication protocol for the server
	// For containers: stdio, sse, or streamable-http
	// For remote servers: sse or streamable-http (stdio not supported)
	Transport string `json:"transport" yaml:"transport"`
	// Tools is a list of tool names provided by this MCP server
	Tools []string `json:"tools" yaml:"tools"`
	// Metadata contains additional information about the server such as popularity metrics
	Metadata *Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
	// RepositoryURL is the URL to the source code repository for the server
	RepositoryURL string `json:"repository_url,omitempty" yaml:"repository_url,omitempty"`
	// Tags are categorization labels for the server to aid in discovery and filtering
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	// CustomMetadata allows for additional user-defined metadata
	CustomMetadata map[string]any `json:"custom_metadata,omitempty" yaml:"custom_metadata,omitempty"`
}

type EnvVar struct {
	// Name is the environment variable name (e.g., API_KEY)
	Name string `json:"name" yaml:"name"`
	// Description is a human-readable explanation of the variable's purpose
	Description string `json:"description" yaml:"description"`
	// Required indicates whether this environment variable must be provided
	// If true and not provided via command line or secrets, the user will be prompted for a value
	Required bool `json:"required" yaml:"required"`
	// Default is the value to use if the environment variable is not explicitly provided
	// Only used for non-required variables
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// Secret indicates whether this environment variable contains sensitive information
	// If true, the value will be stored as a secret rather than as a plain environment variable
	Secret bool `json:"secret,omitempty" yaml:"secret,omitempty"`
}

type Header struct {
	// Name is the header name (e.g., X-API-Key, Authorization)
	Name string `json:"name" yaml:"name"`
	// Description is a human-readable explanation of the header's purpose
	Description string `json:"description" yaml:"description"`
	// Required indicates whether this header must be provided
	// If true and not provided via command line or secrets, the user will be prompted for a value
	Required bool `json:"required" yaml:"required"`
	// Default is the value to use if the header is not explicitly provided
	// Only used for non-required headers
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// Secret indicates whether this header contains sensitive information
	// If true, the value will be stored as a secret rather than as plain text
	Secret bool `json:"secret,omitempty" yaml:"secret,omitempty"`
	// Choices provides a list of valid values for the header (optional)
	Choices []string `json:"choices,omitempty" yaml:"choices,omitempty"`
}

type ImageMetadata struct {
	BaseServerMetadata `yaml:",inline"`
	// Image is the Docker image reference for the MCP server
	Image string `json:"image" yaml:"image"`
	// TargetPort is the port for the container to expose (only applicable to SSE and Streamable HTTP transports)
	TargetPort int `json:"target_port,omitempty" yaml:"target_port,omitempty"`
	// Permissions defines the security profile and access permissions for the server
	Permissions *permissions.Profile `json:"permissions,omitempty" yaml:"permissions,omitempty"`
	// EnvVars defines environment variables that can be passed to the server
	EnvVars []*EnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
	// Args are the default command-line arguments to pass to the MCP server container.
	// These arguments will be used only if no command-line arguments are provided by the user.
	// If the user provides arguments, they will override these defaults.
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`
	// DockerTags lists the available Docker tags for this server image
	DockerTags []string `json:"docker_tags,omitempty" yaml:"docker_tags,omitempty"`
	// Provenance contains verification and signing metadata
	Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`
}

type LocalRegistryProvider struct {
	*BaseProvider
	// contains filtered or unexported fields
}

type Metadata struct {
	// Stars represents the popularity rating or number of stars for the server
	Stars int `json:"stars" yaml:"stars"`
	// Pulls indicates how many times the server image has been downloaded
	Pulls int `json:"pulls" yaml:"pulls"`
	// LastUpdated is the timestamp when the server was last updated, in RFC3339 format
	LastUpdated string `json:"last_updated" yaml:"last_updated"`
}

type OAuthConfig struct {
	// Issuer is the OAuth/OIDC issuer URL (e.g., https://accounts.google.com)
	// Used for OIDC discovery to find authorization and token endpoints
	Issuer string `json:"issuer,omitempty" yaml:"issuer,omitempty"`
	// AuthorizeURL is the OAuth authorization endpoint URL
	// Used for non-OIDC OAuth flows when issuer is not provided
	AuthorizeURL string `json:"authorize_url,omitempty" yaml:"authorize_url,omitempty"`
	// TokenURL is the OAuth token endpoint URL
	// Used for non-OIDC OAuth flows when issuer is not provided
	TokenURL string `json:"token_url,omitempty" yaml:"token_url,omitempty"`
	// ClientID is the OAuth client ID for authentication
	ClientID string `json:"client_id,omitempty" yaml:"client_id,omitempty"`
	// Scopes are the OAuth scopes to request
	// If not specified, defaults to ["openid", "profile", "email"] for OIDC
	Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	// UsePKCE indicates whether to use PKCE for the OAuth flow
	// Defaults to true for enhanced security
	UsePKCE bool `json:"use_pkce,omitempty" yaml:"use_pkce,omitempty"`
	// OAuthParams contains additional OAuth parameters to include in the authorization request
	// These are server-specific parameters like "prompt", "response_mode", etc.
	OAuthParams map[string]string `json:"oauth_params,omitempty" yaml:"oauth_params,omitempty"`
	// CallbackPort is the specific port to use for the OAuth callback server
	// If not specified, a random available port will be used
	CallbackPort int `json:"callback_port,omitempty" yaml:"callback_port,omitempty"`
}

type Provenance struct {
	SigstoreURL       string               `json:"sigstore_url" yaml:"sigstore_url"`
	RepositoryURI     string               `json:"repository_uri" yaml:"repository_uri"`
	RepositoryRef     string               `json:"repository_ref,omitempty" yaml:"repository_ref,omitempty"`
	SignerIdentity    string               `json:"signer_identity" yaml:"signer_identity"`
	RunnerEnvironment string               `json:"runner_environment" yaml:"runner_environment"`
	CertIssuer        string               `json:"cert_issuer" yaml:"cert_issuer"`
	Attestation       *VerifiedAttestation `json:"attestation,omitempty" yaml:"attestation,omitempty"`
}

type Provider interface {
	// GetRegistry returns the complete registry data
	GetRegistry() (*Registry, error)

	// GetServer returns a specific server by name (container or remote)
	GetServer(name string) (ServerMetadata, error)

	// SearchServers searches for servers matching the query (both container and remote)
	SearchServers(query string) ([]ServerMetadata, error)

	// ListServers returns all available servers (both container and remote)
	ListServers() ([]ServerMetadata, error)

	// Legacy methods for backward compatibility
	// GetImageServer returns a specific container server by name
	GetImageServer(name string) (*ImageMetadata, error)

	// SearchImageServers searches for container servers matching the query
	SearchImageServers(query string) ([]*ImageMetadata, error)

	// ListImageServers returns all available container servers
	ListImageServers() ([]*ImageMetadata, error)
}

type Registry struct {
	// Version is the schema version of the registry
	Version string `json:"version" yaml:"version"`
	// LastUpdated is the timestamp when the registry was last updated, in RFC3339 format
	LastUpdated string `json:"last_updated" yaml:"last_updated"`
	// Servers is a map of server names to their corresponding server definitions
	Servers map[string]*ImageMetadata `json:"servers" yaml:"servers"`
	// RemoteServers is a map of server names to their corresponding remote server definitions
	// These are MCP servers accessed via HTTP/HTTPS using the thv proxy command
	RemoteServers map[string]*RemoteServerMetadata `json:"remote_servers,omitempty" yaml:"remote_servers,omitempty"`
}

type RemoteRegistryProvider struct {
	*BaseProvider
	// contains filtered or unexported fields
}

type RemoteServerMetadata struct {
	BaseServerMetadata `yaml:",inline"`
	// URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp)
	URL string `json:"url" yaml:"url"`
	// Headers defines HTTP headers that can be passed to the remote server for authentication
	// These are used with the thv proxy command's authentication features
	Headers []*Header `json:"headers,omitempty" yaml:"headers,omitempty"`
	// OAuthConfig provides OAuth/OIDC configuration for authentication to the remote server
	// Used with the thv proxy command's --remote-auth flags
	OAuthConfig *OAuthConfig `json:"oauth_config,omitempty" yaml:"oauth_config,omitempty"`
	// EnvVars defines environment variables that can be passed to configure the client
	// These might be needed for client-side configuration when connecting to the remote server
	EnvVars []*EnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
}

type ServerMetadata interface {
	// GetName returns the server name
	GetName() string
	// GetDescription returns the server description
	GetDescription() string
	// GetTier returns the server tier
	GetTier() string
	// GetStatus returns the server status
	GetStatus() string
	// GetTransport returns the server transport
	GetTransport() string
	// GetTools returns the list of tools provided by the server
	GetTools() []string
	// GetMetadata returns the server metadata
	GetMetadata() *Metadata
	// GetRepositoryURL returns the repository URL
	GetRepositoryURL() string
	// GetTags returns the server tags
	GetTags() []string
	// GetCustomMetadata returns custom metadata
	GetCustomMetadata() map[string]any
	// IsRemote returns true if this is a remote server
	IsRemote() bool
	// GetEnvVars returns environment variables
	GetEnvVars() []*EnvVar
}

type ToolhivePublisherExtension struct {
	// Tier represents the tier classification level of the server
	Tier string `json:"tier,omitempty" yaml:"tier,omitempty"`
	// Transport defines the communication protocol for the server
	Transport string `json:"transport,omitempty" yaml:"transport,omitempty"`
	// Tools is a list of tool names provided by this MCP server
	Tools []string `json:"tools,omitempty" yaml:"tools,omitempty"`
	// Metadata contains additional information about the server
	Metadata *Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
	// Tags are categorization labels for the server
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	// CustomMetadata allows for additional user-defined metadata
	CustomMetadata map[string]any `json:"custom_metadata,omitempty" yaml:"custom_metadata,omitempty"`
	// Permissions defines the security profile and access permissions for the server
	Permissions *permissions.Profile `json:"permissions,omitempty" yaml:"permissions,omitempty"`
	// TargetPort is the port for the container to expose (only applicable to SSE and Streamable HTTP transports)
	TargetPort int `json:"target_port,omitempty" yaml:"target_port,omitempty"`
	// DockerTags lists the available Docker tags for this server image
	DockerTags []string `json:"docker_tags,omitempty" yaml:"docker_tags,omitempty"`
	// Provenance contains verification and signing metadata
	Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`
}

type UpstreamArgument struct {
	// Type is the argument type
	Type UpstreamArgumentType `json:"type" yaml:"type"`
	// Name is the flag name for named arguments (including leading dashes)
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// ValueHint is an identifier-like hint for positional arguments
	ValueHint string `json:"value_hint,omitempty" yaml:"value_hint,omitempty"`
	// Description describes the argument's purpose
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// IsRequired indicates if the argument is required
	IsRequired bool `json:"is_required,omitempty" yaml:"is_required,omitempty"`
	// IsRepeated indicates if the argument can be repeated
	IsRepeated bool `json:"is_repeated,omitempty" yaml:"is_repeated,omitempty"`
	// Format specifies the input format
	Format UpstreamInputFormat `json:"format,omitempty" yaml:"format,omitempty"`
	// Value is the default or fixed value
	Value string `json:"value,omitempty" yaml:"value,omitempty"`
	// IsSecret indicates if the value is sensitive
	IsSecret bool `json:"is_secret,omitempty" yaml:"is_secret,omitempty"`
	// Default is the default value
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// Choices are valid values for the argument
	Choices []string `json:"choices,omitempty" yaml:"choices,omitempty"`
	// Variables are variable substitutions for the value
	Variables map[string]UpstreamInput `json:"variables,omitempty" yaml:"variables,omitempty"`
}

type UpstreamArgumentType string

type UpstreamInput struct {
	// Description describes the input's purpose
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// IsRequired indicates if the input is required
	IsRequired bool `json:"is_required,omitempty" yaml:"is_required,omitempty"`
	// Format specifies the input format
	Format UpstreamInputFormat `json:"format,omitempty" yaml:"format,omitempty"`
	// Value is the default or fixed value
	Value string `json:"value,omitempty" yaml:"value,omitempty"`
	// IsSecret indicates if the value is sensitive
	IsSecret bool `json:"is_secret,omitempty" yaml:"is_secret,omitempty"`
	// Default is the default value
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// Choices are valid values for the input
	Choices []string `json:"choices,omitempty" yaml:"choices,omitempty"`
}

type UpstreamInputFormat string

type UpstreamKeyValueInput struct {
	// Name is the variable or header name
	Name string `json:"name" yaml:"name"`
	// Description describes the input's purpose
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// IsRequired indicates if the input is required
	IsRequired bool `json:"is_required,omitempty" yaml:"is_required,omitempty"`
	// Format specifies the input format
	Format UpstreamInputFormat `json:"format,omitempty" yaml:"format,omitempty"`
	// Value is the default or fixed value
	Value string `json:"value,omitempty" yaml:"value,omitempty"`
	// IsSecret indicates if the value is sensitive
	IsSecret bool `json:"is_secret,omitempty" yaml:"is_secret,omitempty"`
	// Default is the default value
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// Choices are valid values for the input
	Choices []string `json:"choices,omitempty" yaml:"choices,omitempty"`
	// Variables are variable substitutions for the value
	Variables map[string]UpstreamInput `json:"variables,omitempty" yaml:"variables,omitempty"`
}

type UpstreamPackage struct {
	// RegistryName is the package registry type (e.g., "npm", "pypi", "docker", "nuget")
	RegistryName string `json:"registry_name" yaml:"registry_name"`
	// Name is the package name in the registry
	Name string `json:"name" yaml:"name"`
	// Version is the package version
	Version string `json:"version" yaml:"version"`
	// RuntimeHint provides a hint for the appropriate runtime (e.g., "npx", "uvx", "dnx")
	RuntimeHint string `json:"runtime_hint,omitempty" yaml:"runtime_hint,omitempty"`
	// RuntimeArguments are arguments passed to the package's runtime command
	RuntimeArguments []UpstreamArgument `json:"runtime_arguments,omitempty" yaml:"runtime_arguments,omitempty"`
	// PackageArguments are arguments passed to the package's binary
	PackageArguments []UpstreamArgument `json:"package_arguments,omitempty" yaml:"package_arguments,omitempty"`
	// EnvironmentVariables are environment variables for the package
	EnvironmentVariables []UpstreamKeyValueInput `json:"environment_variables,omitempty" yaml:"environment_variables,omitempty"`
}

type UpstreamPublisher struct {
	// XDevToolhive contains ToolHive-specific extension data
	XDevToolhive *ToolhivePublisherExtension `json:"x-dev.toolhive,omitempty" yaml:"x-dev.toolhive,omitempty"`
}

type UpstreamRemote struct {
	// TransportType is the transport protocol type
	TransportType UpstreamTransportType `json:"transport_type" yaml:"transport_type"`
	// URL is the remote server URL
	URL string `json:"url" yaml:"url"`
	// Headers are HTTP headers to include
	Headers []UpstreamKeyValueInput `json:"headers,omitempty" yaml:"headers,omitempty"`
}

type UpstreamRepository struct {
	// URL is the repository URL
	URL string `json:"url" yaml:"url"`
	// Source is the repository hosting service (e.g., "github")
	Source string `json:"source" yaml:"source"`
	// ID is an optional repository identifier
	ID string `json:"id,omitempty" yaml:"id,omitempty"`
}

type UpstreamServer struct {
	// Name is the server name/identifier (e.g., "io.modelcontextprotocol/filesystem")
	Name string `json:"name" yaml:"name"`
	// Description is a human-readable description of the server's functionality
	Description string `json:"description" yaml:"description"`
	// Status indicates the server lifecycle status
	Status UpstreamServerStatus `json:"status,omitempty" yaml:"status,omitempty"`
	// Repository contains repository information
	Repository *UpstreamRepository `json:"repository,omitempty" yaml:"repository,omitempty"`
	// VersionDetail contains version information
	VersionDetail UpstreamVersionDetail `json:"version_detail" yaml:"version_detail"`
	// Packages contains package installation options
	Packages []UpstreamPackage `json:"packages,omitempty" yaml:"packages,omitempty"`
	// Remotes contains remote server connection options
	Remotes []UpstreamRemote `json:"remotes,omitempty" yaml:"remotes,omitempty"`
}

type UpstreamServerDetail struct {
	// Server contains the core server information
	Server UpstreamServer `json:"server" yaml:"server"`
	// XPublisher contains optional publisher metadata (extension field)
	XPublisher *UpstreamPublisher `json:"x-publisher,omitempty" yaml:"x-publisher,omitempty"`
}

type UpstreamServerStatus string

type UpstreamTransportType string

type UpstreamVersionDetail struct {
	// Version is the server version (equivalent to Implementation.version in MCP spec)
	Version string `json:"version" yaml:"version"`
}

type VerifiedAttestation struct {
	PredicateType string `json:"predicate_type,omitempty" yaml:"predicate_type,omitempty"`
	Predicate     any    `json:"predicate,omitempty" yaml:"predicate,omitempty"`
}