mcp

type AdapterOption func(*adapter)

type AgentToolOptions struct {
	// Name and Description default to the agent's.
	Name        string
	Description string
	// Approve decides the tool calls the agent needs approval for. It
	// defaults to ElicitApproval, which asks the MCP client's user.
	Approve func(ctx context.Context, req *loop.ApprovalRequest) (loop.Approval, error)
	// MaxApprovalRounds bounds how often a call resumes the agent after
	// approvals. Defaults to 16.
	MaxApprovalRounds int
}

type AuthOptions struct {
	// Verify validates bearer tokens. It is required.
	Verify TokenVerifier
	// Metadata is the server's Protected Resource Metadata. The handler
	// serves it at MetadataURL when that request reaches it, and names
	// that URL in its challenges.
	Metadata *ProtectedResourceMetadata
	// MetadataURL is where the metadata is served. Defaults to
	// ProtectedResourceMetadataURL(Metadata.Resource).
	MetadataURL string
	// Scopes are required for every request.
	Scopes []string
	// OperationScopes, if set, returns the scopes an operation needs
	// beyond Scopes: name is the tool or prompt name or resource URI of
	// tools/call, prompts/get and resources/read. A token without them is
	// refused with 403 insufficient_scope naming every scope the operation
	// needs, so that the client can step up its authorization.
	OperationScopes func(method, name string) []string
}

type AuthorizationResponse struct {
	Code             string
	State            string
	Issuer           string
	Error            string
	ErrorDescription string
}

type AuthorizationServerMetadata struct {
	Issuer                                     string   `json:"issuer"`
	AuthorizationEndpoint                      string   `json:"authorization_endpoint,omitempty"`
	TokenEndpoint                              string   `json:"token_endpoint,omitempty"`
	RegistrationEndpoint                       string   `json:"registration_endpoint,omitempty"`
	JWKSURI                                    string   `json:"jwks_uri,omitempty"`
	ScopesSupported                            []string `json:"scopes_supported,omitempty"`
	ResponseTypesSupported                     []string `json:"response_types_supported,omitempty"`
	GrantTypesSupported                        []string `json:"grant_types_supported,omitempty"`
	TokenEndpointAuthMethodsSupported          []string `json:"token_endpoint_auth_methods_supported,omitempty"`
	TokenEndpointAuthSigningAlgValuesSupported []string `json:"token_endpoint_auth_signing_alg_values_supported,omitempty"`
	CodeChallengeMethodsSupported              []string `json:"code_challenge_methods_supported,omitempty"`
	ClientIDMetadataDocumentSupported          bool     `json:"client_id_metadata_document_supported,omitempty"`
	AuthorizationResponseISSParameterSupported bool     `json:"authorization_response_iss_parameter_supported,omitempty"`
}

type CallToolResult struct {
	Content           []Content       `json:"content"`
	StructuredContent json.RawMessage `json:"structuredContent,omitempty"`
	IsError           bool            `json:"isError,omitempty"`
}

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

type ClientOption func(*Client)

type ClientRegistration struct {
	ClientID                string   `json:"client_id"`
	ClientSecret            string   `json:"client_secret,omitempty"`
	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	RedirectURIs            []string `json:"redirect_uris,omitempty"`
}

type Content struct {
	Type     string            `json:"type"`
	Text     string            `json:"text,omitempty"`
	Data     string            `json:"data,omitempty"`
	MimeType string            `json:"mimeType,omitempty"`
	URI      string            `json:"uri,omitempty"`
	Name     string            `json:"name,omitempty"`
	Resource *ResourceContents `json:"resource,omitempty"`
}

type DiscoverResult struct {
	SupportedVersions []string        `json:"supportedVersions"`
	Capabilities      json.RawMessage `json:"capabilities"`
	Instructions      string          `json:"instructions,omitempty"`
	// ServerInfo is self-reported by the server and is only meant for
	// display and logging.
	ServerInfo Implementation `json:"-"`
}

