patrickcarmichael/poke-mcp-production

Poke MCP Production Server

A production-ready Pokémon MCP (Model Context Protocol) server with enterprise features:

• ✅ FastMCP with HTTP Transport - RESTful API access to MCP tools
• 🔒 Authentication - API key-based security
• 📈 Monitoring - Prometheus metrics and health checks
• 📝 Structured Logging - JSON-formatted logs with structlog
• ⚡ Rate Limiting - Protect against abuse
• 🚀 Vercel Deployment - Serverless deployment with continuous integration
• 🔐 SSH Tunneling - Secure remote access configuration

Features

MCP Tools

1. get_pokemon_info - Comprehensive Pokémon information

   • Base stats, types, abilities (with descriptions)
   • Moves with effects (first 10)
   • Full evolution chain

2. simulate_battle - Realistic Pokémon battle simulation

   • Core battle mechanics (type effectiveness, status effects)
   • Turn-based combat with detailed battle log
   • Winner determination

Production Features

• Authentication: Bearer token API key authentication
• Rate Limiting: Configurable request limits per time window
• Monitoring: Prometheus metrics for requests, latency, and tool calls
• Logging: Structured JSON logs with request tracing
• CORS: Configurable cross-origin resource sharing
• Health Checks: /health endpoint for monitoring
• Environment Configuration: Flexible environment-based settings

Quick Start

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Vercel account (for deployment)

Local Development

1. Clone the repository

git clone https://github.com/patrickcarmichael/poke-mcp-production.git
cd poke-mcp-production

2. Install dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

3. Configure environment

cp .env.example .env
# Edit .env with your settings

4. Run the server

# For MCP stdio mode (local testing)
python server.py

# For HTTP mode (production)
uvicorn api.index:app --reload --host 0.0.0.0 --port 8000

5. Test the server

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

# Protected endpoint (requires API key)
curl -H "Authorization: Bearer your-api-key" http://localhost:8000/status

Deployment

See for comprehensive deployment instructions including:

• Vercel deployment
• Environment variable configuration
• SSH tunnel setup for remote access
• Continuous deployment setup
• Production monitoring

Configuration

All configuration is managed through environment variables. See .env.example for all available options.

Key Configuration Options

API Endpoints

Public Endpoints

• GET / - Server information
• GET /health - Health check
• GET /metrics - Prometheus metrics (if enabled)

Protected Endpoints (Require API Key)

• POST /mcp - MCP tool execution endpoint
• GET /status - Detailed server status

Authentication

All protected endpoints require a Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" https://your-server.vercel.app/status

Monitoring

Prometheus Metrics

The server exposes Prometheus-compatible metrics at /metrics:

• http_requests_total - Total HTTP requests by method, endpoint, and status
• http_request_duration_seconds - Request latency histogram
• mcp_tool_calls_total - MCP tool invocations by tool name and status
• mcp_tool_duration_seconds - Tool execution duration
• pokeapi_requests_total - PokeAPI requests by endpoint and status
• active_connections - Current active connections

Logging

Structured JSON logs include:

• Request/response details
• Tool execution tracking
• Error tracking with stack traces
• Performance metrics

SSH Tunneling for Remote Access

See for detailed instructions on:

• Setting up SSH tunnels to access your deployed server
• Configuring Claude Desktop and other MCP clients
• Security best practices
• Troubleshooting

Architecture

poke-mcp-production/
├── api/
│   └── index.py          # Vercel serverless handler
├── src/
│   ├── __init__.py
│   ├── auth.py           # Authentication logic
│   ├── battle_utils.py   # Battle simulation utilities
│   ├── config.py         # Configuration management
│   ├── constants.py      # Type effectiveness, constants
│   ├── logger.py         # Structured logging setup
│   ├── middleware.py     # CORS, rate limiting, logging
│   ├── monitoring.py     # Prometheus metrics
│   └── pokeapi_client.py # PokeAPI integration
├── server.py            # Main MCP server (stdio mode)
├── vercel.json          # Vercel configuration
├── pyproject.toml       # Project metadata
├── requirements.txt     # Python dependencies
└── .env.example         # Environment template

Development

Testing

# Install dev dependencies
uv sync --extra dev

# Run tests (when implemented)
pytest

# Code formatting
black .

# Linting
ruff check .

# Type checking
mypy src/

Adding New Tools

1. Add tool function to server.py:

@mcp.tool()
async def my_new_tool(param: str) -> Dict[str, Any]:
    """Tool description."""
    # Implementation
    return {"result": "data"}

2. Add monitoring and logging as needed
3. Update documentation

Security Considerations

1. API Keys: Always use strong, randomly generated API keys
2. CORS: Configure ALLOWED_ORIGINS for production
3. Rate Limiting: Adjust limits based on expected usage
4. HTTPS: Always use HTTPS in production (Vercel provides this)
5. SSH Tunnels: Use key-based authentication, not passwords
6. Secrets: Never commit .env files or secrets to git

Troubleshooting

Server Won't Start

• Check Python version: python --version (must be 3.11+)
• Verify all dependencies are installed
• Check .env file configuration

Authentication Failures

• Verify API key is set in environment
• Check Authorization header format: Bearer YOUR_KEY
• Ensure CORS settings allow your origin

Rate Limiting Issues

• Adjust RATE_LIMIT_REQUESTS and RATE_LIMIT_WINDOW
• Check client IP address handling
• Review logs for rate limit events

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• PokeAPI - Pokémon data source
• FastMCP - MCP server framework
• Model Context Protocol - MCP specification
• Original poke-mcp implementations by NaveenBandarage and ChiragAgg5k

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check for deployment help
• Review for remote access setup

Roadmap

• Full MCP protocol integration in Vercel endpoint
• WebSocket support for real-time updates
• Caching layer for PokeAPI responses
• Additional battle mechanics
• Team management tools
• Database integration for persistent data
• GraphQL API option
• Docker deployment option