mcp

type Annotations struct {
	// Audience describes who the intended customer of this object or data is.
	// It can include multiple entries to indicate content useful for multiple audiences.
	Audience []Role `json:"audience,omitempty"`
	// Priority describes how important this data is for operating the server.
	// A value of 1 means "most important," and indicates that the data is
	// effectively required, while 0 means "least important," and indicates that
	// the data is entirely optional.
	Priority int `json:"priority,omitempty"`
}

type CallToolParams struct {
	// Name is the unique identifier of the tool to execute
	Name string `json:"name"`

	// Arguments is a JSON object of argument name-value pairs
	// Must satisfy required arguments defined in tool's InputSchema field
	Arguments json.RawMessage `json:"arguments"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

type CallToolResult struct {
	Content []Content `json:"content"`
	IsError bool      `json:"isError"`
}

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

type ClientCapabilities struct {
	Roots    *RootsCapability    `json:"roots,omitempty"`
	Sampling *SamplingCapability `json:"sampling,omitempty"`
}

type ClientOption func(*Client)

type ClientTransport interface {
	// StartSession initiates a new session with the server and returns an iterator that yields server messages.
	// The transport signals its readiness to send messages through the ready channel by either closing it or
	// feeding an error. Operations are canceled when the context is canceled, and appropriate errors are returned
	// for connection or protocol failures. Refer to the returned iterator's documentation for details on message
	// handling.
	StartSession(ctx context.Context, ready chan<- error) (iter.Seq[JSONRPCMessage], error)

	// Send transmits a message to the server. The implementation must only allow sending
	// after the ready channel from StartSession is closed or fed. Operations should be
	// canceled if the context is canceled, and appropriate errors should be returned for
	// transmission failures.
	Send(ctx context.Context, msg JSONRPCMessage) error
}

type CompletesCompletionParams struct {
	// Ref identifies what is being completed (e.g. prompt, resource template)
	Ref CompletionRef `json:"ref"`
	// Argument specifies which argument needs completion suggestions
	Argument CompletionArgument `json:"argument"`
}

type CompletionArgument struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type CompletionRef struct {
	// Type specifies what kind of completion is being requested.
	// Must be either "ref/prompt" or "ref/resource".
	Type string `json:"type"`
	// Name contains the prompt name when Type is "ref/prompt".
	Name string `json:"name,omitempty"`
	// URI contains the resource template URI when Type is "ref/resource".
	URI string `json:"uri,omitempty"`
}

type CompletionResult struct {
	Completion struct {
		Values  []string `json:"values"`
		HasMore bool     `json:"hasMore,omitempty"`
		Total   int      `json:"total,omitempty"`
	} `json:"completion"`
}

type Content struct {
	Type        ContentType  `json:"type"`
	Annotations *Annotations `json:"annotations,omitempty"`

	// For ContentTypeText
	Text string `json:"text,omitempty"`

	// For ContentTypeImage or ContentTypeAudio
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mimeType,omitempty"`

	// For ContentTypeResource
	Resource *ResourceContents `json:"resource,omitempty"`
}

type ContentType string