type ElicitRequest struct {
	// Mode is ElicitationForm or ElicitationURL. Requests without a mode
	// are form requests; the client fills in the mode.
	Mode    string `json:"mode,omitempty"`
	Message string `json:"message"`
	// RequestedSchema describes the form: a flat object of primitive
	// properties.
	RequestedSchema json.RawMessage `json:"requestedSchema,omitempty"`
	// URL is the page a URL mode elicitation asks the user to open. The
	// client must show it in full, must not open or prefetch it without the
	// user's consent, and must open it so that neither it nor the model can
	// see what the user enters.
	URL string `json:"url,omitempty"`
	// ElicitationID identifies a URL mode elicitation of revision
	// 2025-11-25. Later revisions have none.
	ElicitationID string `json:"elicitationId,omitempty"`
}

type ElicitResult struct {
	// Action is ElicitAccept, ElicitDecline or ElicitCancel.
	Action string `json:"action"`
	// Content holds the submitted form data of an accepted form mode
	// elicitation: strings, numbers, booleans and string arrays.
	Content map[string]any `json:"content,omitempty"`
}

type ElicitationHandler func(ctx context.Context, req *ElicitRequest) (*ElicitResult, error)

type Error struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

type GetPromptResult struct {
	Description string          `json:"description,omitempty"`
	Messages    []PromptMessage `json:"messages"`
}

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

type HTTPOptions struct {
	// AllowedOrigins lists the Origin header values accepted, such as
	// "https://app.example.com"; "*" accepts any. Requests from loopback
	// origins (localhost, 127.0.0.1, [::1]) are always accepted. Requests
	// with any other Origin are refused with 403 Forbidden, which protects
	// local servers from DNS rebinding attacks; requests without an Origin,
	// which do not come from browsers, are accepted.
	AllowedOrigins []string
	// AllowedHosts, if set, lists the Host header values accepted, such as
	// "localhost:8080". Servers bound to a loopback address should set it,
	// as a second defense against DNS rebinding.
	AllowedHosts []string
	// Auth, if set, requires bearer tokens; see AuthOptions.
	Auth *AuthOptions
	// SessionTimeout ends sessions of initialization-based revisions that
	// were idle that long, without requests or open streams. Defaults to
	// 30 minutes; negative never ends them.
	SessionTimeout time.Duration
	// PollInterval, if positive, closes the SSE connections of sessions
	// after that long, sending a retry field first, without ending their
	// streams: the client reconnects with Last-Event-ID, as revision
	// 2025-11-25 allows servers to do to avoid long-lived connections.
	PollInterval time.Duration
	// RetryInterval is the reconnection time sent on those streams.
	// Defaults to 1 second.
	RetryInterval time.Duration
	// KeepAlive is the interval of the comments sent on quiet long-lived
	// streams: subscriptions/listen responses and session GET streams.
	// Defaults to 25 seconds; negative disables them.
	KeepAlive time.Duration
	// MaxBodyBytes bounds the size of a POST body. Defaults to 4 MiB.
	MaxBodyBytes int64
	// MaxStreamEvents bounds the events kept per session stream for
	// resumption. Defaults to 1024; older events cannot be replayed.
	MaxStreamEvents int
}

type HTTPStatusError struct {
	StatusCode int
	// Body is the start of the response body.
	Body string
}

type HTTPTransport struct {
	URL    string
	Client *http.Client
	Header http.Header
	// ReconnectDelay is how long to wait before resuming a stream whose
	// server set no reconnection time. Defaults to 1 second.
	ReconnectDelay time.Duration
	// MaxReconnectAttempts bounds the consecutive failed attempts to resume
	// a stream. Defaults to 5.
	MaxReconnectAttempts int
	// contains filtered or unexported fields
}

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

type Icon struct {
	Src      string   `json:"src"`
	MimeType string   `json:"mimeType,omitempty"`
	Sizes    []string `json:"sizes,omitempty"`
	Theme    string   `json:"theme,omitempty"`
}

