api

type Convertible[T any] interface {
	// ToAPIType can be used to convert a wrapped domain type to an API-safe type.
	// It should be responsible for any normalization required to ensure consistency
	// across the API boundary.
	ToAPIType() (T, error)
}

type DomainMeta mcp.Meta

type DomainPrompt mcp.Prompt

type DomainPromptArgument mcp.PromptArgument

type DomainPromptMessage mcp.PromptMessage

type DomainResource mcp.Resource

type DomainResourceTemplate mcp.ResourceTemplate

type DomainServerHealth domain.ServerHealth

type ErrorType string

type GeneratePromptResponse struct {
	Body struct {
		// Description for the prompt.
		Description string `json:"description,omitempty"`

		// Messages that make up the prompt.
		Messages []PromptMessage `json:"messages"`
	}
}

type HealthStatus string

type JSONSchema struct {
	// Type defines the type for this schema, e.g. "object".
	Type string `json:"type"`

	// Properties represents a property name and associated object definition.
	Properties map[string]any `json:"properties,omitempty"`

	// Required lists the (keys of) Properties that are required.
	Required []string `json:"required,omitempty"`
}

type Meta map[string]any

type Prompt struct {
	// Name of the prompt or prompt template.
	Name string `json:"name"`

	// Description of what this prompt provides.
	Description string `json:"description,omitempty"`

	// Arguments for templating the prompt.
	Arguments []PromptArgument `json:"arguments,omitempty"`

	// Meta is reserved by MCP to allow clients and servers to attach additional metadata.
	Meta Meta `json:"_meta,omitempty"` //nolint:tagliatelle
}

type PromptArgument struct {
	// Name of the argument.
	Name string `json:"name"`

	// Description of the argument.
	Description string `json:"description,omitempty"`

	// Whether this argument must be provided.
	Required bool `json:"required,omitempty"`
}

type PromptGenerateArguments struct {
	Arguments map[string]string `doc:"Arguments for templating the prompt" json:"arguments,omitempty"`
}

type PromptMessage struct {
	// Role of the message sender.
	Role string `json:"role"`

	// Content can be text, image, audio, or embedded resource.
	Content interface{} `json:"content"`
}

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

type PromptsListResponse struct {
	Body Prompts
}

type Resource struct {
	// URI of this resource.
	URI string `json:"uri"`

	// Name is a human-readable name for this resource.
	Name string `json:"name"`

	// Description of what this resource represents.
	Description string `json:"description,omitempty"`

	// MIMEType of this resource, if known.
	MIMEType string `json:"mimeType,omitempty"`

	// Meta is reserved by MCP to allow clients and servers to attach additional metadata.
	Meta Meta `json:"_meta,omitempty"` //nolint:tagliatelle
}

type ResourceContent struct {
	// URI of this resource.
	URI string `json:"uri"`

	// MIMEType of this resource, if known.
	MIMEType string `json:"mimeType,omitempty"`

	// Text content (for text resources).
	Text string `json:"text,omitempty"`

	// Blob content (base64 encoded binary data).
	Blob string `json:"blob,omitempty"`

	// Meta is reserved by MCP to allow clients and servers to attach additional metadata.
	Meta Meta `json:"_meta,omitempty"` //nolint:tagliatelle
}

type ResourceContentResponse struct {
	Body []ResourceContent
}

type ResourceTemplate struct {
	// URITemplate is a URI template (RFC 6570) for constructing resource URIs.
	URITemplate string `json:"uriTemplate"`

	// Name is a human-readable name for the type of resource this template refers to.
	Name string `json:"name"`

	// Description of what this template is for.
	Description string `json:"description,omitempty"`

	// MIMEType for all resources that match this template.
	MIMEType string `json:"mimeType,omitempty"`

	// Meta is reserved by MCP to allow clients and servers to attach additional metadata.
	Meta Meta `json:"_meta,omitempty"` //nolint:tagliatelle
}

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

type ResourceTemplatesResponse struct {
	Body ResourceTemplates
}

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

type ResourcesResponse struct {
	Body Resources
}

type ServerHealth struct {
	Name           string       `json:"name"`
	Status         HealthStatus `json:"status"`
	Latency        *string      `json:"latency,omitempty"`
	LastChecked    *time.Time   `json:"lastChecked,omitempty"`
	LastSuccessful *time.Time   `json:"lastSuccessful,omitempty"`
}

type ServerHealthRequest struct {
	Name string `doc:"Name of the server to check" example:"time" path:"name"`
}

type ServerHealthResponse struct {
	Body ServerHealth
}

type ServerPromptGenerateRequest struct {
	ServerName string                  `doc:"Name of the server" path:"name"`
	PromptName string                  `doc:"Name of the prompt" path:"promptName"`
	Body       PromptGenerateArguments `doc:"Prompt arguments"`
}

