mcp-go Documentation

package main

import (
    "context"
    "fmt"

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

func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Demo 🚀",
        "1.0.0",
        server.WithToolCapabilities(false),
    )

    // Add tool
    tool := mcp.NewTool("hello_world",
        mcp.WithDescription("Say hello to someone"),
        mcp.WithString("name",
            mcp.Required(),
            mcp.Description("Name of the person to greet"),
        ),
    )

    // Add tool handler
    s.AddTool(tool, helloHandler)

    // Start the stdio server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}

func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    name, err := request.RequireString("name")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }

    return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil
}

go get github.com/mark3labs/mcp-go

/* Detailed source-code truncated for AI context efficiency. */

// Create a basic server
s := server.NewMCPServer(
    "My Server",  // Server name
    "1.0.0",     // Version
)

// Start the server using stdio
if err := server.ServeStdio(s); err != nil {
    log.Fatalf("Server error: %v", err)
}

// Static resource example - exposing a README file
resource := mcp.NewResource(
    "docs://readme",
    "Project README",
    mcp.WithResourceDescription("The project's README file"), 
    mcp.WithMIMEType("text/markdown"),
)

// Add resource with its handler
s.AddResource(resource, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    content, err := os.ReadFile("README.md")
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      "docs://readme",
            MIMEType: "text/markdown",
            Text:     string(content),
        },
    }, nil
})

// Dynamic resource example - user profiles by ID
template := mcp.NewResourceTemplate(
    "users://{id}/profile",
    "User Profile",
    mcp.WithTemplateDescription("Returns user profile information"),
    mcp.WithTemplateMIMEType("application/json"),
)

// Add template with its handler
s.AddResourceTemplate(template, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    // Extract ID from the URI using regex matching
    // The server automatically matches URIs to templates
    userID := extractIDFromURI(request.Params.URI)
    
    profile, err := getUserProfile(userID)  // Your DB/API call here
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      request.Params.URI,
            MIMEType: "application/json",
            Text:     profile,
        },
    }, nil
})

/* Detailed source-code truncated for AI context efficiency. */

// Tool with optional task support
analyzeTool := mcp.NewTool("analyze_data",
    mcp.WithDescription("Analyze data - can run sync or async"),
    mcp.WithTaskSupport(mcp.TaskSupportOptional),
    mcp.WithString("data", mcp.Required()),
)

// Use AddTaskTool for hybrid tools that support both modes
s.AddTaskTool(analyzeTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    // This handler runs when called as a task
    data := request.GetString("data", "")
    result := analyzeData(data)
    
    return &mcp.CreateTaskResult{
        Task: mcp.Task{},
    }, nil
})

// The server automatically handles both sync and async invocations
// When called without task param: executes handler and returns immediately
// When called with task param: executes handler asynchronously

s := server.NewMCPServer(
    "Task Server",
    "1.0.0",
    server.WithTaskCapabilities(true, true, true),
    server.WithMaxConcurrentTasks(10), // Allow up to 10 concurrent running tasks
)

calculatorTool := mcp.NewTool("calculate",
    mcp.WithDescription("Perform basic arithmetic calculations"),
    mcp.WithString("operation",
        mcp.Required(),
        mcp.Description("The arithmetic operation to perform"),
        mcp.Enum("add", "subtract", "multiply", "divide"),
    ),
    mcp.WithNumber("x",
        mcp.Required(),
        mcp.Description("First number"),
    ),
    mcp.WithNumber("y",
        mcp.Required(),
        mcp.Description("Second number"),
    ),
)

s.AddTool(calculatorTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args := request.GetArguments()
    op := args["operation"].(string)
    x := args["x"].(float64)
    y := args["y"].(float64)

    var result float64
    switch op {
    case "add":
        result = x + y
    case "subtract":
        result = x - y
    case "multiply":
        result = x * y
    case "divide":
        if y == 0 {
            return mcp.NewToolResultError("cannot divide by zero"), nil
        }
        result = x / y
    }
    
    return mcp.FormatNumberResult(result), nil
})

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

func (s *StreamableHTTPServer) Handle(w HTTPResponseWriter, r *HTTPRequest)

httpServer := server.NewStreamableHTTPServer(mcpServer,
    server.WithProtectedResourceMetadata(server.ProtectedResourceMetadataConfig{
        Resource:             "https://my-mcp-server.com",
        AuthorizationServers: []string{"https://auth.example.com"},
        ScopesSupported:      []string{"mcp:read", "mcp:write"},
    }),
)

httpServer := server.NewStreamableHTTPServer(mcpServer,
    server.WithEndpointPath("/mcp"),
    server.WithStreamableHTTPCORS(
        server.WithCORSAllowedOrigins("https://my-ai-app.com", "http://localhost:3000"),
        server.WithCORSAllowCredentials(),
        server.WithCORSMaxAge(300),
    ),
)

httpServer := server.NewStreamableHTTPServer(mcpServer,
    // Or server.WithSSEDisableLocalhostProtection(true) on NewSSEServer.
    server.WithDisableLocalhostProtection(true),
)

// Create a server with session capabilities
s := server.NewMCPServer(
    "Session Demo",
    "1.0.0",
    server.WithToolCapabilities(true),
)

// Implement your own ClientSession
type MySession struct {
    id           string
    notifChannel chan mcp.JSONRPCNotification
    isInitialized bool
    // Add custom fields for your application
}

// Implement the ClientSession interface
func (s *MySession) SessionID() string {
    return s.id
}

func (s *MySession) NotificationChannel() chan<- mcp.JSONRPCNotification {
    return s.notifChannel
}

func (s *MySession) Initialize() {
    s.isInitialized = true
}

func (s *MySession) Initialized() bool {
    return s.isInitialized
}

// Register a session
session := &MySession{
    id:           "user-123",
    notifChannel: make(chan mcp.JSONRPCNotification, 10),
}
if err := s.RegisterSession(context.Background(), session); err != nil {
    log.Printf("Failed to register session: %v", err)
}

// Send notification to a specific client
err := s.SendNotificationToSpecificClient(
    session.SessionID(),
    "notification/update",
    map[string]any{"message": "New data available!"},
)
if err != nil {
    log.Printf("Failed to send notification: %v", err)
}

// Unregister session when done
s.UnregisterSession(context.Background(), session.SessionID())

/* Detailed source-code truncated for AI context efficiency. */

// Add a tool filter that only shows tools with certain prefixes
s := server.NewMCPServer(
    "Tool Filtering Demo",
    "1.0.0",
    server.WithToolCapabilities(true),
    server.WithToolFilter(func(ctx context.Context, tools []mcp.Tool) []mcp.Tool {
        // Get session from context
        session := server.ClientSessionFromContext(ctx)
        if session == nil {
            return tools // Return all tools if no session
        }
        
        // Example: filter tools based on session ID prefix
        if strings.HasPrefix(session.SessionID(), "admin-") {
            // Admin users get all tools
            return tools
        } else {
            // Regular users only get tools with "public-" prefix
            var filteredTools []mcp.Tool
            for _, tool := range tools {
                if strings.HasPrefix(tool.Name, "public-") {
                    filteredTools = append(filteredTools, tool)
                }
            }
            return filteredTools
        }
    }),
)

s.AddTool(mcp.NewTool("session_aware"), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Get the current session from context
    session := server.ClientSessionFromContext(ctx)
    if session == nil {
        return mcp.NewToolResultError("No active session"), nil
    }
    
    return mcp.NewToolResultText("Hello, session " + session.SessionID()), nil
})

// When using handlers in HTTP/SSE servers, you need to pass the context with the session
httpHandler := func(w http.ResponseWriter, r *http.Request) {
    // Get session from somewhere (like a cookie or header)
    session := getSessionFromRequest(r)
    
    // Add session to context
    ctx := s.WithContext(r.Context(), session)
    
    // Use this context when handling requests
    // ...
}

go generate ./...

/* Detailed source-code truncated for AI context efficiency. */

func (p *MyProvider) CompleteResourceArgument(
    ctx context.Context,
    uri string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // Access previously completed arguments
    if previousValue, ok := context.Arguments["previous_arg"]; ok {
        // Provide suggestions based on previous_arg value
        return getSuggestionsFor(argument.Value, previousValue), nil
    }
    
    return &mcp.Completion{Values: []string{}}, nil
}

import otelmcp "github.com/mark3labs/mcp-go/otel"

srv := server.NewMCPServer("svc", "1.0", otelmcp.WithServerTracing(tp.Tracer("mcp")))
cli := client.NewClient(t, otelmcp.WithClientTracing(tp.Tracer("mcp")))

go run main.go

Tool result: LLM Response (model: mock-llm-v1): Mock LLM response to: 'What is the capital of France?'

# Set environment variables (optional)
export MCP_CLIENT_ID=your_client_id
export MCP_CLIENT_SECRET=your_client_secret

# Run the example
go run main.go

const (
    // Replace with your MCP server URL
    serverURL = "https://api.example.com/v1/mcp"
    // Use a localhost redirect URI for this example
    redirectURI = "http://localhost:8085/oauth/callback"
)

go build -o sampling_client

./sampling_client ../sampling_server/sampling_server

./sampling_client /path/to/your/mcp/server

Connected to server: sampling-example-server v1.0.0
Available tools:
  - ask_llm: Ask the LLM a question using sampling
  - greet: Greet the user

--- Testing greet tool ---
Greet result: Hello, Sampling Demo User! This server supports sampling - try using the ask_llm tool!

--- Testing ask_llm tool (with sampling) ---
Mock LLM received: What is the capital of France?
System prompt: You are a helpful geography assistant.
Max tokens: 1000
Temperature: 0.700000
Ask LLM result: LLM Response (model: mock-llm-v1): Mock LLM response to: 'What is the capital of France?'. This is a simulated response from a mock LLM handler.

type RealSamplingHandler struct {
    apiKey string
    client *openai.Client // or other LLM client
}

func (h *RealSamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Convert MCP request to LLM API format
    // Call LLM API
    // Convert response back to MCP format
    // Return result
}

httpTransport, err := transport.NewStreamableHTTP("http://localhost:8080")
mcpClient := client.NewClient(httpTransport, client.WithSamplingHandler(samplingHandler))

type MockSamplingHandler struct{}

func (h *MockSamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Process the sampling request and return LLM response
    // In production, integrate with OpenAI, Anthropic, or other LLM APIs
}

mcpClient := client.NewClient(
    httpTransport,
    client.WithSamplingHandler(samplingHandler),
)
// Sampling capability is automatically declared when a handler is provided

type RealSamplingHandler struct {
    client *openai.Client // or other LLM client
}

func (h *RealSamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Convert MCP request to LLM API format
    // Call LLM API
    // Convert response back to MCP format
    // Return the result
}

Client (HTTP + SSE) ←→ Server (HTTP)
     │                       │
     ├─ POST: Tool Call ──→  │
     │                       │
     │  ←── SSE: Sampling ───┤ 
     │      Request          │
     │                       │
     ├─ POST: Sampling ───→  │
     │      Response         │
     │                       │
     │  ←── HTTP: Tool ──────┤
           Response

// Custom HTTP server integration
mux := http.NewServeMux()
mux.Handle("/mcp", httpServer)
mux.Handle("/health", healthHandler)

server := &http.Server{
    Addr:    ":8080",
    Handler: mux,
}

go build -o sampling_server
./sampling_server

cd ../sampling_client
go build -o sampling_client
./sampling_client ../sampling_server/sampling_server

type WeatherRequest struct {
    Location string `json:"location" jsonschema:"City or location"`
    Units    string `json:"units,omitempty" jsonschema:"celsius or fahrenheit"`
}

type WeatherResponse struct {
    Location    string  `json:"location" jsonschema:"The location"`
    Temperature float64 `json:"temperature" jsonschema:"Current temperature"`
    Conditions  string  `json:"conditions" jsonschema:"Weather conditions"`
}

tool := mcp.NewTool("get_weather",
    mcp.WithDescription("Get weather information"),
    mcp.WithInputSchema[WeatherRequest](),
    mcp.WithOutputSchema[WeatherResponse](),
)

func weatherHandler(ctx context.Context, request mcp.CallToolRequest, args WeatherRequest) (*mcp.CallToolResult, error) {
    response := WeatherResponse{
        Location:    args.Location,
        Temperature: 25.0,
        Conditions:  "Cloudy",
    }
    
    fallbackText := fmt.Sprintf("Weather in %s: %.1f°C, %s", 
        response.Location, response.Temperature, response.Conditions)
    
    return mcp.NewToolResultStructured(response, fallbackText), nil
}

go run ./otel/example

exp, err := otlptracegrpc.New(ctx)
if err != nil {
    log.Fatal(err)
}
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp))

go generate ./...

go get github.com/mark3labs/mcp-go

package main

import (
    "context"
    "fmt"

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

func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Demo 🚀",
        "1.0.0",
        server.WithToolCapabilities(false),
    )

    // Add tool
    tool := mcp.NewTool("hello_world",
        mcp.WithDescription("Say hello to someone"),
        mcp.WithString("name",
            mcp.Required(),
            mcp.Description("Name of the person to greet"),
        ),
    )

    // Add tool handler
    s.AddTool(tool, helloHandler)

    // Start the stdio server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}

func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    name, err := request.RequireString("name")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }

    return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil
}

calculatorTool := mcp.NewTool("calculate",
    mcp.WithDescription("Perform basic arithmetic operations"),
    mcp.WithString("operation",
        mcp.Required(),
        mcp.Enum("add", "subtract", "multiply", "divide"),
    ),
    mcp.WithNumber("x", mcp.Required()),
    mcp.WithNumber("y", mcp.Required()),
)

resource := mcp.NewResource(
    "docs://readme",
    "Project README",
    mcp.WithResourceDescription("The project's README file"),
    mcp.WithMIMEType("text/markdown"),
)

s := server.NewMCPServer(
    "My Server",
    "1.0.0",
    server.WithToolCapabilities(true),
    server.WithRecovery(),
    server.WithHooks(myHooks),
)

/* Detailed source-code truncated for AI context efficiency. */

// Create STDIO client
client, err := client.NewStdioMCPClient("server-command", "arg1", "arg2")

// Create StreamableHTTP client
client := client.NewStreamableHttpClient("http://localhost:8080/mcp")

// Create SSE client
client := client.NewSSEMCPClient("http://localhost:8080/mcp/sse")

// Create in-process client
client := client.NewInProcessClient(server)

