client

type BatchError struct {
	// Code is the JSON-RPC error code
	Code int `json:"code"`

	// Message is a human-readable error message
	Message string `json:"message"`

	// Data contains additional error information
	Data interface{} `json:"data,omitempty"`
}

type BatchRequest struct {
	// Method is the JSON-RPC method to call (e.g., "tools/call", "resources/read")
	Method string `json:"method"`

	// Params contains the parameters for the method call
	Params map[string]interface{} `json:"params,omitempty"`

	// ID is the request identifier. If nil, this is treated as a notification.
	// Notifications do not generate responses.
	ID interface{} `json:"id,omitempty"`
}

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

type BatchResponse struct {
	// ID is the request identifier that this response corresponds to
	ID interface{} `json:"id"`

	// Result contains the successful result of the method call
	Result interface{} `json:"result,omitempty"`

	// Error contains error information if the method call failed
	Error *BatchError `json:"error,omitempty"`
}

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",
	//  })
	//
	// For timeout support:
	//  result, err := client.CallTool("translate", map[string]interface{}{
	//      "text": "Hello world",
	//      "target_language": "Spanish",
	//  }, client.WithRequestTimeoutOption(10*time.Second))
	CallTool(name string, args map[string]interface{}, opts ...RequestOption) (interface{}, error)

	// GetResource retrieves a resource from the server.
	//
	// The path parameter specifies the resource URI to retrieve.
	//
	// Example:
	//  resource, err := client.GetResource("/files/readme.txt")
	//
	// For timeout support:
	//  resource, err := client.GetResource("/files/readme.txt",
	//      client.WithRequestTimeoutOption(5*time.Second))
	GetResource(path string, opts ...RequestOption) (interface{}, error)

	// GetPrompt retrieves a prompt from the server.
	//
	// The name parameter specifies the prompt to retrieve. The variables parameter
	// contains any variables to substitute in the prompt template.
	//
	// Example:
	//  prompt, err := client.GetPrompt("greeting", map[string]interface{}{
	//      "name": "Alice",
	//  })
	//
	// For timeout support:
	//  prompt, err := client.GetPrompt("greeting", map[string]interface{}{
	//      "name": "Alice",
	//  }, client.WithRequestTimeoutOption(3*time.Second))
	GetPrompt(name string, variables map[string]interface{}, opts ...RequestOption) (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)

	// ListTools retrieves the list of available tools from the server.
	//
	// This method calls the tools/list endpoint as specified in the MCP protocol.
	// It automatically handles pagination internally and returns all available tools.
	// The returned slice contains all available tools with their names, descriptions,
	// and input schemas, which can be used for tool discovery and proxy patterns.
	//
	// Example:
	//  tools, err := client.ListTools()
	//  for _, tool := range tools {
	//      fmt.Printf("Tool: %s - %s\n", tool.Name, tool.Description)
	//      fmt.Printf("Schema: %+v\n", tool.InputSchema)
	//  }
	ListTools() ([]Tool, 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

	// Events returns the events subject for subscribing to client events.
	//
	// This provides access to the event system for monitoring client lifecycle,
	// errors, and other significant events. Subscribers can listen for specific
	// event types such as initialization, connection changes, and errors.
	//
	// Example:
	//  events := client.Events()
	//  events.Subscribe(events.TopicClientError, func(event events.ClientErrorEvent) {
	//      log.Printf("Client error: %s", event.Error)
	//  })
	Events() *events.Subject

	// RequestSampling initiates a sampling request to the server.
	//
	// This is the unified method for all sampling operations, supporting both
	// regular and streaming modes through options configuration.
	//
	// Example:
	//  opts := client.NewSamplingOptions(messages, prefs).
	//      WithSystemPrompt("You are a helpful assistant").
	//      WithMaxTokens(1000)
	//  response, err := client.RequestSampling(opts)
	//
	// For streaming (protocol version 2025-03-26 only):
	//  opts := client.NewSamplingOptions(messages, prefs).
	//      WithStreaming(func(chunk *SamplingResponse) error {
	//          fmt.Printf("Received chunk: %s\n", chunk.Content.Text)
	//          return nil
	//      })
	//  response, err := client.RequestSampling(opts)
	RequestSampling(opts *SamplingOptions) (*SamplingResponse, error)

	// SendBatch sends multiple requests to the server in a single batch operation.
	//
	// This method implements JSON-RPC 2.0 batch requests, allowing multiple operations
	// to be sent together for improved efficiency. The requests parameter contains
	// the individual requests to include in the batch.
	//
	// The method returns a slice of BatchResponse objects, where each response
	// corresponds to a request in the batch (excluding notifications). The order
	// of responses matches the order of requests.
	//
	// Example:
	//  requests := []BatchRequest{
	//      {Method: "tools/call", Params: map[string]interface{}{"name": "calculator", "arguments": map[string]interface{}{"op": "add", "a": 1, "b": 2}}},
	//      {Method: "resources/read", Params: map[string]interface{}{"uri": "/config.json"}},
	//      {Method: "prompts/get", Params: map[string]interface{}{"name": "greeting", "arguments": map[string]interface{}{"name": "Alice"}}},
	//  }
	//  responses, err := client.SendBatch(requests)
	//  for i, response := range responses {
	//      if response.Error != nil {
	//          fmt.Printf("Request %d failed: %v\n", i, response.Error)
	//      } else {
	//          fmt.Printf("Request %d result: %v\n", i, response.Result)
	//      }
	//  }
	//
	// For timeout support:
	//  responses, err := client.SendBatch(requests, client.WithRequestTimeoutOption(30*time.Second))
	SendBatch(requests []BatchRequest, opts ...RequestOption) ([]BatchResponse, error)

	// BatchBuilder creates a new batch builder for constructing batch requests.
	//
	// The batch builder provides a fluent interface for adding multiple requests
	// to a batch operation. Use AddRequest to add individual requests.
	//
	// Example:
	//  responses, err := client.BatchBuilder().
	//      AddRequest("tools/call", map[string]interface{}{
	//          "name": "calculator",
	//          "arguments": map[string]interface{}{"op": "add", "a": 1, "b": 2}
	//      }, 1).
	//      AddRequest("resources/read", map[string]interface{}{"uri": "/config.json"}, 2).
	//      AddRequest("prompts/get", map[string]interface{}{
	//          "name": "greeting",
	//          "arguments": map[string]interface{}{"name": "Alice"}
	//      }, 3).
	//      Execute()
	BatchBuilder() *BatchRequestBuilder
}

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

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

