client

type AudioSamplingContent struct {
	Data     string
	MimeType string
}

type Client interface {
	// CallTool invokes a tool on the connected MCP server.
	//
	// The name parameter specifies the tool to call. The args parameter contains
	// the arguments to pass to the tool as key-value pairs. The returned interface{}
	// contains the tool's output, which can be any JSON-serializable value.
	//
	// Example:
	//  result, err := client.CallTool("translate", map[string]interface{}{
	//      "text": "Hello world",
	//      "target_language": "Spanish",
	//  })
	CallTool(name string, args map[string]interface{}) (interface{}, error)

	// GetResource retrieves a resource from the server by its path.
	//
	// The path parameter specifies the resource to retrieve. The returned interface{}
	// contains the resource content, which can be any JSON-serializable value.
	//
	// Example:
	//  resource, err := client.GetResource("/users/123")
	GetResource(path string) (interface{}, error)

	// GetPrompt retrieves and renders a prompt from the server.
	//
	// The name parameter specifies the prompt to render. The variables parameter
	// contains the variables to substitute in the prompt template.
	//
	// Example:
	//  prompt, err := client.GetPrompt("greeting", map[string]interface{}{
	//      "name": "Alice",
	//      "time_of_day": "morning",
	//  })
	GetPrompt(name string, variables map[string]interface{}) (interface{}, error)

	// GetRoot retrieves the root resource from the server.
	//
	// This is a convenience method equivalent to calling GetResource("/").
	//
	// Example:
	//  root, err := client.GetRoot()
	GetRoot() (interface{}, error)

	// Close closes the client connection to the server and releases all resources.
	//
	// After calling Close, the client cannot be used for further operations.
	// It is good practice to defer this call after creating a client.
	//
	// Example:
	//  client, err := client.NewClient("my-client")
	//  if err != nil {
	//      log.Fatal(err)
	//  }
	//  defer client.Close()
	Close() error

	// AddRoot registers a new root endpoint with the server.
	//
	// The uri parameter specifies the path of the root. The name parameter
	// provides a human-readable name for the root.
	//
	// Example:
	//  err := client.AddRoot("/api/v2", "API Version 2")
	AddRoot(uri string, name string) error

	// RemoveRoot unregisters a root endpoint from the server.
	//
	// The uri parameter specifies the path of the root to remove.
	//
	// Example:
	//  err := client.RemoveRoot("/api/v1")
	RemoveRoot(uri string) error

	// GetRoots retrieves the list of root endpoints from the server.
	//
	// The returned slice contains all registered roots with their URIs and names.
	//
	// Example:
	//  roots, err := client.GetRoots()
	//  for _, root := range roots {
	//      fmt.Printf("Root: %s (%s)\n", root.URI, root.Name)
	//  }
	GetRoots() ([]Root, error)

	// Version returns the negotiated protocol version with the server.
	//
	// This returns one of the standardized version strings: "draft", "2024-11-05",
	// or "2025-03-26".
	//
	// Example:
	//  version := client.Version()
	//  fmt.Printf("Connected using MCP protocol version %s\n", version)
	Version() string

	// IsInitialized returns whether the client has been initialized.
	//
	// Initialization occurs during the first operation that requires
	// server communication.
	IsInitialized() bool

	// IsConnected returns whether the client is currently connected to the server.
	//
	// Example:
	//  if client.IsConnected() {
	//      fmt.Println("Client is connected to the server")
	//  } else {
	//      fmt.Println("Client is not connected")
	//  }
	IsConnected() bool

	// WithSamplingHandler registers a handler for sampling requests.
	//
	// The handler will be called when the server requests sampling (e.g., for LLM interactions).
	// Returns the client instance for method chaining.
	//
	// Example:
	//  client = client.WithSamplingHandler(func(params SamplingCreateMessageParams) (SamplingResponse, error) {
	//      // Process sampling request
	//      return SamplingResponse{...}, nil
	//  })
	WithSamplingHandler(handler SamplingHandler) Client

	// GetSamplingHandler returns the currently registered sampling handler.
	GetSamplingHandler() SamplingHandler

	// RequestSampling initiates a sampling request to the server.
	//
	// This is typically used by advanced clients that need to request
	// sampling capabilities from the server.
	RequestSampling(req *SamplingRequest) (*SamplingResponse, error)

	// RequestStreamingSampling initiates a streaming sampling request to the server.
	//
	// The streaming API is available only in protocol version 2025-03-26 and later.
	// The handler is called for each chunk of the streaming response.
	RequestStreamingSampling(req *StreamingSamplingRequest, handler StreamingResponseHandler) (*StreamingSamplingSession, error)
}

type ClientCapabilities struct {
	Roots        RootsCapability        `json:"roots,omitempty"`
	Sampling     map[string]interface{} `json:"sampling,omitempty"`
	Experimental map[string]interface{} `json:"experimental,omitempty"`
}

type ContentSizeAnalyzer struct {
	// Constants for size limitations
	MaxTextBytes     int
	MaxImageBytes    int
	MaxAudioBytes    int
	WarningThreshold float64 // 0.0-1.0 percentage of max before warning
}

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

type ImageSamplingContent struct {
	Data     string
	MimeType string
}

type MCPServer struct {
	Name   string
	Client Client
	// contains filtered or unexported fields
}

type Option func(*clientImpl)

type RetryConfig struct {
	MaxRetries      int
	RetryInterval   time.Duration
	RetryMultiplier float64 // For exponential backoff
	MaxInterval     time.Duration
}

