Philip-Walsh/mcp

🐳 MCP Server Template

Production-ready MCP server template with Docker, dual transport support, and automated CI/CD.

✨ Features

• MCP 2025-06-18 compliant - Latest protocol specification
• Dual transport - stdio and Streamable HTTP
• Docker ready - Multi-arch container with security best practices
• CI/CD pipeline - Automated testing and publishing to GitHub Container Registry
• Template ready - Click "Use this template" to get started

🚀 Quick Start

Docker (Recommended)

# Pull from GitHub Container Registry
docker pull ghcr.io/your-username/mcp-server-template:latest

# Or build locally
docker build -t mcp-server .

# Run stdio mode (for MCP clients)
docker run -i --rm mcp-server

# Run HTTP mode (for web integration)
docker run -p 8000:8000 -e MODE=http mcp-server

Direct Python

# stdio mode
python3 server.py

# HTTP mode
python3 server.py --http --port 8000

🔧 MCP Client Integration

Amazon Q / Claude Desktop

Add to your MCP client configuration:

{
  "mcpServers": {
    "my-server": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/your-username/mcp-server-template:latest"]
    }
  }
}

HTTP Client

curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

🛠️ Development

Project Structure

├── src/                   # Source code
│   ├── server.py         # MCP server implementation
│   └── entrypoint.sh     # Transport mode switching
├── scripts/              # Development scripts
│   └── setup-hooks.sh    # Git hooks setup
├── examples/             # Usage examples
│   └── client-config.json # Amazon Q configuration
├── docs/                 # Documentation
│   └── SETUP.md         # Setup guide
├── .github/workflows/    # CI/CD automation
├── Dockerfile           # Production container
├── Makefile            # Development commands
└── README.md          # This file

Available Commands

make build      # Build Docker image
make test       # Run all tests
make test-stdio # Test stdio transport
make test-http  # Test HTTP transport
make clean      # Clean up containers

Adding Tools

Edit src/server.py and add your tools to the handle_request function:

elif method == 'tools/list':
    return {
        "jsonrpc": "2.0",
        "id": request.get('id'),
        "result": {
            "tools": [
                {"name": "your_tool", "description": "Your tool description", 
                 "inputSchema": {"type": "object", "properties": {...}}}
            ]
        }
    }

📋 Built-in Tools

• echo - Echo back messages
• get_env - Get environment variables

🧪 Testing

The CI pipeline automatically tests:

• ✅ MCP protocol compliance (2024-11-05 & 2025-06-18)
• ✅ stdio transport functionality
• ✅ HTTP transport with proper headers
• ✅ Tool execution and responses
• ✅ Docker container security

🚢 Deployment

GitHub Container Registry (Automatic)

Push to main branch or create a tag to automatically build and publish:

git tag v1.0.0
git push origin v1.0.0

Manual Deployment

# Build multi-arch image
docker buildx build --platform linux/amd64,linux/arm64 -t your-registry/mcp-server .

# Push to registry
docker push your-registry/mcp-server

🔒 Security

• Runs as non-root user
• HTTP server binds to localhost by default
• Protocol version validation
• Input sanitization

📄 License

MIT License - see LICENSE file for details.

🎯 Ready to build your MCP server? Click "Use this template" to get started!