server

package
v0.2.19 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: MPL-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	TransportLabelKey = "mcp.transport"
	AuthModeLabelKey  = "mcp.auth-mode"
)
View Source 
const (
	DefaultConnectionTimeoutMS = 30_000
	MaxConnectionTimeoutMS     = 10 * 60 * 1_000
)

Variables

This section is empty.

Functions

func CleanupRemovedServerSecrets 

func CleanupRemovedServerSecrets(
	ctx context.Context,
	server artifact.ArtifactRef,
	data ServerData,
	cleaner SecretCleaner,
) error

CleanupRemovedServerSecrets removes every local secret binding and OAuth token after source reconciliation has confirmed that the server Artifact is missing and before its local metadata is purged.

func CleanupReplacedServerSecrets 

func CleanupReplacedServerSecrets(
	ctx context.Context,
	server artifact.ArtifactRef,
	before ServerData,
	after ServerData,
	cleaner SecretCleaner,
) error

CleanupReplacedServerSecrets removes secret bindings no longer referenced by a server installation update. OAuth token state is removed whenever the installation data changes because profile, credential, and endpoint changes invalidate prior authorization state.

func CleanupUnboundServerSecrets 

func CleanupUnboundServerSecrets(
	ctx context.Context,
	server artifact.ArtifactRef,
	document ServerDocument,
	data ServerData,
	cleaner SecretCleaner,
) error

CleanupUnboundServerSecrets removes every deterministic secret slot declared by the current canonical server document but not retained by the current installation data.

Unlike before/after-only cleanup, this operation remains retryable after the installation metadata write has committed. A retry can derive all current secret slots from the immutable server Definition and does not need the previous Artifact.Data or overlay value.

func DefinitionForCanonicalServer 

func DefinitionForCanonicalServer(
	input ServerDocument,
) (definition.Definition, error)

DefinitionForCanonicalServer converts an MCP server projected from an Artifact Store-canonicalized MCP Bundle into an immutable Definition.

Portable document validation belongs to the Artifact Store shareable schema registry. This function intentionally performs only MCP Definition projection and generic Definition canonicalization.

func EncodeServerData 

func EncodeServerData(
	input ServerData,
) (json.RawMessage, error)

func NewServerCodec 

func NewServerCodec() shareable.Codec

func SecretInputTargets 

func SecretInputTargets(
	document ServerDocument,
) (map[string]SecretInputTarget, error)

SecretInputTargets validates and returns the allowed target for every secret installation input used by a canonical ServerDocument.

Secret values may only materialize into stdio environment values or HTTP header values. They are prohibited in commands, args, URLs, OAuth metadata URLs, and all other scalar connection fields.

func SecretReferences 

func SecretReferences(data ServerData) ([]string, error)

SecretReferences returns the unique opaque secret references held by local server installation data. It never resolves or returns secret values.

func ServerSubresource 

func ServerSubresource(
	name basespec.LogicalName,
) basespec.SubresourceLocator

func ValidateMaterializedServer 

func ValidateMaterializedServer(
	core CoreServer,
	auth AuthenticationDeclaration,
) error

func ValidateServer 

func ValidateServer(value ServerDocument) error

func ValidateServerData 

func ValidateServerData(value ServerData) error

func ValidateServerDataForDocument 

func ValidateServerDataForDocument(
	server artifact.ArtifactRef,
	document ServerDocument,
	data ServerData,
) error

ValidateServerDataForDocument validates local installation data against the immutable canonical server semantics that own the input declarations.

func ValidateServerParts 

func ValidateServerParts(
	name string,
	core CoreServer,
	extension ServerExtension,
) error

Types

type AuthenticationDeclaration 

type AuthenticationDeclaration struct {
	Mode MCPHTTPAuthMode `json:"mode"`

	ClientCredentialsInput      string `json:"clientCredentialsInput,omitempty"`
	ClientIDMetadataDocumentURL string `json:"clientIDMetadataDocumentURL,omitempty"`
}

type ConnectionProfile 

type ConnectionProfile struct {
	Platforms []string      `json:"platforms,omitempty"`
	Stdio     *StdioProfile `json:"stdio,omitempty"`
	HTTP      *HTTPProfile  `json:"http,omitempty"`
}