type HTTPOption func(*httpConfig)

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

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

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

type MQTTTransportOption func(*MQTTTransport)

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

type NATSTransportOption func(*NATSTransport)

type Option func(*clientImpl)

type RequestOption interface {
	// contains filtered or unexported methods
}

type RequestOptions struct {
	// Timeout specifies the timeout for this specific request
	// If not set, uses the client's default timeout
	Timeout *time.Duration

	// MaxTimeout specifies the maximum timeout regardless of progress notifications
	// If not set, uses 2x the regular timeout as the maximum
	MaxTimeout *time.Duration

	// AllowProgressReset indicates whether progress notifications should reset the timeout clock
	// Default is true as per MCP specification
	AllowProgressReset bool
}

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 SSETransport struct {
	// contains filtered or unexported fields
}

type SamplingCreateMessageParams struct {
	Messages         []SamplingMessage        `json:"messages"`
	ModelPreferences SamplingModelPreferences `json:"modelPreferences"`
	SystemPrompt     string                   `json:"systemPrompt,omitempty"`
	MaxTokens        int                      `json:"maxTokens,omitempty"`
}

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 SamplingOptions struct {
	// Core request parameters
	Messages         []SamplingMessage
	ModelPreferences SamplingModelPreferences
	SystemPrompt     string
	MaxTokens        int

	// Request configuration
	Context         context.Context
	Timeout         time.Duration
	ProtocolVersion string

	// Streaming options (only for protocol version 2025-03-26)
	Streaming      bool
	StreamHandler  func(*SamplingResponse) error // Called for each chunk when streaming
	ChunkSize      int                           // Maximum size of text chunks
	MaxChunks      int                           // Maximum number of chunks (0 for unlimited)
	StopOnComplete bool                          // Stop streaming when isComplete=true

	// Retry configuration
	MaxRetries      int
	RetryInterval   time.Duration
	RetryMultiplier float64
	MaxInterval     time.Duration
}

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

	// Streaming fields
	IsComplete bool `json:"isComplete,omitempty"` // Only for streaming responses
	ChunkIndex int  `json:"chunkIndex,omitempty"` // Only for streaming responses
}

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 StdioOption func(*stdioConfig)

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

type TimeoutOption struct {
	Duration time.Duration
}

type Tool = mcp.Tool

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))
}

type UDPOption func(*udpConfig)

type UnixSocketOption func(*unixConfig)

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