server

type AudioResource struct {
	// URL is the URL of the audio file. Required for all versions.
	URL string
	// Data is the base64-encoded audio data. Used in 2025-03-26 version.
	Data string
	// MimeType is the MIME type of the audio file. Required for all versions.
	MimeType string
	// AltText is an optional descriptive text for the audio
	AltText string
}

type AudioSamplingContent struct {
	Data     string
	MimeType string
}

type ClientInfo struct {
	SamplingSupported bool
	SamplingCaps      SamplingCapabilities
	ProtocolVersion   string
}

type ClientSession struct {
	ID              SessionID         // Unique session identifier
	ClientInfo      ClientInfo        // Information about the client
	Created         time.Time         // When the session was created
	LastActive      time.Time         // Last time the session was active
	ProtocolVersion string            // Negotiated protocol version
	Metadata        map[string]string // Additional session metadata
}

type ContentItem struct {
	Type     string      `json:"type"`
	Text     string      `json:"text,omitempty"`
	ImageURL string      `json:"imageUrl,omitempty"`
	AltText  string      `json:"altText,omitempty"`
	URL      string      `json:"url,omitempty"`
	Title    string      `json:"title,omitempty"`
	Data     interface{} `json:"data,omitempty"`
	MimeType string      `json:"mimeType,omitempty"`
	Filename string      `json:"filename,omitempty"`
	Blob     string      `json:"blob,omitempty"` // Add blob support for MCP Inspector validation
}

type ContentType string

type Context struct {

	// The raw request bytes
	RequestBytes []byte

	// The parsed request
	Request *Request

	// The response to be sent back
	Response *Response

	// Logger for this request
	Logger *slog.Logger

	// Version of the MCP protocol being used
	Version string

	// Request ID for tracing
	RequestID string

	// Metadata for storing contextual information during request processing
	Metadata map[string]interface{}
	// contains filtered or unexported fields
}

type FileResource struct {
	URL      string
	Filename string
	MimeType string
}

type ImageResource struct {
	URL      string
	AltText  string
	MimeType string
}

type ImageSamplingContent struct {
	Data     string
	MimeType string
}

type InvalidParametersError struct {
	Message string
}

type JSONResource struct {
	Data interface{}
}

type LinkResource struct {
	URL   string
	Title string
}

type Option func(*serverImpl)

type Prompt struct {
	Name        string
	Description string
	Templates   []PromptTemplate
	Arguments   []PromptArgument
}

type PromptArgument struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
}

type PromptContent struct {
	Type     ContentType            `json:"type"`
	Text     string                 `json:"text,omitempty"`
	Data     string                 `json:"data,omitempty"`
	MimeType string                 `json:"mimeType,omitempty"`
	Resource map[string]interface{} `json:"resource,omitempty"`
}

type PromptTemplate struct {
	Role    string
	Content string
	// For storing template variables like {{var}}
	Variables []string
}

type ProtocolSamplingConfig struct {
	MaxTokens             int
	SupportedContentTypes map[string]bool
	StreamingSupported    bool
}

type RPCError struct {
	Code    int         `json:"code"`    // Error code
	Message string      `json:"message"` // Error message
	Data    interface{} `json:"data,omitempty"`
}

type Request struct {
	// JSON-RPC 2.0 fields
	JSONRPC string          `json:"jsonrpc"`
	ID      interface{}     `json:"id,omitempty"`     // string or number or null
	Method  string          `json:"method"`           // The method to call
	Params  json.RawMessage `json:"params,omitempty"` // Parameters for the method call

	// Parsed params based on method type
	// These fields are populated after parsing
	ToolName     string
	ToolArgs     map[string]interface{}
	ResourcePath string
	PromptName   string
	PromptArgs   map[string]interface{}
}

type RequestSamplingOptions struct {
	Timeout          time.Duration // Maximum time to wait for a response
	MaxRetries       int           // Maximum number of retry attempts on timeout
	RetryInterval    time.Duration // Time to wait between retries
	IgnoreCapability bool          // Whether to ignore client capability validation
	ForceSession     bool          // Whether to force using the specified session
}