type ServerPromptsListRequest struct {
	Name   string `doc:"Name of the server" path:"name"`
	Cursor string `doc:"Pagination cursor"              query:"cursor"`
}

type ServerResourceContentRequest struct {
	Name string `doc:"Name of the server"  path:"name"`
	URI  string `doc:"URI of the resource"             query:"uri"`
}

type ServerResourceTemplatesRequest struct {
	Name   string `doc:"Name of the server" path:"name"`
	Cursor string `doc:"Pagination cursor"              query:"cursor"`
}

type ServerResourcesRequest struct {
	Name   string `doc:"Name of the server" path:"name"`
	Cursor string `doc:"Pagination cursor"              query:"cursor"`
}

type ServerToolCallRequest struct {
	Server string         `doc:"Name of the server"       example:"time"             path:"server"`
	Tool   string         `doc:"Name of the tool to call" example:"get_current_time" path:"tool"`
	Body   map[string]any `doc:"Body of the tool to call"                            path:"body"`
}

type ServerToolsRequest struct {
	Name string `doc:"Name of the server to lookup tools for" example:"time" path:"name"`

	// Detail specifies the level of detail to return (minimal, summary, or full).
	// NOTE: This field is not used by the handler itself; it exists solely for OpenAPI documentation.
	// The actual filtering is performed by toolFieldSelectTransformer, which reads the query parameter directly.
	Detail toolDetailLevel `default:"full" doc:"Level of detail to return" enum:"minimal,summary,full" query:"detail"`
}

type ServersHealth struct {
	Servers []ServerHealth `json:"servers"`
}

type ServersHealthResponse struct {
	Body struct {
		Servers []ServerHealth `doc:"Tracked MCP server health statuses" json:"servers"`
	}
}

type ServersResponse struct {
	Body []string
}

type Tool struct {
	ToolSummary

	// InputSchema is JSONSchema defining the expected parameters for the tool.
	InputSchema *JSONSchema `doc:"Input parameters schema" json:"inputSchema,omitempty"`

	// OutputSchema is an optional JSONSchema defining the structure of the tool's
	// output returned in the structured content field of a tool call result.
	OutputSchema *JSONSchema `doc:"Output structure schema" json:"outputSchema,omitempty"`

	// Annotations provide optional additional tool information.
	// Display name precedence order is: title, annotations.title when present, then tool name.
	Annotations *ToolAnnotations `doc:"Additional hints about the tool" json:"annotations,omitempty"`

	// Meta is reserved by MCP to allow clients and servers to attach additional metadata to their interactions.
	// See https://modelcontextprotocol.io/specification/2025-06-18/basic#general-fields for notes on _meta usage.
	Meta map[string]any `doc:"Additional metadata" json:"_meta,omitempty"` //nolint:tagliatelle
}

type ToolAnnotations struct {
	// Title is a human-readable title for the tool.
	Title *string `json:"title,omitempty"`

	// ReadOnlyHint if true, the tool should not modify its environment.
	ReadOnlyHint *bool `json:"readOnlyHint,omitempty"`

	// DestructiveHint if true, the tool may perform destructive updates to its environment.
	// If false, the tool performs only additive updates.
	// (This property is meaningful only when ReadOnlyHint is false)
	DestructiveHint *bool `json:"destructiveHint,omitempty"`

	// IdempotentHint if true, calling the tool repeatedly with the same arguments
	// will have no additional effect on its environment.
	// (This property is meaningful only when ReadOnlyHint is false)
	IdempotentHint *bool `json:"idempotentHint,omitempty"`

	// OpenWorldHint if true, this tool may interact with an "open world" of external
	// entities. If false, the tool's domain of interaction is closed.
	// For example, the world of a web search tool is open, whereas that
	// of a memory tool is not.
	OpenWorldHint *bool `json:"openWorldHint,omitempty"`
}

type ToolCallResponse struct {
	Body string
}

type ToolMinimal struct {
	// Name of the tool.
	Name string `doc:"Name of the tool" json:"name"`

	// Title is a human-readable and easily understood title for the tool.
	Title string `doc:"Human-readable title" json:"title,omitempty"`
}

type ToolSummary struct {
	ToolMinimal

	// Description is a human-readable description of the tool.
	// This can be used by clients to improve the LLM's understanding of available tools.
	// It can be thought of like a "hint" to the model.
	Description string `doc:"Description of what the tool does" json:"description"`
}

type ToolView interface {
	ToolMinimal | ToolSummary | Tool
}

type ToolsResponse[T ToolView] struct {
	Body ToolsResponseBody[T]
}

type ToolsResponseBody[T ToolView] struct {
	Tools []T `json:"tools"`
}