mcp

type Annotations struct {
	Audience     []string `json:"audience,omitempty"`
	Priority     *float64 `json:"priority,omitempty"`
	LastModified string   `json:"lastModified,omitempty"`
}

type AuthChallenge struct {
	// Server is the server's name in the client configuration.
	Server string
	// ResourceURL is the URL of the request the server refused: the MCP
	// endpoint, which is the protected resource.
	ResourceURL string
	// Status is 401 (missing or invalid credentials) or 403 (insufficient
	// scope).
	Status int
	// Challenges are the parsed WWW-Authenticate challenges.
	Challenges []WWWAuthenticate
	// ResourceMetadata, Scope, Error and ErrorDescription are the parameters
	// of the Bearer challenge, if there is one. ResourceMetadata is the
	// protected resource metadata URL (RFC 9728); Scope is the scope the
	// server needs.
	ResourceMetadata string
	Scope            string
	Error            string
	ErrorDescription string
	// Header is the response's full header.
	Header http.Header
	// Attempt counts the challenges for this request, starting at 1.
	Attempt int
}

type AuthError struct {
	Server string
	Status int
	Err    error
}

type Authorizer interface {
	// Authorize adds credentials to an outgoing HTTP request: typically an
	// Authorization header, and a DPoP proof where one is used. It is
	// called for every request, including retries after a challenge.
	Authorize(ctx context.Context, req *http.Request) error

	// Challenge is called when the server rejects a request with 401, or
	// with 403 and error="insufficient_scope" (scope step-up). Return nil
	// once new credentials are ready: the request is built and sent again,
	// through Authorize. Return an error to fail the request.
	Challenge(ctx context.Context, challenge *AuthChallenge) error
}

type Client interface {
	// Initialize establishes the MCP connection and negotiates capabilities
	Initialize(ctx context.Context) (*InitializeResponse, error)

	// ListTools retrieves all available tools from the server
	ListTools(ctx context.Context) ([]Tool, error)

	// CallTool executes a tool with the given arguments
	CallTool(ctx context.Context, name string, arguments json.RawMessage) (*ToolCallResponse, error)

	// Close terminates the connection to the MCP server
	Close() error

	// IsAlive checks if the connection is still active
	IsAlive() bool
}

type ClientCapabilities struct {
	Elicitation *ElicitationCapability `json:"elicitation,omitempty"`
	Sampling    *SamplingCapability    `json:"sampling,omitempty"`
	// Deprecated: logging is a server capability; MCP defines no client
	// "logging" capability. The client never sets this.
	Logging *LoggingCapability `json:"logging,omitempty"`
	// Extensions advertises optional protocol extensions, keyed by
	// identifier (2026-07-28). The client advertises none.
	Extensions map[string]json.RawMessage `json:"extensions,omitempty"`
}

type ClientOptions struct {
	// RequestTimeout bounds each request (tools/list, tools/call). It does
	// not run out while the client is answering the server's own request
	// for user input: that time is the user's, not the server's. A
	// tools/call's timeout restarts each time the server reports progress on
	// it; the caller's context still bounds the call.
	RequestTimeout time.Duration
	// InitTimeout bounds connecting: starting a stdio server or reaching an
	// HTTP one, and agreeing the protocol.
	InitTimeout time.Duration
	// MaxRetries is the number of times connecting is retried after a
	// failure that is not the server's answer. tools/call is never retried:
	// a tool may have side effects.
	MaxRetries int
	// RetryDelay is the initial delay between retries (exponential backoff).
	RetryDelay time.Duration
	// EnableGracefulDegradation makes a failed tools/list yield no tools
	// rather than an error.
	EnableGracefulDegradation bool
	// MaxReconnectAttempts is how many times the client reconnects when its
	// connection is lost (a stdio server exits, an SSE stream ends) before
	// reporting the server unresponsive. 0 disables reconnection.
	MaxReconnectAttempts int
	// ElicitationHandler, when set, answers servers' requests for user input
	// and makes the client advertise the elicitation capability (form mode).
	// Without it the client does not advertise elicitation, and refuses
	// elicitation requests.
	ElicitationHandler ElicitationHandler
	// DisableModernProtocol skips stateless (2026-07-28) detection and always
	// uses the initialize handshake. For servers that misbehave when probed.
	DisableModernProtocol bool
	// EraProbeTimeout bounds how long the client waits for a stdio server to
	// answer the server/discover probe before restarting it with the
	// initialize handshake: a handshake-era server may never answer a
	// request it does not know. Defaults to 3s. A server slower than that to
	// start is treated as handshake-era; raise it for modern-only servers
	// with slow starts. HTTP servers always answer, so it does not apply.
	EraProbeTimeout time.Duration
	// Authorizer, when set, supplies credentials for an HTTP server and
	// handles its authorization challenges. The host implements it; see
	// Authorizer. Static credentials can go in ServerConfig.Headers instead.
	Authorizer Authorizer
}

