protocol

type AudioContent struct {
	Data     []byte
	MIMEType string
}

type Bounds struct {
	// MaxSchemaBytes caps one marshaled tool schema document.
	MaxSchemaBytes int
	// MaxSchemaDepth caps schema nesting.
	MaxSchemaDepth int
	// MaxTextBytes caps one text (or embedded-resource text) payload before
	// it is truncated.
	MaxTextBytes int
	// MaxStructuredBytes caps one structured-content document, enforced by
	// FromSDKCallToolResult.
	MaxStructuredBytes int
	// MaxBinaryItemBytes caps one binary (image/audio/blob) item.
	MaxBinaryItemBytes int
	// MaxBinaryItems caps how many binary items one content list may carry.
	MaxBinaryItems int
	// MaxLogBytes caps one server log message's text.
	MaxLogBytes int
	// MaxElicitMessageBytes caps one elicitation prompt: its message, and in
	// url mode the URL and correlation id shown with it. It is separate from
	// MaxTextBytes because it bounds what a *person* is shown, not what a model
	// consumes — a tool result may reasonably be a megabyte; a prompt may not.
	MaxElicitMessageBytes int
	// MaxElicitSchemaBytes caps one elicitation's requested schema. It is
	// separate from MaxSchemaBytes because a form a human fills in is a
	// different thing from a tool's interface; sizing them together would mean
	// raising one to raise the other.
	MaxElicitSchemaBytes int
}

type CallOptions struct {
	// Progress, when non-nil, receives the call's progress notifications. It is
	// invoked on the connection's notification goroutine and blocks it, so it
	// must not do work.
	//
	// Registering it is what puts a progress token on the request; a server is
	// only allowed to send progress for a request that carries one, so a nil
	// Progress means the notifications are never generated in the first place.
	Progress func(ProgressUpdate)
}

type ClientCapabilities struct {
	Elicitation bool
	Sampling    bool
	Roots       bool
}

type ClientIdentity struct {
	Name    string
	Version string
	Title   string
}

type Conn interface {
	// Initialize performs the MCP handshake and reports what the server said
	// about itself. Everything in the result is server-supplied and untrusted;
	// implementations bound it against the ConnectConfig Bounds before
	// returning it.
	Initialize(ctx context.Context) (InitializeResult, error)

	// ListTools fetches one page of tools. cursor is empty for the first page,
	// and otherwise the preceding page's NextCursor. Paginating — and bounding
	// the pagination — is the caller's job; see internal/catalog.
	ListTools(ctx context.Context, cursor string) (ToolPage, error)
	// ListPrompts fetches one page of prompts.
	ListPrompts(ctx context.Context, cursor string) (PromptPage, error)
	// ListResources fetches one page of concrete resources.
	ListResources(ctx context.Context, cursor string) (ResourcePage, error)
	// ListResourceTemplates fetches one page of resource templates.
	ListResourceTemplates(ctx context.Context, cursor string) (ResourceTemplatePage, error)

	// CallTool invokes a tool by its raw server name. args is passed through
	// verbatim; validating it against the tool's schema is the caller's job.
	// Cancelling ctx cancels the call at the protocol level.
	CallTool(ctx context.Context, rawName string, args json.RawMessage, opts CallOptions) (ToolResult, error)
	// GetPrompt fetches a prompt's messages.
	GetPrompt(ctx context.Context, name string, args map[string]string) (PromptResult, error)
	// ReadResource reads a resource by its opaque URI.
	ReadResource(ctx context.Context, uri string) (ResourceResult, error)
	// Subscribe asks the server to report changes to a resource.
	Subscribe(ctx context.Context, uri string) error
	// Unsubscribe asks the server to stop reporting changes to a resource.
	Unsubscribe(ctx context.Context, uri string) error
	// SetLogLevel asks the server to send logs at or above level. A server
	// sends none until this is called.
	SetLogLevel(ctx context.Context, level string) error

	// Close releases the connection's resources.
	Close(ctx context.Context) error
}

