// Package kit 是 fwh-agent-mcp 的工具框架：工具定义、参数辅助、统一结果与中间件。
//
// 设计见 docs/ai-assistant-agentserver/agent-mcp.md 第 3 节。工具不感知调用者：
// 没有 userId / sessionId 参数，也不记录调用人。
package kit

import (
	"context"
	"strings"

	"github.com/mark3labs/mcp-go/mcp"
	"github.com/mark3labs/mcp-go/server"
)

// Meta 工具的静态信息，供注册表与约束测试使用。
type Meta struct {
	Name        string
	Title       string
	Description string
	ReadOnly    bool
}

// IsExport 导出类工具（*_export）使用更长的超时并以 CSV 资源返回。
func (m Meta) IsExport() bool {
	return strings.HasSuffix(m.Name, "_export")
}

// Registrar 可注册到 MCPServer 的工具。
type Registrar interface {
	Meta() Meta
	Tool() mcp.Tool
	Register(s *server.MCPServer)
}

// Def 一个类型化工具的定义。T 为参数结构体，schema 由 mcp.WithInputSchema[T] 生成：
// `jsonschema:"..."` 标签即字段描述，没有 omitempty 的字段为必填；枚举与取值范围写进描述并在 Handler 中校验。
type Def[T any] struct {
	Name        string // <领域>_<动作>，小写下划线，≤ 40 字符
	Title       string // 中文短标题（审批卡片与后台显示）
	Description string // 用途、适用场景、返回字段与单位
	ReadOnly    bool
	Handler     func(ctx context.Context, args T) (*mcp.CallToolResult, error)
}

func (d Def[T]) Meta() Meta {
	return Meta{Name: d.Name, Title: d.Title, Description: d.Description, ReadOnly: d.ReadOnly}
}

func (d Def[T]) Tool() mcp.Tool {
	return mcp.NewTool(d.Name,
		mcp.WithDescription(d.Description),
		mcp.WithInputSchema[T](),
		mcp.WithTitleAnnotation(d.Title),
		mcp.WithReadOnlyHintAnnotation(d.ReadOnly),
		mcp.WithDestructiveHintAnnotation(false),
		mcp.WithIdempotentHintAnnotation(d.ReadOnly),
		mcp.WithOpenWorldHintAnnotation(false),
	)
}

func (d Def[T]) Register(s *server.MCPServer) {
	s.AddTool(d.Tool(), mcp.NewTypedToolHandler(func(ctx context.Context, _ mcp.CallToolRequest, args T) (*mcp.CallToolResult, error) {
		return d.Handler(ctx, args)
	}))
}

// NoArgs 无参数工具的参数类型。
type NoArgs struct{}