mcp

type Catalog struct {
	// Server 所属 server 名（空 = 跨 server 聚合）。
	Server string
	// Tools 工具名清单（已去重、已排序）。
	Tools []string
}

type CatalogDiff struct {
	// Missing 声明了但实际没有（expected - actual）——「我以为有的其实没有」。
	Missing []string
	// Extra 实际有但没声明（actual - expected）——「多出来的、没走授权面」。
	Extra []string
}

type ClassifiedError struct {
	Kind ErrorKind
	Err  error
}

type ErrorKind int

type Health struct {
	// State 三态结论。
	State HealthState
	// Servers 参与聚合的 server 名（排序）。
	Servers []string
	// Issues 问题清单（按 server → tool 排序）。
	Issues []HealthIssue
	// Total 参与聚合的 server 数。
	Total int
	// HealthyCount 完全健康的 server 数。
	HealthyCount int
	// DegradedCount 降级的 server 数。
	DegradedCount int
	// DownCount 不可达的 server 数。
	DownCount int
}

type HealthIssue struct {
	// Server 出问题的 server 名（空 = 跨 server 汇总项）。
	Server string
	// Tool 出问题的工具名（空 = server 级问题，如连不上）。
	Tool string
	// Kind 错误分类。
	Kind ErrorKind
	// Reason 人类可读原因。
	Reason string
}

type HealthState string

type OAuthClientConfig struct {
	ClientID     string // 空=依赖 IdP DCR（handler.RegisterClient 由调用方驱动）
	ClientSecret string
	Scopes       []string
	MetadataURL  string // 空=从 base URL .well-known 发现
	RedirectURI  string // 授权回调落点（无头服务端=固定平台端点）
	TokenStore   client.TokenStore
}

type OutputSchemer interface {
	OutputSchema() json.RawMessage
}

type Pool struct {

	// OnError 建连/列举失败回调（nil 安全）。返回错误不中断其余 server——
	// 部分失败容忍：可用的工具照常返回，失败的 server 由调用方经钩子观测。
	OnError func(server string, err error)
	// RequestMeta 每笔工具调用 _meta 注入来源（nil 安全；批次五十六 B，对标 ZCode
	// request-context）。metaFn 在调用方 ctx 上取值，池不感知业务键；经 metaClient
	// 装饰器注入 req.Params.Meta（见 meta.go）。返回 nil/空 = 不注入。
	RequestMeta func(ctx context.Context) map[string]any
	// Elicitation server→client 征集输入处理器（mcp-go v1.1 SEP-2322）：工具执行中
	// server 反向请求补充输入（表单/URL 模式）时回调；nil 时该类请求得到
	// "no elicitation handler configured" 错误（调用失败呈现，与不声明能力的服务端
	// 行为一致）。池级单点——建连/自愈 redial/Initialize 能力声明共用。
	ElicitationHandler client.ElicitationHandler
	// contains filtered or unexported fields
}

type SelfcheckOptions struct {
	// Server server 名（结果标识 + 缓存键）。
	Server string
	// Timeout 单次探测的超时预算（默认 10s）。
	Timeout time.Duration
	// TTL 目录缓存有效期（默认 30s）。<= 0 表示不缓存（每次都实拉）。
	//
	// 为什么需要缓存：自检是「高频拉目录」的动作，而 MCP 侧的工具目录
	// 在连接生命周期内视为静态（见 catalog.go）。没有 TTL 时，每次探活
	// 都会打一轮 tools/list —— 部署机的巡检会把 server 压垮。
	TTL time.Duration
	// ProbeTools 是否逐工具做一次**调用**探测（默认 false）。
	//
	// true = 每个工具都真调一次（最彻底，但有副作用：会真的执行工具）。
	// 默认 false = 只探连通性 + 拉目录（无副作用）。
	// 工具「存在但调不通」这种情形，用 tools/call 探针单点确认（见 ProbeTool）。
	ProbeTools bool
	// ProbeArgs 逐工具探测时的参数（nil = 用空对象）。
	ProbeArgs map[string]any
	// Initialize 是否在自检前先发 initialize 握手。
	//
	// 默认 false：调用方通常传**已建连**的 client（Pool 的 client 都已
	// 握手过）。但若传的是裸 client（未 initialize），协议请求会返回
	// "client not initialized"——那时自检会误判成 server 不可达。
	// 自检是「诊断工具」，不该因为握手缺失而给出错误结论，
	// 所以提供这个开关。
	Initialize bool
	// Expected 声明期望的工具面（可选）。
	//
	// 给了它，自检会逐个核：这���工具在不在 server 目录里、在但调不通。
	// 这是「装包≠开洞」这类治理规则的输入——只有把声明面与实际面对照，
	// 才能发现「我以为有的工具其实没有」。
	Expected Catalog
}

type SelfcheckResult struct {
	// Server server 名。
	Server string
	// Reachable 连通性（server 能否应答协议请求）。
	Reachable bool
	// Tools 逐工具结果（按工具名排序）。
	Tools []ToolCheck
	// Catalog server 实际提供的工具目录（连通时有效）。
	Catalog Catalog
	// Expected 声明期望的工具面（可选，供差集比对）。
	Expected Catalog
	// Diff 期望 vs 实际的差集（Expected 非空时有效）。
	Diff CatalogDiff
	// PingErr ping 探测的错误（**不代表不可达**——server 可能没实现 ping；
	// 真正的连通性判据是列举成功）。留在这里供诊断。
	PingErr error
	// Kind 整体失败的错误分类（Reachable==false 时有效）。
	Kind ErrorKind
	// Err 整体失败的原始错误。
	Err error
	// Cached 本次结果是否来自 TTL 缓存。
	Cached bool
	// At 探测时刻。
	At time.Time
}

