// Package mcp 实现 MCP (Model Context Protocol) 客户端.
//
// MCP 是 Flyto 的核心扩展机制,允许通过独立的服务器进程
// 提供额外的工具,资源和提示.
//
// 通信协议:JSON-RPC 2.0 over stdio(stdin/stdout)
package mcp

import "encoding/json"

// MCPTool 表示一个 MCP 服务器提供的工具.
type MCPTool struct {
	// Name 工具名称
	Name string `json:"name"`
	// Description 工具描述
	Description string `json:"description,omitempty"`
	// InputSchema 工具的 JSON Schema 输入定义
	InputSchema json.RawMessage `json:"inputSchema,omitempty"`
}

// MCPResource 表示一个 MCP 服务器提供的资源.
type MCPResource struct {
	// URI 资源唯一标识符
	URI string `json:"uri"`
	// Name 资源名称
	Name string `json:"name"`
	// Description 资源描述
	Description string `json:"description,omitempty"`
	// MimeType 资源的 MIME 类型
	MimeType string `json:"mimeType,omitempty"`
}

// MCPPrompt 表示一个 MCP 服务器提供的提示模板.
type MCPPrompt struct {
	// Name 提示名称
	Name string `json:"name"`
	// Description 提示描述
	Description string `json:"description,omitempty"`
	// Arguments 提示模板的参数定义
	Arguments []MCPPromptArgument `json:"arguments,omitempty"`
}

// MCPPromptArgument 是提示模板的参数定义.
type MCPPromptArgument struct {
	// Name 参数名称
	Name string `json:"name"`
	// Description 参数描述
	Description string `json:"description,omitempty"`
	// Required 是否必填
	Required bool `json:"required,omitempty"`
}

// ServerCapabilities 表示 MCP 服务器声明的能力.
type ServerCapabilities struct {
	// Tools 是否支持工具能力
	Tools *CapabilityConfig `json:"tools,omitempty"`
	// Resources 是否支持资源能力
	Resources *CapabilityConfig `json:"resources,omitempty"`
	// Prompts 是否支持提示能力
	Prompts *CapabilityConfig `json:"prompts,omitempty"`
}

// ── Elicitation 类型(MCP 2025-03-26 规范)─────────────────────────────────

// ElicitationCreateParams 是 elicitation/create server-to-client 请求的参数.
//
// 升华改进(ELEVATED): 早期实现 无此类型,遇到服务器请求时直接挂起.
// 我们完整定义 spec 数据结构,消费层可以根据 Schema 渲染合适的 UI.
type ElicitationCreateParams struct {
	// Message 展示给用户的说明文字(Markdown)
	Message string `json:"message"`

	// RequestedSchema 用户输入的 JSON Schema 约束(简化版,仅支持 object type)
	RequestedSchema *ElicitationSchema `json:"requestedSchema,omitempty"`
}

// ElicitationSchema 是 elicitation 请求中描述用户输入结构的简化 JSON Schema.
// MCP 规范只支持 object type + 基本属性类型(string/number/boolean).
type ElicitationSchema struct {
	// Type 固定为 "object"
	Type string `json:"type"`

	// Properties 字段定义(key 为字段名)
	Properties map[string]ElicitationProperty `json:"properties,omitempty"`

	// Required 必填字段列表
	Required []string `json:"required,omitempty"`
}

// ElicitationProperty 是 elicitation schema 中单个字段的定义.
type ElicitationProperty struct {
	// Type 字段类型:"string" / "number" / "boolean"
	Type string `json:"type"`

	// Title 显示给用户的标题(可选)
	Title string `json:"title,omitempty"`

	// Description 字段描述(可选)
	Description string `json:"description,omitempty"`

	// Default 默认值(any,通过 JSON 编码传输)
	Default any `json:"default,omitempty"`
}

// ElicitationCreateResult 是 elicitation/create 请求的响应(client → server).
type ElicitationCreateResult struct {
	// Action 用户操作:"accept" / "decline" / "cancel"
	Action string `json:"action"`

	// Content 用户填写的字段值(仅 action=="accept" 时有意义)
	// 精妙之处(CLEVER): 用 map[string]any 而非强类型--
	// 服务器 schema 声明了类型,客户端只需传字符串,服务器负责类型转换.
	// 这样避免客户端需要反射每个字段的 Go 类型,代码简单.
	Content map[string]any `json:"content,omitempty"`
}

// CapabilityConfig 是能力配置.
type CapabilityConfig struct {
	// ListChanged 是否支持列表变更通知
	ListChanged bool `json:"listChanged,omitempty"`
}

// ServerInfo 是 MCP 服务器的基本信息.
type ServerInfo struct {
	// Name 服务器名称
	Name string `json:"name"`
	// Version 服务器版本
	Version string `json:"version"`
}

// InitializeResult 是 initialize 请求的响应.
type InitializeResult struct {
	// ProtocolVersion 协议版本
	ProtocolVersion string `json:"protocolVersion"`
	// Capabilities 服务器能力
	Capabilities ServerCapabilities `json:"capabilities"`
	// ServerInfo 服务器信息
	ServerInfo ServerInfo `json:"serverInfo"`
}

// ToolCallResult 是工具调用的结果.
type ToolCallResult struct {
	// Content 结果内容列表
	Content []ContentItem `json:"content"`
	// IsError 是否为错误
	IsError bool `json:"isError,omitempty"`
}

// ContentItem 是工具结果的内容项.
type ContentItem struct {
	// Type 内容类型(text, image, resource)
	Type string `json:"type"`
	// Text 文本内容(type=text 时)
	Text string `json:"text,omitempty"`
	// MimeType MIME 类型(type=resource 时)
	MimeType string `json:"mimeType,omitempty"`
	// URI 资源 URI(type=resource 时)
	URI string `json:"uri,omitempty"`
	// Data base64 编码的数据(type=image 时)
	Data string `json:"data,omitempty"`
}

// ResourceContent 是读取资源的响应内容.
type ResourceContent struct {
	// URI 资源 URI
	URI string `json:"uri"`
	// MimeType MIME 类型
	MimeType string `json:"mimeType,omitempty"`
	// Text 文本内容
	Text string `json:"text,omitempty"`
	// Blob base64 编码的二进制数据
	Blob string `json:"blob,omitempty"`
}

// ReadResourceResult 是 resources/read 请求的响应.
type ReadResourceResult struct {
	Contents []ResourceContent `json:"contents"`
}

// ListToolsResult 是 tools/list 请求的响应.
type ListToolsResult struct {
	Tools []MCPTool `json:"tools"`
}

// ListResourcesResult 是 resources/list 请求的响应.
type ListResourcesResult struct {
	Resources []MCPResource `json:"resources"`
}

// MCPPromptMessage 是提示模板返回的消息.
type MCPPromptMessage struct {
	// Role 消息角色(user / assistant)
	Role string `json:"role"`
	// Content 消息内容
	Content any `json:"content"`
}

// GetPromptResult 是 prompts/get 请求的响应.
type GetPromptResult struct {
	// Description 提示描述
	Description string `json:"description,omitempty"`
	// Messages 提示消息列表
	Messages []MCPPromptMessage `json:"messages"`
}

// ListPromptsResult 是 prompts/list 请求的响应.
type ListPromptsResult struct {
	Prompts []MCPPrompt `json:"prompts"`
}