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

2. Install dependencies

3. Configure environment

4. Run the server

5. Test the server

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:

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

Development

Testing

Adding New Tools

1. Add tool function to server.py:

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