type ConnectConfig struct {
	// Client identifies this client to the server.
	Client ClientIdentity
	// Capabilities are the client capabilities to advertise.
	Capabilities ClientCapabilities
	// Bounds caps everything the connection converts from server data. The
	// client passes a normalized (all-positive) value.
	Bounds Bounds
	// Wire caps what a transport buffers off the network, before any of it is
	// parsed. The client passes a normalized (all-positive) value.
	Wire WireLimits
	// OnLog receives the server's log messages, already bounded. Nil drops
	// them.
	//
	// It is a callback on the config rather than a method on Conn because a log
	// is unsolicited: it belongs to no request, so there is nothing to return
	// it from. It is invoked on the connection's notification goroutine and
	// blocks it, so an implementation must not do work.
	OnLog func(LogRecord)

	// OnListChanged receives the server's list-change notifications. Nil drops
	// them.
	//
	// Like OnLog it is a callback rather than a method for want of a request to
	// return it from, and it is invoked on the connection's notification
	// goroutine and blocks it: an implementation must record the change and
	// return, never fetch.
	OnListChanged func(ListChange)

	// OnResourceUpdated receives the server's resource-update notifications: a
	// server telling a subscriber that a resource it subscribed to has changed.
	// Nil drops them.
	//
	// Like OnListChanged it is a callback for want of a request to return it
	// from, and it is invoked on the connection's notification goroutine and
	// blocks it: an implementation must record the update and return, never
	// re-read the resource here. The URI it carries is server-supplied and
	// bounded before it arrives.
	OnResourceUpdated func(ResourceUpdate)

	// OnElicit serves the server's requests for human input, already bounded
	// and validated. Nil means no elicitation is served — and, because a
	// capability with nothing behind it must never reach the wire, nil also
	// means the elicitation capability is not advertised however Capabilities
	// is set (see Session.Initialize).
	//
	// Unlike OnLog and OnListChanged this one answers: it is the only callback
	// here whose return value goes to the server, and the only one that may
	// block. It is invoked on the connection's request-dispatch goroutine with
	// the caller's elicitation deadline already on ctx; returning an error
	// refuses the request, which is a complete and honest answer.
	//
	// It is a callback rather than a Conn method for the same reason as the
	// others: it belongs to no request this module made, so there is nothing to
	// return it from.
	OnElicit func(context.Context, ElicitRequest) (ElicitResult, error)

	// OnSample serves the server's requests for an LLM completion, already
	// bounded and validated. Nil means no sampling is served — and, because a
	// capability with nothing behind it must never reach the wire, nil also
	// means the sampling capability is not advertised however Capabilities is
	// set (see Session.Initialize).
	//
	// Like OnElicit it answers, and its return value goes to the server. It is
	// invoked on the connection's request-dispatch goroutine with the caller's
	// deadline already on ctx; returning an error refuses the request, which a
	// host is always entitled to do — sampling spends the host's money, and
	// "no" is a complete answer.
	OnSample func(context.Context, SampleRequest) (SampleResult, error)

	// OnRoots supplies the filesystem roots this client exposes to the server.
	// Nil means no roots are served — and, because a capability with nothing
	// behind it must never reach the wire, nil also means the roots capability
	// is not advertised however Capabilities is set (see Session.Initialize).
	//
	// Unlike the other callbacks it is not a server request handler: the SDK
	// answers roots/list from a set the client supplies, so this is consulted
	// once, at Initialize, to populate that set. The roots it returns are the
	// only ones a server ever learns — this module never invents host
	// filesystem roots of its own. Returning an error fails the handshake:
	// establishing a binding that advertises roots it cannot determine would be
	// advertise-without-honor, the very thing the gating exists to prevent.
	OnRoots func(context.Context) ([]Root, error)
}

type Content interface {
	// contains filtered or unexported methods
}

type ElicitAction uint8

type ElicitMode uint8

