mcp

type Annotations struct {
	// Audience describes who the data is intended for.
	Audience []Role `json:"audience,omitempty"`
	// Priority describes importance from 0 to 1, with 1 most important.
	Priority *int `json:"priority,omitempty"`
	// LastModified is an ISO 8601 timestamp for the last modification time.
	LastModified string `json:"lastModified,omitempty"`
}

type CacheScope string

type Capabilities struct {
	// Experimental contains non-standard capabilities supported by the server.
	Experimental Extensions `json:"experimental,omitempty"`
	// DeprecatedLogging is present if the server supports sending log messages to the client.
	//
	// Deprecated as of protocol version 2026-07-28, but still present in that
	// schema. This is native 2026-07-28 compatibility, not released-version
	// compat.go support; remove it only after the upstream 2026+ schema drops it.
	DeprecatedLogging MetaObject `json:"logging,omitempty"`
	// Completions is present if the server supports argument completion suggestions.
	Completions MetaObject `json:"completions,omitempty"`
	// Prompts is present if the server offers prompt templates.
	Prompts *PromptsCapability `json:"prompts,omitempty"`
	// Resources is present if the server offers resources to read.
	Resources ResourcesCapability `json:"resources,omitzero"`
	// Tools is present if the server offers tools to call.
	Tools ToolsCapability `json:"tools"`
	// Extensions contains optional MCP extensions supported by the server.
	Extensions Extensions `json:"extensions,omitempty"`
}

type ClientCapabilities struct {
	// Experimental contains non-standard capabilities supported by the client.
	Experimental Extensions `json:"experimental,omitempty"`
	// DeprecatedRoots is present if the client supports listing roots.
	//
	// Deprecated as of protocol version 2026-07-28, but still present in that
	// schema. This is native 2026-07-28 compatibility, not released-version
	// compat.go support; remove it only after the upstream 2026+ schema drops it.
	DeprecatedRoots MetaObject `json:"roots,omitempty"`
	// DeprecatedSampling is present if the client supports server-initiated LLM sampling.
	//
	// Deprecated as of protocol version 2026-07-28, but still present in that
	// schema. This is native 2026-07-28 compatibility, not released-version
	// compat.go support; remove it only after the upstream 2026+ schema drops it.
	DeprecatedSampling *SamplingCapability `json:"sampling,omitempty"`
	// Elicitation is present if the client supports server-initiated user elicitation.
	Elicitation *ElicitationCapability `json:"elicitation,omitempty"`
	// Extensions contains optional MCP extensions supported by the client.
	Extensions Extensions `json:"extensions,omitempty"`
}

type ContentBlock struct {
	Meta  MetaObject `json:"_meta,omitempty"`
	Icons []Icon     `json:"icons,omitempty"`
	// Type identifies the content variant.
	Type ContentType `json:"type"`
	// Name is used by resource_link content.
	Name string `json:"name,omitempty"`
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// Text is the text content for text blocks.
	Text string `json:"text,omitempty"`
	// Data is base64-encoded data for image and audio blocks.
	Data string `json:"data,omitempty"`
	// URI identifies resource_link content.
	URI string `json:"uri,omitempty"`
	// Description helps clients and LLMs understand linked resources.
	Description string `json:"description,omitempty"`
	// MimeType is required for image and audio content and optional for resources.
	MimeType string `json:"mimeType,omitempty"`
	// Size is the raw resource size in bytes, if known.
	Size int64 `json:"size,omitzero"`
	// Resource contains embedded resource contents for resource blocks.
	Resource ResourceContent `json:"resource,omitzero"`
	// Annotations provide optional client metadata.
	Annotations Annotations `json:"annotations,omitzero"`
}

type ContentType string

type ElicitationCapability struct {
	// Form declares support for form-mode elicitation.
	Form MetaObject `json:"form,omitempty"`
	// URL declares support for URL-mode elicitation.
	URL MetaObject `json:"url,omitempty"`
}

type ErrorCode int

type ErrorOutput struct {
	Error string `json:"error" jsonschema_description:"Human-readable error message"`
}

type Extensions map[string]json.RawMessage

type Handler struct {
	Registry   Registry
	ServerInfo Implementation
	// OAuthClientCredentials advertises the official
	// io.modelcontextprotocol/oauth-client-credentials extension in the
	// server/discover capabilities (SEP-2133). Set it when the host's
	// authorization server accepts OAuth 2.0 client-credentials grants
	// (RFC 6749 §4.4), letting machine-to-machine clients skip interactive
	// user authorization.
	OAuthClientCredentials bool
}

