mcp

Philip-Walsh/mcp

3.2

If you are the rightful owner of mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This document provides a comprehensive overview of a production-ready MCP server template designed for seamless integration and deployment.

Tools
2
Resources
0
Prompts
0

๐Ÿณ 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!