type Content struct {
	Type     string `json:"type"` // one of the ContentType constants
	Text     string `json:"text,omitempty"`
	Data     string `json:"data,omitempty"`     // Base64 encoded data (image, audio)
	MimeType string `json:"mimeType,omitempty"` // MIME type for data
	URI      string `json:"uri,omitempty"`      // URI for resource_link
	// Name, Title, Description and Size describe a resource_link.
	Name        string `json:"name,omitempty"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Size        *int64 `json:"size,omitempty"`
	Icons       []Icon `json:"icons,omitempty"`
	// Resource is an embedded resource's contents.
	Resource    *ResourceContents          `json:"resource,omitempty"`
	Annotations *Annotations               `json:"annotations,omitempty"`
	Meta        map[string]json.RawMessage `json:"_meta,omitempty"`
}

type DiscoverResult struct {
	SupportedVersions []string                   `json:"supportedVersions"`
	Capabilities      ServerCapabilities         `json:"capabilities"`
	Instructions      string                     `json:"instructions,omitempty"`
	ResultType        string                     `json:"resultType"`
	TTLMs             *int64                     `json:"ttlMs"`
	CacheScope        string                     `json:"cacheScope"`
	Meta              map[string]json.RawMessage `json:"_meta,omitempty"`
}

type ElicitRequest struct {
	// Mode is ElicitModeForm (the default when absent) or ElicitModeURL.
	Mode            string          `json:"mode,omitempty"`
	Message         string          `json:"message"`
	RequestedSchema json.RawMessage `json:"requestedSchema,omitempty"`
	URL             string          `json:"url,omitempty"`
}

type ElicitResult struct {
	// Action is ElicitActionAccept, ElicitActionDecline or ElicitActionCancel.
	Action string `json:"action"`
	// Content is the submitted input, for an accepted form request.
	Content json.RawMessage `json:"content,omitempty"`
}

type ElicitationCapability struct {
	Form *struct{} `json:"form,omitempty"`
	URL  *struct{} `json:"url,omitempty"`
}

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

type Icon struct {
	Src      string   `json:"src"`
	MimeType string   `json:"mimeType,omitempty"`
	Sizes    []string `json:"sizes,omitempty"`
	// Theme is "light" or "dark", the background the icon is designed for.
	Theme string `json:"theme,omitempty"`
}

type Implementation struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	// Title is a display name.
	Title string `json:"title,omitempty"`
	// Description is a human-readable summary (2025-11-25).
	Description string `json:"description,omitempty"`
	// WebsiteURL links to the implementation's site (2025-11-25).
	WebsiteURL string `json:"websiteUrl,omitempty"`
	// Icons are display icons (2025-11-25).
	Icons []Icon `json:"icons,omitempty"`
}

type InitializeRequest struct {
	ProtocolVersion string             `json:"protocolVersion"`
	Capabilities    ClientCapabilities `json:"capabilities"`
	ClientInfo      Implementation     `json:"clientInfo"`
}

type InitializeResponse struct {
	ProtocolVersion string             `json:"protocolVersion"`
	Capabilities    ServerCapabilities `json:"capabilities"`
	ServerInfo      Implementation     `json:"serverInfo"`
	// Instructions is the server's guidance on how to use it.
	Instructions string `json:"instructions,omitempty"`
}

type InputRequest struct {
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
}

type InputRequiredResult struct {
	ResultType    string                     `json:"resultType"`
	InputRequests map[string]InputRequest    `json:"inputRequests,omitempty"`
	RequestState  json.RawMessage            `json:"requestState,omitempty"`
	Meta          map[string]json.RawMessage `json:"_meta,omitempty"`
}

type JSONRPCError struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

type JSONRPCMessage struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      interface{}     `json:"id,omitempty"`     // Request ID (number or string)
	Method  string          `json:"method,omitempty"` // Method name for requests/notifications
	Params  json.RawMessage `json:"params,omitempty"` // Parameters for method
	Result  json.RawMessage `json:"result,omitempty"` // Result for responses
	Error   *JSONRPCError   `json:"error,omitempty"`  // Error for error responses
}

type PromptsCapability struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

type RPCError struct {
	Code    int
	Message string
	Data    json.RawMessage
}

type Registry interface {
	// RegisterServer adds a new MCP server configuration
	RegisterServer(config ServerConfig) error

	// UnregisterServer closes the client (if any) and removes the server
	// from the registry. Unknown names are no-ops.
	UnregisterServer(name string) error

	// GetClient returns an active client for the given server name
	GetClient(ctx context.Context, serverName string) (Client, error)

	// GetClientForTool returns the client that provides the specified tool
	GetClientForTool(ctx context.Context, toolName string) (Client, error)

	// ListServers returns all registered server names
	ListServers() []string

	// ListAllTools returns all tools from all connected servers
	ListAllTools(ctx context.Context) (map[string][]Tool, error)

	// GetServerConfig returns the configuration for a registered server.
	GetServerConfig(serverName string) (ServerConfig, bool)

	// Close shuts down all MCP servers and connections
	Close() error
}

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

type RegistryOptions struct {
	// MaxProcesses limits the number of concurrent MCP server processes.
	// 0 means unlimited (no limit enforced).
	MaxProcesses int
	// ConfigureClient, when set, adjusts the options of each server's client
	// before it is created: the place a host supplies an Authorizer or an
	// ElicitationHandler per server. The options arrive with the defaults
	// and the server's TimeoutMs applied.
	ConfigureClient func(config ServerConfig, options *ClientOptions)
	// OnToolsChanged, when set, is called after a server reports that its
	// tool list changed (notifications/tools/list_changed) and the registry
	// has re-read it. tools is the server's new list. It is called on its own
	// goroutine. A list that cannot be re-read leaves the previous tools in
	// place and is not reported.
	OnToolsChanged func(serverName string, tools []Tool)
}

type ResourceContents struct {
	URI      string                     `json:"uri"`
	MimeType string                     `json:"mimeType,omitempty"`
	Text     string                     `json:"text,omitempty"`
	Blob     string                     `json:"blob,omitempty"`
	Meta     map[string]json.RawMessage `json:"_meta,omitempty"`
}

type ResourcesCapability struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

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

type SamplingCapability struct{}

type ServerCapabilities struct {
	Tools     *ToolsCapability     `json:"tools,omitempty"`
	Resources *ResourcesCapability `json:"resources,omitempty"`
	Prompts   *PromptsCapability   `json:"prompts,omitempty"`
	// Extensions lists the optional protocol extensions the server supports,
	// keyed by identifier (2026-07-28).
	Extensions map[string]json.RawMessage `json:"extensions,omitempty"`
}

type ServerConfig struct {
	Name    string            `json:"name" yaml:"name"`
	Command string            `json:"command,omitempty" yaml:"command,omitempty"`
	Args    []string          `json:"args,omitempty" yaml:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
	// WorkingDir sets the working directory for the server process (stdio only).
	WorkingDir string `json:"working_dir,omitempty" yaml:"working_dir,omitempty"`
	// URL is the URL of an HTTP MCP server. Without a TransportName the
	// registry uses Streamable HTTP, falling back to HTTP+SSE if the server
	// does not host a Streamable HTTP endpoint at it.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
	// Headers are sent on HTTP transports (both SSE and Streamable HTTP).
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
	// TransportName selects the transport adapter explicitly. When empty it
	// is inferred: URL → Streamable HTTP (with the HTTP+SSE fallback),
	// Command → stdio.
	TransportName Transport `json:"transport,omitempty" yaml:"transport,omitempty"`
	// TimeoutMs sets the per-request timeout in milliseconds.
	TimeoutMs int `json:"timeout_ms,omitempty" yaml:"timeout_ms,omitempty"`
	// ToolFilter controls which tools from this server are exposed.
	ToolFilter *ToolFilter `json:"tool_filter,omitempty" yaml:"tool_filter,omitempty"`
}