type HeaderParam struct {
	Header string
	Path   []string
}

type Icon struct {
	// Src is an icon URI, such as an HTTPS URL or data URI.
	Src string `json:"src"`
	// MimeType overrides a missing or generic source MIME type.
	MimeType string `json:"mimeType,omitempty"`
	// Sizes lists supported dimensions, such as "48x48" or "any".
	Sizes []string `json:"sizes,omitempty"`
	// Theme indicates whether the icon targets a light or dark background.
	Theme string `json:"theme,omitempty"`
}

type Implementation struct {
	// Icons contains optional sized icons for UI display.
	Icons []Icon `json:"icons,omitempty"`
	// Name is the programmatic implementation identifier.
	Name string `json:"name"`
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// Version is the implementation version.
	Version string `json:"version"`
	// Description explains what this implementation does.
	Description string `json:"description,omitempty"`
	// WebsiteURL is an optional website for this implementation.
	WebsiteURL string `json:"websiteUrl,omitempty"`
}

type JSONRPCError struct {
	// Code identifies the error type.
	Code ErrorCode `json:"code"`
	// Message is a concise single-sentence description of the error.
	Message string `json:"message"`
	// Data carries sender-defined additional error information.
	Data any `json:"data,omitempty"`
}

type JSONRPCNotification struct {
	JSONRPC string             `json:"jsonrpc"`
	Method  NotificationMethod `json:"method"`
	Params  any                `json:"params,omitempty"`
}

type JSONRPCRequest struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitzero"`
	Method  Method          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

type JSONRPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitzero"`
	Result  any             `json:"result,omitempty"`
	Error   *JSONRPCError   `json:"error,omitempty"`
}

type MetaObject map[string]any

type Method string

type NotificationMethod string

type OpenAIRequestMeta struct {
	// Locale requests a language and regional convention using a BCP 47 tag,
	// such as en-CA or fr-CA.
	Locale string `json:"openai/locale,omitempty"`
	// Organization carries an anonymized identifier for the caller's ChatGPT
	// organization, when the client provides one.
	Organization string `json:"openai/organization,omitempty"`
	// Session groups tool calls from the same ChatGPT conversation using an
	// anonymized conversation identifier.
	Session string `json:"openai/session,omitempty"`
	// Subject carries an anonymized user identifier for call correlation or
	// rate-limit accounting; it is not an authentication credential.
	Subject string `json:"openai/subject,omitempty"`
	// UserAgent is a best-effort client hint for analytics or presentation;
	// it is not a reliable indication of client capabilities.
	UserAgent string `json:"openai/userAgent,omitempty"`
	// UserLocation is an optional formatting hint supplied by the client.
	UserLocation OpenAIUserLocation `json:"openai/userLocation,omitzero"`
}

type OpenAIUserLocation struct {
	// Timezone is the caller device's IANA timezone, such as America/Toronto.
	Timezone string `json:"timezone,omitempty"`
}

type PaginatedRequestParams struct {
	Meta RequestMeta `json:"_meta"`
	// Cursor is an opaque pagination token.
	Cursor string `json:"cursor,omitempty"`
}

type PromptsCapability struct {
	// ListChanged indicates support for prompt list change notifications.
	ListChanged bool `json:"listChanged,omitempty"`
}

type RawToolResult struct {
	Meta       MetaObject
	Structured any
	IsError    bool
}

type Registry interface {
	Instructions(ctx context.Context) (string, error)
	Tools(ctx context.Context) ([]ToolDescriptor, error)
	// CallTool executes the decoded request. Params must be non-nil and must
	// not be modified during the call.
	CallTool(ctx context.Context, params *ToolsCallParams) (RawToolResult, error)
	ListResources(ctx context.Context, cursor string) (ResourcesListResult, error)
	Resources(ctx context.Context) iter.Seq2[ResourceDescriptor, error]
	// ReadResource reads the decoded request, including caller metadata. Params
	// must be non-nil and must not be modified during the call.
	ReadResource(ctx context.Context, params *ResourcesReadParams) (ResourcesReadResult, error)
}

