mcp

type ClientMetadataDocument struct {
	URL         string
	RedirectURL string
}

type ClientMetadataDocumentFunc func(serverURL, redirectURL string, metadata *oauthex.AuthServerMeta) (*ClientMetadataDocument, error)

type ConvertResultOptions struct {
	// ReadableResources reports that read_mcp_resource can read the server's
	// resources, which resource links then name.
	ReadableResources bool
}

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

type ExtensionOptions struct {
	// Servers are the servers to connect, with distinct names. The
	// extension sets their OnTools; their OnChange is called after the
	// extension's.
	Servers []ServerConnectionOptions
	// Tools receives the servers' tools and the resource tools. Required.
	Tools ToolRegistry
	// StartupWait is how long WaitForStartup waits for servers still
	// connecting. Zero means DefaultStartupWait.
	StartupWait time.Duration
}

type HTTPTransportOptions struct {
	// HTTPClient sends the requests. Nil means a default client. Apps that
	// let users add servers should pass a client that refuses private
	// addresses.
	HTTPClient *http.Client
	// Headers are sent with each request to the endpoint's origin, for
	// example an API key for a server without OAuth. Headers the transport
	// sets itself take precedence, among them the OAuth access token once the
	// user has signed in, as in pi.
	Headers map[string]string
}

type OAuthCallback struct {
	Code  string
	State string
	Iss   string
}

type OAuthCallbackPage struct {
	OK      bool
	Message string
	Details string
}

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

type OAuthCallbackServerOptions struct {
	// Host is the address to listen on. Empty means 127.0.0.1.
	Host string
	// RedirectHost is the host name in the redirect URL, for example
	// localhost for a client registered with it while listening on
	// 127.0.0.1. Empty means Host.
	RedirectHost string
	// Port is the port to listen on. Zero means a free port.
	Port int
	// Path receives the callback. Empty means /callback.
	Path string
	// ExtraPaths receive the callback too, for example the server-specific
	// path of a redirect URI.
	ExtraPaths []string
	// Timeout bounds each wait. Zero means 5 minutes.
	Timeout time.Duration
	// RenderPage renders the browser page as HTML. Nil means a plain-text
	// message.
	RenderPage func(OAuthCallbackPage) string
}

type OAuthError struct {
	Code        string
	Description string
	StatusCode  int
}

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

type OAuthOptions struct {
	// Store keeps the state of each owner's sign-in: client registration,
	// tokens and the pending authorization request. Required.
	Store baseAgent.AuthStore
	// OwnerID is the user or tenant the credentials belong to.
	OwnerID string
	// Server names the server. With ServerURL it keys the stored state, so
	// servers sharing a URL keep separate accounts. Required.
	Server string
	// ServerURL is the MCP endpoint. Required.
	ServerURL string
	// HTTPClient sends discovery, registration and token requests. Apps that
	// let users add servers should pass a client that refuses private
	// addresses, and use it for the transport too. Nil means a default client.
	HTTPClient *http.Client
	// RequestTimeout bounds each request to the authorization server. Zero
	// means 15 seconds.
	RequestTimeout time.Duration

	// RedirectURL receives the authorization response; pass its query to
	// CompleteSignIn. It may be specific to the server, so the callback
	// knows which handler to complete. Required to sign in.
	RedirectURL string
	// ClientID and ClientSecret identify a client registered with the
	// authorization server beforehand. Without ClientID, sign-in registers
	// one dynamically (RFC 7591) and stores it.
	ClientID     string
	ClientSecret string
	// ClientName is the client_name of dynamic registration. Empty means
	// "burrow".
	ClientName string
	// ClientMetadataDocument, when set and ClientID is empty, identifies the
	// client with a Client ID Metadata Document instead of registering it
	// dynamically. See [HostedClientMetadataDocument].
	ClientMetadataDocument ClientMetadataDocumentFunc
	// Scope lists scopes, separated by spaces, to request in addition to the
	// ones the server asks for.
	Scope string
	// AuthServerMetadataURL is an authorization server metadata document
	// (RFC 8414 or OpenID Connect discovery) to use instead of discovery
	// through the server, for servers that advertise a wrong authorization
	// server or none. The document is trusted as configured, so its issuer is
	// not checked. It must use HTTPS, except on loopback hosts.
	AuthServerMetadataURL string

	// Now returns the current time. Nil means time.Now.
	Now func() time.Time
}

type PendingSignIn struct {
	Server    string
	ServerURL string
}

type RequestOptions struct {
	// Timeout bounds the request, restarting at each progress notification
	// when OnProgress is set. Zero leaves it bounded only by its context.
	Timeout time.Duration
	// OnProgress receives the server's progress notifications for the
	// request. Nil means the request does not ask for progress.
	OnProgress func(*sdk.ProgressNotificationParams)
}

