Skip to main content

Go SDK

Official Go SDK for integrating MCPulse analytics into your Go MCP servers.

Installation​

go get github.com/sirrobot01/mcpulse-go

Quick Start​

Basic Usage​

package main

import (
    "context"
    "fmt"
    mcpulse "github.com/sirrobot01/mcpulse-go"
)

func main() {
    ctx := context.Background()

    // Create configuration
    config := mcpulse.DefaultConfig("my-mcp-server")
    config.GRPCEndpoint = "localhost:9090"
    config.APIKey = "your-api-key"

    // Create middleware
    middleware, err := mcpulse.NewMiddleware(ctx, config)
    if err != nil {
        panic(err)
    }
    defer middleware.Close(ctx)

    // Track a tool call
    result, err := middleware.TrackToolCall(ctx, "calculate", map[string]interface{}{
        "operation": "add",
        "a": 5,
        "b": 3,
    }, func(ctx context.Context, params map[string]interface{}) (interface{}, error) {
        a := params["a"].(int)
        b := params["b"].(int)
        return a + b, nil
    })

    if err != nil {
        fmt.Println("Error:", err)
    } else {
        fmt.Println("Result:", result)
    }
}

Configuration​

config := mcpulse.Config{
    ServerID:   "my-mcp-server",
    Transport:  mcpulse.TransportGRPC, // or TransportREST

    // Endpoints
    GRPCEndpoint: "localhost:9090",

    // Authentication
    APIKey: "your-api-key",

    // Collection settings
    EnableParamCollection: true,
    AsyncCollection:       true,
    BufferSize:            100,
    FlushInterval:         5 * time.Second,
    MaxBatchSize:          1000,

    // Privacy
    SanitizeParams: true,
    SensitiveKeys:  []string{"password", "token", "api_key"},

    // Sampling
    SampleRate: 1.0, // 1.0 = 100%, 0.1 = 10%

    // Retry
    MaxRetries:   3,
    RetryBackoff: 1 * time.Second,

    // Timeout
    Timeout: 10 * time.Second,
}

Features​

Middleware Pattern​

Track tool calls automatically:

result, err := middleware.TrackToolCall(ctx, "tool_name", params, handler)

Session Tracking​

Group related calls:

sessionMgr := mcpulse.NewSessionManager(middleware)
ctx, session := sessionMgr.StartSession(ctx)

// All tracked calls use this session
result, _ := middleware.TrackToolCall(ctx, "search", params, handler)

Direct Client​

For manual control:

client, err := mcpulse.New(ctx, mcpulse.ClientOptions{
    Transport:    mcpulse.TransportGRPC,
    GRPCEndpoint: "localhost:9090",
})
defer client.Close()

metrics := []mcpulse.ToolCallMetric{
    {
        ID:         "metric-1",
        Timestamp:  time.Now(),
        ServerID:   "my-server",
        ToolName:   "calculate",
        DurationMS: 42,
        Status:     "success",
    },
}

result, err := client.IngestMetrics(ctx, metrics)

Streaming (gRPC only)​

Stream batches of metrics:

batches := make(chan []mcpulse.ToolCallMetric)

go func() {
    defer close(batches)
    for i := 0; i < 10; i++ {
        batches <- []mcpulse.ToolCallMetric{/* metrics */}
    }
}()

result, err := client.IngestMetricsStream(ctx, batches)

API Reference​

Middleware​

  • NewMiddleware(ctx, config) - Create middleware instance
  • TrackToolCall(ctx, toolName, params, handler) - Track with automatic metrics
  • Flush(ctx) - Flush buffered metrics
  • Close(ctx) - Close and cleanup

Client​

  • New(ctx, opts) - Create low-level client
  • IngestMetrics(ctx, metrics) - Send batch
  • IngestMetricsStream(ctx, batches) - Stream batches (gRPC only)
  • Close() - Close connection

Session​

  • NewSession() - Create session with generated ID
  • WithSession(ctx, session) - Add session to context
  • GetSessionID(ctx) - Get session ID from context

Examples​

See the examples directory for complete examples.

Next Steps​