type Selfchecker struct {
	// contains filtered or unexported fields
}

type ServerConfig struct {
	// Name 逻辑名：ToolSpec.Server 引用。
	Name string
	// Command stdio 传输：可执行 + 参数（子进程由本包启动与回收）。
	Command []string
	// Env stdio 子进程环境白名单：条目为纯变量名（如 "GITHUB_TOKEN"）时按名从
	// 当前进程透传；含 "=" 时按 KEY=VALUE 字面透传。未列出的变量一律不继承
	// （基础集见 procx.ChildEnv），防止本进程密钥泄漏给外部 MCP server。
	Env []string
	// URL HTTP 传输（streamable http）。
	URL string
	// Headers HTTP 请求头（如 Bearer 鉴权）。
	Headers map[string]string
	// Timeout 连接 + Initialize 超时（默认 30s）。仅作用于建连期（dial +
	// Initialize 的 ctx 预算），不约束后续请求——HTTP 传输的每请求兜底见
	// RequestTimeout。
	Timeout time.Duration
	// RequestTimeout HTTP 传输的单请求兜底上限（默认 10 分钟）。mcp-go 的
	// WithHTTPTimeout 直接设 httpClient.Timeout、作用于该连接的每一次请求
	// （含 tools/call）——此前误用连接级 Timeout（30s）会让任何长工具调用
	// 在 HTTP 传输下永远失败（v0.10.29 审计修复）；工具调用的正常时长控制
	// 归调用方 ctx，这里只是挂死兜底。stdio 不受影响。
	RequestTimeout time.Duration
	// ProbeTimeout 探活（PingServer）独立预算（默认 5s；租约面 lease.go——
	// 探活是轻量协议 ping，不该吃连接级 30s 预算）。
	ProbeTimeout time.Duration
	// OAuth URL 模式 OAuth2 客户端配置（批次五十六 C，对标 ZCode oauth 全栈；
	// 仅 URL 传输生效）。非 nil 时 dial 走 NewOAuthStreamableHttpClient——401 触发
	// client.OAuthAuthorizationRequiredError（errors.As 可穿透池的 %w 包装），
	// 调用方经 client.GetOAuthHandler 取 handler 驱动授权码+PKCE 流程；
	// TokenStore 由调用方提供（进程内缓存失效后重 dial 仍能取回已授权 token）。
	OAuth *OAuthClientConfig
}

type ToolCheck struct {
	// Tool 工具名。
	Tool string
	// Status 状态。
	Status ToolStatus
	// Kind 失败时的错误分类（Status==ToolOK 时为 KindUnknown）。
	Kind ErrorKind
	// Reason 人类可读的失败原因（Status==ToolOK 时为空）。
	Reason string
	// Err 原始错误（供 errors.Is/As 穿透）。
	Err error
}

type ToolHints struct {
	ReadOnly    bool
	Idempotent  bool
	Destructive bool
}

type ToolResultError struct {
	// contains filtered or unexported fields
}

type ToolSpec struct {
	// Server ServerConfig.Name。
	Server string
	// Allow 工具名白名单。
	//
	// ⚠️ **破坏式变更**（v0.9.0）：**空 = 不授予任何工具**（缺省拒绝）。
	// 此前空 = 该 server 的**全部**工具——而这个默认值在配置里**不可见**：
	// 一份 `allow: []` 看起来像「没限制」，实际是把该 server 的全部工具
	// （含删除/执行类破坏性工具）都授予了模型，最小权限的责任整个落到了下游
	// （下游只能靠事后门禁兜——那时配置已生效、模型已拿到工具）。
	//
	// 要「全给」必须**显式**写：AllowAll: true，或 Allow 里含 "*"。
	Allow []string
	// AllowAll 显式授予该 server 的全部工具（缺省拒绝的对立面，必须写在配置里）。
	//
	// 与 Allow 里的 "*" 等价；同时存在时以本字段为准（Allow 被忽略）。
	AllowAll bool
}

type ToolStatus string

type ToolsResult struct {
	// Tools 装配成功的工具（跨 server 并行拉取，按 specs 序稳定）。
	//
	// ⚠️ 这是**跨 server 的扁平列表**：拿到的工具没有「它来自哪个 server」的
	// 结构化归属（工具名虽带 server 命名空间，但那是模型侧的名字，不是归属面）。
	// 要按 server 取用走 ByServer；要按 server+名字取单个走 Pool.Tool。
	Tools []tool.BaseTool
	// ByServer server → 该 server 装配出的工具（按目录序）。
	//
	// 它是「工具归属」的结构化面——不让调用方靠位置假设（res.Tools[0]）去猜
	// 某个工具来自哪个 server。空 = 没有工具。
	ByServer map[string][]tool.BaseTool
	// Failed server → 被容忍的失败原因（建连/列举失败、白名单无一命中）。
	// 失败连接已摘除，下次调用透明重建。空 = 全部成功。OnError 仍发射同源
	// 通知（遥测钩子），失败面的程序化消费一律走这里。
	Failed map[string]error
}