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 DEPLOYMENT.md 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 SSH_TUNNELING.md 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 DEPLOYMENT.md for deployment help

• Review SSH_TUNNELING.md 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