type ServerConfigData struct {
	Name          string
	Command       string
	Args          []string
	Env           map[string]string
	WorkingDir    string
	URL           string
	Headers       map[string]string
	TransportName Transport
	TimeoutMs     int
	ToolFilter    *ToolFilter
}

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

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

type Tool struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"inputSchema"` // JSON Schema for tool input
	// Title is a display name.
	Title string `json:"title,omitempty"`
	// OutputSchema is the JSON Schema the tool's structuredContent conforms to.
	OutputSchema json.RawMessage `json:"outputSchema,omitempty"`
	// Annotations are hints about the tool's behavior. They are not
	// guaranteed: a client MUST NOT trust them from an untrusted server.
	Annotations *ToolAnnotations `json:"annotations,omitempty"`
	// Icons are display icons (2025-11-25).
	Icons []Icon `json:"icons,omitempty"`
	// Execution says whether the tool runs as a task (2025-11-25). The
	// client does not implement tasks, so it never lists a tool that
	// requires one.
	Execution *ToolExecution             `json:"execution,omitempty"`
	Meta      map[string]json.RawMessage `json:"_meta,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 ToolCallRequest struct {
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	// InputResponses answers a modern server's input_required result, keyed
	// as the server keyed its inputRequests (2026-07-28 MRTR).
	InputResponses map[string]json.RawMessage `json:"inputResponses,omitempty"`
	// RequestState echoes, unchanged, the requestState of the input_required
	// result being answered.
	RequestState json.RawMessage `json:"requestState,omitempty"`
}

