core

type AuthError struct {
	Code            int
	Message         string
	WWWAuthenticate string // optional WWW-Authenticate header value
}

type AuthValidator interface {
	Validate(r *http.Request) error
}

type BaseContext struct {
	context.Context
	// contains filtered or unexported fields
}

type Claims struct {
	// Subject is the authenticated principal (user ID or client ID).
	Subject string `json:"sub"`

	// Issuer identifies the authorization server that issued the token.
	Issuer string `json:"iss"`

	// Audience lists the intended recipients of the token (RFC 8707).
	Audience []string `json:"aud"`

	// Scopes lists the granted scopes.
	Scopes []string `json:"scope"`

	// Extra holds additional claims not covered by the standard fields.
	Extra map[string]any `json:"extra,omitempty"`
}

type ClaimsProvider interface {
	Claims(r *http.Request) *Claims
}

type ClientCapabilities struct {
	Sampling    *struct{} `json:"sampling,omitempty"`
	Roots       *RootsCap `json:"roots,omitempty"`
	Elicitation *struct{} `json:"elicitation,omitempty"`

	// Extensions maps extension IDs to the client's capability declaration
	// for that extension. Sent during initialize to advertise extension support.
	Extensions map[string]ClientExtensionCap `json:"extensions,omitempty"`
}

type ClientExtensionCap struct {
	// MIMETypes lists content types the client supports for this extension.
	MIMETypes []string `json:"mimeTypes,omitempty"`
}

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

type CompletionArgument struct {
	// Name is the argument name being completed.
	Name string `json:"name"`

	// Value is the partial input the user has typed so far.
	Value string `json:"value"`
}

type CompletionCompleteResult struct {
	Completion CompletionResult `json:"completion"`
}

type CompletionHandler func(ctx PromptContext, ref CompletionRef, arg CompletionArgument) (CompletionResult, error)

type CompletionRef struct {
	// Type is "ref/prompt" for prompt argument completion or "ref/resource" for resource URI completion.
	Type string `json:"type"`

	// Name is the prompt name (when Type is "ref/prompt").
	Name string `json:"name,omitempty"`

	// URI is the resource URI template (when Type is "ref/resource").
	URI string `json:"uri,omitempty"`
}

type CompletionResult struct {
	// Values is the list of completion suggestions.
	Values []string `json:"values"`

	// Total is the total number of available completions (may be larger than len(Values)).
	Total int `json:"total,omitempty"`

	// HasMore indicates there are additional completions beyond what was returned.
	HasMore bool `json:"hasMore"`
}

type Content struct {
	Type     string           `json:"type"`
	Text     string           `json:"text,omitempty"`
	MimeType string           `json:"mimeType,omitempty"`
	Data     string           `json:"data,omitempty"`
	Resource *ResourceContent `json:"resource,omitempty"`
}

type ContentChunk struct {
	// RequestID links the chunk to the original tools/call request.
	RequestID json.RawMessage `json:"requestId"`

	// Content is the partial content block.
	Content Content `json:"content"`
}

type CreateMessageRequest struct {
	Messages         []SamplingMessage `json:"messages"`
	SystemPrompt     string            `json:"systemPrompt,omitempty"`
	IncludeContext   string            `json:"includeContext,omitempty"` // "none", "thisServer", "allServers"
	Temperature      *float64          `json:"temperature,omitempty"`
	MaxTokens        int               `json:"maxTokens"`
	ModelPreferences *ModelPreferences `json:"modelPreferences,omitempty"`
	StopSequences    []string          `json:"stopSequences,omitempty"`
	Metadata         map[string]any    `json:"metadata,omitempty"`
	Meta             *SamplingMeta     `json:"_meta,omitempty"`
}

type CreateMessageResult struct {
	Model      string  `json:"model"`
	StopReason string  `json:"stopReason,omitempty"`
	Role       string  `json:"role"`
	Content    Content `json:"content"`
}

type DisplayMode string

type ElicitationMeta struct {
	// UI contains MCP Apps presentation metadata.
	// When set, the host can render a UI resource during input collection
	// instead of falling back to the default schema-driven form.
	UI *UIMetadata `json:"ui,omitempty"`
}

type ElicitationRequest struct {
	Message         string           `json:"message"`
	RequestedSchema json.RawMessage  `json:"requestedSchema,omitempty"`
	Meta            *ElicitationMeta `json:"_meta,omitempty"`
}