type Root struct {
	URI      string                 `json:"uri"`
	Name     string                 `json:"name,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type RootsCapability struct {
	ListChanged bool `json:"listChanged"`
}

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

type SamplingChunk struct {
	Content SamplingMessageContent `json:"content"`
}

type SamplingCompletion struct {
	Model      string `json:"model,omitempty"`
	StopReason string `json:"stopReason,omitempty"`
}

type SamplingConfig struct {
	// Protocol specific parameters
	MaxTokens             int             // Maximum tokens to generate
	MaxSystemPrompt       int             // Maximum allowed system prompt length
	SupportedContentTypes map[string]bool // Map of supported content types
	ProtocolVersion       string          // The protocol version this config is for

	// Timeout and retry settings
	RequestTimeout time.Duration
	RetryConfig    RetryConfig

	// Streaming settings
	StreamingSupported bool
	MinChunkSize       int
	MaxChunkSize       int
	DefaultChunkSize   int

	// Model configuration
	ModelNameMaxLength int
}

type SamplingContentHandler interface {
	ToMessageContent() SamplingMessageContent
	Validate() error
}

type SamplingCreateMessageParams struct {
	Messages         []SamplingMessage        `json:"messages"`
	ModelPreferences SamplingModelPreferences `json:"modelPreferences"`
	SystemPrompt     string                   `json:"systemPrompt,omitempty"`
	MaxTokens        int                      `json:"maxTokens,omitempty"`
	ProtocolVersion  string                   `json:"-"` // Internal field for version tracking
}

type SamplingError struct {
	ErrorType        string // Category of error (network, parsing, validation, server)
	Message          string
	RetryRecommended bool
	OriginalError    error
}

type SamplingHandler func(params SamplingCreateMessageParams) (SamplingResponse, error)

type SamplingMessage struct {
	Role    string                 `json:"role"`
	Content SamplingMessageContent `json:"content"`
}

type SamplingMessageContent struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mimeType,omitempty"`
}

type SamplingModelHint struct {
	Name string `json:"name"`
}

type SamplingModelPreferences struct {
	Hints                []SamplingModelHint `json:"hints,omitempty"`
	CostPriority         *float64            `json:"costPriority,omitempty"`
	SpeedPriority        *float64            `json:"speedPriority,omitempty"`
	IntelligencePriority *float64            `json:"intelligencePriority,omitempty"`
}

type SamplingOptimizationOptions struct {
	CacheCapacity int
	CacheTTL      time.Duration
	LogWarnings   bool
	MaxTextBytes  int
	MaxImageBytes int
	MaxAudioBytes int
	ImageMaxDim   int
	ImageQuality  int
}

type SamplingPerformanceMetrics struct {
	RequestCount      int64         // Total requests sent
	SuccessCount      int64         // Successful requests
	ErrorCount        int64         // Failed requests
	TotalResponseTime time.Duration // Total time spent on responses
	MaxResponseTime   time.Duration // Maximum response time
	MinResponseTime   time.Duration // Minimum response time
	CacheHits         int64         // Number of cache hits
	CacheMisses       int64         // Number of cache misses
	BytesSent         int64         // Total bytes sent
	BytesReceived     int64         // Total bytes received
	// contains filtered or unexported fields
}

type SamplingRequest struct {
	// Core request parameters
	Messages         []SamplingMessage
	ModelPreferences SamplingModelPreferences
	SystemPrompt     string
	MaxTokens        int

	// Context and options
	Context              context.Context
	Timeout              time.Duration
	RetryConfig          RetryConfig
	ProtocolVersion      string
	FormatAsNotification bool
}

type SamplingResponse struct {
	Role       string                 `json:"role"`
	Content    SamplingMessageContent `json:"content"`
	Model      string                 `json:"model,omitempty"`
	StopReason string                 `json:"stopReason,omitempty"`
}

type SamplingResponseError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    string `json:"data,omitempty"`
}

type ServerConfig struct {
	MCPServers map[string]ServerDefinition `json:"mcpServers"`
}

type ServerDefinition struct {
	Command string            `json:"command"`
	Args    []string          `json:"args"`
	Env     map[string]string `json:"env,omitempty"`
	URL     string            `json:"url,omitempty"`
}

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

type StreamingResponseHandler func(response *StreamingSamplingResponse) error

type StreamingSamplingRequest struct {
	// Base sampling request
	SamplingRequest

	// Streaming-specific options
	ChunkSize      int  // Maximum size of text chunks (applicable for text streaming)
	MaxChunks      int  // Maximum number of chunks to receive (0 for unlimited)
	StopOnComplete bool // Whether to stop streaming when isComplete=true is received
}

type StreamingSamplingResponse struct {
	// Base response fields
	Role       string                 `json:"role"`
	Content    SamplingMessageContent `json:"content"`
	Model      string                 `json:"model,omitempty"`
	StopReason string                 `json:"stopReason,omitempty"`

	// Streaming-specific fields
	IsComplete bool   `json:"isComplete"`
	ChunkID    string `json:"chunkId,omitempty"`
}

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

type TextSamplingContent struct {
	Text string
}

type Transport interface {
	// Connect establishes a connection to the server.
	Connect() error

	// ConnectWithContext establishes a connection to the server with context for timeout/cancellation.
	ConnectWithContext(ctx context.Context) error

	// Disconnect closes the connection to the server.
	Disconnect() error

	// Send sends a message to the server and waits for a response.
	Send(message []byte) ([]byte, error)

	// SendWithContext sends a message with context for timeout/cancellation.
	SendWithContext(ctx context.Context, message []byte) ([]byte, error)

	// SetRequestTimeout sets the default timeout for request operations.
	SetRequestTimeout(timeout time.Duration)

	// SetConnectionTimeout sets the default timeout for connection operations.
	SetConnectionTimeout(timeout time.Duration)

	// RegisterNotificationHandler registers a handler for server-initiated messages.
	RegisterNotificationHandler(handler func(method string, params []byte))
}