import (
    "context"
    "errors"
    "fmt"
    "log"
    "sync"
    "time"

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

type MCPClientManager struct {
    client client.Client
    ctx    context.Context
    cancel context.CancelFunc
}

func NewMCPClientManager(clientType, address string) (*MCPClientManager, error) {
    var c client.Client
    var err error

    switch clientType {
    case "stdio":
        c, err = client.NewStdioMCPClient("server-command")
    case "http":
        c = client.NewStreamableHttpClient(address)
    case "sse":
        c = client.NewSSEMCPClient(address)
    default:
        return nil, fmt.Errorf("unknown client type: %s", clientType)
    }

    if err != nil {
        return nil, err
    }

    ctx, cancel := context.WithCancel(context.Background())

    manager := &MCPClientManager{
        client: c,
        ctx:    ctx,
        cancel: cancel,
    }

    // Initialize connection
    if err := c.Initialize(ctx); err != nil {
        cancel()
        return nil, fmt.Errorf("failed to initialize client: %w", err)
    }

    return manager, nil
}

func (m *MCPClientManager) Close() error {
    m.cancel()
    return m.client.Close()
}

func handleClientErrors(ctx context.Context, c client.Client) {
    // Tool call with error handling
    result, err := c.CallTool(ctx, mcp.CallToolRequest{
        Params: mcp.CallToolRequestParams{
            Name: "example_tool",
            Arguments: map[string]interface{}{
                "param": "value",
            },
        },
    })

    if err != nil {
        switch {
        case errors.Is(err, client.ErrConnectionLost):
            log.Println("Connection lost, attempting reconnect...")
            // Implement reconnection logic
        case errors.Is(err, client.ErrToolNotFound):
            log.Printf("Tool not found: %v", err)
        case errors.Is(err, client.ErrInvalidArguments):
            log.Printf("Invalid arguments: %v", err)
        default:
            log.Printf("Unexpected error: %v", err)
        }
        return
    }

    // Process successful result
    processToolResult(result)
}

func callToolWithRetry(ctx context.Context, c client.Client, req mcp.CallToolRequest, maxRetries int) (*mcp.CallToolResult, error) {
    var lastErr error

    for attempt := 0; attempt <= maxRetries; attempt++ {
        result, err := c.CallTool(ctx, req)
        if err == nil {
            return result, nil
        }

        lastErr = err

        // Don't retry certain errors
        if errors.Is(err, client.ErrInvalidArguments) ||
           errors.Is(err, client.ErrToolNotFound) {
            break
        }

        // Exponential backoff
        if attempt < maxRetries {
            backoff := time.Duration(1<<attempt) * time.Second
            log.Printf("Attempt %d failed, retrying in %v: %v", attempt+1, backoff, err)
            
            select {
            case <-time.After(backoff):
            case <-ctx.Done():
                return nil, ctx.Err()
            }
        }
    }

    return nil, fmt.Errorf("failed after %d attempts: %w", maxRetries+1, lastErr)
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

package main

import (
    "context"
    "fmt"
    "log"
    "os"

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

func main() {
    // Create server (transport-agnostic)
    s := server.NewMCPServer("Multi-Transport Server", "1.0.0",
        server.WithToolCapabilities(true),
    )

    // Add a simple tool
    s.AddTool(
        mcp.NewTool("echo",
            mcp.WithDescription("Echo back the input"),
            mcp.WithString("message", mcp.Required()),
        ),
        handleEcho,
    )

    // Choose transport based on environment
    transport := os.Getenv("MCP_TRANSPORT")
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    switch transport {
    case "sse":
        fmt.Printf("Starting SSE server on port %s\n", port)
        sseServer := server.NewSSEServer(s)
        sseServer.Start(":" + port)
    case "streamablehttp":
        fmt.Printf("Starting StreamableHTTP server on port %s\n", port)
        httpServer := server.NewStreamableHTTPServer(s)
        httpServer.Start(":" + port)
    default:
        fmt.Println("Starting STDIO server")
        server.ServeStdio(s)
    }
}

func handleEcho(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    message, err := req.RequireString("message")
    if err != nil {
        return nil, err
    }
    return mcp.NewToolResultText(fmt.Sprintf("Echo: %s", message)), nil
}

func startServer(s *server.MCPServer) error {
    switch os.Getenv("MCP_TRANSPORT") {
    case "sse":
        sseServer := server.NewSSEServer(s)
        return sseServer.Start(getPort())
    case "streamablehttp":
        httpServer := server.NewStreamableHTTPServer(s)
        return httpServer.Start(getPort())
    case "inprocess":
        // Note: In-process transport doesn't use network ports
        // This would typically be used differently in practice
        client := client.NewInProcessClient(s)
        defer client.Close()
        // Keep the process running
        select {}
    default:
        return server.ServeStdio(s)
    }
}

func getPort() string {
    if port := os.Getenv("PORT"); port != "" {
        return ":" + port
    }
    return ":8080"
}

func main() {
    s := server.NewMCPServer("Multi-Transport", "1.0.0")
    
    // Add your tools, resources, prompts...
    setupServer(s)
    
    // Start multiple transports concurrently with proper error handling
    errChan := make(chan error, 3)
    
    go func() {
        log.Println("Starting STDIO server...")
        if err := server.ServeStdio(s); err != nil {
            log.Printf("STDIO server error: %v", err)
            errChan <- fmt.Errorf("STDIO server failed: %w", err)
        }
    }()
    
    go func() {
        log.Println("Starting SSE server on :8080...")
        sseServer := server.NewSSEServer(s)
        if err := sseServer.Start(":8080"); err != nil {
            log.Printf("SSE server error: %v", err)
            errChan <- fmt.Errorf("SSE server failed: %w", err)
        }
    }()
    
    log.Println("Starting StreamableHTTP server on :8081...")
    httpServer := server.NewStreamableHTTPServer(s)
    if err := httpServer.Start(":8081"); err != nil {
        log.Printf("StreamableHTTP server error: %v", err)
        errChan <- fmt.Errorf("StreamableHTTP server failed: %w", err)
    }
    
    // Wait for any server to fail
    select {
    case err := <-errChan:
        log.Printf("Server failed: %v", err)
        return
    }
}

// Helper function for the multi-transport example
func setupServer(s *server.MCPServer) {
    // Placeholder implementation - would add tools, resources, etc.
}

// Example with security middleware
s := server.NewMCPServer("Secure Server", "1.0.0",
    server.WithToolMiddleware(authMiddleware),
    server.WithToolMiddleware(rateLimitMiddleware),
    server.WithRecovery(),
)

// Static resource
resource := mcp.NewResource(
    "docs://readme",
    "Project README",
    mcp.WithResourceDescription("The project's main documentation"),
    mcp.WithMIMEType("text/markdown"),
)

// Dynamic resource with template
userResource := mcp.NewResource(
    "users://{user_id}",
    "User Profile",
    mcp.WithResourceDescription("User profile information"),
    mcp.WithMIMEType("application/json"),
)

// Simple calculation tool
calcTool := mcp.NewTool("calculate",
    mcp.WithDescription("Perform arithmetic operations"),
    mcp.WithString("operation", 
        mcp.Required(),
        mcp.Enum("add", "subtract", "multiply", "divide"),
    ),
    mcp.WithNumber("x", mcp.Required()),
    mcp.WithNumber("y", mcp.Required()),
)

// File creation tool
fileTool := mcp.NewTool("create_file",
    mcp.WithDescription("Create a new file with content"),
    mcp.WithString("path", mcp.Required()),
    mcp.WithString("content", mcp.Required()),
    mcp.WithString("encoding", mcp.Default("utf-8")),
)

// Code review prompt
reviewPrompt := mcp.NewPrompt("code_review",
    mcp.WithPromptDescription("Review code for best practices and issues"),
    mcp.WithPromptArgument("code", 
        mcp.Required(),
        mcp.Description("The code to review"),
    ),
    mcp.WithPromptArgument("language",
        mcp.Description("Programming language"),
    ),
)

// Data analysis prompt
analysisPrompt := mcp.NewPrompt("analyze_data",
    mcp.WithPromptDescription("Analyze dataset and provide insights"),
    mcp.WithPromptArgument("dataset_uri", mcp.Required()),
    mcp.WithPromptArgument("focus_areas", 
        mcp.Description("Specific areas to focus analysis on"),
    ),
)

// Stdio transport (most common)
server.ServeStdio(s)

// HTTP transport
server.ServeHTTP(s, ":8080")

// SSE transport
server.ServeSSE(s, ":8080")

// Server example - exposes functionality
s := server.NewMCPServer("Database Tools", "1.0.0")
s.AddTool(queryTool, handleQuery)
s.AddResource(tableResource, handleTableAccess)
server.ServeStdio(s)

// Client example - uses functionality
client := client.NewStdioClient("database-server")
tools, _ := client.ListTools(ctx, mcp.ListToolsRequest{})
result, _ := client.CallTool(ctx, queryRequest)

// Same server works with any transport
s := server.NewMCPServer("My Server", "1.0.0")

// Choose transport at runtime
switch transport {
case "stdio":
    server.ServeStdio(s)
case "http":
    server.ServeHTTP(s, ":8080")
case "sse":
    server.ServeSSE(s, ":8080")
}

// Server automatically handles multiple sessions
s := server.NewMCPServer("Multi-Client Server", "1.0.0",
    server.WithHooks(&server.Hooks{
        OnSessionStart: func(sessionID string) {
            log.Printf("Client %s connected", sessionID)
        },
        OnSessionEnd: func(sessionID string) {
            log.Printf("Client %s disconnected", sessionID)
        },
    }),
)

// Per-session state
type SessionState struct {
    UserID   string
    Settings map[string]interface{}
}

var sessions = make(map[string]*SessionState)

func toolHandler(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    sessionID := server.GetSessionID(ctx)
    state := sessions[sessionID]
    
    // Use session-specific state
    return processWithState(state, req)
}

srv := server.NewMCPServer("my-server", "1.0.0",
    server.WithToolCapabilities(true),
)

http.ListenAndServe(":8080", server.NewStreamableHTTPServer(srv))

server.NewStreamableHTTPServer(srv,
    server.WithStreamableHTTPProtocolVersions(mcp.LegacyProtocolVersions()...),
)

client.NewClient(httpTransport, client.WithProtocolVersion(mcp.ProtocolVersion20251125))

server.NewMCPServer("my-server", "1.0.0",
    // Clients may reuse tool and prompt catalogs for a minute.
    server.WithCacheHints(60_000, mcp.CacheScopePublic),
    // Resource contents are user-specific, so no shared cache may hold them.
    server.WithMethodCacheHints(mcp.MethodResourcesRead, 5_000, mcp.CacheScopePrivate),
)

srv.AddTool(mcp.NewTool("deploy"), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // On the retry, the client's answer is waiting for us.
    if answer := server.ElicitationResponse(req.Params.InputResponses, "confirm"); answer != nil {
        if answer.Action != mcp.ElicitationResponseActionAccept {
            return mcp.NewToolResultText("deployment cancelled"), nil
        }
        return mcp.NewToolResultText("deployed"), nil
    }

    // First call: ask, and hand back whatever state we need to resume.
    return server.NewInputRequestBuilder("awaiting-confirmation").
        Elicit("confirm", mcp.ElicitationParams{
            Mode:    mcp.ElicitationModeForm,
            Message: "Deploy to production?",
            RequestedSchema: map[string]any{
                "type":       "object",
                "properties": map[string]any{"ok": map[string]any{"type": "boolean"}},
            },
        }).
        ToolResult(), nil
})

srv := server.NewMCPServer("my-server", "1.0.0",
    server.WithToolCapabilities(true),          // enables toolsListChanged
    server.WithResourceCapabilities(true, true), // enables subscriptions and resourcesListChanged
)

c := client.NewClient(httpTransport)
if err := c.Start(ctx); err != nil {
    return err
}

var req mcp.InitializeRequest
req.Params.ClientInfo = mcp.Implementation{Name: "my-client", Version: "1.0.0"}

result, err := c.Initialize(ctx, req)  // result.ProtocolVersion tells you which era won

c := client.NewClient(httpTransport,
    client.WithElicitationHandler(myHandler),
    client.WithMaxInputRoundTrips(5),  // optional; the default is 10
)

// Returns the final result. Any input the server needed was gathered
// and resubmitted along the way.
result, err := c.CallTool(ctx, req)

stop, err := c.ListenAsync(ctx, mcp.SubscriptionFilter{
    ToolsListChanged:      true,
    ResourceSubscriptions: []string{"file:///config.json"},
}, func(err error) {
    log.Printf("subscription stream ended: %v", err)
})
defer stop()

c := client.NewClient(httpTransport,
    client.WithProtocolVersion(mcp.ProtocolVersion20251125),
)

package main

import (
    "context"
    "fmt"

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

func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Hello World Server",
        "1.0.0",
        server.WithToolCapabilities(true),
    )

    // Define a simple tool
    tool := mcp.NewTool("hello_world",
        mcp.WithDescription("Say hello to someone"),
        mcp.WithString("name",
            mcp.Required(),
            mcp.Description("Name of the person to greet"),
        ),
    )

    // Add tool handler
    s.AddTool(tool, helloHandler)

    // Start the stdio server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}

func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    arguments := request.GetArguments()
    name, ok := arguments["name"].(string)
    if !ok {
        return &mcp.CallToolResult{
            Content: []mcp.Content{
                mcp.TextContent{
                    Type: "text",
                    Text: "Error: name parameter is required and must be a string",
                },
            },
            IsError: true,
        }, nil
    }

    return &mcp.CallToolResult{
        Content: []mcp.Content{
            mcp.TextContent{
                Type: "text",
                Text: fmt.Sprintf("Hello, %s! 👋", name),
            },
        },
    }, nil
}

cd hello-server
go mod init hello-server
go get github.com/mark3labs/mcp-go
go run main.go

# Install the MCP Inspector
npm install @modelcontextprotocol/inspector

# Run your server with the inspector
mcp-inspector go run main.go

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

package main

import (
    "context"
    "fmt"
    
    "github.com/mark3labs/mcp-go/client"
    "github.com/mark3labs/mcp-go/client/transport"
    "github.com/mark3labs/mcp-go/mcp"
)

type MySamplingHandler struct {
    // Add fields for your LLM client (OpenAI, Anthropic, etc.)
}

func (h *MySamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Extract request parameters
    messages := request.Messages
    systemPrompt := request.SystemPrompt
    maxTokens := request.MaxTokens
    temperature := request.Temperature
    
    // Process with your LLM
    response, err := h.callLLM(ctx, messages, systemPrompt, maxTokens, temperature)
    if err != nil {
        return nil, fmt.Errorf("LLM call failed: %w", err)
    }
    
    // Return MCP-formatted result
    return &mcp.CreateMessageResult{
        Model: "your-model-name",
        Role:  mcp.RoleAssistant,
        Content: mcp.TextContent{
            Type: "text",
            Text: response,
        },
        StopReason: "endTurn",
    }, nil
}

func (h *MySamplingHandler) callLLM(ctx context.Context, messages []mcp.SamplingMessage, systemPrompt string, maxTokens int, temperature float64) (string, error) {
    // Implement your LLM integration here
    // This is where you'd call OpenAI, Anthropic, or other LLM APIs
    return "Your LLM response here", nil
}

func main() {
    // Create sampling handler
    samplingHandler := &MySamplingHandler{}
    
    // Create stdio transport
    stdioTransport := transport.NewStdio("/path/to/mcp/server", nil)
    
    // Create client with sampling support
    mcpClient := client.NewClient(stdioTransport, client.WithSamplingHandler(samplingHandler))
    
    // Start the client
    ctx := context.Background()
    if err := mcpClient.Start(ctx); err != nil {
        log.Fatalf("Failed to start client: %v", err)
    }
    defer mcpClient.Close()
    if err := mcpClient.Connect(ctx); err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    
    // The client will now automatically handle sampling requests
    // from the server using your handler
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

// This automatically adds sampling capability
stdioTransport := transport.NewStdio(serverPath, nil)
mcpClient := client.NewClient(stdioTransport, client.WithSamplingHandler(handler))

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "sampling": {}
    },
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

type SamplingCapability struct {
    // Context advertises that the client honours CreateMessageParams.IncludeContext.
    // If nil, servers SHOULD only send IncludeContext "none" (or omit it).
    Context *struct{} `json:"context,omitempty"`
    // Tools advertises that the client honours CreateMessageParams.Tools and
    // CreateMessageParams.ToolChoice (sampling with tools).
    Tools   *struct{} `json:"tools,omitempty"`
}

{
  "capabilities": {
    "sampling": { "context": {}, "tools": {} }
  }
}

func (h *MySamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    var allowedTools []mcp.Tool
    if len(request.Tools) > 0 {
        allowedTools = request.Tools
    }

    mode := mcp.ToolChoiceModeAuto // spec default when ToolChoice is omitted
    if request.ToolChoice != nil && request.ToolChoice.Mode != "" {
        mode = request.ToolChoice.Mode
    }

    switch mode {
    case mcp.ToolChoiceModeNone:
        // Tool use is disabled for this request.
    case mcp.ToolChoiceModeRequired:
        // Model must call at least one tool.
    case mcp.ToolChoiceModeAuto:
        // Model decides.
    }

    // ... forward `allowedTools` and `mode` to your LLM client and return the
    // response as a SamplingMessage (which may carry ToolUseContent /
    // ToolResultContent in addition to TextContent / ImageContent / AudioContent).
    return nil, nil
}

func (h *MySamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Validate request
    if len(request.Messages) == 0 {
        return nil, fmt.Errorf("no messages provided")
    }
    
    // Check for context cancellation
    if err := ctx.Err(); err != nil {
        return nil, fmt.Errorf("request cancelled: %w", err)
    }
    
    // Call LLM with error handling
    response, err := h.callLLM(ctx, request)
    if err != nil {
        // Log error for debugging
        log.Printf("LLM call failed: %v", err)
        
        // Return appropriate error
        if strings.Contains(err.Error(), "rate limit") {
            return nil, fmt.Errorf("rate limit exceeded, please try again later")
        }
        return nil, fmt.Errorf("LLM service unavailable: %w", err)
    }
    
    return response, nil
}

# Build the sampling server
cd examples/sampling_server
go build -o sampling_server

# Build your client
go build -o my_client

# Test the integration
./my_client ./sampling_server

stdioTransport := transport.NewStdio("/path/to/server", nil)
mcpClient := client.NewClient(stdioTransport, client.WithSamplingHandler(&MySamplingHandler{}))

mcpClient, err := client.NewInProcessClientWithSamplingHandler(
    mcpServer, 
    &MySamplingHandler{},
)

// STDIO client - for command-line tools
client, err := client.NewStdioMCPClient("command", "arg1", "arg2")

// StreamableHTTP client - for web services
client := client.NewStreamableHttpClient("http://localhost:8080/mcp")

// SSE client - for real-time web applications
client := client.NewSSEMCPClient("http://localhost:8080/mcp/sse")

// In-process client - for testing and embedded scenarios
client := client.NewInProcessClient(server)

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "math"
    "net/http"
    "sync"
    "time"

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

func createStdioClient() (client.Client, error) {
    // Create client that spawns a subprocess
    c, err := client.NewStdioMCPClient(
        "go", []string{}, "run", "/path/to/server/main.go",
    )
    if err != nil {
        return nil, fmt.Errorf("failed to create STDIO client: %w", err)
    }

    return c, nil
}

// With custom environment variables
func createStdioClientWithEnv() (client.Client, error) {
    env := []string{
        "LOG_LEVEL=debug",
        "DATABASE_URL=sqlite://test.db",
    }
    c, err := client.NewStdioMCPClient(
        "go", env, "run", "/path/to/server/main.go",
    )
    if err != nil {
        return nil, fmt.Errorf("failed to create STDIO client: %w", err)
    }

    return c, nil
}

func createStreamableHTTPClient() client.Client {
    // Basic StreamableHTTP client
	httpTransport, err := transport.NewStreamableHTTP(server.URL,
		// Set timeout
		transport.WithHTTPTimeout(30*time.Second),
		// Set custom headers
		transport.WithHTTPHeaders(map[string]string{
			"X-Custom-Header": "custom-value",
			"Y-Another-Header": "another-value",
		}),
		// With custom HTTP client
		transport.WithHTTPBasicClient(&http.Client{}),
	)
    if err != nil {
        log.Fatalf("Failed to create StreamableHTTP transport: %v", err)
    }
    c := client.NewClient(httpTransport)
    return c
}

func createSSEClient() client.Client {
    // Basic SSE client
	c, err := NewSSEMCPClient(testServer.URL+"/sse",
		// Set custom headers
		WithHeaders(map[string]string{
			"X-Custom-Header": "custom-value",
			"Y-Another-Header": "another-value",
		}),
	)
    return c
}

/* Detailed source-code truncated for AI context efficiency. */

func initializeClientWithDetails(ctx context.Context, c client.Client) error {
    // Initialize with custom client info
    initReq := mcp.InitializeRequest{
        Params: mcp.InitializeRequestParams{
            ProtocolVersion: "2024-11-05",
            Capabilities: mcp.ClientCapabilities{
                Tools:     &mcp.ToolsCapability{},
                Resources: &mcp.ResourcesCapability{},
                Prompts:   &mcp.PromptsCapability{},
            },
            ClientInfo: mcp.ClientInfo{
                Name:    "My Application",
                Version: "1.0.0",
            },
        },
    }

    result, err := c.InitializeWithRequest(ctx, initReq)
    if err != nil {
        return fmt.Errorf("initialization failed: %w", err)
    }

    log.Printf("Connected to server: %s v%s", 
        result.ServerInfo.Name, 
        result.ServerInfo.Version)
    
    log.Printf("Server capabilities: %+v", result.Capabilities)

    return nil
}

/* Detailed source-code truncated for AI context efficiency. */

// Connection errors
var (
    ErrConnectionFailed = errors.New("connection failed")
    ErrConnectionLost   = errors.New("connection lost")
    ErrTimeout          = errors.New("operation timeout")
)

// Protocol errors
var (
    ErrInvalidResponse    = errors.New("invalid response")
    ErrProtocolViolation  = errors.New("protocol violation")
    ErrUnsupportedVersion = errors.New("unsupported protocol version")
)

// Operation errors
var (
    ErrToolNotFound       = errors.New("tool not found")
    ErrResourceNotFound   = errors.New("resource not found")
    ErrInvalidArguments   = errors.New("invalid arguments")
    ErrPermissionDenied   = errors.New("permission denied")
)

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

type ClientHealthMonitor struct {
    client   client.Client
    interval time.Duration
    timeout  time.Duration
    healthy  bool
    mutex    sync.RWMutex
}

func NewClientHealthMonitor(c client.Client, interval, timeout time.Duration) *ClientHealthMonitor {
    return &ClientHealthMonitor{
        client:   c,
        interval: interval,
        timeout:  timeout,
        healthy:  false,
    }
}

func (chm *ClientHealthMonitor) Start(ctx context.Context) {
    ticker := time.NewTicker(chm.interval)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            chm.checkHealth(ctx)
        }
    }
}