type ElicitationResult struct {
	Action  string         `json:"action"` // "accept", "decline", or "cancel"
	Content map[string]any `json:"content,omitempty"`
}

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

type Extension struct {
	// ID is the extension identifier (e.g., "io.mcpkit/auth").
	ID string `json:"id"`

	// SpecVersion is the version of the spec this extension implements.
	SpecVersion string `json:"specVersion"`

	// Stability indicates the maturity of this extension.
	Stability Stability `json:"stability"`

	// Config holds extension-specific configuration, if any.
	Config map[string]any `json:"config,omitempty"`
}

type ExtensionCapability struct {
	SpecVersion string `json:"specVersion"`
	Stability   string `json:"stability"`
}

type ExtensionProvider interface {
	Extension() Extension
}

type InitializeResult struct {
	ProtocolVersion string             `json:"protocolVersion"`
	Capabilities    ServerCapabilities `json:"capabilities"`
	ServerInfo      ServerInfo         `json:"serverInfo"`
}

type LogLevel int

type LogMessage struct {
	Level  string `json:"level"`
	Logger string `json:"logger,omitempty"`
	Data   any    `json:"data"`
}

type ModelHint struct {
	Name string `json:"name,omitempty"`
}

type ModelPreferences struct {
	Hints                []ModelHint `json:"hints,omitempty"`
	CostPriority         *float64    `json:"costPriority,omitempty"`
	SpeedPriority        *float64    `json:"speedPriority,omitempty"`
	IntelligencePriority *float64    `json:"intelligencePriority,omitempty"`
}

type NotificationHandler func(method string, params []byte)

type NotifyFunc func(method string, params any)

type PingResult struct{}

type ProgressNotification struct {
	// ProgressToken is the token from the request's _meta.progressToken field.
	// It links this notification to the original request.
	ProgressToken any `json:"progressToken"`

	// Progress is the current progress value (e.g., bytes processed, items completed).
	Progress float64 `json:"progress"`

	// Total is the expected total value. Zero means indeterminate progress.
	Total float64 `json:"total,omitempty"`

	// Message is an optional human-readable status message.
	Message string `json:"message,omitempty"`
}

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

	// Schema is an optional JSON Schema describing the expected value shape
	// for this argument. Mirrors ToolDef.InputSchema: typically a
	// map[string]any with "type", "enum", "minimum", etc. Arbitrary JSON
	// Schema keywords ($ref, $defs, additionalProperties, ...) are preserved
	// as-is through registration, serialization, and client deserialization.
	//
	// Enforced server-side: when set, the dispatcher validates incoming
	// argument values against the schema before invoking the handler and
	// returns -32602 Invalid Params with a structured errors list on
	// failure (#184). Arguments without a Schema bypass validation.
	// Use server.WithSchemaValidation(false) to opt out of call-time
	// validation if you prefer to validate in the handler.
	Schema any `json:"schema,omitempty"`
}

type PromptContext struct {
	BaseContext
}

type PromptDef struct {
	// Name is the prompt identifier used in prompts/get.
	Name string `json:"name"`

	// Title is an optional display title.
	Title string `json:"title,omitempty"`

	// Description explains what this prompt does.
	Description string `json:"description,omitempty"`

	// Arguments defines the parameters this prompt accepts.
	Arguments []PromptArgument `json:"arguments,omitempty"`

	// Annotations holds optional metadata for this prompt.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Timeout is a per-prompt execution timeout. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

type PromptHandler func(ctx PromptContext, req PromptRequest) (PromptResult, error)

type PromptMessage struct {
	Role    string  `json:"role"`
	Content Content `json:"content"` // reuses Content from tool.go
}

type PromptRequest struct {
	Name      string
	Arguments map[string]any
}

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

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

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

type RefValidator interface {
	ValidateRefs(tools []ToolDef, resourceURIs []string, templateURIs []string) []string
}

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

type RequestFunc func(ctx context.Context, method string, params any) (json.RawMessage, error)

type ResourceContent struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`
}

type ResourceContentMeta struct {
	// UI contains MCP Apps presentation metadata.
	UI *UIMetadata `json:"ui,omitempty"`
}

type ResourceContext struct {
	BaseContext
}

type ResourceDef struct {
	// URI uniquely identifies this resource.
	URI string `json:"uri"`

	// Name is a human-readable short name.
	Name string `json:"name"`

	// Title is an optional display title.
	Title string `json:"title,omitempty"`

	// Description explains what this resource provides.
	Description string `json:"description,omitempty"`

	// MimeType is the MIME type of the resource content.
	MimeType string `json:"mimeType,omitempty"`

	// Annotations holds optional metadata for this resource.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Timeout is a per-resource execution timeout. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

type ResourceHandler func(ctx ResourceContext, req ResourceRequest) (ResourceResult, error)

type ResourceReadContent struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`

	// Meta holds per-content metadata (e.g., UI overrides).
	// Takes precedence over the resource-level _meta from resources/list.
	Meta *ResourceContentMeta `json:"_meta,omitempty"`
}