type Resource struct {
	Path        string
	Description string
	Handler     ResourceHandler
	Schema      interface{}
	Template    *wilduri.Template
	IsTemplate  bool // Whether this resource is a template with parameters
}

type ResourceConverter interface {
	ToResourceResponse() map[string]interface{}
}

type ResourceHandler func(ctx *Context, args interface{}) (interface{}, error)

type ResourceResponse struct {
	Content  []ContentItem          `json:"content"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
	IsError  bool                   `json:"isError,omitempty"`
}

type Response struct {
	// JSON-RPC 2.0 fields
	JSONRPC string      `json:"jsonrpc"`
	ID      interface{} `json:"id,omitempty"`     // Must match request ID
	Result  interface{} `json:"result,omitempty"` // Result data, null if error
	Error   *RPCError   `json:"error,omitempty"`  // Error data, null if success
}

type SamplingCapabilities struct {
	Supported    bool
	TextSupport  bool
	ImageSupport bool
	AudioSupport bool
}

type SamplingConfig struct {
	// Rate limiting settings
	MaxRequestsPerMinute  int  // Maximum number of sampling requests per minute
	MaxConcurrentRequests int  // Maximum number of concurrent sampling requests
	MaxTokensPerRequest   int  // Maximum tokens allowed per request
	PerClientRateLimit    bool // Whether to apply rate limits per client

	// Timeout settings
	DefaultTimeout time.Duration // Default timeout for sampling requests
	MaxTimeout     time.Duration // Maximum allowed timeout for sampling requests

	// Retry settings
	DefaultMaxRetries    int           // Default number of retries for failed requests
	DefaultRetryInterval time.Duration // Default interval between retries

	// Priority settings
	EnablePrioritization bool // Whether to enable request prioritization
	DefaultPriority      int  // Default priority for sampling requests (1-10, 10 being highest)

	// Resource allocation
	ResourceQuota map[string]int // Resource quotas for different content types

	// Error handling
	GracefulDegradation bool // Whether to enable graceful degradation on errors

	// Protocol-specific settings
	ProtocolDefaults map[string]*ProtocolSamplingConfig // Protocol-specific settings
}

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

type SamplingController 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 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 SamplingResponse struct {
	Role       string                 `json:"role"`
	Content    SamplingMessageContent `json:"content"`
	Model      string                 `json:"model,omitempty"`
	StopReason string                 `json:"stopReason,omitempty"`
}

type Server interface {
	// Run starts the server and blocks until it exits.
	//
	// This method initializes the server, starts listening for connections,
	// and processes incoming requests. It blocks until the server encounters
	// an error or is explicitly stopped.
	//
	// Example:
	//  if err := server.Run(); err != nil {
	//      log.Fatalf("Server error: %v", err)
	//  }
	Run() error

	// Tool registers a tool with the server.
	//
	// The name parameter is the unique identifier for the tool. The description
	// parameter provides human-readable documentation. The handler parameter is
	// a function that implements the tool's logic.
	//
	// Tool handlers can have one of the following signatures:
	//  func(ctx *Context) (interface{}, error)
	//  func(ctx *Context, args T) (interface{}, error)
	//  func(ctx *Context) error
	//  func(ctx *Context, args T) error
	//
	// Where T is any struct type that can be unmarshaled from JSON. The struct
	// fields should use `json` tags to map to JSON property names.
	//
	// Example:
	//  server.Tool("add", "Add two numbers", func(ctx *server.Context, args struct {
	//      X float64 `json:"x" required:"true"`
	//      Y float64 `json:"y" required:"true"`
	//  }) (float64, error) {
	//      return args.X + args.Y, nil
	//  })
	Tool(name string, description string, handler interface{}) Server

	// WithAnnotations adds annotations to a tool.
	//
	// Annotations provide additional metadata about a tool, such as examples,
	// parameter descriptions, or usage notes.
	//
	// Example:
	//  server.Tool("greet", "Greet a user", greetHandler).
	//      WithAnnotations("greet", map[string]interface{}{
	//          "examples": []map[string]interface{}{
	//              {
	//                  "description": "Greet a user by name",
	//                  "args": map[string]interface{}{
	//                      "name": "Alice",
	//                  },
	//              },
	//          },
	//      })
	WithAnnotations(toolName string, annotations map[string]interface{}) Server

	// Resource registers a resource with the server.
	//
	// The path parameter defines the resource path, which can include path
	// parameters in the format {paramName}. The description parameter provides
	// human-readable documentation. The handler parameter is a function that
	// implements the resource's logic.
	//
	// Example:
	//  server.Resource("/users/{id}", "Get user information", func(ctx *server.Context, params struct {
	//      ID string `path:"id"`
	//  }) (interface{}, error) {
	//      return getUserById(params.ID)
	//  })
	Resource(path string, description string, handler interface{}) Server

	// Prompt registers a prompt with the server.
	//
	// The name parameter is the unique identifier for the prompt. The description
	// parameter provides human-readable documentation. The template parameters
	// define the prompt template and can be either a string or a function that
	// generates the template.
	//
	// Example:
	//  server.Prompt("greeting", "Greeting template",
	//      "Hello, {{name}}! Welcome to {{service}}.")
	Prompt(name string, description string, template ...interface{}) Server

	// Root sets the allowed root paths.
	//
	// Root paths are the entry points for resource navigation. At least one
	// root path must be defined for resources to be accessible.
	//
	// Example:
	//  server.Root("/api/v1", "/api/v2")
	Root(paths ...string) Server

	// AsStdio configures the server to use Standard I/O for communication.
	//
	// This is useful for child processes or integration with other MCP systems.
	// An optional logFile parameter can be provided to redirect stdio logs.
	//
	// Example:
	//  server.AsStdio("./mcp-server.log")
	AsStdio(logFile ...string) Server

	// AsWebsocket configures the server to use WebSocket for communication.
	//
	// The address parameter specifies the host and port to listen on.
	//
	// Example:
	//  server.AsWebsocket("localhost:8080")
	AsWebsocket(address string) Server

	// AsSSE configures the server to use Server-Sent Events for communication.
	//
	// The address parameter specifies the host and port to listen on.
	//
	// Example:
	//  server.AsSSE("localhost:8080")
	AsSSE(address string) Server

	// AsHTTP configures the server to use HTTP for communication.
	//
	// The address parameter specifies the host and port to listen on.
	//
	// Example:
	//  server.AsHTTP("localhost:8080")
	AsHTTP(address string) Server

	// GetServer returns the underlying server implementation.
	//
	// This is primarily used for advanced configuration or testing.
	GetServer() *serverImpl

	// GetRoots returns the list of registered root paths.
	GetRoots() []string

	// IsPathInRoots checks if a path is within any registered root.
	IsPathInRoots(path string) bool

	// WithSamplingConfig sets the sampling configuration for the server.
	//
	// Sampling configuration controls how sampling requests are handled,
	// including rate limits, caching, and other performance parameters.
	//
	// Example:
	//  config := server.NewSamplingConfig().WithRateLimit(10)
	//  server.WithSamplingConfig(config)
	WithSamplingConfig(config *SamplingConfig) Server

	// WithSamplingController sets a custom sampling controller for the server.
	//
	// This is an advanced method for applications that need fine-grained
	// control over sampling behavior.
	WithSamplingController(controller *SamplingController) Server

	// Logger returns the server's configured logger.
	//
	// This can be used to access the logger for custom logging needs.
	Logger() *slog.Logger
}

type SessionID string

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

type TextResource struct {
	Text string
}

type TextSamplingContent struct {
	Text string
}

type Tool struct {
	Name        string
	Description string
	Handler     ToolHandler
	Schema      interface{}
	Annotations map[string]interface{} // Additional metadata about the tool
}

type ToolHandler func(ctx *Context, args interface{}) (interface{}, error)