func (chm *ClientHealthMonitor) checkHealth(ctx context.Context) {
    ctx, cancel := context.WithTimeout(ctx, chm.timeout)
    defer cancel()

    // Try to list tools as a health check
    _, err := chm.client.ListTools(ctx, mcp.ListToolsRequest{})
    
    chm.mutex.Lock()
    chm.healthy = (err == nil)
    chm.mutex.Unlock()

    if err != nil {
        log.Printf("Health check failed: %v", err)
    }
}

func (chm *ClientHealthMonitor) IsHealthy() bool {
    chm.mutex.RLock()
    defer chm.mutex.RUnlock()
    return chm.healthy
}

/* Detailed source-code truncated for AI context efficiency. */

import (
    "base64"
    "context"
    "encoding/json"
    "fmt"
    "log"
    "reflect"
    "regexp"
    "strings"
    "sync"
    "time"

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

func listResources(ctx context.Context, c client.Client) error {
    // List all available resources
    resources, err := c.ListResources(ctx, mcp.ListResourcesRequest{})
    if err != nil {
        return fmt.Errorf("failed to list resources: %w", err)
    }

    fmt.Printf("Available resources: %d\n", len(resources.Resources))
    for _, resource := range resources.Resources {
        fmt.Printf("- %s (%s): %s\n", 
            resource.URI, 
            resource.MIMEType, 
            resource.Name)
        
        if resource.Description != "" {
            fmt.Printf("  Description: %s\n", resource.Description)
        }
    }

    return nil
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

type ResourceCache struct {
    cache map[string]cacheEntry
    mutex sync.RWMutex
    ttl   time.Duration
}

type cacheEntry struct {
    result    *mcp.ReadResourceResult
    timestamp time.Time
}

func NewResourceCache(ttl time.Duration) *ResourceCache {
    return &ResourceCache{
        cache: make(map[string]cacheEntry),
        ttl:   ttl,
    }
}

func (rc *ResourceCache) Get(uri string) (*mcp.ReadResourceResult, bool) {
    rc.mutex.RLock()
    defer rc.mutex.RUnlock()

    entry, exists := rc.cache[uri]
    if !exists || time.Since(entry.timestamp) > rc.ttl {
        return nil, false
    }

    return entry.result, true
}

func (rc *ResourceCache) Set(uri string, result *mcp.ReadResourceResult) {
    rc.mutex.Lock()
    defer rc.mutex.Unlock()

    rc.cache[uri] = cacheEntry{
        result:    result,
        timestamp: time.Now(),
    }
}

func (rc *ResourceCache) ReadResource(ctx context.Context, c client.Client, uri string) (*mcp.ReadResourceResult, error) {
    // Check cache first
    if cached, found := rc.Get(uri); found {
        return cached, nil
    }

    // Read from server
    result, err := readResource(ctx, c, uri)
    if err != nil {
        return nil, err
    }

    // Cache the result
    rc.Set(uri, result)
    return result, nil
}

func callTool(ctx context.Context, c client.Client, name string, args map[string]interface{}) (*mcp.CallToolResult, error) {
    result, err := c.CallTool(ctx, mcp.CallToolRequest{
        Params: mcp.CallToolRequestParams{
            Name:      name,
            Arguments: args,
        },
    })
    if err != nil {
        return nil, fmt.Errorf("tool call failed: %w", err)
    }

    return result, nil
}

func demonstrateToolCalling(ctx context.Context, c client.Client) {
    // List available tools
    tools, err := c.ListTools(ctx, mcp.ListToolsRequest{})
    if err != nil {
        log.Printf("Failed to list tools: %v", err)
        return
    }

    fmt.Printf("Available tools: %d\n", len(tools.Tools))
    for _, tool := range tools.Tools {
        fmt.Printf("- %s: %s\n", tool.Name, tool.Description)
    }

    // Call a specific tool
    if len(tools.Tools) > 0 {
        tool := tools.Tools[0]
        fmt.Printf("\nCalling tool: %s\n", tool.Name)

        result, err := callTool(ctx, c, tool.Name, map[string]interface{}{
            "input": "example input",
            "format": "text",
        })
        if err != nil {
            log.Printf("Tool call failed: %v", err)
            return
        }

        fmt.Printf("Tool result:\n")
        for i, content := range result.Content {
            fmt.Printf("Content %d (%s): %s\n", i+1, content.Type, content.Text)
        }
    }
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

type PromptProcessor struct {
    client client.Client
}

func NewPromptProcessor(c client.Client) *PromptProcessor {
    return &PromptProcessor{client: c}
}

func (pp *PromptProcessor) ProcessPrompt(ctx context.Context, name string, args map[string]interface{}) ([]mcp.PromptMessage, error) {
    result, err := pp.client.GetPrompt(ctx, mcp.GetPromptRequest{
        Params: mcp.GetPromptRequestParams{
            Name:      name,
            Arguments: args,
        },
    })
    if err != nil {
        return nil, err
    }

    return result.Messages, nil
}

func (pp *PromptProcessor) BuildConversation(ctx context.Context, promptName string, args map[string]interface{}, userMessage string) ([]mcp.PromptMessage, error) {
    // Get prompt template
    messages, err := pp.ProcessPrompt(ctx, promptName, args)
    if err != nil {
        return nil, err
    }

    // Add user message
    messages = append(messages, mcp.PromptMessage{
        Role: "user",
        Content: mcp.TextContent(userMessage),
    })

    return messages, nil
}

func (pp *PromptProcessor) FormatForLLM(messages []mcp.PromptMessage) []map[string]interface{} {
    formatted := make([]map[string]interface{}, len(messages))
    
    for i, message := range messages {
        formatted[i] = map[string]interface{}{
            "role":    message.Role,
            "content": message.Content.Text,
        }
    }
    
    return formatted
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

import "github.com/mark3labs/mcp-go/client"

// Implement the SamplingHandler interface
type MySamplingHandler struct {
    // Add your LLM client here
}

func (h *MySamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Process the request with your LLM
    // Return the result in MCP format
    return &mcp.CreateMessageResult{
        Model: "your-model",
        Role:  mcp.RoleAssistant,
        Content: mcp.TextContent{
            Type: "text",
            Text: "Your LLM response here",
        },
        StopReason: "endTurn",
    }, nil
}

// Create client with sampling support
mcpClient, err := client.NewStdioClient(
    "/path/to/server",
    client.WithSamplingHandler(&MySamplingHandler{}),
)

cc, ok := c.(*client.Client)
if !ok {
    return fmt.Errorf("iterators require *client.Client, got %T", c)
}
// safe to call cc.IterTools / cc.IterResources / ... here

func printToolNames(ctx context.Context, c *client.Client) error {
    for tool, err := range c.IterTools(ctx, mcp.ListToolsRequest{}) {
        if err != nil {
            return fmt.Errorf("list tools: %w", err)
        }
        fmt.Println(tool.Name)
    }
    return nil
}

func findTool(ctx context.Context, c *client.Client, name string) (*mcp.Tool, error) {
    for tool, err := range c.IterTools(ctx, mcp.ListToolsRequest{}) {
        if err != nil {
            return nil, err
        }
        if tool.Name == name {
            return &tool, nil // no further pages are fetched
        }
    }
    return nil, fmt.Errorf("tool %q not found", name)
}

func processResources(ctx context.Context, c *client.Client) error {
    for resource, err := range c.IterResources(ctx, mcp.ListResourcesRequest{}) {
        if err != nil {
            // ctx.Err() or a transport / server error — iterator is now done.
            return err
        }
        process(resource)
    }
    return nil
}

package main

import (
    "context"
    "crypto/tls"
    "errors"
    "fmt"
    "log"
    "net/http"
    "os"
    "sync"
    "time"

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

func createStdioClient() {
    // Create client that spawns a subprocess
    c, err := client.NewStdioMCPClient(
        "go", []string{}, "run", "/path/to/server/main.go",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()

    ctx := context.Background()

    // Initialize connection
    if err := c.Initialize(ctx, initRequest); err != nil {
        log.Fatal(err)
    }

    // Use the client
    tools, err := c.ListTools(ctx, mcp.ListToolsRequest{})
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Available tools: %d", len(tools.Tools))
}

func createCustomStdioClient() {
    // Create custom logger for debugging
    logger := myCustomLogger{}

    // Create STDIO client with custom options
    c, err := client.NewStdioMCPClientWithOptions(
        "go",
        []string{"GOCACHE=/tmp/gocache"}, // Custom environment
        []string{"run", "/path/to/server/main.go"},
        transport.WithCommandLogger(logger),
        transport.WithCommandFunc(func(ctx context.Context, command string, args []string, env []string) (*exec.Cmd, error) {
            cmd := exec.CommandContext(ctx, command, args...)
            cmd.Env = append(os.Environ(), env...)
            cmd.Dir = "/path/to/working/directory"
            return cmd, nil
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()

    ctx := context.Background()

    // Initialize connection
    if err := c.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Use the client...
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

// Define connection error constants
var (
    ErrConnectionLost   = errors.New("connection lost")
    ErrConnectionFailed = errors.New("connection failed")
    ErrUnauthorized     = errors.New("unauthorized")
    ErrForbidden        = errors.New("forbidden")
)

import "github.com/mark3labs/mcp-go/client/transport"

func connectWithFallback(ctx context.Context, url string) (*client.Client, error) {
    // Try StreamableHTTP first
    streamableTransport, err := transport.NewStreamableHTTP(url)
    if err != nil {
        return nil, err
    }

    c := client.New(streamableTransport)
    if err := c.Start(ctx); err != nil {
        if errors.Is(err, transport.ErrLegacySSEServer) {
            // Fall back to legacy SSE transport
            sseTransport, err := transport.NewSSE(url)
            if err != nil {
                return nil, err
            }
            c = client.New(sseTransport)
            if err := c.Start(ctx); err != nil {
                return nil, err
            }
            return c, nil
        }
        return nil, err
    }
    return c, nil
}

func createStreamableHTTPClient() {
    // Create StreamableHTTP client
    c := client.NewStreamableHttpClient("http://localhost:8080/mcp")
    defer c.Close()

    ctx := context.Background()

    // Initialize
    if err := c.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Use client
    tools, err := c.ListTools(ctx, mcp.ListToolsRequest{})
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Available tools: %d", len(tools.Tools))
}

func createCustomStreamableHTTPClient() {
    // Create custom logger for debugging
    logger := myCustomLogger{}

    // Create StreamableHTTP client with options
    c := client.NewStreamableHttpClient("https://api.example.com/mcp",
        transport.WithLogger(logger),
        transport.WithHTTPTimeout(30*time.Second),
        transport.WithHTTPHeaders(map[string]string{
            "User-Agent": "MyApp/1.0",
            "Accept":     "application/json",
        }),
        transport.WithHTTPBasicClient(&http.Client{
            Transport: &http.Transport{
                MaxIdleConns:        100,
                MaxIdleConnsPerHost: 10,
                IdleConnTimeout:     90 * time.Second,
                TLSClientConfig: &tls.Config{
                    InsecureSkipVerify: false,
                },
            },
        }),
    )
    defer c.Close()

    ctx := context.Background()

    if err := c.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Use client...
}

if errors.Is(err, client.ErrAuthorizationServerChanged) {
    // Verify the new authorization server before opting into registration.
    if err := handler.RegisterClient(ctx, "My MCP client"); err != nil {
        return err
    }
    // Start a fresh authorization flow; do not reuse the old code or token.
}

func createAuthenticatedStreamableHTTPClient() (*client.Client, error) {
    c, err := client.NewOAuthStreamableHttpClient("http://localhost:8080/mcp",
        client.OAuthConfig{
            ClientID:              "your-client-id",
            ClientSecret:          "your-client-secret",
            CredentialsIssuer:     "https://auth.example.com",
            RedirectURI:           "http://localhost:8085/callback",
            Scopes:                []string{"mcp:read", "mcp:write"},
        },
    )
    if err != nil {
        return nil, err
    }
    // Start and initialize the client, completing OAuth if required.
    // The caller owns c and must close it when finished.
    return c, nil
}

type StreamableHTTPClientPool struct {
    clients chan *client.Client
    factory func() *client.Client
    maxSize int
}

func NewStreamableHTTPClientPool(baseURL string, maxSize int) *StreamableHTTPClientPool {
    pool := &StreamableHTTPClientPool{
        clients: make(chan *client.Client, maxSize),
        maxSize: maxSize,
        factory: func() *client.Client {
            return client.NewStreamableHttpClient(baseURL)
        },
    }

    // Pre-populate pool
    for i := 0; i < maxSize; i++ {
        pool.clients <- pool.factory()
    }

    return pool
}

func (pool *StreamableHTTPClientPool) Get() *client.Client {
    select {
    case c := <-pool.clients:
        return c
    default:
        return pool.factory()
    }
}

func (pool *StreamableHTTPClientPool) Put(c *client.Client) {
    select {
    case pool.clients <- c:
    default:
        // Pool full, close client
        c.Close()
    }
}

func (pool *StreamableHTTPClientPool) CallTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    c := pool.Get()
    defer pool.Put(c)

    return c.CallTool(ctx, req)
}

func createStreamableHTTPClientWithSession() {
    // Create StreamableHTTP client with options
    sessionID := // fetch existing session ID
    c := client.NewStreamableHttpClient("https://api.example.com/mcp",
        transport.WithSession(sessionID),
    )
    defer c.Close()

    ctx := context.Background()
    // Use client...
    _, err := c.ListTools(ctx, mcp.ListToolsRequest{})
    // If the session is terminated, you must reinitialize the client
    if errors.Is(err, transport.ErrSessionTerminated) {
        c.Initialize(ctx) // Reinitialize if session is terminated
        // The session ID should change after reinitialization
        sessionID = c.GetSessionId() // Update session ID
    }
}

func createSSEClient() {
    // Create SSE client
    c, err := client.NewSSEMCPClient("http://localhost:8080/mcp/sse",
        transport.WithHeaders(map[string]string{
            "Authorization": "Bearer your-token",
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()

    ctx := context.Background()

    // Initialize
    if err := c.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Subscribe to notifications
    notifications, err := c.Subscribe(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Handle notifications in background
    go func() {
        for notification := range notifications {
            log.Printf("Notification: %+v", notification)
        }
    }()

    // Use client for regular operations
    tools, err := c.ListTools(ctx, mcp.ListToolsRequest{})
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Available tools: %d", len(tools.Tools))
}

func createCustomSSEClient() {
    // Create custom logger for debugging
    logger := myCustomLogger{}

    // Create SSE client with custom options
    c, err := client.NewSSEMCPClient("http://localhost:8080/mcp/sse",
        transport.WithSSELogger(logger),
        transport.WithHeaders(map[string]string{
            "Authorization": "Bearer your-token",
            "User-Agent":    "MyApp/1.0",
        }),
        transport.WithHTTPClient(&http.Client{
            Timeout: 30 * time.Second,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()

    ctx := context.Background()

    // Initialize
    if err := c.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Use client...
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

func createInProcessClient() {
    // Create server
    s := server.NewMCPServer("Test Server", "1.0.0")

    // Add tools to server
    s.AddTool(
        mcp.NewTool("test_tool",
            mcp.WithDescription("Test tool"),
            mcp.WithString("input", mcp.Required()),
        ),
        func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            input := req.Params.Arguments["input"].(string)
            return mcp.NewToolResultText("Processed: " + input), nil
        },
    )

    // Create in-process client
    c := client.NewInProcessClient(s)
    defer c.Close()

    ctx := context.Background()

    // Initialize (no network overhead)
    if err := c.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Use client
    result, err := c.CallTool(ctx, mcp.CallToolRequest{
        Params: mcp.CallToolRequestParams{
            Name: "test_tool",
            Arguments: map[string]interface{}{
                "input": "test data",
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Tool result: %+v", result)
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

type myCustomLogger struct {}

func (myCustomLogger) Infof(format string, args ...any) {
    // TODO
}

func (myCustomLogger) Errorf(format string, args ...any) {
    // TODO
}

import (
    "log/slog"
    "os"

    "github.com/mark3labs/mcp-go/client"
    "github.com/mark3labs/mcp-go/client/transport"
)

func tracedClient() (*client.Client, error) {
    inner, err := transport.NewStdio("my-server", nil)
    if err != nil {
        return nil, err
    }

    logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
        Level: slog.LevelDebug,
    }))

    // Wrap the transport so every JSON-RPC message is logged.
    logged := transport.NewLogging(inner, logger,
        transport.WithLoggingLevel(slog.LevelDebug),
        transport.WithLoggingPayloads(true), // include params/result bodies
    )

    return client.NewClient(logged), nil
}

level=DEBUG msg="→ request"  method=initialize id=1
level=DEBUG msg="← response" method=initialize id=1 duration=12ms
level=DEBUG msg="→ request"  method=tools/list id=2
level=DEBUG msg="← response" method=tools/list id=2 duration=3ms
level=DEBUG msg="← notification" method=notifications/tools/list_changed

package main

import (
    "context"
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    // Create server
    mcpServer := server.NewMCPServer("my-server", "1.0.0")
    
    // Enable sampling capability
    mcpServer.EnableSampling()
    
    // Add tools that use sampling...
    
    // Start server
    server.ServeStdio(mcpServer)
}

/* Detailed source-code truncated for AI context efficiency. */

samplingRequest := mcp.CreateMessageRequest{
    CreateMessageParams: mcp.CreateMessageParams{
        // Required: Messages to send to the LLM
        Messages: []mcp.SamplingMessage{
            {
                Role: mcp.RoleUser,        // or mcp.RoleAssistant
                Content: mcp.TextContent{   // or mcp.ImageContent
                    Type: "text",
                    Text: "Your message here",
                },
            },
        },

        // Optional: System prompt for context
        SystemPrompt: "You are a helpful assistant.",

        // Optional: Maximum tokens to generate
        MaxTokens: 1000,

        // Optional: Temperature for randomness (0.0 to 1.0)
        Temperature: 0.7,

        // Optional: Stop sequences
        StopSequences: []string{"\\n\\n"},

        // Optional (2025-11-25): Context inclusion hint. Only send a value other
        // than "none" when the client advertised `sampling.context` — see
        // [Capability Gating](#capability-gating-2025-11-25) below.
        IncludeContext: "thisServer",

        // Optional (2025-11-25): Tools the model may use during generation, and
        // how aggressively the model should reach for them. Only send these when
        // the client advertised `sampling.tools`.
        Tools: []mcp.Tool{ /* ... */ },
        ToolChoice: &mcp.ToolChoice{Mode: mcp.ToolChoiceModeAuto},
    },
}

func askLLMWithTools(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    session := server.ClientSessionFromContext(ctx)
    sessionWithClient, ok := session.(server.SessionWithClientInfo)
    if !ok {
        return mcp.NewToolResultError("client session is not capability-aware"), nil
    }
    caps := sessionWithClient.GetClientCapabilities()

    params := mcp.CreateMessageParams{
        Messages:  []mcp.SamplingMessage{ /* ... */ },
        MaxTokens: 1000,
    }

    // Only attach Tools / ToolChoice if the client opted in.
    if caps.Sampling != nil && caps.Sampling.Tools != nil {
        params.Tools = []mcp.Tool{ /* ... */ }
        params.ToolChoice = &mcp.ToolChoice{Mode: mcp.ToolChoiceModeAuto}
    }

    // Only ask for context inclusion if the client opted in.
    if caps.Sampling != nil && caps.Sampling.Context != nil {
        params.IncludeContext = "thisServer"
    }

    result, err := mcpServer.RequestSampling(ctx, mcp.CreateMessageRequest{CreateMessageParams: params})
    // ...
}

// User message
{
    Role: mcp.RoleUser,
    Content: mcp.TextContent{
        Type: "text",
        Text: "What is the capital of France?",
    },
}

// Assistant message (for conversation context)
{
    Role: mcp.RoleAssistant,
    Content: mcp.TextContent{
        Type: "text", 
        Text: "The capital of France is Paris.",
    },
}

mcp.TextContent{
    Type: "text",
    Text: "Your text content here",
}

mcp.ImageContent{
    Type: "image",
    Data: "base64-encoded-image-data",
    MimeType: "image/jpeg",
}

// Assistant requesting a tool call
mcp.ToolUseContent{
    Type:  "tool_use",
    ID:    "tu_1",
    Name:  "get_weather",
    Input: map[string]any{"city": "London"},
}

// User-role message carrying the tool's output
mcp.ToolResultContent{
    Type:      "tool_result",
    ToolUseID: "tu_1",
    Content:   []mcp.Content{mcp.NewTextContent("Sunny, 22°C")},
}

result, err := mcpServer.RequestSampling(ctx, samplingRequest)
if err != nil {
    // Log the error
    log.Printf("Sampling request failed: %v", err)
    
    // Return appropriate error response
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            mcp.TextContent{
                Type: "text",
                Text: "Sorry, I couldn't process your request at this time.",
            },
        },
        IsError: true,
    }, nil
}

// Set a timeout for the sampling request
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

result, err := mcpServer.RequestSampling(ctx, samplingRequest)

/* Detailed source-code truncated for AI context efficiency. */

// Start STDIO server with sampling
server.ServeStdio(mcpServer)

// Create in-process client with sampling handler
mcpClient, err := client.NewInProcessClientWithSamplingHandler(mcpServer, samplingHandler)
if err != nil {
    log.Fatal(err)
}

mcp.Icon{
    Src:      "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiLz4=",
    MIMEType: "image/svg+xml",
}

icons := []mcp.Icon{
    {
        Src:      "https://example.com/icons/tool-light.svg",
        MIMEType: "image/svg+xml",
        Theme:    mcp.IconThemeLight,    // Designed for light backgrounds
    },
    {
        Src:      "https://example.com/icons/tool-dark.svg",
        MIMEType: "image/svg+xml",
        Theme:    mcp.IconThemeDark,     // Designed for dark backgrounds
    },
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

import (
    "path/filepath"
    "strings"

    "github.com/go-playground/validator/v10"
)

type FileOperationInput struct {
    Path      string `json:"path" validate:"required,filepath"`
    Operation string `json:"operation" validate:"required,oneof=read write delete"`
    Content   string `json:"content" validate:"required_if=Operation write"`
}

// Custom validator
func init() {
    validate := validator.New()
    validate.RegisterValidation("filepath", validateFilePath)
}

func validateFilePath(fl validator.FieldLevel) bool {
    path := fl.Field().String()
    
    // Prevent directory traversal
    if strings.Contains(path, "..") {
        return false
    }
    
    // Ensure path is within allowed directory
    allowedDir := "/app/data"
    absPath, err := filepath.Abs(path)
    if err != nil {
        return false
    }
    
    return strings.HasPrefix(absPath, allowedDir)
}

type SessionState struct {
    UserID      string
    Permissions []string
    Settings    map[string]interface{}
    StartTime   time.Time
}

type SessionManager struct {
    sessions map[string]*SessionState
    mutex    sync.RWMutex
}

func NewSessionManager() *SessionManager {
    return &SessionManager{
        sessions: make(map[string]*SessionState),
    }
}

func (sm *SessionManager) CreateSession(sessionID, userID string, permissions []string) {
    sm.mutex.Lock()
    defer sm.mutex.Unlock()
    
    sm.sessions[sessionID] = &SessionState{
        UserID:      userID,
        Permissions: permissions,
        Settings:    make(map[string]interface{}),
        StartTime:   time.Now(),
    }
}

func (sm *SessionManager) GetSession(sessionID string) (*SessionState, bool) {
    sm.mutex.RLock()
    defer sm.mutex.RUnlock()
    
    session, exists := sm.sessions[sessionID]
    return session, exists
}

func (sm *SessionManager) RemoveSession(sessionID string) {
    sm.mutex.Lock()
    defer sm.mutex.Unlock()
    
    delete(sm.sessions, sessionID)
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

type RateLimitMiddleware struct {
    limiters map[string]*rate.Limiter
    mutex    sync.RWMutex
    rate     rate.Limit
    burst    int
}

func NewRateLimitMiddleware(requestsPerSecond float64, burst int) *RateLimitMiddleware {
    return &RateLimitMiddleware{
        limiters: make(map[string]*rate.Limiter),
        rate:     rate.Limit(requestsPerSecond),
        burst:    burst,
    }
}

func (m *RateLimitMiddleware) getLimiter(sessionID string) *rate.Limiter {
    m.mutex.RLock()
    limiter, exists := m.limiters[sessionID]
    m.mutex.RUnlock()
    
    if !exists {
        m.mutex.Lock()
        limiter = rate.NewLimiter(m.rate, m.burst)
        m.limiters[sessionID] = limiter
        m.mutex.Unlock()
    }
    
    return limiter
}

func (m *RateLimitMiddleware) ToolMiddleware(next server.ToolHandler) server.ToolHandler {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        sessionID := server.GetSessionID(ctx)
        limiter := m.getLimiter(sessionID)
        
        if !limiter.Allow() {
            return nil, fmt.Errorf("rate limit exceeded for session %s", sessionID)
        }
        
        return next(ctx, req)
    }
}

type AuthMiddleware struct {
    tokenValidator TokenValidator
}

func NewAuthMiddleware(validator TokenValidator) *AuthMiddleware {
    return &AuthMiddleware{tokenValidator: validator}
}

func (m *AuthMiddleware) ToolMiddleware(next server.ToolHandler) server.ToolHandler {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        // Extract token from context or request
        token := extractToken(ctx, req)
        if token == "" {
            return nil, fmt.Errorf("authentication required")
        }
        
        // Validate token
        user, err := m.tokenValidator.Validate(token)
        if err != nil {
            return nil, fmt.Errorf("invalid token: %w", err)
        }
        
        // Add user to context
        ctx = context.WithValue(ctx, "user", user)
        
        return next(ctx, req)
    }
}

s := server.NewMCPServer("My Server", "1.0.0",
    server.WithHooks(initialHooks),
)

// Later, add more hooks without replacing existing ones
hooks := s.GetHooks()
if hooks == nil {
    hooks = &server.Hooks{}
}
hooks.AddBeforeAny(func(ctx context.Context, id any, method mcp.MCPMethod, message any) {
    log.Printf("Request: %s", method)
})

/* Detailed source-code truncated for AI context efficiency. */

type BusinessHooks struct {
    auditLogger AuditLogger
    notifier    Notifier
}

func (h *BusinessHooks) OnToolCall(sessionID, toolName string, duration time.Duration, err error) {
    // Audit sensitive operations
    if isSensitiveTool(toolName) {
        h.auditLogger.LogToolCall(sessionID, toolName, err)
    }
    
    // Alert on errors
    if err != nil {
        h.notifier.SendAlert(fmt.Sprintf("Tool %s failed for session %s: %v", 
            toolName, sessionID, err))
    }
    
    // Monitor performance
    if duration > 30*time.Second {
        h.notifier.SendAlert(fmt.Sprintf("Slow tool execution: %s took %v", 
            toolName, duration))
    }
}

func (h *BusinessHooks) OnSessionStart(sessionID string) {
    // Initialize user-specific resources
    h.initializeUserResources(sessionID)
    
    // Send welcome notification
    h.notifier.SendWelcome(sessionID)
}

func (h *BusinessHooks) OnSessionEnd(sessionID string) {
    // Cleanup user resources
    h.cleanupUserResources(sessionID)
    
    // Log session summary
    h.auditLogger.LogSessionEnd(sessionID)
}

type PermissionFilter struct {
    sessionManager *SessionManager
}

func NewPermissionFilter(sm *SessionManager) *PermissionFilter {
    return &PermissionFilter{sessionManager: sm}
}

func (f *PermissionFilter) FilterTools(ctx context.Context, tools []mcp.Tool) []mcp.Tool {
    sessionID := server.GetSessionID(ctx)
    session, exists := f.sessionManager.GetSession(sessionID)
    if !exists {
        return []mcp.Tool{} // No tools for invalid sessions
    }

    var filtered []mcp.Tool
    for _, tool := range tools {
        if f.hasPermissionForTool(session, tool.Name) {
            filtered = append(filtered, tool)
        }
    }
    
    return filtered
}

func (f *PermissionFilter) hasPermissionForTool(session *SessionState, toolName string) bool {
    requiredPermissions := map[string][]string{
        "delete_user":    {"admin"},
        "modify_system":  {"admin", "operator"},
        "read_data":      {"admin", "operator", "user"},
        "create_report":  {"admin", "operator", "user"},
    }
    
    required, exists := requiredPermissions[toolName]
    if !exists {
        return true // Allow tools without specific requirements
    }
    
    for _, permission := range session.Permissions {
        for _, req := range required {
            if permission == req {
                return true
            }
        }
    }
    
    return false
}

type ContextFilter struct{}

func (f *ContextFilter) FilterTools(ctx context.Context, tools []mcp.Tool) []mcp.Tool {
    timeOfDay := time.Now().Hour()
    environment := os.Getenv("ENVIRONMENT")
    
    var filtered []mcp.Tool
    for _, tool := range tools {
        if f.shouldIncludeTool(tool, timeOfDay, environment) {
            filtered = append(filtered, tool)
        }
    }
    
    return filtered
}

func (f *ContextFilter) shouldIncludeTool(tool mcp.Tool, hour int, env string) bool {
    // Maintenance tools only during off-hours
    maintenanceTools := map[string]bool{
        "backup_database":  true,
        "cleanup_logs":     true,
        "restart_service":  true,
    }
    
    if maintenanceTools[tool.Name] {
        return hour < 6 || hour > 22 // Only between 10 PM and 6 AM
    }
    
    // Debug tools only in development
    debugTools := map[string]bool{
        "debug_session": true,
        "dump_state":    true,
    }
    
    if debugTools[tool.Name] {
        return env == "development"
    }
    
    return true
}

func handleLongRunningTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    srv := server.ServerFromContext(ctx)
    
    // Simulate long-running work
    for i := 0; i < 100; i++ {
        time.Sleep(100 * time.Millisecond)
        
        // Send custom notification to all clients
        notification := map[string]interface{}{
            "type":     "progress",
            "progress": i + 1,
            "total":    100,
            "message":  fmt.Sprintf("Processing step %d/100", i+1),
        }
        
        srv.SendNotificationToAllClients("progress", notification)
    }
    
    return mcp.NewToolResultText("Long operation completed successfully"), nil
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

package main

import (
    "context"
    "fmt"

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

func main() {
    s := server.NewMCPServer("Typed Server", "1.0.0",
        server.WithToolCapabilities(true),
    )

     s.AddTool(
        mcp.NewTool("calculate",
            mcp.WithDescription("Perform basic mathematical calculations"),
            mcp.WithString("operation",
                mcp.Required(),
                mcp.Enum("add", "subtract", "multiply", "divide"),
                mcp.Description("The operation to perform"),
            ),
            mcp.WithNumber("x", mcp.Required(), mcp.Description("First number")),
            mcp.WithNumber("y", mcp.Required(), mcp.Description("Second number")),
        ),
        handleCalculate,
    )

    server.ServeStdio(s)
}

func handleCalculate(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    session := server.ClientSessionFromContext(ctx)
	if session == nil {
		return nil, fmt.Errorf("no active session")
	}

	if clientSession, ok := session.(server.SessionWithClientInfo); ok {
             clientCapabilities := clientSession.GetClientCapabilities()
			 if clientCapabilities.Sampling == nil {
				 fmt.Println("sampling is not enabled in client")
			 }
	}

    // TODO: implement calculation logic
    return mcp.NewToolResultError("not implemented"), nil
}

/* Detailed source-code truncated for AI context efficiency. */

audioResult := &mcp.CallToolResult{
    Content: []mcp.Content{
        mcp.AudioContent{
            Type:     "audio",
            Data:     base64EncodedAudioData,
            MIMEType: "audio/wav",
        },
    },
}

result := &mcp.CallToolResult{
    Content: []mcp.Content{
        mcp.ResourceLink{
            Type:        "resource_link",
            URI:         "files://reports/q4-summary.pdf",
            Name:        "Q4 Summary Report",
            Description: "Quarterly financial summary",
            MIMEType:    "application/pdf",
        },
    },
}

s := server.NewMCPServer("Server", "1.0.0",
    server.WithRoots(),
)

package main

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

func main() {
    // Create a basic server
    s := server.NewMCPServer(
        "My MCP Server",  // Server name
        "1.0.0",          // Server version
    )
    
    // Start the server (stdio transport)
    server.ServeStdio(s)
}

s := server.NewMCPServer(
    "Advanced Server",
    "2.0.0",
    server.WithToolCapabilities(true),      // Enable tools
    server.WithResourceCapabilities(true, true),  // Enable resources
    server.WithPromptCapabilities(true),    // Enable prompts
    server.WithRecovery(),                  // Add panic recovery
    server.WithHooks(myHooks),              // Add lifecycle hooks
    server.WithIcons(                       // Add server icons
        mcp.Icon{
            Src:      "https://example.com/server-icon.png",
            MIMEType: "image/png",
            Sizes:    []string{"48x48"},
        },
    ),
)

// Enable specific capabilities
s := server.NewMCPServer(
    "Specialized Server",
    "1.0.0",
    server.WithToolCapabilities(true),      // Can execute tools
    server.WithResourceCapabilities(true, true),  // Can provide resources
    server.WithPromptCapabilities(true),    // Can provide prompts
)

// Or enable all capabilities
s := server.NewMCPServer(
    "Full-Featured Server", 
    "1.0.0",
    server.WithToolCapabilities(true),
    server.WithResourceCapabilities(true, true),
    server.WithPromptCapabilities(true),
)

s := server.NewMCPServer(
    "Robust Server",
    "1.0.0", 
    server.WithRecovery(), // Automatically recover from panics
)

s := server.NewMCPServer(
    "My Server",
    "1.0.0",
    server.WithInstructions("A server that does amazing things"),
)

// These fields are set automatically from NewMCPServer args:
//   Name    string — server name
//   Version string — server version
//
// Additional optional fields on mcp.Implementation:
//   Title       string — human-readable display title
//   Description string — brief description of the server
//   WebsiteURL  string — URL for the server's website or docs
//   Icons       []Icon — visual identifiers for the implementation

s := server.NewMCPServer(
    "My Server",
    "1.0.0",
    server.WithTitle("My Server"),                                    // Human-readable display title
    server.WithDescription("A server that does amazing things"),     // Brief description
    server.WithWebsiteURL("https://example.com"),                    // Website or docs URL
    server.WithIcons(                                                // Visual identifiers
        mcp.Icon{
            Src:      "https://example.com/icon.png",
            MIMEType: "image/png",
            Sizes:    []string{"48x48"},
        },
    ),
)

s := server.NewMCPServer("My Server", "1.0.0",
    // Set experimental capabilities
    server.WithExperimental(map[string]any{
        "claude/channel": map[string]any{
            "supported": true,
        },
    }),
)

func main() {
    s := server.NewMCPServer("My Server", "1.0.0")
    
    // Start stdio server (blocks until terminated)
    if err := server.ServeStdio(s); err != nil {
        log.Fatal(err)
    }
}

func main() {
    s := server.NewMCPServer("HTTP Server", "1.0.0")
    
    // Create HTTP server
    httpServer := server.NewStreamableHTTPServer(s)
    
    // Start HTTP server on port 8080
    if err := httpServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}

func main() {
    s := server.NewMCPServer("SSE Server", "1.0.0")
    
    // Create SSE server
    sseServer := server.NewSSEServer(s)
    
    // Start SSE server on port 8080
    if err := sseServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}

// HTTP with custom options
httpServer := server.NewStreamableHTTPServer(s,
    server.WithEndpointPath("/mcp"),
    server.WithStateLess(true),
    server.WithTLSCert("/path/to/cert.pem", "/path/to/key.pem"),
)

if err := httpServer.Start(":8080"); err != nil {
    log.Fatal(err)
}

// SSE with custom options
sseServer := server.NewSSEServer(s,
    server.WithSSEEndpoint("/events"),
    server.WithMessageEndpoint("/message"),
    server.WithKeepAlive(true),
)

if err := sseServer.Start(":8080"); err != nil {
    log.Fatal(err)
}

func main() {
    s := server.NewMCPServer("Configurable Server", "1.0.0")
    
    // Choose transport based on environment
    transport := os.Getenv("MCP_TRANSPORT")
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    
    switch transport {
    case "http":
        httpServer := server.NewStreamableHTTPServer(s)
        httpServer.Start(":"+port)
    case "sse":
        sseServer := server.NewSSEServer(s)
        sseServer.Start(":"+port)
    default:
        server.ServeStdio(s)
    }
}
}

func main() {
    hooks := &server.Hooks{}
    
    // Add session lifecycle hooks
    hooks.AddOnRegisterSession(func(ctx context.Context, session server.ClientSession) {
        log.Printf("Client %s connected", session.ID())
    })
    
    hooks.AddOnUnregisterSession(func(ctx context.Context, session server.ClientSession) {
        log.Printf("Client %s disconnected", session.ID())
    })
    
    // Add request hooks
    hooks.AddBeforeAny(func(ctx context.Context, id any, method mcp.MCPMethod, message any) {
        log.Printf("Processing %s request", method)
    })
    
    hooks.AddOnError(func(ctx context.Context, id any, method mcp.MCPMethod, message any, err error) {
        log.Printf("Error in %s: %v", method, err)
    })
    
    s := server.NewMCPServer("Lifecycle Server", "1.0.0",
        server.WithHooks(hooks),
    )
    
    // Graceful shutdown
    c := make(chan os.Signal, 1)
    signal.Notify(c, os.Interrupt, syscall.SIGTERM)
    
    go func() {
        <-c
        log.Println("Shutting down server...")
        s.Shutdown()
    }()
    
    server.ServeStdio(s)
}

func main() {
    s := server.NewMCPServer("Error-Safe Server", "1.0.0",
        server.WithRecovery(), // Panic recovery
    )
    
    // Add error handling for server startup
    if err := server.ServeStdio(s); err != nil {
        if errors.Is(err, server.ErrServerClosed) {
            log.Println("Server closed gracefully")
        } else {
            log.Fatalf("Server error: %v", err)
        }
    }
}

s := server.NewMCPServer("Completion Server", "1.0.0",
    server.WithPromptCapabilities(true),
    server.WithResourceCapabilities(true, true),
    server.WithCompletions(), // Enable the completion capability
)

type PromptCompletionProvider interface {
    CompletePromptArgument(ctx context.Context, promptName string, argument mcp.CompleteArgument, context mcp.CompleteContext) (*mcp.Completion, error)
}

type MyPromptCompletionProvider struct {
    prompts map[string][]string // prompt name -> known argument values
}

func (p *MyPromptCompletionProvider) CompletePromptArgument(
    ctx context.Context,
    promptName string,
    argument mcp.CompleteArgument,
    compCtx mcp.CompleteContext,
) (*mcp.Completion, error) {
    // Return completions based on the prompt name and argument
    switch promptName {
    case "code_review":
        if argument.Name == "language" {
            languages := []string{"go", "python", "javascript", "rust", "java"}
            // Filter by what the user has typed so far
            var matches []string
            for _, lang := range languages {
                if strings.HasPrefix(lang, strings.ToLower(argument.Value)) {
                    matches = append(matches, lang)
                }
            }
            return &mcp.Completion{
                Values:  matches,
                HasMore: false,
            }, nil
        }
    }
    return &mcp.Completion{Values: []string{}}, nil
}

s := server.NewMCPServer("Server", "1.0.0",
    server.WithCompletions(),
    server.WithPromptCompletionProvider(&MyPromptCompletionProvider{}),
)

type ResourceCompletionProvider interface {
    CompleteResourceArgument(ctx context.Context, uri string, argument mcp.CompleteArgument, context mcp.CompleteContext) (*mcp.Completion, error)
}

type MyResourceCompletionProvider struct{}

func (p *MyResourceCompletionProvider) CompleteResourceArgument(
    ctx context.Context,
    uri string,
    argument mcp.CompleteArgument,
    compCtx mcp.CompleteContext,
) (*mcp.Completion, error) {
    // Provide completions for resource URI template parameters
    if strings.HasPrefix(uri, "db://") && argument.Name == "table" {
        tables := []string{"users", "orders", "products", "inventory"}
        var matches []string
        for _, t := range tables {
            if strings.HasPrefix(t, argument.Value) {
                matches = append(matches, t)
            }
        }
        return &mcp.Completion{
            Values:  matches,
            HasMore: false,
        }, nil
    }
    return &mcp.Completion{Values: []string{}}, nil
}

s := server.NewMCPServer("Server", "1.0.0",
    server.WithCompletions(),
    server.WithResourceCompletionProvider(&MyResourceCompletionProvider{}),
)

type Completion struct {
    // An array of completion values. Must not exceed 100 items.
    Values []string `json:"values"`
    // The total number of completion options available. This can exceed the
    // number of values actually sent in the response.
    Total int `json:"total,omitempty"`
    // Indicates whether there are additional completion options beyond those
    // provided in the current response, even if the exact total is unknown.
    HasMore bool `json:"hasMore,omitempty"`
}

// CompleteArgument is the argument the client is asking about.
type CompleteArgument struct {
    Name  string `json:"name"`  // Argument name
    Value string `json:"value"` // What the user has typed so far
}

// CompleteContext holds values for arguments that are already resolved.
type CompleteContext struct {
    Arguments map[string]string `json:"arguments"`
}

package main

import (
    "context"
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    // Create server with elicitation capability
    s := server.NewMCPServer("Elicitation Server", "1.0.0",
        server.WithElicitation(),
    )

    // Add tools that use elicitation...

    // Start server
    server.ServeStdio(s)
}

type ElicitationParams struct {
    Meta            *Meta  `json:"_meta,omitempty"`
    Mode            string `json:"mode,omitempty"`            // "form" or "url", defaults to "form"
    Message         string `json:"message"`                   // Human-readable message

    // Form mode fields
    RequestedSchema any    `json:"requestedSchema,omitempty"` // JSON Schema for the form

    // URL mode fields
    ElicitationID   string `json:"elicitationId,omitempty"`   // Unique ID for tracking
    URL             string `json:"url,omitempty"`             // URL for the user to visit
}

mcp.ElicitationResponseActionAccept   // User provided the requested information
mcp.ElicitationResponseActionDecline  // User explicitly declined
mcp.ElicitationResponseActionCancel   // User cancelled without making a choice

type ElicitationResult struct {
    Result
    ElicitationResponse
}

type ElicitationResponse struct {
    Action  ElicitationResponseAction `json:"action"`
    Content any                       `json:"content,omitempty"` // User's response data
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

mcpServer.AddTool(
    mcp.NewTool(
        "auth_via_url",
        mcp.WithDescription("Authenticate via browser"),
    ),
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        session := server.ClientSessionFromContext(ctx)
        if session == nil {
            return nil, fmt.Errorf("no active session")
        }

        // Generate a unique elicitation ID for tracking
        elicitationID := uuid.New().String()
        url := fmt.Sprintf("https://myserver.com/auth?id=%s", elicitationID)

        // Send the URL elicitation request
        result, err := mcpServer.RequestURLElicitation(
            ctx,
            session,
            elicitationID,
            url,
            "Please authenticate in your browser to continue.",
        )
        if err != nil {
            return nil, fmt.Errorf("URL elicitation failed: %w", err)
        }

        if result.Action == mcp.ElicitationResponseActionAccept {
            return &mcp.CallToolResult{
                Content: []mcp.Content{
                    mcp.NewTextContent("Authentication flow initiated. Complete the process in your browser."),
                },
            }, nil
        }

        return &mcp.CallToolResult{
            Content: []mcp.Content{
                mcp.NewTextContent(fmt.Sprintf("User declined authentication: %s", result.Action)),
            },
        }, nil
    },
)

// Send after the server receives the callback from the browser
err := mcpServer.SendElicitationComplete(ctx, session, elicitationID)
if err != nil {
    log.Printf("Failed to send completion notification: %v", err)
}

notification := mcp.NewElicitationCompleteNotification("elicitation-id-123")

func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    if !isAuthorized(ctx) {
        elicitationID := uuid.New().String()
        return nil, mcp.URLElicitationRequiredError{
            Elicitations: []mcp.ElicitationParams{
                {
                    Mode:          mcp.ElicitationModeURL,
                    ElicitationID: elicitationID,
                    URL:           fmt.Sprintf("https://myserver.com/authorize?id=%s", elicitationID),
                    Message:       "Authorization is required to access this resource.",
                },
            },
        }
    }

    return mcp.NewToolResultText("Action completed successfully!"), nil
}

type ElicitationHandler interface {
    Elicit(ctx context.Context, request mcp.ElicitationRequest) (*mcp.ElicitationResult, error)
}

import "github.com/mark3labs/mcp-go/client"

handler := &MyElicitationHandler{}
c := client.NewClient(transport, client.WithElicitationHandler(handler))

type ElicitationCapability struct {
    Form *struct{} `json:"form,omitempty"` // Supports form mode
    URL  *struct{} `json:"url,omitempty"`  // Supports URL mode
}

result, err := mcpServer.RequestElicitation(ctx, elicitationRequest)
if err != nil {
    // Common errors:
    // - server.ErrNoActiveSession: no session in context
    // - server.ErrElicitationNotSupported: session/transport doesn't support elicitation
    // - validation errors from ElicitationParams.Validate()
    log.Printf("Elicitation failed: %v", err)
    return mcp.NewToolResultError(fmt.Sprintf("Could not request information: %v", err)), nil
}

ctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
defer cancel()

result, err := mcpServer.RequestElicitation(ctx, elicitationRequest)

type ToolHandlerFunc func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)

type ToolHandlerMiddleware func(ToolHandlerFunc) ToolHandlerFunc

s := server.NewMCPServer("my-server", "1.0.0")

// Register a single middleware
s.Use(loggingMiddleware)

// Register multiple middlewares at once
s.Use(authMiddleware, rateLimitMiddleware)

s := server.NewMCPServer("my-server", "1.0.0",
    server.WithToolHandlerMiddleware(loggingMiddleware),
    server.WithResourceHandlerMiddleware(resourceLogger),
    server.WithPromptHandlerMiddleware(promptLogger),
)

import (
    "context"
    "log"

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

func loggingMiddleware(next server.ToolHandlerFunc) server.ToolHandlerFunc {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        log.Printf("tool call: %s", req.Params.Name)
        return next(ctx, req)
    }
}

s := server.NewMCPServer("my-server", "1.0.0")
s.Use(loggingMiddleware)

func timingMiddleware(next server.ToolHandlerFunc) server.ToolHandlerFunc {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        start := time.Now()
        result, err := next(ctx, req)
        log.Printf("tool=%s duration=%v", req.Params.Name, time.Since(start))
        return result, err
    }
}

// userKey is a custom context key for storing the authenticated user.
type contextKey string
const userKey contextKey = "user"

func authMiddleware(next server.ToolHandlerFunc) server.ToolHandlerFunc {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        token := extractToken(ctx) // your token extraction logic
        if token == "" {
            return nil, fmt.Errorf("authentication required")
        }

        user, err := validateToken(token) // your token validation logic
        if err != nil {
            return nil, fmt.Errorf("invalid token: %w", err)
        }

        ctx = context.WithValue(ctx, userKey, user)
        return next(ctx, req)
    }
}

type rateLimiter struct {
    limiters sync.Map
    rate     rate.Limit
    burst    int
}

func newRateLimiter(rps float64, burst int) *rateLimiter {
    return &rateLimiter{rate: rate.Limit(rps), burst: burst}
}

func (r *rateLimiter) middleware(next server.ToolHandlerFunc) server.ToolHandlerFunc {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        sessionID := server.GetSessionID(ctx)
        limiter, _ := r.limiters.LoadOrStore(sessionID, rate.NewLimiter(r.rate, r.burst))
        if !limiter.(*rate.Limiter).Allow() {
            return nil, fmt.Errorf("rate limit exceeded")
        }
        return next(ctx, req)
    }
}

// Usage
rl := newRateLimiter(10, 20)
s.Use(rl.middleware)

s.Use(A, B)
s.Use(C)

// Call order: A → B → C → tool handler → C → B → A

tool := mcp.NewTool("long-running",
    mcp.WithDescription("A tool that supports task mode"),
    mcp.WithTaskSupport(mcp.TaskSupportOptional),
)
s.AddTool(tool, handler)

// This middleware applies to regular calls and when this regular tool is executed via the task path
s.Use(loggingMiddleware)

s := server.NewMCPServer("my-server", "1.0.0",
    server.WithRecovery(),
)

// Create a simple prompt
prompt := mcp.NewPrompt("code_review",
    mcp.WithPromptDescription("Review code for best practices and issues"),
    mcp.WithPromptArgument("code",
        mcp.Required(),
        mcp.Description("The code to review"),
    ),
    mcp.WithPromptArgument("language",
        mcp.Description("Programming language"),
        mcp.Default("auto-detect"),
    ),
)

prompt := mcp.NewPrompt("code_review",
    mcp.WithPromptDescription("Review code for best practices"),
    mcp.WithPromptIcons(
        mcp.Icon{
            Src:      "https://example.com/icons/review.png",
            MIMEType: "image/png",
        },
    ),
    // ... arguments
)

prompt := mcp.NewPrompt("code_review",
    mcp.WithPromptTitle("Code Review"),                            // Shown in UI
    mcp.WithPromptDescription("Review code for best practices"),
    mcp.WithArgument("code",
        mcp.ArgumentTitle("Source Code"),                          // Argument display name
        mcp.ArgumentDescription("The code to review"),
        mcp.RequiredArgument(),
    ),
)

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

s := server.NewMCPServer("Prompt Server", "1.0.0",
    server.WithPromptCapabilities(true),
    server.WithPromptFilter(func(ctx context.Context, prompts []mcp.Prompt) []mcp.Prompt {
        session := server.ClientSessionFromContext(ctx)
        if session == nil {
            return nil
        }

        // Filter prompts based on session or context
        var filtered []mcp.Prompt
        for _, p := range prompts {
            if shouldExposePrompt(ctx, p) {
                filtered = append(filtered, p)
            }
        }
        return filtered
    }),
)

s := server.NewMCPServer("Server", "1.0.0",
    server.WithPromptCapabilities(true),
    server.WithPromptFilter(roleFilter),
    server.WithPromptFilter(environmentFilter),
)

s := server.NewMCPServer("Server", "1.0.0",
    server.WithPromptCapabilities(true),
    server.WithPromptHandlerMiddleware(func(next server.PromptHandlerFunc) server.PromptHandlerFunc {
        return func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
            start := time.Now()
            log.Printf("Prompt requested: %s", req.Params.Name)

            result, err := next(ctx, req)

            log.Printf("Prompt %s served in %v", req.Params.Name, time.Since(start))
            return result, err
        }
    }),
)

s := server.NewMCPServer("Server", "1.0.0",
    server.WithPromptCapabilities(true),
    server.WithPromptHandlerMiddleware(loggingMiddleware),
    server.WithPromptHandlerMiddleware(authMiddleware),
)

// Create a simple resource
resource := mcp.NewResource(
    "docs://readme",           // URI - unique identifier
    "Project README",          // Name - human-readable
    mcp.WithResourceDescription("Main project documentation"),
    mcp.WithMIMEType("text/markdown"),
)

resource := mcp.NewResource(
    "docs://readme",
    "Project README",
    mcp.WithResourceDescription("Main project documentation"),
    mcp.WithMIMEType("text/markdown"),
    mcp.WithResourceIcons(
        mcp.Icon{
            Src:      "https://example.com/icons/document.svg",
            MIMEType: "image/svg+xml",
        },
    ),
)

resource := mcp.NewResource(
    "docs://readme",
    "readme.md",                                          // name (stable identifier)
    mcp.WithResourceTitle("Project README"),              // Shown in UI
    mcp.WithResourceDescription("Main project documentation"),
    mcp.WithMIMEType("text/markdown"),
)

// Same option exists on resource templates
template := mcp.NewResourceTemplate(
    "users://{user_id}",
    "user-profile",
    mcp.WithTemplateTitle("User Profile"),
    mcp.WithTemplateDescription("Profile information for a specific user"),
)

resource := mcp.NewResource(
    "file:///var/log/app.log",
    "app.log",
    mcp.WithResourceTitle("Application Log"),
    mcp.WithMIMEType("text/plain"),
    mcp.WithResourceSize(2_048_576),    // 2 MiB, measured before base64 encoding
)

func main() {
    s := server.NewMCPServer("File Server", "1.0.0",
        server.WithResourceCapabilities(true),
    )

    // Add a static file resource
    s.AddResource(
        mcp.NewResource(
            "file://README.md",
            "Project README",
            mcp.WithResourceDescription("Main project documentation"),
            mcp.WithMIMEType("text/markdown"),
        ),
        handleReadmeFile,
    )

    server.ServeStdio(s)
}

func handleReadmeFile(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    content, err := os.ReadFile("README.md")
    if err != nil {
        return nil, fmt.Errorf("failed to read README: %w", err)
    }

    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            {
                URI:      req.Params.URI,
                MIMEType: "text/markdown",
                Text:     string(content),
            },
        },
    }, nil
}

// Configuration resource
s.AddResource(
    mcp.NewResource(
        "config://app",
        "Application Configuration", 
        mcp.WithResourceDescription("Current application settings"),
        mcp.WithMIMEType("application/json"),
    ),
    handleAppConfig,
)

func handleAppConfig(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    config := map[string]interface{}{
        "database_url": os.Getenv("DATABASE_URL"),
        "debug_mode":   os.Getenv("DEBUG") == "true",
        "version":      "1.0.0",
        "features": []string{
            "authentication",
            "caching", 
            "logging",
        },
    }

    configJSON, err := json.Marshal(config)
    if err != nil {
        return nil, err
    }
    
    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            mcp.TextResourceContent{
                URI:      req.Params.URI,
                MIMEType: "application/json",
                Text:     string(configJSON),
            },
        },
    }, nil
}

// User profile resource with dynamic user ID
s.AddResource(
    mcp.NewResource(
        "users://{user_id}",
        "User Profile",
        mcp.WithResourceDescription("User profile information"),
        mcp.WithMIMEType("application/json"),
    ),
    handleUserProfile,
)

func handleUserProfile(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    // Extract user_id from URI
    userID := extractUserID(req.Params.URI) // "users://123" -> "123"
    
    // Fetch user data (from database, API, etc.)
    user, err := getUserFromDB(userID)
    if err != nil {
        return nil, fmt.Errorf("user not found: %w", err)
    }

    jsonData, err := json.Marshal(user)
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      req.Params.URI,
            MIMEType: "application/json",
            Text:     string(jsonData),
        },
    }, nil
}

func extractUserID(uri string) string {
    // Extract ID from "users://123" format
    parts := strings.Split(uri, "://")
    if len(parts) == 2 {
        return parts[1]
    }
    return ""
}

/* Detailed source-code truncated for AI context efficiency. */

// Weather API resource
s.AddResource(
    mcp.NewResource(
        "weather://{location}",
        "Weather Data",
        mcp.WithResourceDescription("Current weather for a location"),
        mcp.WithMIMEType("application/json"),
    ),
    handleWeatherData,
)

func handleWeatherData(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    location := extractLocation(req.Params.URI)
    
    // Call external weather API
    apiURL := fmt.Sprintf("https://api.weather.com/v1/current?location=%s&key=%s", 
        url.QueryEscape(location), os.Getenv("WEATHER_API_KEY"))
    
    resp, err := http.Get(apiURL)
    if err != nil {
        return nil, fmt.Errorf("weather API error: %w", err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("failed to read response: %w", err)
    }

    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            {
                URI:      req.Params.URI,
                MIMEType: "application/json",
                Text:     string(body),
            },
        },
    }, nil
}

func handleTextResource(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    content := "This is plain text content"
    
    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            {
                URI:      req.Params.URI,
                MIMEType: "text/plain",
                Text:     content,
            },
        },
    }, nil
}

func handleJSONResource(ctx context.Context, req mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    data := map[string]interface{}{
        "message": "Hello, World!",
        "timestamp": time.Now().Unix(),
        "status": "success",
    }
    
    jsonData, err := json.Marshal(data)
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      req.Params.URI,
            MIMEType: "application/json",
            Text:     string(jsonData),
        },
    }, nil
}