type ResourceRequest struct {
	URI string
}

type ResourceResult struct {
	Contents []ResourceReadContent `json:"contents"`
}

type ResourceTemplate struct {
	// URITemplate is an RFC 6570 URI template (e.g., "file:///{path}").
	// This serves as the unique identifier for the template in the registry —
	// registering a template with the same URI template string overwrites the
	// previous registration.
	URITemplate string `json:"uriTemplate"`

	// Name is a human-readable short name.
	Name string `json:"name"`

	// Title is an optional display title.
	Title string `json:"title,omitempty"`

	// Description explains what this template provides.
	Description string `json:"description,omitempty"`

	// MimeType is the default MIME type for resources matching this template.
	MimeType string `json:"mimeType,omitempty"`

	// Annotations holds optional metadata for this template.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Timeout is a per-template execution timeout. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

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

type ResourceUpdatedNotification struct {
	URI string `json:"uri"`
}

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

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

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

type Root struct {
	// URI is the root's location (e.g., "file:///home/user/project").
	URI string `json:"uri"`

	// Name is an optional human-readable label for this root.
	Name string `json:"name,omitempty"`
}

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

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

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

type SamplingMeta struct {
	// UI contains MCP Apps presentation metadata.
	// When set, the host can associate the sampling request with a UI resource.
	UI *UIMetadata `json:"ui,omitempty"`
}

type ScopeAwareTokenSource interface {
	TokenSource
	// TokenForScopes invalidates the cached token and triggers a new
	// authorization flow with the given scopes merged into the existing set.
	TokenForScopes(scopes []string) (string, error)
}

type ServerCapabilities struct {
	Tools       *ToolsCap                      `json:"tools,omitempty"`
	Resources   *ResourcesCap                  `json:"resources,omitempty"`
	Prompts     *PromptsCap                    `json:"prompts,omitempty"`
	Logging     *struct{}                      `json:"logging,omitempty"`
	Completions *struct{}                      `json:"completions,omitempty"`
	Extensions  map[string]ExtensionCapability `json:"extensions,omitempty"`
}

type ServerInfo struct {
	Name         string `json:"name"`
	Version      string `json:"version"`
	Title        string `json:"title,omitempty"`
	Description  string `json:"description,omitempty"`
	Instructions string `json:"instructions,omitempty"`
	WebsiteURL   string `json:"websiteUrl,omitempty"`
}

type ServerRequestHandler func(ctx context.Context, req *Request) *Response

type Stability string

type TemplateHandler func(ctx ResourceContext, uri string, params map[string]string) (ResourceResult, error)

type TokenSource interface {
	// Token returns a valid access token, refreshing if necessary.
	Token() (string, error)
}

type ToolContext struct {
	BaseContext
}

type ToolDef struct {
	// Name is the tool identifier used in tools/call.
	Name string `json:"name"`

	// Description is a human-readable summary of what the tool does.
	Description string `json:"description"`

	// InputSchema is the JSON Schema for the tool's arguments.
	// Typically a map[string]any with "type": "object", "properties": {...}, "required": [...].
	// Arbitrary JSON Schema fields (e.g. "$schema", "$defs", "$ref",
	// "additionalProperties") are preserved as-is through registration,
	// serialization, and client-side deserialization.
	InputSchema any `json:"inputSchema"`

	// OutputSchema is an optional JSON Schema for the tool's structuredContent output.
	// When present, the tool SHOULD return StructuredContent matching this schema.
	// Per MCP spec: enables clients to validate and process tool output programmatically.
	OutputSchema any `json:"outputSchema,omitempty"`

	// Annotations holds optional metadata for this tool.
	// Convention: {"experimental": true} marks experimental tools.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Meta holds protocol-level metadata (e.g., UI presentation hints).
	// Serialized as "_meta" in the tools/list response.
	Meta *ToolMeta `json:"_meta,omitempty"`

	// Timeout is a per-tool execution timeout. If set, overrides the
	// server-wide WithToolTimeout for this tool. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

type ToolHandler func(ctx ToolContext, req ToolRequest) (ToolResult, error)

type ToolMeta struct {
	// UI contains MCP Apps presentation metadata.
	UI *UIMetadata `json:"ui,omitempty"`
}

type ToolRequest struct {
	// Name of the tool being called.
	Name string

	// Arguments is the raw JSON arguments from the tools/call params.
	Arguments json.RawMessage

	// RequestID is the JSON-RPC request ID.
	RequestID json.RawMessage

	// ProgressToken is the token from the request's _meta.progressToken field.
	// Nil if the client did not request progress reporting. Pass this to
	// EmitProgress to send notifications/progress notifications.
	ProgressToken any
}

type ToolResult struct {
	// Content is the list of content items to return.
	Content []Content `json:"content"`

	// IsError indicates the tool execution failed (but the JSON-RPC call itself succeeded).
	IsError bool `json:"isError,omitempty"`

	// StructuredContent holds optional structured data for the tool result.
	// When the tool has an OutputSchema, this field carries typed data matching
	// that schema. On error (IsError=true), it can carry structured error details.
	// Per MCP spec: "If outputSchema is present, structuredContent SHOULD be included."
	StructuredContent any `json:"structuredContent,omitempty"`

	// Meta holds optional result metadata (e.g., pagination cursor).
	Meta *ToolResultMeta `json:"_meta,omitempty"`
}

type ToolResultMeta struct {
	// NextCursor is a pagination cursor for fetching the next page.
	// Empty when there are no more pages.
	NextCursor string `json:"nextCursor,omitempty"`
}

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

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

type Transport interface {
	// Connect establishes the transport (e.g., SSE handshake, session creation).
	Connect(ctx context.Context) error

	// Call sends a JSON-RPC request and returns the response.
	Call(ctx context.Context, req *Request) (*Response, error)

	// Notify sends a JSON-RPC notification (no response expected).
	Notify(ctx context.Context, req *Request) error

	// Close shuts down the transport.
	Close() error

	// SessionID returns the transport's session identifier (empty if none).
	SessionID() string
}

type UICSPConfig struct {
	// ConnectDomains → CSP connect-src (fetch, XHR, WebSocket targets).
	ConnectDomains []string `json:"connectDomains,omitempty"`

	// ResourceDomains → CSP script-src, style-src, img-src, font-src, media-src.
	ResourceDomains []string `json:"resourceDomains,omitempty"`

	// FrameDomains → CSP frame-src (nested iframes).
	FrameDomains []string `json:"frameDomains,omitempty"`

	// BaseUriDomains → CSP base-uri.
	BaseUriDomains []string `json:"baseUriDomains,omitempty"`
}

type UIMetadata struct {
	// ResourceUri points to a ui:// resource containing the HTML to render.
	// Required for tools that want inline UI rendering.
	ResourceUri string `json:"resourceUri,omitempty"`

	// Visibility controls who can see/call this tool.
	// Default (nil): host applies its own default (typically ["model", "app"]).
	Visibility []UIVisibility `json:"visibility,omitempty"`

	// CSP declares external domains the app needs to load resources from.
	// Hosts construct Content-Security-Policy from these declarations.
	CSP *UICSPConfig `json:"csp,omitempty"`

	// Permissions lists browser capabilities the app requests
	// (e.g., "camera", "microphone", "geolocation", "clipboardWrite").
	Permissions []string `json:"permissions,omitempty"`

	// PrefersBorder hints whether the host should draw a visible border.
	// nil = host decides, true = border, false = no border.
	PrefersBorder *bool `json:"prefersBorder,omitempty"`

	// Domain requests a dedicated sandbox origin for the app.
	// Format is host-dependent (e.g., "myapp" → myapp.claudemcpcontent.com).
	Domain string `json:"domain,omitempty"`

	// SupportedDisplayModes declares which display modes this app can render in.
	// Nil means the host decides. Hosts use this to offer mode switching UI.
	SupportedDisplayModes []DisplayMode `json:"supportedDisplayModes,omitempty"`
}

type UIVisibility string