type ResourceServer interface {
	Name() string
	Timeout() time.Duration
	ResourcesPage(ctx context.Context, cursor string, opts *RequestOptions) (*sdk.ListResourcesResult, error)
	ResourceTemplatesPage(ctx context.Context, cursor string, opts *RequestOptions) (*sdk.ListResourceTemplatesResult, error)
	AllResources(ctx context.Context, opts *RequestOptions) ([]*sdk.Resource, error)
	AllResourceTemplates(ctx context.Context, opts *RequestOptions) ([]*sdk.ResourceTemplate, error)
	ReadResource(ctx context.Context, uri string, opts *RequestOptions) (*sdk.ReadResourceResult, error)
}

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

type ServerConnectionOptions struct {
	// Name names the server in tool names, labels and messages. Required.
	Name string
	// CreateTransport returns the transport of each connection attempt.
	// Required.
	CreateTransport TransportFactory
	// OAuth authorizes requests to a server that signs users in with OAuth.
	// It is passed to CreateTransport.
	OAuth *OAuthHandler
	// Timeout bounds connecting and each request; for tool calls, the time
	// between progress notifications. Zero means DefaultTimeout.
	Timeout time.Duration
	// Client identifies the client to the server. Nil means burrow.
	Client *sdk.Implementation
	// OnTools is called when the server's tools were listed: after each
	// connect and when the server reports that they changed.
	OnTools func(*ServerConnection)
	// OnChange is called when the status or the tools change.
	OnChange func(*ServerConnection)
}

type ServerState string

type ServerStatus struct {
	State ServerState
	// Error says why the server failed or disconnected, or that refreshing
	// its tools failed.
	Error string
}

type SignInOptions struct {
	// Prompt shows the authorization URL and asks for the redirect URL.
	// Required.
	Prompt SignInPrompt
	// CallbackURL is the loopback redirect URI. Empty means
	// http://127.0.0.1/callback. One with a port is sent exactly as
	// written, since servers compare it as a string; localhost is served on
	// 127.0.0.1.
	CallbackURL string
	// CallbackPort is the port of a CallbackURL without one. Zero means the
	// port of the stored client's redirect URI, so it stays valid, else a
	// free port.
	CallbackPort int
	// RenderPage renders the browser page after the redirect as HTML. Nil
	// means a plain-text message.
	RenderPage func(OAuthCallbackPage) string
}

type SignInPrompt interface {
	// ShowAuthorizationURL shows the authorization URL to the user and opens
	// it in a browser.
	ShowAuthorizationURL(url string)
	// PromptForRedirectURL asks for the redirect URL from the browser
	// address bar, for when the browser cannot reach the loopback callback
	// (for example over SSH). ctx is cancelled once the callback arrives or
	// the sign-in is cancelled. An empty answer cancels the sign-in. A
	// prompt that cannot ask waits for ctx and returns its error.
	PromptForRedirectURL(ctx context.Context) (string, error)
}

type ToolCaller interface {
	CallTool(ctx context.Context, name string, args map[string]any, opts *RequestOptions) (*sdk.CallToolResult, error)
}

type ToolDefinitionOptions struct {
	// Server names the server in labels and messages.
	Server string
	Tool   *sdk.Tool
	// Name is the agent tool name, from [CreateToolName].
	Name string
	// Timeout bounds each call, restarting at each progress notification.
	// Zero leaves calls bounded only by their context.
	Timeout time.Duration
	// GetClient returns the caller at execution time, so a tool outlives the
	// connection it was listed on.
	GetClient func(ctx context.Context) (ToolCaller, error)
	// ReadableResources reports whether read_mcp_resource can read the
	// server's resources, which resource links then name. Nil means it
	// cannot.
	ReadableResources func() bool
}

type ToolDetails struct {
	Server string `json:"server"`
	Tool   string `json:"tool"`
	// StructuredContent is the result's structured content, if any. It is
	// never truncated.
	StructuredContent any `json:"structuredContent,omitempty"`
	// SignInRequired reports that the call failed because the user must sign
	// in to Server (see [ErrSignInRequired]); the result is an error result
	// saying so. Apps check it in tool events to offer sign-in. Details
	// restored from a session store are decoded JSON, not ToolDetails.
	SignInRequired bool `json:"signInRequired,omitempty"`
}

type ToolRegistry interface {
	// RegisterTool adds a tool, active, or replaces the tool of that name,
	// keeping whether it is active.
	RegisterTool(tool agent.AgentTool[any, any]) error
	GetActiveToolNames() ([]string, error)
	// SetActiveToolsByName activates the named tools and deactivates the
	// rest, ignoring unknown names.
	SetActiveToolsByName(names []string) error
}

type TransportFactory func(oauth *OAuthHandler) (sdk.Transport, error)