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

get_pokemon_info - Comprehensive Pokémon information
- Base stats, types, abilities (with descriptions)
- Moves with effects (first 10)
- Full evolution chain
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

Clone the repository

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

Install dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

Configure environment

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

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

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

Variable	Description	Default
`API_KEY`	Authentication key	(required)
`ALLOWED_ORIGINS`	CORS allowed origins	`http://localhost:*`
`LOG_LEVEL`	Logging level	`INFO`
`RATE_LIMIT_REQUESTS`	Max requests per window	`100`
`RATE_LIMIT_WINDOW`	Time window in seconds	`60`
`ENABLE_METRICS`	Enable Prometheus metrics	`true`

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

Add tool function to server.py:

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

Add monitoring and logging as needed
Update documentation

Security Considerations

API Keys: Always use strong, randomly generated API keys
CORS: Configure ALLOWED_ORIGINS for production
Rate Limiting: Adjust limits based on expected usage
HTTPS: Always use HTTPS in production (Vercel provides this)
SSH Tunnels: Use key-based authentication, not passwords
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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