type ElicitRequest struct {
	// Mode is the kind of elicitation. It is always a declared mode: an
	// unrecognized one is refused at conversion.
	Mode ElicitMode
	// Message is the prompt to show the human, within
	// Bounds.MaxElicitMessageBytes.
	Message string
	// Schema is the JSON Schema the answer must satisfy, in form mode only; nil
	// otherwise. It is raw JSON because a schema is a serialization-boundary
	// document, not domain data.
	Schema json.RawMessage
	// URL is the out-of-band action's URL, in url mode only; empty otherwise.
	URL string
	// ElicitationID is the server's correlation id, in url mode only. It may be
	// empty even there: MCP does not require one.
	ElicitationID string
}

type ElicitResult struct {
	Action ElicitAction
	// Content is the accepted answer as a JSON object, or nil. It is raw JSON
	// for the same reason Schema is: its shape is the server's schema, which is
	// data, so there is no Go type to narrow it to.
	Content json.RawMessage
}

type EmbeddedResourceContent struct {
	URI       string
	MIMEType  string
	Text      string
	Data      []byte
	Truncated bool
}

type ImageContent struct {
	Data     []byte
	MIMEType string
}

type InitializeResult struct {
	// Server is what the server claims to be.
	Server ServerIdentity
	// ProtocolVersion is the version the server wants to speak.
	ProtocolVersion ProtocolVersion
	// Instructions is the server's usage hint, truncated to
	// Bounds.MaxTextBytes.
	Instructions string
	// Capabilities is what the server advertised.
	Capabilities ServerCapabilities
}

type ListChange struct {
	// Family names the list the server says changed.
	Family ListFamily
}

type ListFamily uint8

type LogRecord struct {
	// Level is the severity the server claimed, verbatim.
	Level string
	// Logger is the server-side logger name, if it sent one.
	Logger string
	// Text is the message, truncated to Bounds.MaxLogBytes.
	Text string
}

type ProgressUpdate struct {
	// Progress is how far the server claims to have got.
	Progress float64
	// Total is the server's claimed total, or 0 when it did not say.
	Total float64
	// Message is the server's bounded description of what it is doing.
	Message string
}

type PromptArgSpec struct {
	Name        string
	Title       string
	Description string
	Required    bool
}

type PromptMessage struct {
	Role    string
	Content Content
}

type PromptPage struct {
	Prompts    []PromptSpec
	NextCursor string
	Warnings   []string
}

type PromptResult struct {
	Description string
	Messages    []PromptMessage
}

type PromptSpec struct {
	RawName     string
	Title       string
	Description string
	Arguments   []PromptArgSpec
}

type ProtocolVersion string

type ResourceContent struct {
	URI       string
	MIMEType  string
	Text      string
	Data      []byte
	Truncated bool
}

type ResourcePage struct {
	Resources  []ResourceSpec
	NextCursor string
	Warnings   []string
}

type ResourceResult struct {
	Contents []ResourceContent
}

type ResourceSpec struct {
	URI         string
	Name        string
	Title       string
	Description string
	MIMEType    string
}

type ResourceTemplatePage struct {
	Templates  []ResourceTemplateSpec
	NextCursor string
	Warnings   []string
}

type ResourceTemplateSpec struct {
	URITemplate string
	Name        string
	Title       string
	Description string
	MIMEType    string
}

type ResourceUpdate struct {
	// URI names the resource the server says changed. It may be a sub-resource
	// of the one that was subscribed to.
	URI string
}

type Root struct {
	URI  string
	Name string
}

type SampleMessage struct {
	// Role is always a declared role: an unrecognized one is refused at
	// conversion.
	Role SampleRole
	// Text is the message's text content.
	Text string
}

type SampleRequest struct {
	// SystemPrompt is the server's requested system prompt. The host may modify
	// or ignore it.
	SystemPrompt string
	// Messages is the conversation to complete. It is never empty: a request
	// with nothing to complete is refused at conversion.
	Messages []SampleMessage
	// MaxTokens is the server's requested completion budget, always positive.
	// It is a request, not a grant: the layer above caps it against its own
	// limit, and a server can only ever lower the ceiling, never raise it.
	MaxTokens int
}