func handleImageResource(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    imageData, err := os.ReadFile("logo.png")
    if err != nil {
        return nil, err
    }
    
    // Encode binary data as base64
    encoded := base64.StdEncoding.EncodeToString(imageData)
    
    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            {
                URI:      req.Params.URI,
                MIMEType: "image/png",
                Blob:     encoded,
            },
        },
    }, nil
}

func handleMultiFormatResource(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    data := map[string]interface{}{
        "name": "John Doe",
        "age":  30,
        "city": "New York",
    }
    
    // JSON representation
    jsonData, _ := json.Marshal(data)
    
    // Text representation  
    textData := fmt.Sprintf("Name: %s\nAge: %d\nCity: %s", 
        data["name"], data["age"], data["city"])
    
    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            {
                URI:      req.Params.URI,
                MIMEType: "application/json",
                Text:     string(jsonData),
            },
            {
                URI:      req.Params.URI,
                MIMEType: "text/plain", 
                Text:     textData,
            },
        },
    }, nil
}

func handleResourceWithErrors(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    // Validate URI format
    if !isValidURI(req.Params.URI) {
        return nil, fmt.Errorf("invalid URI format: %s", req.Params.URI)
    }
    
    // Check permissions
    if !hasPermission(ctx, req.Params.URI) {
        return nil, fmt.Errorf("access denied to resource: %s", req.Params.URI)
    }
    
    // Handle resource not found
    data, err := fetchResourceData(req.Params.URI)
    if err != nil {
        if errors.Is(err, ErrResourceNotFound) {
            return nil, fmt.Errorf("resource not found: %s", req.Params.URI)
        }
        return nil, fmt.Errorf("failed to fetch resource: %w", err)
    }
    
    jsonData, err := json.Marshal(data)
    if err != nil {
        return nil, err
    }
    
    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContents{
            mcp.TextResourceContents{
                URI:      req.Params.URI,
                MIMEType: "application/json",
                Text:     string(jsonData),
            },
        },
    }, nil
}

