mcp

type Capabilities struct {
	// Tools indicates whether the implementation supports tool/function calling.
	Tools bool `json:"tools,omitempty"`

	// Resources indicates whether the implementation supports resource access.
	Resources bool `json:"resources,omitempty"`

	// Prompts indicates whether the implementation supports prompt templates.
	Prompts bool `json:"prompts,omitempty"`
}

type ClientInfo struct {
	// Name is the name of the client implementation.
	Name string `json:"name"`

	// Version is the version of the client implementation.
	Version string `json:"version"`
}

type ConnectionSession struct {
	// ClientInfo contains information about the connected client (from initialize request).
	ClientInfo map[string]interface{}

	// ProtocolVersion is the MCP protocol version negotiated during initialization.
	ProtocolVersion string

	// Capabilities lists the client's declared capabilities (if provided).
	Capabilities map[string]interface{}

	// ConnectionTime records when the connection was established.
	ConnectionTime int64 // Unix timestamp in nanoseconds
}

type Content struct {
	Type     string // "text", "image", or "resource"
	Text     string // For type="text"
	Data     string // For type="image" (base64 encoded)
	MimeType string // For type="image"
	Resource string // For type="resource" (resource URI)
}

type ContentBlock struct {
	Type     string // "text", "image", "resource"
	Text     string
	Data     string // Base64 for images
	MimeType string
	Resource string // Resource URI
}

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

type Error struct {
	// Code is a number that indicates the error type that occurred.
	// Standard error codes are defined as constants in this package.
	Code int `json:"code"`

	// Message provides a short description of the error.
	Message string `json:"message"`

	// Data contains additional information about the error.
	// May be omitted. The value is defined by the server (e.g. detailed error information, nested errors etc.).
	Data any `json:"data,omitempty"`
}

type InitializeRequest struct {
	// ProtocolVersion specifies the MCP protocol version the client supports.
	// Format: "YYYY-MM-DD" (e.g., "2025-06-18").
	ProtocolVersion string `json:"protocolVersion"`

	// ClientInfo describes the client making the request.
	ClientInfo ClientInfo `json:"clientInfo"`

	// Capabilities describes the optional features the client supports.
	Capabilities Capabilities `json:"capabilities"`
}

type InitializeResponse struct {
	// ProtocolVersion specifies the MCP protocol version the server supports.
	// Must match the version requested by the client.
	ProtocolVersion string `json:"protocolVersion"`

	// ServerInfo describes the server implementation.
	ServerInfo ServerInfo `json:"serverInfo"`

	// Capabilities describes the optional features the server supports.
	Capabilities Capabilities `json:"capabilities"`
}

