Games MCP Server - HTTP API

A simple HTTP API for coin flipping and dice rolling games, optimized for deployment on Render and integration with OpenAI.

Features

• Coin Flipping: Flip 1-100 coins with statistical summaries
• Dice Rolling: Roll 1-100 dice with 2-1000 sides each
• Custom Dice Notation: Support for expressions like 2d6+5, 3d20-2
• Dual Response Formats: Both plain text and JSON responses
• CORS Enabled: Ready for web integration
• Production Ready: Optimized for Render deployment

API Endpoints

Health Check

• GET /health - Returns "ok" if service is running

Text Response Endpoints

• GET /flip-coin?flips=1..100 - Flip coins (plain text)
• GET /roll-dice?dice=1..100&sides=2..1000 - Roll dice (plain text)
• GET /roll-custom?expression=2d6+5 - Custom dice notation (plain text)

JSON Response Endpoints

• GET /api/flip-coin?flips=1..100 - Flip coins (JSON)
• GET /api/roll-dice?dice=1..100&sides=2..1000 - Roll dice (JSON)
• GET /api/roll-custom?expression=2d6+5 - Custom dice notation (JSON)

Documentation

• GET /docs - Interactive API documentation (Swagger UI)
• GET /redoc - Alternative API documentation

Local Development

Prerequisites

• Python 3.11+
• pip

Setup

# Clone the repository
git clone <your-repo-url>
cd games-mcp-server

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m main

Test Locally

# Health check
curl http://localhost:8000/health

# Flip 3 coins
curl "http://localhost:8000/flip-coin?flips=3"

# Roll 2 dice with 6 sides
curl "http://localhost:8000/roll-dice?dice=2&sides=6"

# Custom dice notation
curl "http://localhost:8000/roll-custom?expression=2d6+5"

# JSON responses
curl "http://localhost:8000/api/flip-coin?flips=3"
curl "http://localhost:8000/api/roll-dice?dice=2&sides=6"
curl "http://localhost:8000/api/roll-custom?expression=2d6+5"

Render Deployment

Method 1: Using render.yaml (Recommended)

1. Push to GitHub: Push your code to a GitHub repository
2. Connect to Render:
   • Go to render.com
   • Sign up/Login with GitHub
   • Click "New +" → "Web Service"
   • Connect your GitHub repository
3. Configure Service:
   • Name: games-mcp-api (or your preferred name)
   • Environment: Python 3
   • Build Command: pip install -r requirements.txt
   • Start Command: python -m main
   • Plan: Free (or upgrade as needed)
4. Deploy: Click "Create Web Service"

Method 2: Manual Configuration

If you prefer manual setup:

1. Service Type: Web Service
2. Environment: Python 3
3. Build Command: pip install -r requirements.txt
4. Start Command: python -m main
5. Environment Variables:
   • PORT: 8000 (Render will set this automatically)
   • PYTHON_VERSION: 3.11.0

Method 3: Docker Deployment

If you prefer Docker:

1. Service Type: Web Service
2. Environment: Docker
3. Dockerfile: Use the provided Dockerfile
4. Start Command: Leave empty (uses CMD from Dockerfile)

Testing Your Deployment

Once deployed, test your API:

# Replace YOUR_RENDER_URL with your actual Render URL
export RENDER_URL="https://your-app-name.onrender.com"

# Health check
curl "$RENDER_URL/health"

# Test coin flipping
curl "$RENDER_URL/api/flip-coin?flips=5"

# Test dice rolling
curl "$RENDER_URL/api/roll-dice?dice=3&sides=20"

# Test custom notation
curl "$RENDER_URL/api/roll-custom?expression=4d6+2"

# View API documentation
open "$RENDER_URL/docs"

Integration with OpenAI

Using with OpenAI API

You can use this API with OpenAI's function calling feature:

import openai
import requests

# Define your function
def flip_coins(flips=1):
    response = requests.get(f"https://your-app-name.onrender.com/api/flip-coin?flips={flips}")
    return response.json()

def roll_dice(dice=1, sides=6):
    response = requests.get(f"https://your-app-name.onrender.com/api/roll-dice?dice={dice}&sides={sides}")
    return response.json()

def roll_custom_dice(expression):
    response = requests.get(f"https://your-app-name.onrender.com/api/roll-custom?expression={expression}")
    return response.json()

# Use with OpenAI
client = openai.OpenAI(api_key="your-api-key")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Flip 3 coins for me"}],
    functions=[
        {
            "name": "flip_coins",
            "description": "Flip one or more coins",
            "parameters": {
                "type": "object",
                "properties": {
                    "flips": {
                        "type": "integer",
                        "description": "Number of coins to flip (1-100)",
                        "minimum": 1,
                        "maximum": 100
                    }
                },
                "required": ["flips"]
            }
        }
    ],
    function_call="auto"
)

Example Function Definitions for OpenAI

{
  "name": "flip_coins",
  "description": "Flip one or more coins and get results with statistics",
  "parameters": {
    "type": "object",
    "properties": {
      "flips": {
        "type": "integer",
        "description": "Number of coins to flip (1-100)",
        "minimum": 1,
        "maximum": 100
      }
    },
    "required": ["flips"]
  }
}

{
  "name": "roll_dice",
  "description": "Roll one or more dice with specified number of sides",
  "parameters": {
    "type": "object",
    "properties": {
      "dice": {
        "type": "integer",
        "description": "Number of dice to roll (1-100)",
        "minimum": 1,
        "maximum": 100
      },
      "sides": {
        "type": "integer",
        "description": "Number of sides per die (2-1000)",
        "minimum": 2,
        "maximum": 1000
      }
    },
    "required": ["dice", "sides"]
  }
}

{
  "name": "roll_custom_dice",
  "description": "Roll dice using standard gaming notation like 2d6+5 or 3d20-2",
  "parameters": {
    "type": "object",
    "properties": {
      "expression": {
        "type": "string",
        "description": "Dice expression in standard notation (e.g., 2d6+5, 3d20-2, 1d100)"
      }
    },
    "required": ["expression"]
  }
}

Production Considerations

• CORS: Currently set to allow all origins (*). For production, configure specific domains.
• Rate Limiting: Consider adding rate limiting for production use.
• Authentication: Add API keys or authentication if needed.
• Monitoring: Use Render's built-in monitoring or add custom logging.
• Scaling: Upgrade to paid plans for better performance and reliability.

Troubleshooting

Common Issues

1. Build Fails: Check that all dependencies are in requirements.txt
2. Service Won't Start: Verify the start command is correct
3. Port Issues: Ensure your app binds to 0.0.0.0 and uses the PORT environment variable
4. CORS Errors: Check browser console and configure CORS settings

Logs

View logs in Render dashboard:

1. Go to your service
2. Click on "Logs" tab
3. Check for any error messages

License

This project is open source and available under the MIT License.