mcpclient

type Connection interface {
	// Run 持有连接状态：启动后马上连接；断开后立刻重连一次，再断开要等下一次 GetTools 才连；收到 tools/list_changed 后重读工具列表；
	// ctx 结束时断开，stdio 进程随之结束，返回 ctx.Err()。只能调用一次。
	Run(ctx context.Context) error
	// GetTools 返回提供给模型的工具（名字已改成 mcp__<id>__<原名>，MCPServerID 已填）：已连上时返回缓存；
	// 正在连时等这次连接；失败过时再连一次；最多等启动超时，连不上返回错误。Run 已返回时返回错误；
	// Run 还没开始时等它开始，最多等到 ctx 结束。
	GetTools(ctx context.Context) ([]*defs.ToolDefinition, error)
	// CallTool 在已连上的会话上调用一次工具；没连上时返回 mcp_server_unavailable，超时、取消、server 报错和中途断开也都写进结果的 Error。
	// 工具名不在本连接的工具列表里时返回 mcp_request_failed，不发给 server。
	CallTool(ctx context.Context, call *defs.Item) *defs.ToolResult
	// IsRequired 这个 server 是不是强依赖：连不上时让这一轮报错，而不是跳过？
	IsRequired() bool
	// GetInfo 返回连接此刻的情况；还没连上时也立刻返回。
	GetInfo() ConnectionInfo
}

type ConnectionInfo struct {
	ServerID string          `json:"server_id"`
	State    ConnectionState `json:"state"`
	Required bool            `json:"required"`
	// Tools 是 server 当前提供的工具（已按 ToolNames 过滤）；没连上时为空。
	Tools []ConnectionTool `json:"tools"`
	// Error 是最近一次连接失败或断开的原因；连上后清空。
	Error string `json:"error,omitempty"`
	// PluginName 是声明这个 server 的插件名；不是插件声明的为空。
	PluginName string `json:"plugin_name,omitempty"`
}

type ConnectionOpt struct {
	Definition *ServerDefinition
	// Workspace 是运行位置：stdio 用 StartProcess 启动，http、sse 用 Dial 连接。
	Workspace workspace.Workspace
	// Transport 是客户端 MCP 用的消息转发传输（RelayTransport）：MCP 消息经客户端连接转发给客户端侧的 MCP server。
	Transport mcp.Transport
}

type ConnectionState string

type ConnectionTool struct {
	// Name 是模型看到的名字 mcp__<server id>__<原名>：非法字符换成下划线，替换后重名或超过 64 字符时改用带哈希的名字。
	Name string `json:"name"`
	// OriginalName 是 server 里的原名。
	OriginalName string          `json:"original_name"`
	Description  string          `json:"description,omitempty"`
	InputSchema  json.RawMessage `json:"input_schema"`
}

type RelaySender interface {
	// SendMCPConnect 请求客户端为 streamID 连接指定 server。
	SendMCPConnect(streamID, serverID string) error
	// SendMCPMessage 向客户端发送流上的完整 JSON-RPC 消息。
	SendMCPMessage(streamID string, message json.RawMessage) error
	// SendMCPDisconnect 请求客户端断开指定流。
	SendMCPDisconnect(streamID string) error
}

type RelayTransport interface {
	mcp.Transport
	// DeliverMessage 交付客户端在 streamID 这条流上发来的一条完整 JSON-RPC 消息，直到 MCP SDK 读走它或这条流结束才返回，
	// 同一条流按到达顺序交付消息，流不存在或已结束时丢弃。
	DeliverMessage(streamID string, message json.RawMessage)
	// DeliverClosed 告知客户端已结束 streamID 这条流：MCP SDK 的读取随之以 err 结束，err 为 nil 表示正常结束。
	// 流不存在或已结束时丢弃。
	DeliverClosed(streamID string, err error)
}

type RelayTransportOpt struct {
	// ServerID 是客户端登记的 MCP server id，每次连接都带给客户端，让它找到对应的配置。
	ServerID string
	// Sender 把消息发给客户端。
	Sender RelaySender
}

type ServerDefinition struct {
	ID      string
	Type    ServerTransportType
	Command string
	Args    []string
	Env     map[string]string
	URL     string
	Headers map[string]string
	// ExecutorIDs 是在哪些 Executor 上运行；客户端 MCP 为空。
	ExecutorIDs []string
	// ToolNames 是提供给模型的工具原名；nil 表示全部。
	ToolNames []string
	// Required 是否强依赖？连不上时让这一轮报错，而不是跳过。
	Required bool
	// StartupTimeout 是一次连接（启动、握手、读工具列表）最多等多久。
	StartupTimeout time.Duration
	// ToolTimeout 是一次工具调用最多等多久。
	ToolTimeout time.Duration
	// Plugin 是声明这个 server 的插件，只读；其他来源为 nil。plugin update 会改 InstalledAt，reload 时这个 server 随之重启。
	Plugin *defs.Plugin
}

type ServerTransportType string