mcp_demo by beiyu - MCP Server

MCP Demo - Multi-Transport Protocol Support

This project demonstrates how to implement Model Context Protocol (MCP) servers with multiple transport protocols using pure Go. The primary purpose is to understand MCP principles and interaction details by implementing the protocol from scratch without any external frameworks.

🎯 Project Purpose

This is a learning-oriented implementation designed to:

Understand MCP Protocol: Learn the core concepts and message flows of Model Context Protocol
Master Protocol Details: Implement JSON-RPC 2.0 and MCP specifications from scratch
Explore Transport Mechanisms: Compare different transport protocols (STDIO, HTTP, SSE)
Pure Go Implementation: Build without external dependencies to understand every detail

Note: This is an educational project focused on protocol understanding rather than production use.

📁 Project Structure

mcp_demo/
├── cmd/                    # Different transport protocol entry points
│   ├── stdio/             # Standard Input/Output implementation
│   ├── http/              # HTTP transport implementation
│   └── sse/               # Server-Sent Events implementation
├── internal/mcp/          # Custom MCP protocol implementation
│   ├── types.go           # MCP protocol type definitions
│   └── server.go          # MCP server implementation
├── bin/                   # Compiled output directory
├── Makefile              # Build system
├── README.md             # English documentation
├── README-CN.md          # Chinese documentation
└── go.mod                # Go module definition

🚀 Supported Transport Protocols

1. STDIO (Standard Input/Output)

Purpose: Local MCP servers, command-line interface communication
Features: Simplest implementation, suitable for local tool integration
Port: None (uses stdin/stdout)

2. HTTP (Simple HTTP JSON-RPC)

Purpose: Basic remote access, RESTful API style
Features: Simple request-response pattern, easy to test and debug
Port: 8080

3. SSE (Server-Sent Events)

Purpose: Real-time bidirectional communication, server push support
Features: HTTP-based streaming communication, persistent connections
Port: 8081

🛠️ Quick Start

Build All Versions

make all

Build Specific Versions

# Build STDIO version
make stdio

# Build HTTP version
make http

# Build SSE version
make sse

Run Servers

# Run STDIO server
make run-stdio

# Run HTTP server
make run-http

# Run SSE server
make run-sse

🧪 Testing Guide

STDIO Testing

# Start server
./bin/mcp-stdio

# Send initialization message (via stdin)
{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}},"id":1}

# Send calculator request
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"calculate","arguments":{"operation":"add","x":5,"y":3}},"id":2}

HTTP Testing

# Start server
./bin/mcp-http

# Test initialization
curl -X POST http://localhost:8080 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}},"id":1}'

# Test tool list
curl -X POST http://localhost:8080 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

# Test calculator tool
curl -X POST http://localhost:8080 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"calculate","arguments":{"operation":"add","x":5,"y":3}},"id":3}'

SSE Testing

# Start server
./bin/mcp-sse

# Open test page in browser
open http://localhost:8081

# Or test SSE connection with curl
curl -N -H "Accept: text/event-stream" http://localhost:8081/sse

📖 MCP Protocol Overview

Model Context Protocol (MCP) is an open protocol for seamless integration between LLM applications and external data sources and tools.

Core Concepts

JSON-RPC 2.0: All messages follow the JSON-RPC 2.0 specification
Tools: Functions for AI models to execute
Resources: Context and data for users or AI models to use
Prompts: Templated messages and workflows

Transport Mechanism Comparison

Feature	STDIO	HTTP	SSE
Complexity	Low	Medium	High
Real-time	High	Low	High
Remote Access	No	Yes	Yes
Bidirectional	Yes	No	Yes
Debug Convenience	Low	High	Medium
Production Use	Local tools	API services	Real-time apps

🔧 Development Guide

Adding New Tools

Define new tools in the appropriate cmd/*/main.go files
Use mcp.NewTool() to create tool definitions
Use server.AddTool() to register tool handlers

Extending Protocol Support

Create new transport implementations in the cmd/ directory
Update Makefile to add new build targets
Update this README documentation

💡 Learning Highlights

This implementation helps you understand:

JSON-RPC 2.0 Protocol: How to implement request/response and notification patterns
MCP Message Flow: Initialization, capability negotiation, tool calling
Transport Abstractions: How different protocols can carry the same messages
Go Concurrency: Handling multiple connections in SSE implementation
Protocol Design: Clean separation between transport and application logic

beiyu/mcp_demo