type RequestMeta struct {
	// ProtocolVersion is the MCP protocol version used for this request.
	//
	// For HTTP, it must match the MCP-Protocol-Version header.
	ProtocolVersion string `json:"io.modelcontextprotocol/protocolVersion"`
	// ClientInfo identifies the client software making the request.
	ClientInfo Implementation `json:"io.modelcontextprotocol/clientInfo"`
	// ClientCapabilities declares client capabilities for this request.
	ClientCapabilities ClientCapabilities `json:"io.modelcontextprotocol/clientCapabilities"`
	// ProgressToken requests out-of-band progress notifications for this request.
	ProgressToken any `json:"progressToken,omitempty"`
	// DeprecatedLogLevel requests server log message notifications for this request.
	//
	// Deprecated as of protocol version 2026-07-28, but still present in that
	// schema. This is native 2026-07-28 compatibility, not released-version
	// compat.go support; remove it only after the upstream 2026+ schema drops it.
	DeprecatedLogLevel string `json:"io.modelcontextprotocol/logLevel,omitempty"`
	OpenAIRequestMeta
	// Extra preserves forward-compatible metadata fields.
	Extra MetaObject `json:"-"`
}

type RequestParams struct {
	Meta RequestMeta `json:"_meta"`
}

type ResourceContent struct {
	Meta MetaObject `json:"_meta,omitempty"`
	// URI identifies this resource.
	URI string `json:"uri"`
	// MimeType is the resource MIME type, if known.
	MimeType string `json:"mimeType,omitempty"`
	// Text contains textual resource contents.
	Text string `json:"text,omitempty"`
	// Blob contains base64-encoded binary resource contents.
	Blob string `json:"blob,omitempty"`
}

type ResourceDescriptor struct {
	Meta  MetaObject `json:"_meta,omitempty"`
	Icons []Icon     `json:"icons,omitempty"`
	// URI identifies this resource.
	URI string `json:"uri"`
	// Name is the programmatic resource identifier.
	Name string `json:"name"`
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// Description helps clients and LLMs understand the resource.
	Description string `json:"description,omitempty"`
	// MimeType is the resource MIME type, if known.
	MimeType string `json:"mimeType,omitempty"`
	// Annotations provide optional client metadata.
	Annotations *Annotations `json:"annotations,omitempty"`
	// Size is the raw resource size in bytes, if known.
	Size int64 `json:"size,omitzero"`
}

type ResourceLink struct {
	Type  ContentType `json:"type"`
	Icons []Icon      `json:"icons,omitempty"`
	// Name is the programmatic resource identifier.
	Name string `json:"name"`
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// URI identifies the resource.
	URI string `json:"uri"`
	// Description helps clients and LLMs understand the resource.
	Description string `json:"description,omitempty"`
	// MimeType is the resource MIME type, if known.
	MimeType string `json:"mimeType,omitempty"`
	// Size is the raw resource size in bytes, if known.
	Size int64 `json:"size,omitzero"`
}

type ResourceTemplateDescriptor struct {
	Meta  MetaObject `json:"_meta,omitempty"`
	Icons []Icon     `json:"icons,omitempty"`
	// Name is the programmatic template identifier.
	Name string `json:"name"`
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// URITemplate is an RFC 6570 URI template for constructing resource URIs.
	URITemplate string `json:"uriTemplate"`
	// Description helps clients and LLMs understand the template.
	Description string `json:"description,omitempty"`
	// MimeType is the MIME type for matching resources, if uniform.
	MimeType string `json:"mimeType,omitempty"`
	// Annotations provide optional client metadata.
	Annotations *Annotations `json:"annotations,omitempty"`
}

type ResourceTemplatesListResult struct {
	Meta              MetaObject                   `json:"_meta,omitempty"`
	ResultType        ResultType                   `json:"resultType"`
	NextCursor        string                       `json:"nextCursor,omitempty"`
	ResourceTemplates []ResourceTemplateDescriptor `json:"resourceTemplates"`
	TTLMS             int                          `json:"ttlMs"`
	CacheScope        CacheScope                   `json:"cacheScope"`
}

type ResourceTemplatesRegistry interface {
	ResourceTemplates(ctx context.Context) ([]ResourceTemplateDescriptor, error)
}

type ResourceUpdate struct {
	// KeepAlive requests an SSE heartbeat without a resource notification.
	KeepAlive bool
	// ResourcesListChanged indicates the resource list may have changed.
	ResourcesListChanged bool
	// ResourceURIs are subscribed resource URIs whose contents may have changed.
	ResourceURIs []string
}

