servercard

package
v1.0.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package servercard builds, validates, and fetches SEP-2127 Server Cards and the draft AI Catalog document that points at them.

Cards are advisory public metadata. They are not a trust decision, a credential source, or a substitute for the gateway's own pin flow.

Index

Constants

View Source 
const (
	MediaTypeServerCard = "application/mcp-server-card+json"
	MediaTypeCatalog    = "application/ai-catalog+json"
	SchemaURL           = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json"
	ServerCardSuffix    = "/server-card"
	CatalogWellKnown    = "/.well-known/ai-catalog.json"
	MaxBodyBytes        = 64 * 1024
)

Media types and the schema URL the card document must declare.

Variables

View Source 
var (
	ErrNoCard      = errors.New("no server card")
	ErrInvalidCard = errors.New("invalid server card")
	ErrOffOrigin   = errors.New("off-origin server card remote")
	ErrFetchFailed = errors.New("server card fetch failed")
	ErrTemplateURL = errors.New("server card URL template")
)

Fetch failures the REST and CLI callers map onto typed codes.

Functions

func CardURL 

func CardURL(origin, prefix, group string) string

CardURL builds the absolute card URL for an origin and optional group.

func CardURLFor 

func CardURLFor(raw string) (string, error)

CardURLFor appends /server-card to a server URL unless it already ends there.

func CatalogURLFor 

func CatalogURLFor(raw string) (string, error)

CatalogURLFor returns the origin's /.well-known/ai-catalog.json.

func CompileVendoredSchema 

func CompileVendoredSchema(path string) (*jsonschema.Schema, error)

CompileVendoredSchema loads the vendored SEP-2127 schema and compiles #/$defs/ServerCard. Production Validate does not call this. Tests and the integration suite use it so the schema library stays a direct dependency and the check does not fetch a schema over the network.

func SameOrigin 

func SameOrigin(a, b string) bool

SameOrigin reports whether two URLs share scheme, host, and port. Default ports are normalized so https://host and https://host:443 match.

func Segment 

func Segment(name string) string

Segment returns the sanitized gateway-name segment used in card names and catalog identifiers. Dots are preserved. A group suffix is not appended.

func Validate 

func Validate(card *ServerCard) error

Validate enforces the vendored schema's required fields, name pattern, and length bounds. It does not load a JSON Schema library.

Types

type Catalog 

type Catalog struct {
	SpecVersion string         `json:"specVersion"`
	Entries     []CatalogEntry `json:"entries"`
}

Catalog is an AI Catalog document. specVersion 1.0 allows an empty entries array.

func BuildCatalog 

func BuildCatalog(origin, prefix, segment string, groups []string, cards map[string]string) *Catalog

BuildCatalog returns a catalog whose entries use the same origin as the cards. An empty origin yields an empty entries array.

func FetchCatalog 

func FetchCatalog(ctx context.Context, rawURL string, opts FetchOptions) (*Catalog, error)

FetchCatalog retrieves an AI Catalog document with the same bounds as Fetch.

type CatalogEntry 

type CatalogEntry struct {
	Identifier string `json:"identifier"`
	Type       string `json:"type"`
	URL        string `json:"url"`
}

CatalogEntry points at one Server Card.

type Draft 

type Draft struct {
	Entry              catalog.Entry
	Warnings           []string
	ProtocolGeneration string
	CardURL            string
}

Draft is a catalog entry synthesized from a card, plus warnings that did not become stack fields. ProtocolGeneration is empty unless every listed version is supported and they share one era.

func DraftFromCard 

func DraftFromCard(card *ServerCard, submittedURL string) (Draft, error)

DraftFromCard maps one same-origin remote onto a catalog entry the existing add path can prompt, vault, and write. The submitted URL is the caller's origin; an off-origin remote or a URL template is refused rather than followed.

func (Draft) ServerDraft 

func (d Draft) ServerDraft(name string) (config.MCPServer, []string, error)

ServerDraft fills required inputs with ${var:KEY} placeholders and returns the stack block. It never copies a credential value.

type FetchOptions 

type FetchOptions struct {
	Timeout  time.Duration
	MaxBytes int64
	Client   *http.Client
}

FetchOptions bounds a card or catalog fetch. Zero values use the package defaults. Client, when set, is used as-is except that a nil CheckRedirect is replaced so redirects are refused.

type Identity 

type Identity struct {
	// GatewayName is the serverInfo.name the gateway announces, before any
	// group suffix.
	GatewayName string
	// StackName is the stack file name used in the default description.
	StackName string
	// Description overrides the default when non-empty.
	Description string
	// Version is the gateway version string.
	Version string
	// Group is empty for the gateway card.
	Group string
	// AuthType is "bearer", "api_key", or empty.
	AuthType string
	// AuthHeader is the api_key header name. Empty means Authorization.
	AuthHeader string
	// Origin is scheme://host[:port]. Empty omits remotes.
	Origin string
	// PathPrefix is the public_url path, without a trailing slash.
	PathPrefix string
	// ProtocolVersions is copied onto the remote when an origin exists.
	ProtocolVersions []string
}

Identity is the gateway identity a card is built from. It never carries a credential value.

type Input 

type Input struct {
	Description string `json:"description,omitempty"`
	Value       string `json:"value,omitempty"`
	IsRequired  bool   `json:"isRequired,omitempty"`
	IsSecret    bool   `json:"isSecret,omitempty"`
}

Input describes one user-supplied or pre-set value.

type KeyValueInput 

type KeyValueInput struct {
	Name        string           `json:"name"`
	Value       string           `json:"value,omitempty"`
	Description string           `json:"description,omitempty"`
	IsRequired  bool             `json:"isRequired,omitempty"`
	IsSecret    bool             `json:"isSecret,omitempty"`
	Variables   map[string]Input `json:"variables,omitempty"`
}

KeyValueInput is a named header whose value may reference variables.

type Remote 

type Remote struct {
	Type                      string          `json:"type"`
	URL                       string          `json:"url"`
	Headers                   []KeyValueInput `json:"headers,omitempty"`
	SupportedProtocolVersions []string        `json:"supportedProtocolVersions,omitempty"`
}

Remote is one HTTP endpoint a client can connect to.

type ServerCard 

type ServerCard struct {
	Schema      string         `json:"$schema"`
	Name        string         `json:"name"`
	Title       string         `json:"title,omitempty"`
	Description string         `json:"description"`
	Version     string         `json:"version"`
	Remotes     []Remote       `json:"remotes,omitempty"`
	Meta        map[string]any `json:"_meta,omitempty"`
}

ServerCard is a static discovery document for one remote MCP server. Field names follow the vendored schema. Tools, prompts, and resources are intentionally absent.

func Build 

func Build(id Identity) (*ServerCard, error)

Build returns a card that Validate accepts. A gateway name with a slash, a space, or a long value is sanitized before it reaches name.

func Fetch 

func Fetch(ctx context.Context, rawURL string, opts FetchOptions) (*ServerCard, error)

Fetch retrieves one Server Card. It sends no credentials, follows no redirects, and refuses a body over the byte bound.

func Resolve 

func Resolve(ctx context.Context, submittedURL string, opts FetchOptions) (*ServerCard, error)

Resolve fetches <url>/server-card and, on 404, the origin catalog. Catalog entries on another host are skipped; they are not a selected remote. A selected remote on a different scheme, host, or port is refused. URL templates are refused. The returned card is the one whose remote was accepted.

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.