func handleResourceWithTimeout(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    // Create timeout context
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()
    
    // Use context in operations
    data, err := fetchDataWithContext(ctx, req.Params.URI)
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            return nil, fmt.Errorf("resource fetch timeout: %s", req.Params.URI)
        }
        return nil, err
    }
    
    jsonData, err := json.Marshal(data)
    if err != nil {
        return nil, err
    }
    
    return &mcp.ReadResourceResult{
        Contents: []mcp.ResourceContent{
            mcp.TextResourceContent{
                URI:      req.Params.URI,
                MIMEType: "application/json",
                Text:     string(jsonData),
            },
        },
    }, nil
}
}

func main() {
    s := server.NewMCPServer("Resource Server", "1.0.0",
        server.WithResourceCapabilities(true),
    )

    // Add multiple resources
    resources := []struct {
        uri         string
        name        string
        description string
        mimeType    string
        handler     server.ResourceHandler
    }{
        {"docs://readme", "README", "Project documentation", "text/markdown", handleReadme},
        {"config://app", "App Config", "Application settings", "application/json", handleConfig},
        {"users://{id}", "User Profile", "User information", "application/json", handleUser},
    }

    for _, r := range resources {
        s.AddResource(
            mcp.NewResource(r.uri, r.name,
                mcp.WithResourceDescription(r.description),
                mcp.WithMIMEType(r.mimeType),
            ),
            r.handler,
        )
    }

    server.ServeStdio(s)
}

