mcp by edouard-claude - MCP Server

MCP Everything Boilerplate (Go)

A complete and extensible Model Context Protocol (MCP) server, built with Go 1.24+. This project provides a solid foundation with clear architecture to quickly create custom MCP servers with integrated tools, prompts, resources and transports.

📋 Table of Contents

🚀 Features
📂 Architecture
🛠 Installation
▶️ Quick Start
🔍 Testing with MCP Inspector
🧩 Available Tools
📝 Prompts
📦 Resources
🚀 Transport
🧪 Tests
📦 Build and Deployment
🔧 Adding New Tools
⚙️ Configuration
🐳 Docker
📖 References
🤝 Contributing

🚀 Features

✅ Built-in tools: 7 ready-to-use tools (greet, ping, log, sample, etc.)
✅ Custom prompts: prompt system with parameters
✅ Embedded resources: file access via embedded: URI
✅ Flexible transport:

stdio (default, compatible with Claude Desktop)
HTTP streamable (for web integrations)
✅ Extensible architecture: easy addition of new tools
✅ Optimized build: static binary with distroless Dockerfile
✅ Tests included: unit and end-to-end tests
✅ Makefile: simplified development commands

📂 Architecture

mcp/
├── cmd/
│   └── server/              # Main entry point
│       └── main.go
├── internal/
│   ├── server/              # Server configuration and initialization
│   │   ├── server.go
│   │   └── options.go
│   ├── tools/               # MCP tools (one folder per tool)
│   │   ├── greet/
│   │   ├── greetstructured/
│   │   ├── ping/
│   │   ├── logtool/
│   │   ├── sample/
│   │   ├── elicit/
│   │   └── roots/
│   ├── prompts/             # Predefined prompts
│   │   └── greet.go
│   ├── resources/           # Embedded resources
│   │   ├── embedded.go
│   │   └── data/
│   │       └── info.txt
│   └── transport/           # Transport layers
│       ├── stdio.go
│       └── http.go
├── pkg/                     # Reusable libraries
│   ├── auth/
│   │   └── jwt.go
│   └── logging/
│       └── logger.go
├── configs/                 # Configuration files
│   └── server.example.yaml
├── Dockerfile              # Optimized multi-stage build
├── Makefile               # Development commands
├── go.mod                 # Go dependencies
├── go.sum
└── README.md

🛠 Installation

Prerequisites

Go 1.24+
Git
Node.js (optional, for MCP Inspector)

Clone the project

git clone https://github.com/edouard-claude/mcp.git
cd mcp
go mod tidy

▶️ Quick Start

Stdio mode (default)

# With Go run
go run ./cmd/server

# Or with Make
make run

HTTP streamable mode

# HTTP server on port 8080
go run ./cmd/server -http :8080

# Or with Make
make http

The server will be available at http://localhost:8080 for web integrations.

🔍 Testing with MCP Inspector

Highly recommended! Use the official MCP Inspector to test and debug your server interactively:

Quick Test (Stdio Mode)

# Start your server in stdio mode
go run ./cmd/server &

# Test with MCP Inspector
npx @modelcontextprotocol/inspector go run ./cmd/server

HTTP Mode Testing

# Start HTTP server
go run ./cmd/server -http :8080

# Test HTTP endpoint
npx @modelcontextprotocol/inspector http://localhost:8080

What you can do with MCP Inspector:

🔍 Explore all available tools and their schemas
🧪 Test tool calls with real parameters
📝 Try prompts with different arguments
📦 Browse resources and test URI access
🐛 Debug responses and error messages
📊 View server capabilities and metadata

The MCP Inspector provides a web-based interface that makes it easy to understand how your server works and test all its features without writing any client code.

🧩 Available Tools

The server includes 7 ready-to-use tools:

Tool	Description	Parameters
`greet`	Simple greeting	`name: string`
`greet (structured)`	Greeting with structured data	-
`ping`	Connectivity test	-
`log`	Log recording	-
`sample`	Example tool	-
`elicit`	Information extraction	-
`roots`	Root information	-

Usage example

{
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": {
      "name": "Alice"
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "Hi Alice"
    }
  ]
}

📝 Prompts

`greet` prompt

Generates a custom greeting prompt.

Usage:

{
  "method": "prompts/get",
  "params": {
    "name": "greet",
    "arguments": {
      "name": "Bob"
    }
  }
}

Response:

{
  "description": "Hi prompt",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Say hi to Bob"
      }
    }
  ]
}

📦 Resources

Embedded `info` resource

Access to the internal/resources/data/info.txt file via the embedded:info URI.

Usage:

{
  "method": "resources/read",
  "params": {
    "uri": "embedded:info"
  }
}

🚀 Transport

Stdio (default)

Compatible with Claude Desktop and other standard MCP clients:

go run ./cmd/server

HTTP Streamable

For web integrations with streaming support:

go run ./cmd/server -http :8080

🧪 Tests

# All tests
make test

# Tests with go directly
go test ./...

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

Tests include:

Unit tests for tools
Server integration tests
End-to-end tests with stdio transport

📦 Build and Deployment

Local build

# Optimized build
make build

# Run binary
./bin/mcp-server

Environment variables

The generated binary is static (CGO_ENABLED=0) and portable.

🔧 Adding New Tools

1. Create the structure

mkdir -p internal/tools/mytool

2. Implement the tool

Create internal/tools/mytool/tool.go:

package mytool

import (
    "context"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type Args struct {
    Input string `json:"input" jsonschema:"description: User input"`
}

func Handle(_ context.Context, _ *mcp.CallToolRequest, a Args) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: "You said: " + a.Input},
        },
    }, nil, nil
}

3. Register the tool

In internal/server/server.go, add:

import "mcp/internal/tools/mytool"

// In the New() function
mcp.AddTool(s, &mcp.Tool{
    Name: "mytool", 
    Description: "My tool description"
}, mytool.Handle)

4. Test

make test
make run

# Test with MCP Inspector
npx @modelcontextprotocol/inspector go run ./cmd/server

⚙️ Configuration

Configuration file

Example in configs/server.example.yaml:

instructions: "Use this MCP server!"
http: ":8080"

Code options

In cmd/server/main.go:

srv := intsrv.New(intsrv.Options{
    Instructions: "Custom instructions",
})

🐳 Docker

Build image

docker build -t mcp-server .

Run

# Stdio mode
docker run --rm -it mcp-server

# HTTP mode (with port mapping)
docker run --rm -p 8080:8080 mcp-server -http :8080

Optimized image

The Docker image uses:

Multi-stage build with Go 1.24 Alpine
Distroless base for execution (security)
Non-root user
Static binary (no system dependencies)

Final size: ~20MB

📖 References

Useful resources

🤝 Contributing

Contributions are welcome! Please:

Fork the project
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Guidelines

Follow standard Go conventions
Add tests for new features
Update documentation
Use make lint before committing

💡 Roadmap

Built with ❤️ in Go