type MCPServer interface {
	// Start begins serving MCP requests and blocks until the context is cancelled
	// or an error occurs.
	//
	// Start performs the following:
	// - Transitions from Uninitialized to Initializing state.
	// - Sets up transport layer (stdin/stdout by default).
	// - Registers JSON-RPC method handlers.
	// - Transitions to Running state after initialization completes.
	// - Blocks until ctx.Done() or fatal error.
	//
	// Start can only be called once. Subsequent calls return an error.
	//
	// Parameters:
	//   - ctx: context for server lifetime management and cancellation.
	//
	// Returns:
	//   - error: nil on clean shutdown, error if startup or operation fails.
	Start(ctx context.Context) error

	// Stop gracefully shuts down the server and releases all resources.
	//
	// Stop performs the following:
	// - Transitions to Stopped state.
	// - Closes transport connections.
	// - Flushes observability events if Emitter is configured.
	// - Releases all registered capabilities.
	//
	// Stop can be called multiple times safely. Subsequent calls are no-ops.
	//
	// Returns:
	//   - error: nil on success, error if shutdown fails.
	Stop() error

	// RegisterTool registers a tool implementation with metadata for MCP clients.
	//
	// Tools enable LLM clients to perform actions via the server. Each tool must
	// have a unique name and provide metadata describing its purpose and parameters.
	//
	// RegisterTool should be called before Start() to ensure tools are available
	// during client initialization. Tools registered after Start() may not be
	// visible to already-connected clients.
	//
	// Parameters:
	//   - name: unique tool identifier (must match tool.Tool.Name()).
	//   - tool: tool implementation that executes the tool logic.
	//   - metadata: descriptive information about the tool and its parameters.
	//
	// Returns:
	//   - error: nil on success, error if name conflicts or server is stopped.
	RegisterTool(name string, tool tool.Tool, metadata ToolMetadata) error

	// RegisterResource is deprecated. Use RegisterStaticResource or RegisterDynamicResource instead.
	//
	// Deprecated: Use RegisterStaticResource for fixed content or RegisterDynamicResource for computed content.
	RegisterResource(uri string, resource Resource) error

	// RegisterStaticResource registers a resource with fixed content.
	//
	// Static resources have content that is fixed at registration time and never changes.
	// Use this for cached data, configuration files, or any content that doesn't need
	// to be computed on-demand.
	//
	// RegisterStaticResource should be called before Start() to ensure resources are
	// available during client initialization.
	//
	// Parameters:
	//   - uri: unique resource identifier (must match pattern ^[a-z][a-z0-9_/]*$).
	//   - name: human-readable resource name.
	//   - description: resource description for clients.
	//   - mimeType: MIME type of the content (e.g., "application/json", "text/plain").
	//   - content: the resource content as bytes.
	//
	// Returns:
	//   - error: nil on success, error if URI conflicts, invalid, or content exceeds size limit.
	RegisterStaticResource(uri, name, description, mimeType string, content []byte) error

	// RegisterDynamicResource registers a resource with computed content.
	//
	// Dynamic resources compute content on-demand using a generator function. Use this
	// for live metrics, current state, or any content that changes over time.
	//
	// The generator function is called each time a client reads the resource and should
	// respect context cancellation.
	//
	// RegisterDynamicResource should be called before Start() to ensure resources are
	// available during client initialization.
	//
	// Parameters:
	//   - uri: unique resource identifier (must match pattern ^[a-z][a-z0-9_/]*$).
	//   - name: human-readable resource name.
	//   - description: resource description for clients.
	//   - mimeType: MIME type of the content (e.g., "application/json", "text/plain").
	//   - generator: function that computes content on-demand, receives context for cancellation.
	//
	// Returns:
	//   - error: nil on success, error if URI conflicts, invalid, or generator is nil.
	RegisterDynamicResource(uri, name, description, mimeType string, generator func(context.Context) ([]byte, error)) error

	// RegisterPrompt registers a prompt template that clients can invoke.
	//
	// Prompt templates provide reusable prompts with parameter substitution,
	// enabling clients to generate consistent prompts for common tasks.
	//
	// RegisterPrompt should be called before Start() to ensure prompts are
	// available during client initialization.
	//
	// Parameters:
	//   - template: prompt template implementation with name and rendering logic.
	//
	// Returns:
	//   - error: nil on success, error if name conflicts or server is stopped.
	RegisterPrompt(template PromptTemplate) error
}

type Message struct {
	Role    string  // "user" or "assistant"
	Content Content // Message content
}

type PromptInfo struct {
	Name        string
	Description string
	Arguments   []PromptParameter
}

type PromptParameter struct {
	// Name: Parameter name (used in {{name}} placeholders)
	// SHOULD match pattern: ^[a-z][a-z0-9_]*$ (recommended)
	Name string

	// Description: Parameter description (optional)
	// Helps LLM understand parameter purpose
	Description string

	// Required: Whether parameter must be provided during rendering
	// If true and parameter not provided, Render() returns error
	Required bool

	// DefaultValue: Default value if parameter not provided (optional)
	// Only used when Required=false
	// If empty and parameter not provided, placeholder remains empty
	DefaultValue string
}

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

type PromptTemplate struct {
	// Name: Unique prompt identifier
	// MUST match pattern: ^[a-z][a-z0-9_]*$ (lowercase, underscores)
	// Examples: "start_workflow", "resume_checkpoint", "analyze_results"
	Name string

	// Description: Human-readable description of prompt purpose
	// MUST be non-empty
	Description string

	// Parameters: Template parameters (optional, can be empty array)
	// Defines which placeholders are available in the template
	Parameters []PromptParameter

	// Template: Template string with {{param}} placeholders
	// MUST be non-empty
	// Placeholders are substituted during rendering
	// Example: "Start workflow '{{workflow_id}}' with input: {{input_data}}"
	Template string
}