type GetPromptParams struct {
	// Name is the unique identifier of the prompt to retrieve
	Name string `json:"name"`

	// Arguments is a map of argument name-value pairs
	// Must satisfy required arguments defined in prompt's Arguments field
	Arguments map[string]string `json:"arguments"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

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

type Info struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type JSONRPCError struct {
	// Code indicates the error type that occurred.
	// Must use standard JSON-RPC error codes or custom codes outside the reserved range.
	Code int `json:"code"`

	// Message provides a short description of the error.
	// Should be limited to a concise single sentence.
	Message string `json:"message"`

	// Data contains additional information about the error.
	// The value is unstructured and may be omitted.
	Data map[string]any `json:"data,omitempty"`
}

type JSONRPCMessage struct {
	// JSONRPC must always be "2.0" per the JSON-RPC specification
	JSONRPC string `json:"jsonrpc"`
	// ID uniquely identifies request-response pairs and must be a string or number
	ID MustString `json:"id,omitempty"`
	// Method contains the RPC method name for requests and notifications
	Method string `json:"method,omitempty"`
	// Params contains the parameters for the method call as a raw JSON message
	Params json.RawMessage `json:"params,omitempty"`
	// Result contains the successful response data as a raw JSON message
	Result json.RawMessage `json:"result,omitempty"`
	// Error contains error details if the request failed
	Error *JSONRPCError `json:"error,omitempty"`
}

type ListPromptResult struct {
	Prompts    []Prompt `json:"prompts"`
	NextCursor string   `json:"nextCursor,omitempty"`
}

type ListPromptsParams struct {
	// Cursor is an optional pagination cursor from previous ListPrompts call.
	// Empty string requests the first page.
	Cursor string `json:"cursor,omitempty"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

type ListResourceTemplatesParams struct {
	// Cursor is a pagination cursor from previous ListResourceTemplates call.
	// Empty string requests the first page.
	Cursor string `json:"cursor"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

type ListResourceTemplatesResult struct {
	Templates  []ResourceTemplate `json:"resourceTemplates"`
	NextCursor string             `json:"nextCursor,omitempty"`
}

type ListResourcesParams struct {
	// Cursor is a pagination cursor from previous ListResources call.
	// Empty string requests the first page.
	Cursor string `json:"cursor"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

type ListResourcesResult struct {
	Resources  []Resource `json:"resources"`
	NextCursor string     `json:"nextCursor,omitempty"`
}

type ListToolsParams struct {
	// Cursor is a pagination cursor from previous ListTools call.
	// Empty string requests the first page.
	Cursor string `json:"cursor"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

type ListToolsResult struct {
	Tools      []Tool `json:"tools"`
	NextCursor string `json:"nextCursor,omitempty"`
}

type LogHandler interface {
	// LogStreams returns an iterator that emits log messages with metadata.
	LogStreams() iter.Seq[LogParams]

	// SetLogLevel configures the minimum severity level for emitted log messages.
	// Messages below this level are filtered out.
	SetLogLevel(level LogLevel)
}

type LogLevel int

type LogParams struct {
	// Level indicates the severity level of the message.
	// Must be one of the defined LogLevel constants.
	Level LogLevel `json:"level"`
	// Logger identifies the source/component that generated the message.
	Logger string `json:"logger"`
	// Data contains the message content and any structured metadata.
	Data json.RawMessage `json:"data"`
}

type LogReceiver interface {
	// OnLog is called when a log message is received from the server.
	OnLog(params LogParams)
}

type LoggingCapability struct{}

type MustString string

type ParamsMeta struct {
	// ProgressToken uniquely identifies an operation for progress tracking.
	// When provided, the server can emit progress updates via ProgressReporter.
	ProgressToken MustString `json:"progressToken"`
}

type ProgressListener interface {
	// OnProgress is called when a progress update is received for an operation.
	OnProgress(params ProgressParams)
}

type ProgressParams struct {
	// ProgressToken uniquely identifies the operation this progress update relates to
	ProgressToken MustString `json:"progressToken"`
	// Progress represents the current progress value
	Progress float64 `json:"progress"`
	// Total represents the expected final value when known.
	// When non-zero, completion percentage can be calculated as (Progress/Total)*100
	Total float64 `json:"total,omitempty"`
}

type ProgressReporter func(progress ProgressParams)

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

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

type PromptListUpdater interface {
	PromptListUpdates() iter.Seq[struct{}]
}

type PromptListWatcher interface {
	// OnPromptListChanged is called when the server notifies that its prompt list has changed.
	// This can happen when prompts are added, removed, or modified on the server side.
	OnPromptListChanged()
}

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

type PromptServer interface {
	// ListPrompts returns a paginated list of available prompts. The ProgressReporter
	// can be used to report operation progress, and RequestClientFunc enables
	// client-server communication during execution.
	// Returns error if operation fails or context is cancelled.
	ListPrompts(context.Context, ListPromptsParams, ProgressReporter, RequestClientFunc) (ListPromptResult, error)

	// GetPrompt retrieves a specific prompt template by name with the given arguments.
	// The ProgressReporter can be used to report operation progress, and RequestClientFunc
	// enables client-server communication during execution.
	// Returns error if prompt not found, arguments are invalid, or context is cancelled.
	GetPrompt(context.Context, GetPromptParams, ProgressReporter, RequestClientFunc) (GetPromptResult, error)

	// CompletesPrompt provides completion suggestions for a prompt argument.
	// Used to implement interactive argument completion in clients. The RequestClientFunc
	// enables client-server communication during execution.
	// Returns error if prompt doesn't exist, completions cannot be generated, or context is cancelled.
	CompletesPrompt(context.Context, CompletesCompletionParams, RequestClientFunc) (CompletionResult, error)
}

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

type ReadResourceParams struct {
	// URI is the unique identifier of the resource to retrieve.
	URI string `json:"uri"`

	// Meta contains optional metadata including progressToken for tracking operation progress.
	// The progressToken is used by ProgressReporter to emit progress updates if supported.
	Meta ParamsMeta `json:"_meta,omitempty"`
}

type ReadResourceResult struct {
	Contents []ResourceContents `json:"contents"`
}

type RequestClientFunc func(msg JSONRPCMessage) (JSONRPCMessage, error)

type Resource struct {
	Annotations *Annotations `json:"annotations,omitempty"`
	URI         string       `json:"uri"`
	Name        string       `json:"name"`
	Description string       `json:"description,omitempty"`
	MimeType    string       `json:"mimeType,omitempty"`
}

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

type ResourceListUpdater interface {
	ResourceListUpdates() iter.Seq[struct{}]
}

type ResourceListWatcher interface {
	// OnResourceListChanged is called when the server notifies that its resource list has changed.
	// This can happen when resources are added, removed, or modified on the server side.
	OnResourceListChanged()
}

type ResourceServer interface {
	// ListResources returns a paginated list of available resources. The ProgressReporter
	// can be used to report operation progress, and RequestClientFunc enables
	// client-server communication during execution.
	// Returns error if operation fails or context is cancelled.
	ListResources(context.Context, ListResourcesParams, ProgressReporter, RequestClientFunc) (
		ListResourcesResult, error)

	// ReadResource retrieves a specific resource by its URI. The ProgressReporter
	// can be used to report operation progress, and RequestClientFunc enables
	// client-server communication during execution.
	// Returns error if resource not found, cannot be read, or context is cancelled.
	ReadResource(context.Context, ReadResourceParams, ProgressReporter, RequestClientFunc) (
		ReadResourceResult, error)

	// ListResourceTemplates returns all available resource templates. The ProgressReporter
	// can be used to report operation progress, and RequestClientFunc enables
	// client-server communication during execution.
	// Returns error if templates cannot be retrieved or context is cancelled.
	ListResourceTemplates(context.Context, ListResourceTemplatesParams, ProgressReporter, RequestClientFunc) (
		ListResourceTemplatesResult, error)

	// CompletesResourceTemplate provides completion suggestions for a resource template argument.
	// The RequestClientFunc enables client-server communication during execution.
	// Returns error if template doesn't exist, completions cannot be generated, or context is cancelled.
	CompletesResourceTemplate(context.Context, CompletesCompletionParams, RequestClientFunc) (CompletionResult, error)
}

type ResourceSubscribedWatcher interface {
	// OnResourceSubscribedChanged is called when the server notifies that a subscribed resource has changed.
	OnResourceSubscribedChanged(uri string)
}

type ResourceSubscriptionHandler interface {
	// SubscribeResource subscribes to a resource.
	SubscribeResource(SubscribeResourceParams)
	// UnsubscribeResource unsubscribes from a resource.
	UnsubscribeResource(UnsubscribeResourceParams)
	// SubscribedResourceUpdates returns an iterator that emits notifications whenever a subscribed resource changes.
	SubscribedResourceUpdates() iter.Seq[string]
}

type ResourceTemplate struct {
	Annotations *Annotations `json:"annotations,omitempty"`
	URITemplate string       `json:"uriTemplate"`
	Name        string       `json:"name"`
	Description string       `json:"description,omitempty"`
	MimeType    string       `json:"mimeType,omitempty"`
}

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

type Role string

type Root struct {
	URI  string `json:"uri"`
	Name string `json:"name,omitempty"`
}

type RootList struct {
	Roots []Root `json:"roots"`
}

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

type RootsListHandler interface {
	// RootsList returns the list of available root resources.
	// Returns error if operation fails or context is cancelled.
	RootsList(ctx context.Context) (RootList, error)
}

type RootsListUpdater interface {
	// RootsListUpdates returns an iterator that emits notifications when the root list changes.
	RootsListUpdates() iter.Seq[struct{}]
}

type RootsListWatcher interface {
	// OnRootsListChanged is called when the client notifies that its root list has changed
	OnRootsListChanged()
}

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

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

type SamplingCapability struct{}

type SamplingContent struct {
	Type ContentType `json:"type"`

	Text string `json:"text"`

	Data     string `json:"data"`
	MimeType string `json:"mimeType"`
}

type SamplingHandler interface {
	// CreateSampleMessage generates a response message based on the provided conversation history and parameters.
	// Returns error if model selection fails, generation fails, token limit is exceeded, or context is cancelled.
	CreateSampleMessage(ctx context.Context, params SamplingParams) (SamplingResult, error)
}

type SamplingMessage struct {
	Role    Role            `json:"role"`
	Content SamplingContent `json:"content"`
}

type SamplingModelPreferences struct {
	Hints []struct {
		Name string `json:"name"`
	} `json:"hints"`
	CostPriority         int `json:"costPriority"`
	SpeedPriority        int `json:"speedPriority"`
	IntelligencePriority int `json:"intelligencePriority"`
}

type SamplingParams struct {
	// Messages contains the conversation history as a sequence of user and assistant messages
	Messages []SamplingMessage `json:"messages"`

	// ModelPreferences controls model selection through cost, speed, and intelligence priorities
	ModelPreferences SamplingModelPreferences `json:"modelPreferences"`

	// SystemPrompts provides system-level instructions to guide the model's behavior
	SystemPrompts string `json:"systemPrompts"`

	// MaxTokens specifies the maximum number of tokens allowed in the generated response
	MaxTokens int `json:"maxTokens"`
}

type SamplingResult struct {
	Role       Role            `json:"role"`
	Content    SamplingContent `json:"content"`
	Model      string          `json:"model"`
	StopReason string          `json:"stopReason"`
}

type Server interface {
	Info() Info
	RequireRootsListClient() bool
	RequireSamplingClient() bool
}

type ServerCapabilities struct {
	Prompts   *PromptsCapability   `json:"prompts,omitempty"`
	Resources *ResourcesCapability `json:"resources,omitempty"`
	Tools     *ToolsCapability     `json:"tools,omitempty"`
	Logging   *LoggingCapability   `json:"logging,omitempty"`
}

type ServerOption func(*server)

type ServerTransport interface {
	// Sessions returns an iterator that yields new client sessions as they are initiated.
	// Each yielded Session represents a unique client connection and provides methods for
	// bidirectional communication. The implementation must guarantee that each session ID
	// is unique across all active connections.
	Sessions() iter.Seq[Session]
}

type Session interface {
	// ID returns the unique identifier for this session. The implementation must
	// guarantee that session IDs are unique across all active sessions managed by
	// the ServerTransport.
	ID() string

	// Send transmits a message to the client. The implementation should cancel
	// operations if the context is canceled and return appropriate errors for
	// transmission failures.
	Send(ctx context.Context, msg JSONRPCMessage) error

	// Messages returns an iterator that yields messages received from the client.
	Messages() iter.Seq[JSONRPCMessage]
}

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

type SubscribeResourceParams struct {
	// URI is the unique identifier of the resource to subscribe to.
	// Must match URI used in ReadResource calls.
	URI string `json:"uri"`
}

type Tool struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"inputSchema,omitempty"`
}

type ToolListUpdater interface {
	ToolListUpdates() iter.Seq[struct{}]
}

type ToolListWatcher interface {
	// OnToolListChanged is called when the server notifies that its tool list has changed.
	// This can happen when tools are added, removed, or modified on the server side.
	OnToolListChanged()
}

type ToolServer interface {
	// ListTools returns a paginated list of available tools. The ProgressReporter
	// can be used to report operation progress, and RequestClientFunc enables
	// client-server communication during execution.
	// Returns error if operation fails or context is cancelled.
	ListTools(context.Context, ListToolsParams, ProgressReporter, RequestClientFunc) (ListToolsResult, error)

	// CallTool executes a specific tool with the given arguments. The ProgressReporter
	// can be used to report operation progress, and RequestClientFunc enables
	// client-server communication during execution.
	// Returns error if tool not found, arguments are invalid, execution fails, or context is cancelled.
	CallTool(context.Context, CallToolParams, ProgressReporter, RequestClientFunc) (CallToolResult, error)
}

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

type UnsubscribeResourceParams struct {
	// URI is the unique identifier of the resource to unsubscribe from.
	// Must match URI used in ReadResource calls.
	URI string `json:"uri"`
}