registry

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"`
	// Title is an optional human-readable display name for the server.
	// If not provided, the Name field is used for display purposes.
	Title string `json:"title,omitempty" yaml:"title,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"`
	// Stateless indicates the server only supports POST (no SSE/GET)
	Stateless bool `json:"stateless,omitempty" yaml:"stateless,omitempty"`
	// 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"`
	// Overview is a longer Markdown-formatted description for web display.
	// Unlike the Description field (limited to 500 chars), this supports
	// full Markdown and is intended for rich rendering on catalog pages.
	Overview string `json:"overview,omitempty" yaml:"overview,omitempty"`
	// ToolDefinitions contains full MCP Tool definitions describing the tools
	// available from this server, including name, description, inputSchema, and annotations.
	ToolDefinitions []mcp.Tool `json:"tool_definitions,omitempty" yaml:"tool_definitions,omitempty" swaggerignore:"true"`
	// 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 Group struct {
	// Name is the identifier for the group, used when referencing the group in commands
	Name string `json:"name" yaml:"name"`
	// Description is a human-readable description of the group's purpose and functionality
	Description string `json:"description" yaml:"description"`
	// Servers is a map of server names to their corresponding server definitions within this group
	Servers map[string]*ImageMetadata `json:"servers,omitempty" yaml:"servers,omitempty"`
	// RemoteServers is a map of server names to their corresponding remote server definitions within this group
	RemoteServers map[string]*RemoteServerMetadata `json:"remote_servers,omitempty" yaml:"remote_servers,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
	// 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"`
	// ProxyPort is the port for the HTTP proxy to listen on (host port)
	// If not specified, a random available port will be assigned
	ProxyPort int `json:"proxy_port,omitempty" yaml:"proxy_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 KubernetesMetadata struct {
	// Kind is the Kubernetes resource kind (e.g., MCPServer, VirtualMCPServer, MCPRemoteProxy)
	Kind string `json:"kind,omitempty" yaml:"kind,omitempty"`
	// Namespace is the Kubernetes namespace where the resource is deployed
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	// Name is the Kubernetes resource name
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// UID is the Kubernetes resource UID
	UID string `json:"uid,omitempty" yaml:"uid,omitempty"`
	// Image is the container image used by the Kubernetes workload (applicable to MCPServer)
	Image string `json:"image,omitempty" yaml:"image,omitempty"`
	// Transport is the transport type configured for the Kubernetes workload (applicable to MCPServer)
	Transport string `json:"transport,omitempty" yaml:"transport,omitempty"`
}

type Metadata struct {
	// Stars represents the popularity rating or number of stars for the server
	Stars int `json:"stars,omitempty" yaml:"stars,omitempty"`
	// LastUpdated is the timestamp when the server was last updated, in RFC3339 format
	LastUpdated string `json:"last_updated,omitempty" yaml:"last_updated,omitempty"`
	// Kubernetes contains Kubernetes-specific metadata when the MCP server is deployed in a cluster.
	// This field is optional and only populated when:
	// - The server is served from ToolHive Registry Server
	// - The server was auto-discovered from a Kubernetes deployment
	// - The Kubernetes resource has the required registry annotations
	Kubernetes *KubernetesMetadata `json:"kubernetes,omitempty" yaml:"kubernetes,omitempty"`
}

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"`
	// Resource is the OAuth 2.0 resource indicator (RFC 8707)
	Resource string `json:"resource,omitempty" yaml:"resource,omitempty"`
}

type Plugin struct {
	// Namespace is the namespace of the plugin.
	// The format is reverse-DNS, e.g. "io.github.user".
	Namespace string `json:"namespace"`
	// Name is the name of the plugin.
	// The format is that of identifiers, e.g. "my-plugin".
	Name string `json:"name"`
	// Description is the description of the plugin.
	Description string `json:"description"`
	// Version is the version of the plugin.
	// Any non-empty string is valid, but ideally it should be either a
	// semantic version or a commit hash.
	Version string `json:"version"`
	// Status is the status of the plugin.
	// Can be one of "active", "deprecated", or "archived".
	Status string `json:"status,omitempty"` // active, deprecated, archived
	// Title is the title of the plugin.
	// This is for human consumption, not an identifier.
	Title string `json:"title,omitempty"`
	// License is the SPDX license identifier of the plugin.
	License string `json:"license,omitempty"`
	// Repository is the source repository of the plugin.
	Repository *SkillRepository `json:"repository,omitempty"`
	// Icons is the list of icons for the plugin.
	Icons []SkillIcon `json:"icons,omitempty"`
	// Packages is the list of packages for the plugin.
	Packages []SkillPackage `json:"packages,omitempty"`
	// Provenance contains the expected certificate identity and attestation
	// constraints for the plugin artifact.
	Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	// Metadata is the official metadata of the plugin as reported in the
	// plugin manifest file.
	Metadata map[string]any `json:"metadata,omitempty"`
	// Meta is an opaque payload with extended meta data details of the plugin.
	Meta map[string]any `json:"_meta,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 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"`
	// Groups is a slice of group definitions containing related MCP servers
	Groups []*Group `json:"groups,omitempty" yaml:"groups,omitempty"`
}

