MCP Server Framework

A simple, reusable Model Context Protocol (MCP) server framework written in Go. This framework supports multiple transport mechanisms including HTTP Streams (MCP-compliant), SSE (Server-Sent Events), and STDIO transports and can be used as both a library and a standalone executable.

Features

• 🚀 Multiple Transports: Support for HTTP Streams (MCP-compliant), SSE (Server-Sent Events), and STDIO
• 📦 Library & Standalone: Use as a Go library or run as a standalone server
• 🧪 Well Tested: Comprehensive test coverage
• 🔄 JSON-RPC 2.0: Full JSON-RPC 2.0 protocol support
• 🌐 CORS Enabled: Built-in CORS support for web clients
• 🐳 Containerized: Docker support with automated builds
• ⚡ Easy to Use: Simple API for registering handlers
• 🔧 MCP Client: Full-featured client implementation for testing and development

Quick Start

As a Standalone Server

# HTTP Streams transport (default)
go run cmd/mcp-server/main.go -addr=8080

# SSE transport
go run cmd/mcp-server/main.go -transport=sse -addr=8080

# STDIO transport
go run cmd/mcp-server/main.go -transport=stdio

As a Library

package main

import (
    "context"
    "encoding/json"
    "log"

    "github.com/protobomb/mcp-server-framework/pkg/transport"
    "github.com/protobomb/mcp-server-framework/pkg/mcp"
)

func main() {
    // Create transport (HTTP Streams, SSE, or STDIO)
    transport := transport.NewHTTPStreamsTransport(mcp.NewServerWithoutTransport(), transport.HTTPStreamsTransportOptions{})
    // transport := transport.NewSSETransport(":8080")
    // transport := transport.NewSTDIOTransport()

    // Create server
    server := mcp.NewServer(transport)

    // Register a custom handler
    server.RegisterHandler("greet", func(ctx context.Context, params json.RawMessage) (interface{}, error) {
        var greetParams struct {
            Name string `json:"name"`
        }
        
        if len(params) > 0 {
            json.Unmarshal(params, &greetParams)
        }
        
        return map[string]string{
            "message": "Hello, " + greetParams.Name + "!",
        }, nil
    })

    // Start server
    ctx := context.Background()
    if err := server.Start(ctx); err != nil {
        log.Fatal(err)
    }

    // Keep running...
    select {}
}

As a Client

package main

import (
    "context"
    "log"

    "github.com/openhands/mcp-server-framework/internal/transport"
    "github.com/openhands/mcp-server-framework/pkg/client"
    "github.com/openhands/mcp-server-framework/pkg/mcp"
)

func main() {
    // Create transport (STDIO or HTTP)
    transport := transport.NewSTDIOTransport("./mcp-server")
    // transport := transport.NewHTTPTransport("http://localhost:8080")

    // Create client
    client := client.NewClient(transport)
    defer client.Close()

    ctx := context.Background()

    // Initialize connection
    clientInfo := mcp.ServerInfo{
        Name:    "my-client",
        Version: "1.0.0",
    }
    
    result, err := client.Initialize(ctx, clientInfo)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Server: %s v%s", result.ServerInfo.Name, result.ServerInfo.Version)

    // List available tools
    tools, err := client.ListTools(ctx)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Available tools: %d", len(tools.Tools))

    // Call a tool
    params := map[string]interface{}{
        "message": "Hello from client!",
    }
    
    response, err := client.CallTool(ctx, "echo", params)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Tool response: %v", response)
}

Quick Commands

# Build everything
make build-both

# Test the client
make run-client

# Try the interactive demo
make demo

# Run all tests
make test

Installation

Go Module

go get github.com/openhands/mcp-server-framework

Docker

docker pull ghcr.io/openhands/mcp-server-frame

... [View full README on GitHub](https://github.com/Protobomb/mcp-server-framework#readme)