type Implementation struct {
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
	WebsiteURL  string `json:"websiteUrl,omitempty"`
	Icons       []Icon `json:"icons,omitempty"`
}

type InputRequiredError struct {
	InputRequests map[string]json.RawMessage
	RequestState  string
}

type LogLevel string

type LogMessage struct {
	Level  LogLevel        `json:"level"`
	Logger string          `json:"logger,omitempty"`
	Data   json.RawMessage `json:"data"`
}

type LoopbackRedirect struct {
	// Open shows the authorization URL to the user. Defaults to
	// OpenBrowser.
	Open func(authURL string) error
	// contains filtered or unexported fields
}

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

type MissingCapabilityError struct {
	Method string
	// Required is the missing capability in the form of
	// ClientCapabilities, such as {"sampling": {}}.
	Required map[string]any
}

type ModelHint struct {
	Name string `json:"name,omitempty"`
}

type ModelPreferences struct {
	Hints                []ModelHint `json:"hints,omitempty"`
	CostPriority         *float64    `json:"costPriority,omitempty"`
	SpeedPriority        *float64    `json:"speedPriority,omitempty"`
	IntelligencePriority *float64    `json:"intelligencePriority,omitempty"`
}

type OAuthConfig struct {
	// Grant is GrantAuthorizationCode, the default, or
	// GrantClientCredentials for machine-to-machine access without a user,
	// as the OAuth client credentials extension of MCP
	// (io.modelcontextprotocol/oauth-client-credentials) describes. The
	// latter needs a pre-registered ClientID with ClientSecret or
	// ClientAssertion.
	Grant string

	// ClientID and ClientSecret are pre-registered client credentials,
	// which take precedence over the other ways to obtain a client ID.
	ClientID     string
	ClientSecret string
	// ClientIssuer, if set, is the issuer of the authorization server the
	// pre-registered credentials belong to. Authorization fails if the
	// server names another one, rather than sending it the credentials.
	ClientIssuer string
	// TokenEndpointAuthMethod is how the pre-registered client
	// authenticates at the token endpoint. Defaults to
	// AuthMethodClientSecretBasic, or AuthMethodClientSecretPost when the
	// server supports only that, with a secret; to AuthMethodPrivateKeyJWT
	// with ClientAssertion; and to AuthMethodNone otherwise.
	TokenEndpointAuthMethod string
	// ClientAssertion returns a signed JWT for AuthMethodPrivateKeyJWT
	// (RFC 7523); see PrivateKeyJWT.
	ClientAssertion func(ctx context.Context, issuer, tokenEndpoint string) (string, error)

	// ClientMetadataURL is the HTTPS URL of the client's Client ID Metadata
	// Document, used as the client ID with authorization servers that
	// declare client_id_metadata_document_supported. The document must list
	// RedirectURL.
	ClientMetadataURL string

	// ClientName, ClientURI and ApplicationType describe the client in
	// Dynamic Client Registration, the fallback for servers that support
	// neither of the above. ApplicationType defaults to "native" for a
	// loopback RedirectURL and "web" otherwise.
	ClientName      string
	ClientURI       string
	ApplicationType string

	// RedirectURL receives the authorization response; it must be a
	// loopback or HTTPS URL. See LoopbackRedirect.
	RedirectURL string
	// Authorize lets the user authorize the client: it shows authURL to
	// the user, usually by opening a browser, and returns the authorization
	// response delivered to RedirectURL. It is required for
	// GrantAuthorizationCode. LoopbackRedirect.Authorize implements it.
	Authorize func(ctx context.Context, authURL string) (*AuthorizationResponse, error)

	// Scopes are requested when neither the challenge nor the Protected
	// Resource Metadata names any.
	Scopes []string
	// Store keeps tokens and dynamic client registrations. Defaults to a
	// MemoryTokenStore.
	Store TokenStore
	// HTTPClient sends the requests to the authorization server and for the
	// metadata. Defaults to an http.Client with the wrapped transport.
	HTTPClient *http.Client
	// SelectAuthorizationServer chooses among the authorization servers of
	// the Protected Resource Metadata. Defaults to the first.
	SelectAuthorizationServer func(issuers []string) string
}

