MCP Docker Demo

A Model Context Protocol (MCP) server implementation with Docker support and a web-based inspector.

🚀 Quick Start

1. Build the Docker Image

docker build -t rak-greet .

2. Test the Server (Simple Client)

docker run --rm -i rak-greet python client.py

3. Launch Web Inspector (Recommended)

docker run --rm -p 8000:8000 rak-greet python mcp_inspector_web.py

Then open your browser to: http://localhost:8000

📁 Project Structure

mcpdocker-demo/
├── server.py              # MCP server with hello-world tool
├── client.py             # Simple test client
├── mcp_inspector_web.py  # Web UI for testing
├── Dockerfile            # Container configuration
└── requirements.txt      # Python dependencies

🔧 What's Inside

MCP Server (server.py)

• Implements a simple "hello-world" tool
• Accepts a greeting and returns it with " World!" appended
• Runs over stdio transport
• Includes debug logging

Web Inspector (mcp_inspector_web.py)

• Beautiful web interface for testing MCP servers
• Lists available tools
• Shows tool schemas
• Interactive testing with real-time results
• Built with FastAPI

Simple Client (client.py)

• Command-line MCP client
• Connects to server via stdio
• Tests the hello-world tool

🛠️ Development

Local Development (without Docker)

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run server
python server.py

# In another terminal, run client
python client.py

Run Web Inspector Locally

uvicorn mcp_inspector_web:app --host 0.0.0.0 --port 8000 --reload

📝 API Reference

Hello World Tool

Name: hello-world

Description: A simple tool that returns a greeting.

Input Schema:

{
  "type": "object",
  "properties": {
    "greeting": {
      "type": "string",
      "description": "The greeting to return"
    }
  },
  "required": ["greeting"]
}

Example:

Input:  {"greeting": "Hello"}
Output: "Hello World!"

🐳 Docker Commands

# Build image
docker build -t rak-greet .

# Run server
docker run --rm -i rak-greet python server.py

# Run client
docker run --rm -i rak-greet python client.py

# Run web inspector
docker run --rm -p 8000:8000 rak-greet python mcp_inspector_web.py

🔍 Troubleshooting

"Connection closed" Error

This usually means the server failed to start. Check:

1. Python version (should be 3.11+)
2. All dependencies installed
3. Server logs for errors

Port Already in Use

If port 8000 is busy:

docker run --rm -p 8001:8000 rak-greet python mcp_inspector_web.py

Then open: http://localhost:8001

📚 Learn More

• Model Context Protocol Documentation
• MCP Specification
• MCP Python SDK

🤝 Contributing

Feel free to open issues or submit pull requests!

📄 License

MIT License - feel free to use this code however you'd like!