type ToolCallResponse struct {
	Content []Content `json:"content"`
	// StructuredContent is the tool's structured result (MCP 2025-06-18).
	// Servers SHOULD mirror it as serialized JSON in Content, but are not
	// required to, so it is the authoritative result when present.
	StructuredContent json.RawMessage `json:"structuredContent,omitempty"`
	IsError           bool            `json:"isError,omitempty"`
	// ResultType is "complete" from a 2026-07-28 server (absent before).
	ResultType string                     `json:"resultType,omitempty"`
	Meta       map[string]json.RawMessage `json:"_meta,omitempty"`
}

type ToolExecution struct {
	// TaskSupport is "forbidden" (the default), "optional" or "required".
	TaskSupport string `json:"taskSupport,omitempty"`
}

type ToolFilter struct {
	Allowlist []string `json:"allowlist,omitempty" yaml:"allowlist,omitempty"`
	Blocklist []string `json:"blocklist,omitempty" yaml:"blocklist,omitempty"`
}

type ToolsCapability struct {
	ListChanged bool `json:"listChanged,omitempty"` // Server can send notifications
}

type ToolsListRequest struct {
	// Cursor requests the page after the one that returned it as NextCursor.
	Cursor string `json:"cursor,omitempty"`
}

type ToolsListResponse struct {
	Tools []Tool `json:"tools"`
	// NextCursor is set when more tools follow; the client requests the next
	// page with it.
	NextCursor string `json:"nextCursor,omitempty"`
	// ResultType, TTLMs and CacheScope are set by 2026-07-28 servers.
	// TTLMs is how long the list may be cached; CacheScope is "public" or
	// "private". The client does not cache tool lists.
	ResultType string                     `json:"resultType,omitempty"`
	TTLMs      *int64                     `json:"ttlMs,omitempty"`
	CacheScope string                     `json:"cacheScope,omitempty"`
	Meta       map[string]json.RawMessage `json:"_meta,omitempty"`
}

type Transport string

type WWWAuthenticate struct {
	Scheme string
	Params map[string]string
}