type OAuthError struct {
	StatusCode  int    `json:"-"`
	Code        string `json:"error"`
	Description string `json:"error_description,omitempty"`
	URI         string `json:"error_uri,omitempty"`
}

type Prompt struct {
	Name        string           `json:"name"`
	Title       string           `json:"title,omitempty"`
	Description string           `json:"description,omitempty"`
	Arguments   []PromptArgument `json:"arguments,omitempty"`
	Icons       []Icon           `json:"icons,omitempty"`
}

type PromptArgument struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

type PromptHandler func(ctx context.Context, args map[string]string) (*GetPromptResult, error)

type PromptMessage struct {
	Role    string  `json:"role"`
	Content Content `json:"content"`
}

type PromptSource interface {
	// Prompts lists the prompts, in a stable order.
	Prompts(ctx context.Context) ([]Prompt, error)
	// GetPrompt renders one; it returns an error wrapping
	// ErrPromptNotFound for a name it does not know.
	GetPrompt(ctx context.Context, name string, args map[string]string) (*GetPromptResult, error)
}

type ProtectedResourceMetadata struct {
	// Resource is the server's resource identifier: its canonical URI,
	// such as https://mcp.example.com/mcp.
	Resource string `json:"resource"`
	// AuthorizationServers lists the issuer identifiers of the
	// authorization servers; MCP requires at least one.
	AuthorizationServers              []string `json:"authorization_servers,omitempty"`
	JWKSURI                           string   `json:"jwks_uri,omitempty"`
	ScopesSupported                   []string `json:"scopes_supported,omitempty"`
	BearerMethodsSupported            []string `json:"bearer_methods_supported,omitempty"`
	ResourceSigningAlgValuesSupported []string `json:"resource_signing_alg_values_supported,omitempty"`
	ResourceName                      string   `json:"resource_name,omitempty"`
	ResourceDocumentation             string   `json:"resource_documentation,omitempty"`
	ResourcePolicyURI                 string   `json:"resource_policy_uri,omitempty"`
	ResourceTOSURI                    string   `json:"resource_tos_uri,omitempty"`
}

type RequestInfo struct {
	Method string
	// ProtocolVersion is ProtocolVersion, or the revision of the session.
	ProtocolVersion string
	// Client is what the client reports about itself; it is not verified.
	Client Implementation
	// SessionID is the Streamable HTTP session of an initialization-based
	// revision, if any.
	SessionID string
	// Token is the verified access token, when the HTTP handler checks
	// tokens.
	Token *TokenInfo
}

type Resource struct {
	URI         string `json:"uri"`
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
	Icons       []Icon `json:"icons,omitempty"`
}

type ResourceContents struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`
}

type ResourceHandler func(ctx context.Context, uri string) ([]ResourceContents, error)

type ResourceSource interface {
	// Resources lists the resources, in a stable order.
	Resources(ctx context.Context) ([]Resource, error)
	// ReadResource reads one; it returns an error wrapping
	// ErrResourceNotFound for a URI it does not know.
	ReadResource(ctx context.Context, uri string) ([]ResourceContents, error)
}

type ResourceTemplate struct {
	URITemplate string `json:"uriTemplate"`
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
	Icons       []Icon `json:"icons,omitempty"`
}

type ResourceTemplateSource interface {
	ResourceTemplates(ctx context.Context) ([]ResourceTemplate, error)
}

type Root struct {
	// URI must be a file:// URI.
	URI  string `json:"uri"`
	Name string `json:"name,omitempty"`
}

type RootsFunc func(ctx context.Context) ([]Root, error)

type SamplingContent struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
	// Data is the base64 data of an image or audio block.
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mimeType,omitempty"`

	// ID, Name and Input describe a tool_use block.
	ID    string          `json:"id,omitempty"`
	Name  string          `json:"name,omitempty"`
	Input json.RawMessage `json:"input,omitempty"`

	// ToolUseID, Content, StructuredContent and IsError describe a
	// tool_result block.
	ToolUseID         string          `json:"toolUseId,omitempty"`
	Content           []Content       `json:"content,omitempty"`
	StructuredContent json.RawMessage `json:"structuredContent,omitempty"`
	IsError           bool            `json:"isError,omitempty"`
}

