pokemon-mcp-server

harikantbajaj/pokemon-mcp-server

3.2

If you are the rightful owner of pokemon-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Pokemon Battle Server is a specialized program designed to simulate Pokemon battles and provide comprehensive Pokemon information.

Tools
6
Resources
0
Prompts
0

🎮 Pokemon Battle Server - Fun Pokemon Battles Made Easy!

Welcome to my Pokemon Battle Server project! This is a special computer program I made that lets you have Pokemon battles and learn about Pokemon. It's like having a Pokemon game on your computer!

What Does This Project Do? 🤔

Imagine you have a magical computer that knows everything about Pokemon:

  • Pokemon Information: Tell it any Pokemon name, and it will tell you all about it (like how strong it is, what type it is, what moves it can learn)
  • Pokemon Battles: Make two Pokemon fight each other! The computer calculates who wins using real Pokemon battle rules
  • Pokemon Types: Learn which Pokemon types are strong or weak against others (like Water beats Fire)

How to Run This Project (Super Easy Steps!) 🚀

Step 1: Get Python Ready

First, you need Python on your computer. It's free! Go to python.org and download Python 3.11 or newer.

Step 2: Download My Project

# Copy this project to your computer
git clone <your-project-url>
cd pokemon-mcp-server

Step 3: Set Up a Special Folder for the Project

# Create a special folder for the project (like a Pokemon gym!)
python -m venv pokemon-gym

# Go into the gym (Windows)
pokemon-gym\Scripts\activate

# Go into the gym (Mac/Linux)
source pokemon-gym/bin/activate

Step 4: Install Pokemon Data

# Install all the Pokemon stuff needed
pip install -r requirements.txt

Step 5: Start the Pokemon Server!

# Start the server (like turning on a Pokemon game)
python main.py

Alternative Ways to Run the Server If u have Install everything

You can also run the project on different servers using these commands:

python -m src.server.pokemon_server_v4

To validate the server with MCP Inspector, run:

npx @modelcontextprotocol/inspector -- python src/server/pokemon_server_v4.py

That's it! Your Pokemon server is now running! 🎉

How to Use Your Pokemon Server 🎯

Option 1: Simple Demo (Recommended!)

# Run the demo to see everything working
python demo_server.py

This will show you:

  • Server information
  • Pokemon data (try Pikachu, Charizard, etc.)
  • Pokemon battles
  • Type matchups

Option 2: Manual Testing

Open your web browser and go to: http://localhost:8000

You'll see a welcome message from your Pokemon server!

What Makes This Project Special? 🌟

✅ Real Pokemon Rules

  • Uses the same battle formulas as real Pokemon games
  • Includes special effects like Burn, Poison, Sleep, Freeze, and Paralysis
  • Calculates damage correctly based on Pokemon types

✅ Lots of Pokemon Data

  • Information about 800+ Pokemon
  • All 18 Pokemon types with their strengths and weaknesses
  • Evolution information (how Pokemon change and grow)
  • Pokemon moves and abilities

✅ Fast and Smart

  • Remembers Pokemon information so it doesn't have to look it up every time
  • Can handle many people using it at the same time
  • Works on Windows, Mac, and Linux computers

✅ Well Tested

  • Tested with special tools to make sure everything works correctly
  • Includes examples and test files to show how everything works
  • Has error checking so it doesn't crash
image image image

Architecture Overview 🏗️

''' FastAPI App ──── MCP Server ──── Pokemon API │ │ │ └───────────────┼───────────────┘ │ Core Engine (Battle Logic + Analytics) '''

Available MCP Resources
  • pokemon://{name}/complete - Full Pokemon data
  • pokemon://{name}/stats - Base stats analysis
  • pokemon://{name}/types - Type effectiveness
  • pokemon://{name}/abilities - Ability information
  • pokemon://{name}/moves - Move database
  • pokemon://{name}/evolution - Evolution chains
  • types://effectiveness/{type1}/{type2} - Type matchups
  • server://info - Server information
  • server://health - Health status