type RegisteredTool struct {
	Tool     tool.Tool
	Metadata ToolAdapterMetadata
}

type RegistryOption func(*toolRegistry)

type RenderedPrompt struct {
	Description string
	Messages    []Message
}

type Request struct {
	// JSONRPC specifies the JSON-RPC protocol version. Must be exactly "2.0".
	JSONRPC string `json:"jsonrpc"`

	// ID is a unique identifier for the request. Used to correlate requests with responses.
	// May be a string, number, or null. Omitted for notification requests.
	ID any `json:"id,omitempty"`

	// Method is the name of the method to be invoked.
	Method string `json:"method"`

	// Params holds the parameter values to be used during the invocation of the method.
	// May be omitted if the method requires no parameters.
	Params any `json:"params,omitempty"`
}

type Resource interface {
	// URI returns the resource identifier
	URI() string

	// MimeType returns the content type
	MimeType() string

	// Read fetches resource content (may be cached or computed)
	Read(ctx context.Context) ([]byte, error)

	// Info returns the resource metadata
	Info() ResourceInfo
}

type ResourceContent struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`
}

type ResourceInfo struct {
	URI         string `json:"uri"`
	Name        string `json:"name"`
	Description string `json:"description"`
	MimeType    string `json:"mimeType"`
}

type ResourceProvider interface {
	// RegisterStatic registers a resource with fixed content
	RegisterStatic(uri, name, description, mimeType string, content []byte) error

	// RegisterDynamic registers a resource with computed content
	RegisterDynamic(uri, name, description, mimeType string, generator func(context.Context) ([]byte, error)) error

	// Get retrieves a resource by URI
	Get(uri string) (Resource, error)

	// List returns all resource metadata
	List() []ResourceInfo

	// Read fetches resource content by URI
	Read(ctx context.Context, uri string) ([]byte, error)
}

type ResourceProviderOption func(*resourceProvider)

type ResourcesListResult struct {
	Resources []ResourceInfo `json:"resources"`
}

type ResourcesReadParams struct {
	URI string `json:"uri"`
}

type ResourcesReadResult struct {
	Contents []ResourceContent `json:"contents"`
}

type Response struct {
	// JSONRPC specifies the JSON-RPC protocol version. Must be exactly "2.0".
	JSONRPC string `json:"jsonrpc"`

	// ID is the identifier from the corresponding request. Must match the request ID.
	ID any `json:"id"`

	// Result contains the result of the method invocation if successful.
	// Must be omitted if there was an error.
	Result any `json:"result,omitempty"`

	// Error contains error information if the method invocation failed.
	// Must be omitted if the method succeeded.
	Error *Error `json:"error,omitempty"`
}

type ServerConfig struct {
	// Name is the human-readable server name exposed to clients.
	// Example: "langgraph-weather", "database-tools".
	Name string

	// Version is the semantic version of the server implementation.
	// Example: "1.0.0", "2.1.3-beta".
	Version string

	// Emitter is an optional observability backend for emitting server events.
	// If nil, no events are emitted (useful for testing or minimal setups).
	Emitter emit.Emitter
}

type ServerInfo struct {
	// Name is the name of the server implementation.
	Name string `json:"name"`

	// Version is the version of the server implementation.
	Version string `json:"version"`
}

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

type ToolAdapterMetadata struct {
	Name        string                 // Tool name (validated against pattern ^[a-z][a-z0-9_]*$)
	Description string                 // Human-readable description
	InputSchema map[string]interface{} // JSON Schema for input validation
}

type ToolMetadata struct {
	// Description provides a human-readable explanation of what the tool does.
	Description string `json:"description"`

	// Schema defines the input parameters expected by the tool.
	// This should be a JSON Schema object describing the tool's input structure.
	Schema map[string]interface{} `json:"schema,omitempty"`
}

type ToolRegistry interface {
	// Register a LangGraph tool with MCP metadata
	Register(tool tool.Tool, metadata ToolAdapterMetadata) error

	// Get registered tool by name
	Get(name string) (*RegisteredTool, error)

	// List all tool metadata
	List() []ToolAdapterMetadata

	// Invoke tool with validated input
	Invoke(ctx context.Context, name string, arguments map[string]interface{}) (*ToolResult, error)
}

type ToolResult struct {
	Content []ContentBlock
	IsError bool
}