type SamplingContents []SamplingContent

type SamplingHandler func(ctx context.Context, req *SamplingRequest) (*SamplingResult, error)

type SamplingMessage struct {
	// Role is "user" or "assistant".
	Role    string           `json:"role"`
	Content SamplingContents `json:"content"`
}

type SamplingOption func(*samplingConfig)

type SamplingRequest struct {
	Messages         []SamplingMessage `json:"messages"`
	ModelPreferences *ModelPreferences `json:"modelPreferences,omitempty"`
	SystemPrompt     string            `json:"systemPrompt,omitempty"`
	// IncludeContext is "none", or the deprecated "thisServer" or
	// "allServers"; the client may ignore it.
	IncludeContext string   `json:"includeContext,omitempty"`
	Temperature    *float64 `json:"temperature,omitempty"`
	// MaxTokens is the most tokens to sample; the client must respect it.
	MaxTokens     int             `json:"maxTokens"`
	StopSequences []string        `json:"stopSequences,omitempty"`
	Metadata      json.RawMessage `json:"metadata,omitempty"`
	// Tools and ToolChoice are set only for a client that declared tool
	// use with SamplingTools.
	Tools      []Tool              `json:"tools,omitempty"`
	ToolChoice *SamplingToolChoice `json:"toolChoice,omitempty"`
}

type SamplingResult struct {
	// Role is "assistant"; it defaults to that when empty.
	Role    string           `json:"role"`
	Content SamplingContents `json:"content"`
	// Model names the model that generated the message.
	Model      string `json:"model"`
	StopReason string `json:"stopReason,omitempty"`
}

type SamplingToolChoice struct {
	Mode string `json:"mode,omitempty"`
}

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

type ServerOptions struct {
	// Instructions tell models how to use the server.
	Instructions string
	// Registry is served live: tools registered or removed later are
	// listed too. Call Server.ToolsChanged after changing it directly.
	// Defaults to a new registry.
	Registry *tool.Registry
	// Tools are registered in the registry.
	Tools []tool.Tool
	// ToolMiddleware wraps every tool call, as tool.Executor does.
	ToolMiddleware []tool.Middleware
	// Resources and Prompts are consulted after the resources and prompts
	// added to the server.
	Resources ResourceSource
	Prompts   PromptSource
	// Logger receives the server's own warnings. Defaults to slog.Default.
	Logger *slog.Logger
	// PageSize, if positive, paginates list results.
	PageSize int
	// CacheTTL and CacheScope are the caching hints of list and read
	// results with ProtocolVersion
	// (https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching).
	// They default to 0, immediately stale, and CachePrivate.
	CacheTTL   time.Duration
	CacheScope string
	// StateKey authenticates the requestState of input_required results.
	// Servers behind a load balancer need the same key on every instance;
	// it defaults to a random key.
	StateKey []byte
	// InputTimeout bounds how long a handler waiting for client input with
	// ProtocolVersion is kept for the client's retry. Defaults to 10
	// minutes.
	InputTimeout time.Duration
	// ModernOnly serves ProtocolVersion alone: initialize is rejected with
	// an error naming the supported version, and HTTP GET and DELETE are
	// refused with 405 Method Not Allowed, as
	// https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#earlier-streamable-http-revisions
	// describes.
	ModernOnly bool
}