Available MCP Tools
  • simulate_battle - Complete battle simulation
  • get_pokemon_summary - Quick Pokemon info
  • analyze_battle - Battle analysis with insights
  • get_performance_metrics - Server performance data
  • get_battle_analytics - Battle statistics
  • server_status - Server status information
Environment Variables

Server identity

MCP_SERVER_NAME=Pokemon Battle MCP Server MCP_SERVER_VERSION=4.0.0 ENVIRONMENT=development # or production DEBUG_MODE=false

Logging

LOG_LEVEL=INFO LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s

Transport

TRANSPORT=stdio # options: stdio, http, sse HTTP_HOST=0.0.0.0 HTTP_PORT=8000

PokeAPI settings

POKEAPI_BASE_URL=https://pokeapi.co/api/v2 POKEAPI_RATE_LIMIT=300 # requests per hour

Caching

CACHE_SIZE=5000 # max entries CACHE_TTL=7200 # seconds to live

Connection pool

CONNECTION_POOL_SIZE=20

Battle simulation

MAX_BATTLE_TURNS=50 ENABLE_CONCURRENT_BATTLES=true BATTLE_CACHE_TTL=300 # seconds

Rate limiting (per client IP)

ENABLE_RATE_LIMITING=true MAX_REQUESTS_PER_MINUTE=100

Performance monitoring & analytics

ENABLE_PERFORMANCE_MONITORING=true ENABLE_BATTLE_ANALYTICS=true METRICS_RETENTION_HOURS=24

Security Features 🔒

Input Validation
  • Pokemon Name Validation: Sanitization and format checking
  • Type Safety: Pydantic models for all data structures
  • Rate Limiting: Request throttling to prevent abuse
  • SQL Injection Prevention: Parameterized queries and input escaping
Production Security
  • HTTPS Only: SSL/TLS encryption for all communications
  • API Key Authentication: Secure access control
  • CORS Configuration: Cross-origin resource sharing controls
  • Security Headers: OWASP recommended security headers
  • Regular Updates: Dependency updates and security patches

Monitoring & Analytics 📈

Real-time Metrics
  • Request Count: Total API requests processed
  • Response Times: Average, min, max response times
  • Error Rates: Percentage of failed requests
  • Cache Performance: Hit rates and miss rates
  • Memory Usage: RAM consumption over time
  • CPU Usage: Processor utilization
Battle Analytics
  • Win/Loss Ratios: Pokemon performance statistics
  • Type Effectiveness: Most effective type combinations
  • Popular Moves: Frequently used moves in battles
  • Battle Duration: Average length of simulated battles
  • Status Effect Usage: Frequency of status conditions

Troubleshooting Guide 🛠️

Common Issues & Solutions

Server Won't Start

# Check Python version
python --version

# Verify dependencies
pip list | grep fastapi

# Check port availability
netstat -an | grep 8000

Pokemon Data Not Loading

# Test internet connection
curl https://pokeapi.co/api/v2/pokemon/pikachu

# Check API timeout settings
# Increase timeout in environment variables
POKEAPI_TIMEOUT_SECONDS=60

Battle Simulation Errors

# Verify Pokemon names
python -c "from src.utils.validators import validate_pokemon_identifier; print(validate_pokemon_identifier('pikachu'))"

# Check battle mechanics
python -c "from src.tools.battle_mechanics import battle_mechanics; print('Battle engine loaded')"

Performance Issues

# Check cache status
python -c "from src.optimization.performance_optimization import optimized_pokemon_api; print(optimized_pokemon_api.get_cache_stats())"

# Monitor memory usage
python -c "import psutil; print(f'Memory: {psutil.virtual_memory().percent}%')"

🎮 Ready to explore the world of Pokemon battles? Your Pokemon MCP Server is fully equipped and ready for action! ⚡🔥💧