ProperMCP - Model Context Protocol Framework for Go

A comprehensive, production-ready implementation of the Model Context Protocol (MCP) in Go, providing a robust foundation for building AI-powered applications with multiple transport protocols and advanced workflow capabilities.

🚀 Features

Core MCP Implementation

• Complete MCP Specification: Full implementation of Tools, Prompts, and Resources
• Multi-Transport Support: HTTP, stdio, and Server-Sent Events (SSE)
• Type-Safe Operations: Comprehensive parameter validation and type checking
• Error Handling: Standardized error responses with detailed context
• Lifecycle Management: Proper resource initialization and cleanup

Advanced Capabilities

• Smart Tool Orchestration: Automatic prerequisite tool execution with prompts
• Service Layer Integration: Clean adapter patterns for existing business services
• Complex Workflows: Multi-step business process automation
• Real-time Monitoring: Performance metrics and business KPI tracking
• Business Intelligence: Analytics, reporting, and forecasting capabilities

Transport Protocols

• HTTP: Traditional REST-like API with JSON request/response
• stdio: Standard input/output for command-line tools and process communication
• SSE: Server-Sent Events for real-time streaming and push notifications

📦 Installation

go get repo.nusatek.id/sugeng/propermcp

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  Transport       │───▶│  MCP Server     │
│                 │    │  Layer           │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │  HTTP/stdio/SSE  │    │  Tools/Prompts  │
                       │  Protocols       │    │  Resources      │
                       └──────────────────┘    └─────────────────┘

🛠️ Project Structure

propermcp/
├── pkg/
│   ├── mcp/           # Core MCP interfaces and types
│   ├── server/        # Server implementation
│   └── transport/     # Multi-transport support
├── examples/
│   ├── calculator/    # Basic examples
│   ├── filesystem/    # File operations
│   ├── database/      # Database integration
│   ├── workflows/     # Complex business workflows
│   └── transports/    # Transport protocol examples
├── tests/
│   ├── unit/          # Unit tests
│   └── integration/   # Integration tests
└── docs/              # Documentation

🚀 Quick Start

Basic MCP Server

package main

import (
    "context"
    "log"

    "repo.nusatek.id/sugeng/propermcp/pkg/mcp"
    "repo.nusatek.id/sugeng/propermcp/pkg/server"
)

// Define a simple tool
type CalculatorTool struct {
    name        string
    description string
    operations  []mcp.Operation
}

func NewCalculatorTool() *CalculatorTool {
    return &CalculatorTool{
        name:        "calculator",
        description: "Basic mathematical operations",
        operations: []mcp.Operation{
            {
                Name:        "add",
                Description: "Add two numbers",
                Parameters: []mcp.ToolParameter{
                    mcp.WithNumberParameter("a", true, "First number"),
                    mcp.WithNumberParameter("b", true, "Second number"),
                },
            },
        },
    }
}

func (t *CalculatorTool) Name() string { return t.name }
func (t *CalculatorTool) Description() string { return t.description }
func (t *CalculatorTool) Operations() []mcp.Operation { return t.operations }

// Implement the tool handler
type CalculatorHandler struct{}

func (h *CalculatorHandler) Handle(ctx context.Context, operation string, args map[string]interface{}) (interface{}, error) {
    switch operation {
    case "add":
        a := args["a"].(float64)
        b := args["b"].(float64)
        return map[string]interface{}{
            "result": a + b,
            "operation": "addition",
        }, nil
    default:
        return nil, mcp.NewMCPError(mcp.ErrorCodeOperationNotFound, "unknown operation", operation)
    }
}

func main() {
    // Create server
    s := server.NewServer("Calculator MCP Server", "1.0.0",
        server.WithToolCapabilities(true),
        server.WithHost("localhost"),
        server.WithPort(8080),
    )

    // Register tool
    tool := NewCalculatorTool()
    handler := &CalculatorHandler{}

    if err := s.RegisterTool(tool, handler); err != nil {
        log.Fatalf("Failed to register tool: %v", err)
    }

    // Start server
    if err := s.Start(":8080"); err != nil {
        log.Fatalf("Failed to start server: %v", err)
    }
}

Using the Server

# Get server status
curl http://localhost:8080/mcp/status

# List available tools
curl http://localhost:8080/mcp/tools

# Invoke a tool
curl -X POST http://localhost:8080/mcp/tools/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "calculator",
    "operation_name": "add",
    "arguments": {"a": 5, "b": 3}
  }'

📚 Examples

Basic Examples

• Calculator: Mathematical operations with validation
• File System: Secure file operations
• Database: CRUD operations with connection pooling
• External API: Weather, currency, and notification services
• Prompts: Text generation and analysis

Advanced Workflows

• Smart Orchestration: Intelligent tool coordination
• Service Integration: Adapter patterns for existing services
• E-commerce Workflow: Complete order processing pipeline
• Business Intelligence: Analytics and reporting
• Comprehensive Workflow: Multi-service orchestration

Transport Examples

• Multi-Transport Server: HTTP, stdio, and SSE protocols
• stdio Communication: Command-line integration
• SSE Streaming: Real-time data streaming

🔧 Configuration

Server Configuration

s := server.NewServer("My MCP Server", "1.0.0",
    server.WithToolCapabilities(true),
    server.WithPromptCapabilities(true),
    server.WithResourceCapabilities(true),
    server.WithHost("localhost"),
    server.WithPort(8080),
    server.WithCORS(true),
    server.WithTimeout(30*time.Second),
)

Transport Configuration

// HTTP Transport (default)
httpConfig := transport.DefaultHTTPConfig()

// stdio Transport
stdioConfig := transport.DefaultStdioConfig()
stdioConfig.UseStderr = true
stdioConfig.LineDelimited = true

// SSE Transport
sseConfig := transport.DefaultSSEConfig()
sseConfig.Port = 8080
sseConfig.KeepAliveInterval = 30 * time.Second

🛠️ Development

Running Examples

# Basic calculator example
go run examples/calculator/main.go

# Complex e-commerce workflow
go run examples/workflows/ecommerce_workflow.go

# Multi-transport server
go run examples/transports/multi_transport_server.go

# Using the workflow runner
go run examples/workflows/workflow_runner.go ecommerce

Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test suites
go test ./tests/unit/
go test ./tests/integration/

📖 Documentation

Core Concepts

• MCP Specification: Understanding the Model Context Protocol
• Tools Guide: Creating and managing tools
• Prompts Guide: Implementing prompt handlers
• Resources Guide: Managing resources and data
• Transport Protocols: HTTP, stdio, and SSE communication

Advanced Topics

• Workflow Orchestration: Building complex business processes
• Service Integration: Integrating with existing systems
• Performance Optimization: Scaling and optimization strategies
• Security Best Practices: Authentication, authorization, and data protection

API Reference

• Server API: Server configuration and lifecycle
• Tool API: Tool definition and execution
• Prompt API: Prompt handling and responses
• Transport API: Transport protocol interfaces

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/your-org/propermcp.git
cd propermcp

# Install dependencies
go mod tidy

# Run tests
go test ./...

# Run examples
go run examples/calculator/main.go

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol Specification
• Anthropic for the MCP specification
• Go community for excellent tooling and libraries

📞 Support

• Documentation: docs/
• Examples: examples/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

ProperMCP - Building the future of AI-powered applications with Go 🚀