type SampleResult struct {
	// Model names the model the host actually used, which need not be one the
	// server asked for.
	Model string
	// Text is the completion.
	Text string
	// StopReason is why generation stopped.
	StopReason string
}

type SampleRole uint8

type ServerCapabilities struct {
	// Tools reports whether the server exposes tools.
	Tools bool
	// Prompts reports whether the server exposes prompts.
	Prompts bool
	// Resources reports whether the server exposes resources.
	Resources bool
	// ResourcesSubscribe reports whether the server supports subscribing to
	// resource updates. It is only meaningful when Resources is set.
	ResourcesSubscribe bool
	// Logging reports whether the server sends log messages.
	Logging bool
	// Completions reports whether the server supports argument autocompletion.
	Completions bool
}

type ServerIdentity struct {
	Name    string
	Version string
	Title   string
}

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

type TextContent struct {
	Text      string
	Truncated bool
}

type ToolAnnotations struct {
	Title           string
	ReadOnlyHint    bool
	IdempotentHint  bool
	DestructiveHint *bool
	OpenWorldHint   *bool
}

type ToolPage struct {
	Tools []ToolSpec
	// NextCursor is the cursor for the following page, empty when this is the
	// last one. It is opaque: nothing in this module interprets it.
	NextCursor string
	// Warnings records items dropped during conversion, bounded by MaxWarnings.
	Warnings []string
}

type ToolResult struct {
	// IsError reports that the tool itself failed. Content carries the tool's
	// explanation.
	IsError bool
	// Content is the unstructured result, already bounded.
	Content []Content
	// Structured is the optional structured result, within
	// Bounds.MaxStructuredBytes. Nil when the server sent none, or when an
	// over-bound one was dropped (see Warnings).
	Structured json.RawMessage
	// Warnings records defects tolerated during conversion.
	Warnings []string
}

type ToolSpec struct {
	RawName      string
	Title        string
	Description  string
	InputSchema  json.RawMessage
	OutputSchema json.RawMessage
	// Annotations are server-declared behavioural hints. They are untrusted
	// policy *input* and never authority: a server claiming ReadOnlyHint does
	// not make a tool read-only. Nil when the server sent none.
	Annotations *ToolAnnotations
	// Warnings records defects tolerated during conversion (e.g. a dropped
	// output schema). Bounded by MaxWarnings.
	Warnings []string
	// OutputSchemaDefect is the bounded reason this tool's optional output
	// schema was dropped, or empty when there was nothing wrong with it (which
	// includes the ordinary case of a server sending none at all).
	//
	// It exists so that dropping the schema is a *decision* the layer above can
	// make rather than one this conversion makes for it. The drop is the safe
	// tolerance, but whether it is applied is compatibility policy — a strict
	// profile rejects the tool instead — and policy cannot be expressed by
	// pattern-matching the text of a warning.
	OutputSchemaDefect string
}

type UnsupportedContent struct {
	// Kind is one of the Kind* constants.
	Kind string
	// Bytes is the size of the payload that was refused. It is exact for an
	// item dropped on a size bound (image, audio, embedded blob), and a
	// diagnostic lower bound for a kind dropped as unsupported, whose size is
	// summed from its known fields rather than by marshalling data we are
	// refusing. Treat it as a diagnostic, never as an accounting figure.
	Bytes int
}

type WireLimits struct {
	// MaxBodyBytes caps one whole non-streaming response body.
	//
	// It deliberately does not cap a long-lived stream: an SSE stream carries
	// an entire session's worth of frames and is bounded per frame, by
	// MaxFrameBytes, because a total on it is just a slow session's expiry
	// date.
	MaxBodyBytes int
	// MaxFrameBytes caps one wire frame — one JSON-RPC message, or one SSE
	// event — however long the stream carrying it lives.
	MaxFrameBytes int
}