type StdioTransport struct {
	Command string
	Args    []string
	// Env holds KEY=value entries added to the server's environment. The
	// server inherits only a few variables of the current process, those
	// DefaultEnvironment lists, unless InheritEnv is set: a third-party
	// server must not read the API keys and tokens in the client's
	// environment.
	Env []string
	// InheritEnv passes the whole environment of the current process to
	// the server, before Env.
	InheritEnv bool
	Dir        string
	// Stderr receives the server's standard error. Defaults to discarding.
	Stderr io.Writer
	// ShutdownTimeout bounds how long Close waits for the process to exit
	// after closing its input. Defaults to 5 seconds.
	ShutdownTimeout time.Duration
	// contains filtered or unexported fields
}

type Subscription struct {
	ToolsListChanged      bool     `json:"toolsListChanged,omitempty"`
	PromptsListChanged    bool     `json:"promptsListChanged,omitempty"`
	ResourcesListChanged  bool     `json:"resourcesListChanged,omitempty"`
	ResourceSubscriptions []string `json:"resourceSubscriptions,omitempty"`
}

type TemplateHandler func(ctx context.Context, uri string, vars map[string]string) ([]ResourceContents, error)

type Token struct {
	AccessToken  string    `json:"access_token"`
	TokenType    string    `json:"token_type,omitempty"`
	RefreshToken string    `json:"refresh_token,omitempty"`
	Expiry       time.Time `json:"expiry,omitzero"`
	// Scope is the space-separated scope granted, or requested if the
	// server did not say.
	Scope string `json:"scope,omitempty"`
	// Issuer is the authorization server that issued the token, and
	// Resource the resource it was requested for.
	Issuer   string `json:"issuer,omitempty"`
	Resource string `json:"resource,omitempty"`
}

type TokenInfo struct {
	// Subject identifies the principal. Sessions and the requestState of
	// input_required results are bound to it.
	Subject string
	// Scopes are the scopes the token grants.
	Scopes []string
	// Audience, if set, must include the resource of the Protected
	// Resource Metadata.
	Audience []string
	// ExpiresAt, if set, is checked on every request.
	ExpiresAt time.Time
	// Extra holds verifier-specific claims.
	Extra map[string]any
}

type TokenStore interface {
	// Token returns the token for server, or nil if there is none.
	Token(ctx context.Context, server string) (*Token, error)
	// SetToken saves the token for server; nil deletes it.
	SetToken(ctx context.Context, server string, tok *Token) error
	// Client returns the registration with issuer, or nil.
	Client(ctx context.Context, issuer string) (*ClientRegistration, error)
	// SetClient saves the registration with issuer; nil deletes it.
	SetClient(ctx context.Context, issuer string, reg *ClientRegistration) error
}

type TokenVerifier func(ctx context.Context, token string, r *http.Request) (*TokenInfo, error)

type Tool struct {
	Name         string           `json:"name"`
	Title        string           `json:"title,omitempty"`
	Description  string           `json:"description,omitempty"`
	InputSchema  json.RawMessage  `json:"inputSchema"`
	OutputSchema json.RawMessage  `json:"outputSchema,omitempty"`
	Annotations  *ToolAnnotations `json:"annotations,omitempty"`
	Icons        []Icon           `json:"icons,omitempty"`
}

type ToolAnnotations struct {
	Title           string `json:"title,omitempty"`
	ReadOnlyHint    *bool  `json:"readOnlyHint,omitempty"`
	DestructiveHint *bool  `json:"destructiveHint,omitempty"`
	IdempotentHint  *bool  `json:"idempotentHint,omitempty"`
	OpenWorldHint   *bool  `json:"openWorldHint,omitempty"`
}

type Transport interface {
	// Start connects the transport. It is called once before Send.
	Start(ctx context.Context) error
	// Send writes one JSON-RPC message. If it fails after the message may
	// have reached the peer, the error wraps ErrMaybeSent.
	Send(ctx context.Context, msg []byte) error
	// Receive returns incoming messages. The channel is closed when the
	// connection ends; Err then reports why.
	Receive() <-chan []byte
	// Err returns the error that ended the connection, if any.
	Err() error
	// Close shuts the transport down.
	Close() error
}