type RemoteServerMetadata struct {
	BaseServerMetadata
	// URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp)
	URL string `json:"url" yaml:"url"`
	// ProxyPort is the port for the HTTP proxy to listen on (host port)
	// If not specified, a random available port will be assigned
	ProxyPort int `json:"proxy_port,omitempty" yaml:"proxy_port,omitempty"`
	// 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 ServerExtensions struct {
	// Status indicates whether the server is active or deprecated (required)
	Status string `json:"status" yaml:"status"`
	// Tier represents the classification level (e.g., "Official", "Community")
	Tier string `json:"tier,omitempty" yaml:"tier,omitempty"`
	// Tools lists the tool names provided by this MCP server
	Tools []string `json:"tools,omitempty" yaml:"tools,omitempty"`
	// Tags are categorization labels for search and filtering
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Overview is a longer Markdown-formatted description for web display.
	// Unlike the upstream description (limited to 100 chars), this supports
	// full Markdown and is intended for rich rendering on catalog pages.
	Overview string `json:"overview,omitempty" yaml:"overview,omitempty"`
	// Metadata contains popularity metrics and optional Kubernetes-specific metadata.
	// The Kubernetes metadata is only populated when:
	// - The server is served from ToolHive Registry Server
	// - The server was auto-discovered from a Kubernetes deployment
	// - The Kubernetes resource has the required registry annotations
	Metadata *Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
	// CustomMetadata allows for additional user-defined metadata
	CustomMetadata map[string]any `json:"custom_metadata,omitempty" yaml:"custom_metadata,omitempty"`

	// Permissions defines security permissions for container-based servers
	Permissions *permissions.Profile `json:"permissions,omitempty" yaml:"permissions,omitempty"`
	// Args are default command-line arguments for container-based servers
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`
	// Provenance contains supply chain provenance information for container-based servers
	Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	// DockerTags lists available Docker tags for container-based servers
	DockerTags []string `json:"docker_tags,omitempty" yaml:"docker_tags,omitempty"`
	// ProxyPort is the HTTP proxy port (1-65535). Applies to both container-based
	// and remote servers.
	ProxyPort int `json:"proxy_port,omitempty" yaml:"proxy_port,omitempty"`
	// Stateless indicates the server only supports POST (no SSE/GET).
	// Applies to both container-based and remote servers.
	Stateless bool `json:"stateless,omitempty" yaml:"stateless,omitempty"`

	// OAuthConfig defines OAuth/OIDC configuration for remote servers
	OAuthConfig *OAuthConfig `json:"oauth_config,omitempty" yaml:"oauth_config,omitempty"`
	// EnvVars defines environment variables for remote server client configuration
	EnvVars []*EnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`

	// ToolDefinitions contains an array of MCP Tool definitions that describe the tools
	// available from this server. This field can be populated by:
	// - ToolHive Registry Server (extracted from Kubernetes annotations)
	// - Registry publishers (to pre-declare available tools)
	// - Any other source that wants to advertise tool capabilities
	// The array contains Tool objects as defined in the MCP specification.
	ToolDefinitions []mcp.Tool `json:"tool_definitions,omitempty" yaml:"tool_definitions,omitempty"`
}