type CoreServer 

type CoreServer struct {
	Type ServerType `json:"type,omitempty"`

	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`

	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
}

func NormalizeCoreServer 

func NormalizeCoreServer(value CoreServer) CoreServer

type EnvironmentResolver 

type EnvironmentResolver interface {
	ResolveEnvironment(
		ctx context.Context,
		name string,
	) (string, bool, error)
}

type HTTPProfile 

type HTTPProfile struct {
	URL           *string           `json:"url,omitempty"`
	Headers       map[string]string `json:"headers,omitempty"`
	RemoveHeaders []string          `json:"removeHeaders,omitempty"`
}

type InputBinding 

type InputBinding struct {
	Value     *string `json:"value,omitempty"`
	SecretRef string  `json:"secretRef,omitempty"`
}

type InputDeclaration 

type InputDeclaration struct {
	Kind                 InputKind `json:"kind"`
	Label                string    `json:"label,omitempty"`
	Description          string    `json:"description,omitempty"`
	Note                 string    `json:"note,omitempty"`
	Placeholder          string    `json:"placeholder,omitempty"`
	Required             bool      `json:"required,omitempty"`
	Default              *string   `json:"default,omitempty"`
	ClientSecretRequired bool      `json:"clientSecretRequired,omitempty"`
}

type InputKind 

type InputKind string
const (
	InputText   InputKind = "text"
	InputSecret InputKind = "secret"
	InputPath   InputKind = "path"
	//nolint:gosec // Cred enum.
	InputOAuthClientCredentials InputKind = "oauthClientCredentials"
)

type InstallationDeclaration 

type InstallationDeclaration struct {
	Note             string                      `json:"note,omitempty"`
	Inputs           map[string]InputDeclaration `json:"inputs,omitempty"`
	AllowEnvironment []string                    `json:"allowEnvironment,omitempty"`
}

type MCPHTTPAuthMode 

type MCPHTTPAuthMode string
const (
	MCPHTTPAuthNone              MCPHTTPAuthMode = "none"
	MCPHTTPAuthAPIKey            MCPHTTPAuthMode = "apiKey"
	MCPHTTPAuthOAuth             MCPHTTPAuthMode = "oauth"
	MCPHTTPAuthClientCredentials MCPHTTPAuthMode = "clientCredentials"
)

type MCPRuntimeStdioConfig 

type MCPRuntimeStdioConfig struct {
	Command          string            `json:"command"`
	Args             []string          `json:"args,omitempty"`
	Env              map[string]string `json:"env,omitempty"`
	StartupTimeoutMS int               `json:"startupTimeoutMS,omitempty"`
}

MCPRuntimeStdioConfig is the materialized process-local stdio transport configuration. Secret values have already been resolved into Env only at connection preparation time and are never persisted in an MCP document.

type MCPRuntimeStreamableHTTPConfig 

type MCPRuntimeStreamableHTTPConfig struct {
	URL       string          `json:"url"`
	TimeoutMS int             `json:"timeoutMS,omitempty"`
	AuthMode  MCPHTTPAuthMode `json:"authMode"`

	Headers map[string]string `json:"headers,omitempty"`

	ClientCredentialRef         string `json:"clientCredentialRef,omitempty"`
	ClientIDMetadataDocumentURL string `json:"clientIDMetadataDocumentURL,omitempty"`
}

MCPRuntimeStreamableHTTPConfig is the materialized process-local HTTP transport configuration. ClientCredentialRef remains an opaque Artifact-scoped Setting Store reference. Secret HTTP values are materialized only immediately before opening a runtime connection.

type MCPTransportType 

type MCPTransportType string
const (
	MCPTransportStreamableHTTP MCPTransportType = "streamableHttp"
	MCPTransportStdio          MCPTransportType = "stdio"
)

type Materialized 

type Materialized struct {
	Core CoreServer
	Auth AuthenticationDeclaration

	ClientCredentialRef            string
	ClientCredentialSecretRequired bool
	TimeoutMS                      int
	SensitiveValues                []string
}

func MaterializeInspectionValidated 

func MaterializeInspectionValidated(
	ctx context.Context,
	server artifact.ArtifactRef,
	document ServerDocument,
	data ServerData,
	environment EnvironmentResolver,
) (Materialized, error)

MaterializeInspectionValidated creates a sanitized materialization for health and setup inspection. It validates installation shape and resolves non-secret values, but it never loads a secret value from Setting Store.

func MaterializeValidated 

func MaterializeValidated(
	ctx context.Context,
	server artifact.ArtifactRef,
	document ServerDocument,
	data ServerData,
	secrets SecretResolver,
	environment EnvironmentResolver,
) (Materialized, error)

MaterializeValidated is for the internal resolver-to-runtime path. Callers must have already established that server, document, and data are valid.

It intentionally validates only values created by profile selection and substitution. Those values are not known until this function runs.

type PolicyReference 

type PolicyReference struct {
	Ref      basespec.LogicalName `json:"ref"`
	Required bool                 `json:"required"`
}

type Resolved 

type Resolved struct {
	Server               artifact.ArtifactRef     `json:"server"`
	Collection           collection.CollectionRef `json:"collection"`
	ArtifactRevision     uint64                   `json:"artifactRevision"`
	CatalogRevision      uint64                   `json:"catalogRevision"`
	DefinitionDigest     cryptoutil.Digest        `json:"definitionDigest"`
	SourceContentDigest  cryptoutil.Digest        `json:"sourceContentDigest"`
	SourceGeneration     string                   `json:"sourceGeneration"`
	Document             ServerDocument           `json:"document"`
	Installation         ServerData               `json:"installation"`
	Policy               policy.Effective         `json:"policy"`
	InstallationRevision uint64                   `json:"installationRevision"`
	RuntimeEnabled       bool                     `json:"runtimeEnabled"`
	BuiltIn              bool                     `json:"builtIn"`
	Version              cryptoutil.Digest        `json:"version"`
}

func (Resolved) Materialize 

func (r Resolved) Materialize(
	ctx context.Context,
	secrets SecretResolver,
	environment EnvironmentResolver,
) (RuntimeConfig, error)

func (Resolved) MaterializeForInspection 

func (r Resolved) MaterializeForInspection(
	ctx context.Context,
	environment EnvironmentResolver,
) (RuntimeConfig, error)

MaterializeForInspection resolves local installation inputs without requiring RuntimeEnabled. It is used only for sanitized auth-health projection and never resolves or exposes a secret value.

func (Resolved) MaterializeTrusted 

func (r Resolved) MaterializeTrusted(
	ctx context.Context,
	secrets SecretResolver,
	environment EnvironmentResolver,
) (RuntimeConfig, error)

MaterializeTrusted is the resolver-to-runtime fast path. Resolver output has already passed full Artifact, Catalog, Definition, policy, and installation validation. This method validates only values that do not exist until profile application and local substitution occur.

func (Resolved) Validate 

func (r Resolved) Validate() error

type Resolver 

type Resolver interface {
	ResolveMCPServer(
		ctx context.Context,
		ref artifact.ArtifactRef,
	) (Resolved, error)
}

type RuntimeConfig 

type RuntimeConfig struct {
	Server     artifact.ArtifactRef
	Collection collection.CollectionRef

	LogicalName string
	DisplayName string

	Transport                 MCPTransportType
	Stdio                     *MCPRuntimeStdioConfig
	StreamableHTTP            *MCPRuntimeStreamableHTTPConfig
	OAuthClientSecretRequired bool

	TrustLevel    policy.MCPTrustLevel
	DefaultPolicy policy.MCPServerPolicy
	ToolPolicies  map[string]policy.MCPToolPolicyOverride
	AppsPolicy    policy.MCPAppsPolicy

	SensitiveValues []string
}

type SecretCleaner 

type SecretCleaner interface {
	DeleteSecret(ctx context.Context, ref string) error
}

SecretCleaner removes an opaque installation-local secret reference.

Implementations must be idempotent: deleting an already removed secret must return nil. This permits retry after a successful document publication but a failed local cleanup step.

type SecretInputTarget 

type SecretInputTarget struct {
	Kind SecretInputTargetKind
	Slot string
}

SecretInputTarget is the single runtime materialization target permitted for one `secret` installation input.

A local secret reference has a target-specific kind and slot. One portable secret input cannot safely bind multiple distinct environment variables or HTTP headers because one opaque local reference cannot prove both targets.

type SecretInputTargetKind 

type SecretInputTargetKind string
const (
	//nolint:gosec // Enum.
	SecretInputTargetStdioEnv   SecretInputTargetKind = "stdioEnv"
	SecretInputTargetHTTPHeader SecretInputTargetKind = "httpHeader"
)

type SecretResolver 

type SecretResolver interface {
	ResolveSecret(
		ctx context.Context,
		ref string,
	) (string, error)
}

type ServerCodec 

type ServerCodec struct{}

func (ServerCodec) Canonicalize 

func (ServerCodec) Canonicalize(
	ctx context.Context,
	raw []byte,
) (shareable.ParsedDocument, error)

func (ServerCodec) JSONSchema 

func (ServerCodec) JSONSchema() []byte

func (ServerCodec) Key 

func (ServerCodec) Key() shareable.SchemaKey

type ServerData 

type ServerData struct {
	SchemaVersion string `json:"schemaVersion"`

	SelectedConnectionProfile string                  `json:"selectedConnectionProfile,omitempty"`
	Inputs                    map[string]InputBinding `json:"inputs,omitempty"`
	AdditionalPolicies        []artifact.ArtifactRef  `json:"additionalPolicies,omitempty"`
}

func DecodeServerData 

func DecodeServerData(
	raw json.RawMessage,
) (ServerData, error)

func DefaultServerData 

func DefaultServerData() ServerData

type ServerDefinitionBody 

type ServerDefinitionBody struct {
	MCPServer CoreServer      `json:"mcpServer"`
	Extension ServerExtension `json:"extension"`
}

func ServerBodyFromDefinition 

func ServerBodyFromDefinition(
	input definition.Definition,
) (ServerDefinitionBody, error)

type ServerDocument 

type ServerDocument struct {
	Kind          basespec.ArtifactKind `json:"kind"`
	SchemaID      basespec.SchemaID     `json:"schemaID"`
	SchemaVersion string                `json:"schemaVersion"`
	Digest        cryptoutil.Digest     `json:"digest,omitempty"`

	LogicalName    basespec.LogicalName    `json:"logicalName"`
	LogicalVersion basespec.LogicalVersion `json:"logicalVersion,omitempty"`
	DisplayName    string                  `json:"displayName,omitempty"`
	Description    string                  `json:"description,omitempty"`
	Labels         map[string]string       `json:"labels,omitempty"`

	MCPServer CoreServer      `json:"mcpServer"`
	Extension ServerExtension `json:"extension"`
}

func CanonicalizeServer 

func CanonicalizeServer(
	input ServerDocument,
) (ServerDocument, json.RawMessage, error)

func (ServerDocument) OAuthClientSecretRequired 

func (d ServerDocument) OAuthClientSecretRequired() bool

OAuthClientSecretRequired reports whether the declared OAuth client input must contain a confidential-client secret. Client-credentials flow always requires a secret even if a document omitted the explicit declaration flag.

type ServerExtension 

type ServerExtension struct {
	LogicalVersion basespec.LogicalVersion `json:"logicalVersion,omitempty"`
	DisplayName    string                  `json:"displayName,omitempty"`
	Description    string                  `json:"description,omitempty"`
	TimeoutMS      int                     `json:"timeoutMS,omitempty"`
	Labels         map[string]string       `json:"labels,omitempty"`

	Auth               AuthenticationDeclaration    `json:"auth"`
	Install            InstallationDeclaration      `json:"install"`
	ConnectionProfiles map[string]ConnectionProfile `json:"connectionProfiles,omitempty"`
	Policy             *PolicyReference             `json:"policy,omitempty"`
}

func NormalizeServerExtension 

func NormalizeServerExtension(
	name string,
	value ServerExtension,
) ServerExtension

type ServerType 

type ServerType string
const (
	ServerTypeStdio ServerType = "stdio"
	ServerTypeHTTP  ServerType = "http"
)

type StdioProfile 

type StdioProfile struct {
	Command   *string           `json:"command,omitempty"`
	Args      *[]string         `json:"args,omitempty"`
	Env       map[string]string `json:"env,omitempty"`
	RemoveEnv []string          `json:"removeEnv,omitempty"`
}

Source Files

View all Source files

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.