type ResourcesCapability struct {
	// Subscribe indicates support for subscribing to individual resource updates.
	Subscribe bool `json:"subscribe,omitempty"`
	// ListChanged indicates support for resource list change notifications.
	ListChanged bool `json:"listChanged,omitempty"`
}

type ResourcesListResult struct {
	Meta       MetaObject           `json:"_meta,omitempty"`
	ResultType ResultType           `json:"resultType"`
	NextCursor string               `json:"nextCursor,omitempty"`
	Resources  []ResourceDescriptor `json:"resources"`
	TTLMS      int                  `json:"ttlMs"`
	CacheScope CacheScope           `json:"cacheScope"`
}

type ResourcesReadParams struct {
	Meta RequestMeta `json:"_meta"`
	// InputResponses carries responses to server-initiated requests from a prior input_required result.
	InputResponses json.RawMessage `json:"inputResponses,omitempty"`
	// RequestState carries opaque state from a prior input_required result.
	RequestState string `json:"requestState,omitempty"`
	// URI identifies the resource to read.
	URI string `json:"uri"`
}

type ResourcesReadResult struct {
	Meta       MetaObject `json:"_meta,omitempty"`
	ResultType ResultType `json:"resultType"`
	// Contents contains text or blob resource contents.
	Contents []ResourceContent `json:"contents"`
	// TTLMS hints how long clients may cache this response in milliseconds.
	TTLMS int `json:"ttlMs"`
	// CacheScope indicates whether the response may be cached publicly or privately.
	CacheScope CacheScope `json:"cacheScope"`
}

type ResultType string

type Role string

type SamplingCapability struct {
	// Context declares context inclusion support.
	Context MetaObject `json:"context,omitempty"`
	// Tools declares tool-use support.
	Tools MetaObject `json:"tools,omitempty"`
}

type ServerDiscoverResult struct {
	ResultType ResultType `json:"resultType"`
	// SupportedVersions lists MCP protocol versions supported by this server.
	SupportedVersions []string `json:"supportedVersions"`
	// Capabilities advertises server features.
	Capabilities Capabilities `json:"capabilities"`
	// ServerInfo describes the server software implementation.
	ServerInfo Implementation `json:"serverInfo"`
	// Instructions gives natural-language guidance for using the server effectively.
	//
	// Clients may include it in an LLM system prompt. It should not duplicate tool
	// descriptions.
	Instructions string `json:"instructions,omitempty"`
	// TTLMS hints how long clients may cache this response in milliseconds.
	TTLMS int `json:"ttlMs"`
	// CacheScope indicates whether the response may be cached publicly or privately.
	CacheScope CacheScope `json:"cacheScope"`
}

type Skill struct {
	URI         string          `json:"uri"`
	Frontmatter map[string]any  `json:"frontmatter"`
	Resources   []SkillResource `json:"resources"`
}

type SkillResource struct {
	URI    string `json:"uri"`
	Digest string `json:"digest"`
	Size   int64  `json:"size"`
}

type SkillsGetParams struct {
	Meta RequestMeta `json:"_meta"`
	URI  string      `json:"uri"`
}

type SkillsGetResult struct {
	Meta       MetaObject `json:"_meta,omitempty"`
	ResultType ResultType `json:"resultType"`
	Skill      Skill      `json:"skill"`
	TTLMS      int        `json:"ttlMs"`
	CacheScope CacheScope `json:"cacheScope"`
}

type SkillsListResult struct {
	Meta       MetaObject `json:"_meta,omitempty"`
	ResultType ResultType `json:"resultType"`
	NextCursor string     `json:"nextCursor,omitempty"`
	Skills     []Skill    `json:"skills"`
	TTLMS      int        `json:"ttlMs"`
	CacheScope CacheScope `json:"cacheScope"`
}

type SkillsRegistry interface {
	ListSkills(ctx context.Context, cursor string) (SkillsListResult, error)
	GetSkill(ctx context.Context, uri string) (SkillsGetResult, error)
}

type SubscriptionFilter struct {
	// ResourcesListChanged requests resource list change notifications.
	ResourcesListChanged bool `json:"resourcesListChanged,omitempty"`
	// ResourceSubscriptions requests updates for individual resource URIs.
	ResourceSubscriptions []string `json:"resourceSubscriptions,omitempty"`
}

type SubscriptionNotificationParams struct {
	Meta MetaObject `json:"_meta,omitempty"`
	// Notifications is the subset of requested notification types the server accepted.
	Notifications *SubscriptionFilter `json:"notifications,omitempty"`
	// URI identifies an updated resource.
	URI string `json:"uri,omitempty"`
}