type ServerMetadata interface {
	// GetName returns the server name
	GetName() string
	// GetTitle returns the optional human-readable display name
	GetTitle() 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
	// GetStateless returns whether the server is stateless (POST-only, no SSE/GET)
	GetStateless() bool
	// 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
	// GetOverview returns the longer Markdown-formatted description
	GetOverview() string
	// GetToolDefinitions returns the full MCP Tool definitions
	GetToolDefinitions() []mcp.Tool
	// 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 Skill struct {
	// Namespace is the namespace of the skill.
	// The format is reverse-DNS, e.g. "io.github.user".
	Namespace string `json:"namespace"`
	// Name is the name of the skill.
	// The format is that of identifiers, e.g. "my-skill".
	Name string `json:"name"`
	// Description is the description of the skill.
	Description string `json:"description"`
	// Version is the version of the skill.
	// Any non-empty string is valid, but ideally it should be either a
	// semantic version or a commit hash.
	Version string `json:"version"`
	// Status is the status of the skill.
	// Can be one of "active", "deprecated", or "archived".
	Status string `json:"status,omitempty"` // active, deprecated, archived
	// Title is the title of the skill.
	// This is for human consumption, not an identifier.
	Title string `json:"title,omitempty"`
	// License is the SPDX license identifier of the skill.
	License string `json:"license,omitempty"`
	// Compatibility is the environment requirements of the skill.
	Compatibility string `json:"compatibility,omitempty"`
	// AllowedTools is the list of tools that the skill is compatible with.
	// This is experimental.
	AllowedTools []string `json:"allowedTools,omitempty"`
	// Repository is the source repository of the skill.
	Repository *SkillRepository `json:"repository,omitempty"`
	// Icons is the list of icons for the skill.
	Icons []SkillIcon `json:"icons,omitempty"`
	// Packages is the list of packages for the skill.
	Packages []SkillPackage `json:"packages,omitempty"`
	// Provenance is the expected signer identity for this skill, checked on
	// first install instead of trust-on-first-use. Absent means unconstrained
	// — most catalog entries won't have this for a while, and that must not
	// break installs; it's an opt-in tightening per entry, not a requirement.
	//
	// Each field constrains independently, and an empty string leaves that
	// dimension unconstrained. Attestation is the exception: setting it at
	// all, even to an empty struct, requires the artifact to be attested, so
	// verification fails against a signature carrying no statement. Its own
	// PredicateType and Predicate then follow the usual rule and constrain
	// only when set. Predicate must be a JSON object; anything else can never
	// match, and Validate rejects it rather than letting it through as a
	// constraint that silently fails every artifact.
	Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	// Metadata is the official metadata of the skill as reported in the
	// SKILL.md file.
	Metadata map[string]any `json:"metadata,omitempty"`
	// Meta is an opaque payload with extended meta data details of the skill.
	Meta map[string]any `json:"_meta,omitempty"`
}

type SkillIcon struct {
	// Src is the source of the icon.
	Src string `json:"src"`
	// Size is the size of the icon.
	Size string `json:"size,omitempty"`
	// Type is the type of the icon.
	Type string `json:"type,omitempty"`
	// Label is the label of the icon.
	Label string `json:"label,omitempty"`
}

type SkillPackage struct {
	// RegistryType is the type of registry the package is from.
	// Can be "oci" or "git".
	RegistryType string `json:"registryType"` // "oci" or "git"
	// Identifier is the OCI identifier of the package.
	Identifier string `json:"identifier,omitempty"`
	// Digest is the digest of the package.
	Digest string `json:"digest,omitempty"`
	// MediaType is the media type of the package.
	MediaType string `json:"mediaType,omitempty"`
	// URL is the URL of the package.
	URL string `json:"url,omitempty"`
	// Ref is the reference of the package.
	Ref string `json:"ref,omitempty"`
	// Commit is the commit of the package.
	Commit string `json:"commit,omitempty"`
	// Subfolder is the subfolder of the package.
	Subfolder string `json:"subfolder,omitempty"`
}

type SkillRepository struct {
	// URL is the URL of the repository.
	URL string `json:"url,omitempty"`
	// Type is the type of the repository.
	Type string `json:"type,omitempty"`
}

type UpstreamData struct {
	// Servers contains the server definitions in upstream MCP format
	Servers []upstreamv0.ServerJSON `json:"servers" yaml:"servers"`

	// Skills contains the skill definitions
	Skills []Skill `json:"skills,omitempty" yaml:"skills,omitempty"`

	// Plugins contains the plugin definitions
	Plugins []Plugin `json:"plugins,omitempty" yaml:"plugins,omitempty"`
}

type UpstreamMeta struct {
	// LastUpdated is the timestamp when registry was last updated in RFC3339 format
	LastUpdated string `json:"last_updated" yaml:"last_updated"`
}

type UpstreamRegistry struct {
	// Schema is the JSON schema URL for validation
	Schema string `json:"$schema" yaml:"$schema"`

	// Version is the schema version (e.g., "1.0.0")
	Version string `json:"version" yaml:"version"`

	// Meta contains registry metadata
	Meta UpstreamMeta `json:"meta" yaml:"meta"`

	// Data contains the actual registry content
	Data UpstreamData `json:"data" yaml:"data"`
}

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