type CachedResourceHandler struct {
    cache map[string]cacheEntry
    mutex sync.RWMutex
    ttl   time.Duration
}

type cacheEntry struct {
    data      *mcp.ReadResourceResult
    timestamp time.Time
}

func (h *CachedResourceHandler) HandleResource(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    h.mutex.RLock()
    if entry, exists := h.cache[req.Params.URI]; exists {
        if time.Since(entry.timestamp) < h.ttl {
            h.mutex.RUnlock()
            return entry.data, nil
        }
    }
    h.mutex.RUnlock()

    // Fetch fresh data
    data, err := h.fetchFreshData(ctx, req)
    if err != nil {
        return nil, err
    }

    // Cache the result
    h.mutex.Lock()
    h.cache[req.Params.URI] = cacheEntry{
        data:      data,
        timestamp: time.Now(),
    }
    h.mutex.Unlock()

    return data, nil
}

s := server.NewMCPServer("Resource Server", "1.0.0",
    // (subscribe, listChanged)
    server.WithResourceCapabilities(true, true),
)

type mySession struct {
    server.ClientSession
    mu   sync.Mutex
    subs map[string]struct{}
}

func (s *mySession) SubscribeToResource(uri string) {
    s.mu.Lock()
    defer s.mu.Unlock()
    if s.subs == nil {
        s.subs = make(map[string]struct{})
    }
    s.subs[uri] = struct{}{}
}

func (s *mySession) UnsubscribeFromResource(uri string) {
    s.mu.Lock()
    defer s.mu.Unlock()
    delete(s.subs, uri)
}

func (s *mySession) SubscribedResources() []string {
    s.mu.Lock()
    defer s.mu.Unlock()
    out := make([]string, 0, len(s.subs))
    for uri := range s.subs {
        out = append(out, uri)
    }
    return out
}

func (s *mySession) IsSubscribedToResource(uri string) bool {
    s.mu.Lock()
    defer s.mu.Unlock()
    _, ok := s.subs[uri]
    return ok
}

var (
    sessionsMu sync.Mutex
    sessions   = map[string]server.ClientSession{}
)