type SubscriptionRegistry interface {
	SubscribeResourceUpdates(ctx context.Context, filter SubscriptionFilter) (iter.Seq2[ResourceUpdate, error], error)
}

type SubscriptionsInitialStateParams struct {
	Meta MetaObject `json:"_meta,omitempty"`
	// URI is the subscribed target whose initial state was delivered.
	URI string `json:"uri"`
	// Contents is the resources/read result for the same target, so a client
	// that applies the payload holds the post-subscription state without a
	// second read.
	Contents []ResourceContent `json:"contents"`
}

type SubscriptionsListenParams struct {
	Meta RequestMeta `json:"_meta"`
	// Notifications declares notification types the client opts in to.
	Notifications SubscriptionFilter `json:"notifications"`
}

type TextOutput struct {
	Result string `json:"result" jsonschema_description:"Human-readable tool result"`
}

type ToolAnnotations struct {
	// Title is a human-readable title for the tool.
	Title string `json:"title,omitempty"`
	// ReadOnlyHint indicates the tool does not modify its environment.
	ReadOnlyHint bool `json:"readOnlyHint,omitempty"`
	// DestructiveHint indicates the tool may perform destructive updates.
	DestructiveHint bool `json:"destructiveHint,omitempty"`
	// IdempotentHint indicates repeated calls with the same arguments have no additional effect.
	IdempotentHint bool `json:"idempotentHint,omitempty"`
	// OpenWorldHint indicates the tool may interact with external entities.
	OpenWorldHint bool `json:"openWorldHint,omitempty"`
}

type ToolCallResult struct {
	Meta       MetaObject `json:"_meta,omitempty"`
	ResultType ResultType `json:"resultType"`
	// Content is the unstructured result of the tool call.
	Content []ContentBlock `json:"content"`
	// StructuredContent is optional JSON matching the tool output schema on success.
	StructuredContent any `json:"structuredContent,omitempty"`
	// IsError indicates the tool call ended in an error visible to the model.
	IsError bool `json:"isError,omitempty"`
}

type ToolDescriptor struct {
	Meta  MetaObject `json:"_meta,omitempty"`
	Icons []Icon     `json:"icons,omitempty"`
	// Name is the programmatic tool identifier.
	Name string `json:"name"`
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// Description helps clients and LLMs understand the tool.
	Description string `json:"description,omitempty"`
	// InputSchema defines the expected JSON object arguments for the tool.
	InputSchema *jsonschema.Schema `json:"inputSchema"`
	// OutputSchema defines the structuredContent shape for successful results.
	OutputSchema *jsonschema.Schema `json:"outputSchema,omitempty"`
	// Annotations contains optional tool behavior hints.
	Annotations *ToolAnnotations `json:"annotations,omitempty"`
}

type ToolHandler func(context.Context, *ToolsCallParams) (RawToolResult, error)

type ToolRequest[T any] struct {
	Params    RequestParams
	Arguments T
}

type ToolResult[T any] struct {
	Meta       MetaObject
	Structured any
	IsError    bool
	// contains filtered or unexported fields
}

type ToolSpec struct {
	Name         string
	Title        string
	Description  string
	InputSchema  *jsonschema.Schema
	OutputSchema *jsonschema.Schema
	Annotations  *ToolAnnotations
	Handler      ToolHandler
}

type ToolsCallParams struct {
	Meta RequestMeta `json:"_meta"`
	// InputResponses carries responses to server-initiated requests from a prior input_required result.
	InputResponses json.RawMessage `json:"inputResponses,omitempty"`
	// RequestState carries opaque state from a prior input_required result.
	RequestState string `json:"requestState,omitempty"`
	// Name identifies the tool to invoke.
	Name string `json:"name"`
	// Arguments contains tool arguments as a JSON object.
	Arguments json.RawMessage `json:"arguments,omitempty"`
}

type ToolsCapability struct {
	// ListChanged indicates support for tool list change notifications.
	ListChanged bool `json:"listChanged,omitempty"`
}

type ToolsListResult struct {
	Meta       MetaObject       `json:"_meta,omitempty"`
	ResultType ResultType       `json:"resultType"`
	NextCursor string           `json:"nextCursor,omitempty"`
	Tools      []ToolDescriptor `json:"tools"`
	TTLMS      int              `json:"ttlMs"`
	CacheScope CacheScope       `json:"cacheScope"`
}