hooks := &server.Hooks{}
hooks.AddOnRegisterSession(func(ctx context.Context, session server.ClientSession) {
    sessionsMu.Lock()
    defer sessionsMu.Unlock()
    sessions[session.SessionID()] = session
})
hooks.AddOnUnregisterSession(func(ctx context.Context, session server.ClientSession) {
    sessionsMu.Lock()
    defer sessionsMu.Unlock()
    delete(sessions, session.SessionID())
})

func notifyResourceUpdated(s *server.MCPServer, uri string) {
    sessionsMu.Lock()
    snapshot := make([]server.ClientSession, 0, len(sessions))
    for _, sess := range sessions {
        snapshot = append(snapshot, sess)
    }
    sessionsMu.Unlock()

    for _, sess := range snapshot {
        subs, ok := sess.(server.SessionWithResourceSubscriptions)
        if !ok || !subs.IsSubscribedToResource(uri) {
            continue
        }
        _ = s.SendNotificationToSpecificClient(
            sess.SessionID(),
            "notifications/resources/updated",
            map[string]any{"uri": uri},
        )
    }
}

hooks := &server.Hooks{}
hooks.AddBeforeSubscribe(func(ctx context.Context, id any, req *mcp.SubscribeRequest) {
    log.Printf("subscribe: %s", req.Params.URI)
})
hooks.AddAfterUnsubscribe(func(ctx context.Context, id any, req *mcp.UnsubscribeRequest, _ *mcp.EmptyResult) {
    log.Printf("unsubscribed: %s", req.Params.URI)
})

s := server.NewMCPServer("Resource Server", "1.0.0",
    server.WithResourceCapabilities(true, true),
    server.WithHooks(hooks),
)

/* Detailed source-code truncated for AI context efficiency. */

sseServer := server.NewSSEServer(
    s,
    server.WithAppendQueryToMessageEndpoint(),
    server.WithSSEContextFunc(func(ctx context.Context, r *http.Request) context.Context {
        withNewResources := r.URL.Query().Get("withNewResources")
        if withNewResources != "1" {
            return ctx
        }

        session := server.ClientSessionFromContext(ctx)
        if sessionWithResources, ok := session.(server.SessionWithResources); ok {
            // Add the new resources
            sessionWithResources.SetSessionResources(map[string]server.ServerResource{
                myNewResource.URI: {
                    Resource: myNewResource,
                    Handler:  myNewResourceHandler,
                },
            })
        }

        return ctx
    }),
)

// Set task support when creating a tool
tool := mcp.NewTool("long_process",
    mcp.WithDescription("A long-running operation"),
    mcp.WithTaskSupport(mcp.TaskSupportRequired),
)

s := server.NewMCPServer("Task Server", "1.0.0",
    server.WithToolCapabilities(true),
    server.WithTaskCapabilities(true, true, true), // list, cancel, toolCallTasks
)

tool := mcp.NewTool("long_process",
    mcp.WithDescription("Run a long process asynchronously"),
    mcp.WithTaskSupport(mcp.TaskSupportRequired),
    mcp.WithString("input", mcp.Required(), mcp.Description("Input data")),
)

s.AddTaskTool(tool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    input := req.GetString("input", "")

    // Do the actual work here — this runs in the background.
    // Check ctx.Done() to support cancellation.
    for i := 0; i < 100; i++ {
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        default:
            // simulate work
            time.Sleep(100 * time.Millisecond)
        }
    }

    // Return result — the server manages the Task lifecycle
    return &mcp.CreateTaskResult{
        Task: mcp.NewTask("unique-task-id",
            mcp.WithTaskStatusMessage("Processing started"),
            mcp.WithTaskPollInterval(2000), // suggest polling every 2s
            mcp.WithTaskTTL(300000),        // task expires after 5 minutes
        ),
    }, nil
})

s.AddTaskTools(
    server.ServerTaskTool{Tool: tool1, Handler: handler1},
    server.ServerTaskTool{Tool: tool2, Handler: handler2},
)

type TaskToolHandlerFunc func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CreateTaskResult, error)

Working ──→ Completed
       ──→ Failed
       ──→ Cancelled
       ──→ InputRequired ──→ Working (resumed)

task := mcp.NewTask("my-task")

// Later, check if the task is done
if task.Status.IsTerminal() {
    // task is Completed, Failed, or Cancelled
}

task := mcp.NewTask("task-123",
    mcp.WithTaskStatus(mcp.TaskStatusWorking),       // set initial status (default: Working)
    mcp.WithTaskStatusMessage("Initializing..."),     // human-readable status message
    mcp.WithTaskTTL(300000),                          // TTL in milliseconds (5 minutes)
    mcp.WithTaskPollInterval(2000),                   // suggested poll interval in ms
    mcp.WithTaskCreatedAt("2025-01-15T10:30:00Z"),    // custom creation timestamp
)

s.AddTaskTool(tool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    // ... start processing ...

    task := mcp.NewTask("task-456",
        mcp.WithTaskStatusMessage("Processing started"),
        mcp.WithTaskPollInterval(5000),
    )

    return &mcp.CreateTaskResult{
        Task: task,
        Result: mcp.Result{
            Meta: mcp.WithModelImmediateResponse("Processing your request. This may take a few minutes."),
        },
    }, nil
})

meta := mcp.WithRelatedTask("task-id-123")

taskHooks := &server.TaskHooks{}

taskHooks.AddOnTaskCreated(func(ctx context.Context, metrics server.TaskMetrics) {
    log.Printf("Task %s created for tool %s", metrics.TaskID, metrics.ToolName)
})

taskHooks.AddOnTaskCompleted(func(ctx context.Context, metrics server.TaskMetrics) {
    log.Printf("Task %s completed in %v", metrics.TaskID, metrics.Duration)
})

taskHooks.AddOnTaskFailed(func(ctx context.Context, metrics server.TaskMetrics) {
    log.Printf("Task %s failed: %v", metrics.TaskID, metrics.Error)
})

taskHooks.AddOnTaskCancelled(func(ctx context.Context, metrics server.TaskMetrics) {
    log.Printf("Task %s was cancelled", metrics.TaskID)
})

taskHooks.AddOnTaskStatusChanged(func(ctx context.Context, metrics server.TaskMetrics) {
    log.Printf("Task %s status: %s", metrics.TaskID, metrics.Status)
})

s := server.NewMCPServer("Task Server", "1.0.0",
    server.WithToolCapabilities(true),
    server.WithTaskCapabilities(true, true, true),
    server.WithTaskHooks(taskHooks),
)

s := server.NewMCPServer("Task Server", "1.0.0",
    server.WithToolCapabilities(true),
    server.WithTaskCapabilities(true, true, true),
    server.WithMaxConcurrentTasks(10),
)

/* Detailed source-code truncated for AI context efficiency. */

// Create a simple tool
tool := mcp.NewTool("calculate",
    mcp.WithDescription("Perform arithmetic operations"),
    mcp.WithString("operation", 
        mcp.Required(),
        mcp.Enum("add", "subtract", "multiply", "divide"),
        mcp.Description("The arithmetic operation to perform"),
    ),
    mcp.WithNumber("x", mcp.Required(), mcp.Description("First number")),
    mcp.WithNumber("y", mcp.Required(), mcp.Description("Second number")),
)

tool := mcp.NewTool("calculate_arithmetic",
    mcp.WithToolTitle("Calculator"),               // Shown in UI
    mcp.WithDescription("Perform arithmetic operations"),
    // ... parameters
)

tool := mcp.NewTool("calculate",
    mcp.WithDescription("Perform arithmetic operations"),
    mcp.WithToolIcons(
        mcp.Icon{
            Src:      "https://example.com/icons/calculator.png",
            MIMEType: "image/png",
            Sizes:    []string{"32x32", "64x64"},
        },
    ),
    // ... parameters
)

// String parameters
mcp.WithString("name", 
    mcp.Required(),
    mcp.Description("User's name"),
    mcp.MinLength(1),
    mcp.MaxLength(100),
)

// Number parameters  
mcp.WithNumber("age",
    mcp.Required(),
    mcp.Description("User's age"),
    mcp.Min(0),
    mcp.Max(150),
)

// Integer parameters
mcp.WithInteger("count",
    mcp.DefaultNumber(10),
    mcp.Description("Number of items"),
    mcp.Min(1),
    mcp.Max(1000),
)

// Boolean parameters
mcp.WithBoolean("enabled",
    mcp.DefaultBool(true),
    mcp.Description("Whether feature is enabled"),
)

// Array parameters
mcp.WithArray("tags",
    mcp.Description("List of tags"),
    mcp.Items(map[string]any{"type": "string"}),
)

// Object parameters
mcp.WithObject("config",
    mcp.Description("Configuration object"),
    mcp.Properties(map[string]any{
        "timeout": map[string]any{"type": "number"},
        "retries": map[string]any{"type": "integer"},
    }),
)

// Enum values
mcp.WithString("priority",
    mcp.Required(),
    mcp.Enum("low", "medium", "high", "critical"),
    mcp.Description("Task priority level"),
)

// String constraints
mcp.WithString("email",
    mcp.Required(),
    mcp.Pattern(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`),
    mcp.Description("Valid email address"),
)

// Number constraints
mcp.WithNumber("price",
    mcp.Required(),
    mcp.Min(0),
    mcp.Max(10000),
    mcp.Description("Product price in USD"),
)

// Define input struct with JSON schema tags
type SearchRequest struct {
    Query      string   `json:"query" jsonschema:"Search query"`
    Limit      int      `json:"limit,omitempty" jsonschema:"Maximum results"`
    Categories []string `json:"categories,omitempty" jsonschema:"Filter by categories"`
    SortBy     string   `json:"sortBy,omitempty" jsonschema:"Sort field"`
}

// Create tool with struct-based input schema
searchTool := mcp.NewTool("search_products",
    mcp.WithDescription("Search product catalog"),
    mcp.WithInputSchema[SearchRequest](),
)

// Define output struct
type SearchResponse struct {
    Query       string    `json:"query" jsonschema:"Original search query"`
    TotalCount  int       `json:"totalCount" jsonschema:"Total matching products"`
    Products    []Product `json:"products" jsonschema:"Search results"`
    ProcessedAt time.Time `json:"processedAt" jsonschema:"When search was performed"`
}

type Product struct {
    ID          string  `json:"id" jsonschema:"Product ID"`
    Name        string  `json:"name" jsonschema:"Product name"`
    Price       float64 `json:"price" jsonschema:"Price in USD"`
    InStock     bool    `json:"inStock" jsonschema:"Availability"`
}

// Create tool with both input and output schemas
searchTool := mcp.NewTool("search_products",
    mcp.WithDescription("Search product catalog with structured output"),
    mcp.WithInputSchema[SearchRequest](),
    mcp.WithOutputSchema[SearchResponse](),
)

func main() {
    s := server.NewMCPServer("Product Search", "1.0.0",
        server.WithToolCapabilities(false),
    )

    // Define tool with input and output schemas
    searchTool := mcp.NewTool("search_products",
        mcp.WithDescription("Search product catalog"),
        mcp.WithInputSchema[SearchRequest](),
        mcp.WithOutputSchema[SearchResponse](),
    )

    // Add tool with structured handler
    s.AddTool(searchTool, mcp.NewStructuredToolHandler(searchProductsHandler))
    
    server.ServeStdio(s)
}

// Handler receives typed input and returns typed output
func searchProductsHandler(ctx context.Context, req mcp.CallToolRequest, args SearchRequest) (SearchResponse, error) {
    // Input is already validated and bound to SearchRequest struct
    limit := args.Limit
    if limit <= 0 {
        limit = 10
    }

    // Perform search logic
    products := searchDatabase(args.Query, args.Categories, limit)

    // Return structured response
    return SearchResponse{
        Query:       args.Query,
        TotalCount:  len(products),
        Products:    products,
        ProcessedAt: time.Now(),
    }, nil
}

s := server.NewMCPServer("Product Search", "1.0.0",
    server.WithToolCapabilities(false),
    server.WithOutputSchemaValidation(), // reject results that don't match outputSchema
)

// Define asset struct
type Asset struct {
    ID       string  `json:"id" jsonschema:"Asset identifier"`
    Name     string  `json:"name" jsonschema:"Asset name"`
    Value    float64 `json:"value" jsonschema:"Current value"`
    Currency string  `json:"currency" jsonschema:"Currency code"`
}

// Tool that returns array of assets
assetsTool := mcp.NewTool("list_assets",
    mcp.WithDescription("List portfolio assets"),
    mcp.WithInputSchema[struct {
        Portfolio string `json:"portfolio" jsonschema:"Portfolio ID"`
    }](),
    mcp.WithOutputSchema[[]Asset](), // Array output schema
)

func listAssetsHandler(ctx context.Context, req mcp.CallToolRequest, args struct{ Portfolio string }) ([]Asset, error) {
    // Return array of assets
    return []Asset{
        {ID: "btc", Name: "Bitcoin", Value: 45000.50, Currency: "USD"},
        {ID: "eth", Name: "Ethereum", Value: 3200.75, Currency: "USD"},
    }, nil
}

// build/warm-cache.go — run as part of your build pipeline
func main() {
    cache := mcp.NewSchemaCache()
    if err := mcp.WarmFor[WeatherRequest](cache); err != nil {
        log.Fatal(err)
    }
    if err := mcp.WarmFor[WeatherResponse](cache); err != nil {
        log.Fatal(err)
    }
    if err := cache.Save("schemas.json"); err != nil {
        log.Fatal(err)
    }
}

var cache = func() *mcp.SchemaCache {
    c, err := mcp.LoadSchemaCache("schemas.json")
    if err != nil {
        return mcp.NewSchemaCache() // fall back to live reflection
    }
    return c
}()

weatherTool := mcp.NewTool("get_weather",
    mcp.WithDescription("Get current weather"),
    mcp.WithCachedInputSchema[WeatherRequest](cache),
    mcp.WithCachedOutputSchema[WeatherResponse](cache),
)

if err := mcp.WarmFor[WeatherRequest](cache, "weather.v1.input"); err != nil {
    log.Fatal(err)
}

mcp.WithCachedInputSchemaKey[WeatherRequest](cache, "weather.v1.input")

type ExampleStruct struct {
    // Required field (no omitempty in json tag means required)
    Name string `json:"name" jsonschema:"User's full name"`

    // Field with description
    Age int `json:"age" jsonschema:"User age in years"`

    // Optional field (omitempty makes it optional)
    PageSize int `json:"pageSize,omitempty" jsonschema:"Number of items per page"`

    // Optional field with description
    Status string `json:"status,omitempty" jsonschema:"Current status"`
}

manualTool := mcp.NewTool("process_data",
    mcp.WithDescription("Process data with custom result"),
    mcp.WithInputSchema[ProcessRequest](),
    mcp.WithOutputSchema[ProcessResponse](),
)

s.AddTool(manualTool, mcp.NewTypedToolHandler(manualProcessHandler))

func manualProcessHandler(ctx context.Context, req mcp.CallToolRequest, args ProcessRequest) (*mcp.CallToolResult, error) {
    // Process the data
    response := ProcessResponse{
        Status:      "completed",
        ProcessedAt: time.Now(),
        ItemCount:   42,
    }
    
    // Create custom fallback text for backward compatibility
    fallbackText := fmt.Sprintf("Processed %d items successfully", response.ItemCount)
    
    // Return structured result with custom text
    return mcp.NewToolResultStructured(response, fallbackText), nil
}

/* Detailed source-code truncated for AI context efficiency. */

// Required parameters - return error if missing or wrong type
name, err := req.RequireString("name")
age, err := req.RequireInt("age") 
price, err := req.RequireFloat("price")
enabled, err := req.RequireBool("enabled")

// Optional parameters with defaults
name := req.GetString("name", "default")
count := req.GetInt("count", 10)
price := req.GetFloat("price", 0.0)
enabled := req.GetBool("enabled", false)

// Structured data binding
type Config struct {
    Timeout int    `json:"timeout"`
    Retries int    `json:"retries"`
    Debug   bool   `json:"debug"`
}
var config Config
if err := req.BindArguments(&config); err != nil {
    return mcp.NewToolResultError(err.Error()), nil
}

// Raw access (for backward compatibility)
args := req.GetArguments() // returns map[string]any
rawArgs := req.GetRawArguments() // returns any

func handleCalculate(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Extract parameters using helper methods
    operation, err := req.RequireString("operation")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    
    x, err := req.RequireFloat("x")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    
    y, err := req.RequireFloat("y")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    
    // Perform calculation
    var result float64
    switch operation {
    case "add":
        result = x + y
    case "subtract":
        result = x - y
    case "multiply":
        result = x * y
    case "divide":
        if y == 0 {
            return mcp.NewToolResultError("division by zero"), nil
        }
        result = x / y
    default:
        return mcp.NewToolResultError(fmt.Sprintf("unknown operation: %s", operation)), nil
    }
    
    // Return result
    return mcp.NewToolResultText(fmt.Sprintf("%.2f", result)), nil
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

func handleValidatedTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Required parameters with validation
    name, err := req.RequireString("name")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    
    age, err := req.RequireFloat("age")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    
    // Optional parameter with default
    enabled := req.GetBool("enabled", true)
    
    // Validate constraints
    if len(name) == 0 {
        return mcp.NewToolResultError("name cannot be empty"), nil
    }
    
    if age < 0 || age > 150 {
        return mcp.NewToolResultError("age must be between 0 and 150"), nil
    }
    
    // Process with validated parameters
    result := processUser(name, int(age), enabled)
    
    jsonData, err := json.Marshal(result)
    if err != nil {
        return mcp.NewToolResultError(fmt.Sprintf("failed to marshal result: %v", err)), nil
    }
    
    return mcp.NewToolResultText(string(jsonData)), nil
}

// Required parameters (return error if missing or wrong type)
name, err := req.RequireString("name")
age, err := req.RequireInt("age")
price, err := req.RequireFloat("price")
enabled, err := req.RequireBool("enabled")

// Optional parameters with defaults
name := req.GetString("name", "default")
count := req.GetInt("count", 10)
price := req.GetFloat("price", 0.0)
enabled := req.GetBool("enabled", false)

// Structured data binding
type UserData struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}
var user UserData
if err := req.BindArguments(&user); err != nil {
    return mcp.NewToolResultError(err.Error()), nil
}

### Custom Validation Functions

```go
func validateEmail(email string) error {
    emailRegex := regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
    if !emailRegex.MatchString(email) {
        return fmt.Errorf("invalid email format")
    }
    return nil
}

func validateURL(url string) error {
    parsed, err := url.Parse(url)
    if err != nil {
        return fmt.Errorf("invalid URL format: %w", err)
    }
    
    if parsed.Scheme != "http" && parsed.Scheme != "https" {
        return fmt.Errorf("URL must use http or https scheme")
    }
    
    return nil
}

func handleTextTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    message := "Operation completed successfully"
    return mcp.NewToolResultText(message), nil
}

func handleJSONTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    result := map[string]interface{}{
        "status":    "success",
        "timestamp": time.Now().Unix(),
        "data": map[string]interface{}{
            "processed": 42,
            "errors":    0,
        },
    }
    
    jsonData, err := json.Marshal(result)
    if err != nil {
        return mcp.NewToolResultError(fmt.Sprintf("failed to marshal result: %v", err)), nil
    }
    
    return mcp.NewToolResultText(string(jsonData)), nil
}

func handleMultiContentTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    data := map[string]interface{}{
        "name": "John Doe",
        "age":  30,
    }
    
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            {
                Type: "text",
                Text: "User information retrieved successfully",
            },
            {
                Type: "text",
                Text: fmt.Sprintf("Name: %s, Age: %d", data["name"], data["age"]),
            },
        },
    }, nil
}

func handleGetResourceLinkTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	resourceID, err := req.RequireString("resource_id")
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	// Create a resource link pointing to an existing resource
	uri := fmt.Sprintf("file://documents/%s", resourceID)
	resourceLink := mcp.NewResourceLink(uri, "Document", "The requested document", "application/pdf")
	return &mcp.CallToolResult{
		Content: []mcp.Content{
			mcp.NewTextContent("Found the requested document:"),
			resourceLink,
		},
	}, nil
}

func handleSearchDocumentsTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	query, err := req.RequireString("query")
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	// Simulate document search
	foundDocs := []string{"doc1.pdf", "doc2.txt", "doc3.md"}

	content := []mcp.Content{
		mcp.NewTextContent(fmt.Sprintf("Found %d documents matching '%s':", len(foundDocs), query)),
	}

	// Add resource links for each found document
	for _, doc := range foundDocs {
		uri := fmt.Sprintf("file://documents/%s", doc)
		parts := strings.SplitN(doc, ".", 2)
		name := parts[0]
		mimeType := "application/octet-stream" // default
		if len(parts) > 1 {
			// Map extension to MIME type (simplified)
			switch parts[1] {
			case "pdf":
				mimeType = "application/pdf"
			case "txt":
				mimeType = "text/plain"
			case "md":
				mimeType = "text/markdown"
			}
		}
		resourceLink := mcp.NewResourceLink(uri, name, fmt.Sprintf("Document: %s", doc), mimeType)
		content = append(content, resourceLink)
	}

	return &mcp.CallToolResult{
		Content: content,
	}, nil
}

func handleGetAnnotatedResourceTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	docType := req.GetString("type", "general")
	// Create resource link with annotations
	annotated := mcp.Annotated{
		Annotations: &mcp.Annotations{
			Audience:     []mcp.Role{mcp.RoleUser},
			LastModified: "2025-01-12T15:00:58Z",
		},
	}
	url := "file://documents/test.pdf"
	resourceLink := mcp.NewResourceLink(url, "Test Document", fmt.Sprintf("A %s document", docType), "application/pdf")
	resourceLink.Annotated = annotated
	return &mcp.CallToolResult{
		Content: []mcp.Content{
			mcp.NewTextContent("Here's the important document you requested:"),
			resourceLink,
		},
	}, nil
}

func handleToolWithErrors(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // For validation errors, return error result (not Go error)
    name, err := req.RequireString("name")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
    
    // For business logic errors, also return error result
    if someCondition {
        return mcp.NewToolResultError("invalid input: " + reason), nil
    }
    
    // For system errors, you can return Go errors
    if systemError {
        return nil, fmt.Errorf("system failure: %v", err)
    }
    
    // Or return structured error information
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            {
                Type: "text", 
                Text: "Operation failed",
            },
        },
        IsError: true,
    }, nil
}

type InvalidCustomerIDError struct {
    CustomerID string
}

func (e InvalidCustomerIDError) Error() string {
    return "invalid customer ID"
}

func (e InvalidCustomerIDError) JSONRPCError() mcp.JSONRPCError {
    return mcp.JSONRPCError{
        Error: mcp.NewJSONRPCErrorDetails(
            mcp.INVALID_PARAMS,
            e.Error(),
            map[string]any{"customerId": e.CustomerID},
        ),
    }
}

func handleCustomer(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    customerID := req.GetString("customerId", "")
    if customerID == "" {
        return nil, server.NewHandlerError(InvalidCustomerIDError{CustomerID: customerID})
    }
    return mcp.NewToolResultText("customer found"), nil
}

tool := mcp.NewTool("search_database",
    mcp.WithDescription("Search the product database"),
    mcp.WithString("query",
        mcp.Required(),
        mcp.Description("Search query (supports wildcards with *)"),
    ),
    mcp.WithNumber("limit",
        mcp.DefaultNumber(10),
        mcp.Min(1),
        mcp.Max(100),
        mcp.Description("Maximum number of results to return"),
    ),
    mcp.WithArray("categories",
        mcp.Description("Filter by product categories"),
        mcp.Items(map[string]any{"type": "string"}),
    ),
)

s.AddTool(tool, handleSearchDatabase)

func handleStreamingTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // For operations that take time, provide progress updates
    results := []string{}
    
    for i := 0; i < 10; i++ {
        // Simulate work
        time.Sleep(100 * time.Millisecond)
        
        // Check for cancellation
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        default:
        }
        
        results = append(results, fmt.Sprintf("Processed item %d", i+1))
    }
    
    resultData := map[string]interface{}{
        "status":  "completed",
        "results": results,
    }
    
    jsonData, err := json.Marshal(resultData)
    if err != nil {
        return mcp.NewToolResultError(fmt.Sprintf("failed to marshal result: %v", err)), nil
    }
    
    return mcp.NewToolResultText(string(jsonData)), nil
}

func addConditionalTools(s *server.MCPServer, userRole string) {
    // Admin-only tools
    if userRole == "admin" {
        adminTool := mcp.NewTool("delete_user",
            mcp.WithDescription("Delete a user account (admin only)"),
            mcp.WithString("user_id", mcp.Required()),
        )
        s.AddTool(adminTool, handleDeleteUser)
    }
    
    // User tools available to all
    userTool := mcp.NewTool("get_profile",
        mcp.WithDescription("Get user profile information"),
    )
    s.AddTool(userTool, handleGetProfile)
}

// Add a single session tool
userTool := mcp.NewTool(
    "get_user_data",
    mcp.WithDescription("Get current user's data"),
)

err := s.AddSessionTool(
    sessionID,
    userTool,
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        // This handler is only available to this specific session
        return mcp.NewToolResultText("User data for " + sessionID), nil
    },
)
if err != nil {
    log.Printf("Failed to add session tool: %v", err)
}

// Add multiple session tools at once
err = s.AddSessionTools(
    sessionID,
    server.ServerTool{
        Tool: mcp.NewTool("user_settings", mcp.WithDescription("Manage user settings")),
        Handler: func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            return handleUserSettings(sessionID, req)
        },
    },
    server.ServerTool{
        Tool: mcp.NewTool("user_history", mcp.WithDescription("Access user history")),
        Handler: func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            return handleUserHistory(sessionID, req)
        },
    },
)
if err != nil {
    log.Printf("Failed to add session tools: %v", err)
}

// Delete session tools when no longer needed
err = s.DeleteSessionTools(sessionID, "get_user_data", "user_settings")
if err != nil {
    log.Printf("Failed to delete session tools: %v", err)
}

sseServer := server.NewSSEServer(
    s,
    server.WithAppendQueryToMessageEndpoint(),
    server.WithSSEContextFunc(func(ctx context.Context, r *http.Request) context.Context {
        withNewTools := r.URL.Query().Get("withNewTools")
        if withNewTools != "1" {
            return ctx
        }

        session := server.ClientSessionFromContext(ctx)
        if sessionWithTools, ok := session.(server.SessionWithTools); ok {
            // Add the new tools
            sessionWithTools.SetSessionTools(map[string]server.ServerTool{
                myNewTool.Name: {
                    Tool:    myNewTool,
                    Handler: NewToolHandler(myNewToolHandler),
                },
            })
        }

        return ctx
    }),
)

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

POST /mcp/initialize     - Initialize MCP session
POST /mcp/tools/list     - List available tools
POST /mcp/tools/call     - Call a tool
POST /mcp/resources/list - List available resources
POST /mcp/resources/read - Read a resource
POST /mcp/prompts/list   - List available prompts
POST /mcp/prompts/get    - Get a prompt
GET  /mcp/health         - Health check
GET  /mcp/capabilities   - Server capabilities

/* Detailed source-code truncated for AI context efficiency. */

POST /mcp/tools/call
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_users",
    "arguments": {
      "query": "john",
      "limit": 10,
      "offset": 0
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"users\":[...],\"total\":25,\"limit\":10,\"offset\":0}"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "user_id is required"
    }
  }
}

httpServer := server.NewStreamableHTTPServer(s,
    server.WithSessionIdleTTL(10*time.Minute), // Sweep sessions idle for 10+ minutes
)

httpServer := server.NewStreamableHTTPServer(s,
    server.WithEventStore(server.NewInMemoryEventStore()),
)

// Each request is independent
func handleStatelessTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Extract all needed information from request
    userID := extractUserFromToken(ctx)
    params := req.Params.Arguments
    
    // Process without relying on server state
    result, err := processRequest(userID, params)
    if err != nil {
        return nil, err
    }
    
    return mcp.NewToolResultJSON(result)
}

// Use external storage for persistence
func getUserPreferences(userID string) (map[string]interface{}, error) {
    // Load from database, cache, etc.
    return loadFromRedis(fmt.Sprintf("user:%s:prefs", userID))
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

mcpServer := server.NewMCPServer("my-server", "1.0.0")

httpServer := server.NewStreamableHTTPServer(mcpServer,
    server.WithProtectedResourceMetadata(server.ProtectedResourceMetadataConfig{
        Resource:               "https://my-mcp-server.com",
        AuthorizationServers:   []string{"https://auth.example.com"},
        ScopesSupported:        []string{"mcp:read", "mcp:write"},
        BearerMethodsSupported: []string{"header"},
        ResourceName:           "My MCP Server",
    }),
)

httpServer.Start(":8080")
// GET http://localhost:8080/.well-known/oauth-protected-resource
//   -> 200 application/json with the metadata above

sseServer := server.NewSSEServer(mcpServer,
    server.WithSSEProtectedResourceMetadata(server.ProtectedResourceMetadataConfig{
        Resource:             "https://my-mcp-server.com",
        AuthorizationServers: []string{"https://auth.example.com"},
    }),
)

mux := http.NewServeMux()
mux.Handle("/mcp", mcpHandler)
mux.Handle("/.well-known/oauth-protected-resource",
    server.NewProtectedResourceMetadataHandler(server.ProtectedResourceMetadataConfig{
        Resource:             "https://my-mcp-server.com",
        AuthorizationServers: []string{"https://auth.example.com"},
        ScopesSupported:      []string{"mcp:read", "mcp:write"},
    }))
http.ListenAndServe(":8080", mux)

cfg := server.ProtectedResourceMetadataConfig{
    Resource:             "https://example.com/mcp",
    AuthorizationServers: []string{"https://auth.example.com"},
}
mux.Handle(server.ProtectedResourceMetadataPath(cfg.Resource),
    server.NewProtectedResourceMetadataHandler(cfg))
// -> mounts at /.well-known/oauth-protected-resource/mcp

httpServer := server.NewStreamableHTTPServer(mcpServer,
    // Only disable this if you understand the security implications.
    server.WithDisableLocalhostProtection(true),
)

httpServer := server.NewStreamableHTTPServer(mcpServer,
    server.WithEndpointPath("/mcp"),
    server.WithStreamableHTTPCORS(
        server.WithCORSAllowedOrigins("https://my-ai-app.com", "http://localhost:3000"),
        server.WithCORSAllowCredentials(),
        server.WithCORSMaxAge(300),
    ),
)

func handleGetUser(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Access request headers
    headers := req.Header

    // Use headers for authentication, tracing, etc.
    authToken := headers.Get("Authorization")
    if authToken == "" {
        return nil, fmt.Errorf("authentication required")
    }
    
    // Access other headers
    requestID := headers.Get("X-Request-ID")
    userAgent := headers.Get("User-Agent")
    
    // Rest of your handler code...
}

// Client setup with sampling support
httpTransport, err := transport.NewStreamableHTTP(
    serverURL,
    transport.WithContinuousListening(), // Required for sampling
)

// Create client with sampling handler
mcpClient := client.NewClient(httpTransport, 
    client.WithSamplingHandler(samplingHandler))

/* Detailed source-code truncated for AI context efficiency. */

type ApprovalSamplingHandler struct {
    llmClient LLMClient // Your actual LLM client
    ui        UserInterface // Your UI for presenting requests to users
}

func (h *ApprovalSamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
    // Step 1: Present the sampling request to the user for review
    approved, modifiedRequest, err := h.ui.PresentSamplingRequest(ctx, request)
    if err != nil {
        return nil, fmt.Errorf("failed to get user approval: %w", err)
    }
    
    if !approved {
        return nil, fmt.Errorf("user rejected sampling request")
    }
    
    // Step 2: Send the approved/modified request to the LLM
    response, err := h.llmClient.CreateCompletion(ctx, modifiedRequest)
    if err != nil {
        return nil, fmt.Errorf("LLM request failed: %w", err)
    }
    
    // Step 3: Present the response to the user for final approval
    approved, modifiedResponse, err := h.ui.PresentSamplingResponse(ctx, response)
    if err != nil {
        return nil, fmt.Errorf("failed to get response approval: %w", err)
    }
    
    if !approved {
        return nil, fmt.Errorf("user rejected sampling response")
    }
    
    // Step 4: Return the approved response to the server
    return modifiedResponse, nil
}

// HTTPRequest is a transport-agnostic view of an incoming MCP HTTP request.
type HTTPRequest struct {
    Method  string          // "POST", "GET", "DELETE"
    URL     *url.URL        // optional; only Path is consulted
    Header  http.Header     // required; plain map[string][]string
    Body    []byte          // already buffered; may be nil for GET/DELETE
    Context context.Context // request context; cancellation is honored
}

// HTTPResponseWriter is the minimum surface mcp-go needs to write a
// streamable HTTP response.
type HTTPResponseWriter interface {
    Header() http.Header
    WriteHeader(statusCode int)
    Write(p []byte) (int, error)
    Flush()
    CanStream() bool
}

func (s *StreamableHTTPServer) Handle(w HTTPResponseWriter, r *HTTPRequest)