mrvikky17/MCP_server

Pokémon MCP Server

This project is a Pokémon MCP (Model Context Protocol) Server built with FastAPI.
It exposes two AI-friendly capabilities:

• Pokémon Data Resource – Fetch detailed data about any Pokémon (stats, abilities, moves, evolutions).
• Battle Simulation Tool – Run a turn-based Pokémon battle simulation between two Pokémon with simplified but realistic mechanics.

The API can be used directly with Postman, curl, or LLMs.
No Pokémon knowledge or technical expertise is required — just follow the steps below.

Features

• Fetch Pokémon Data (types, stats, abilities, moves, evolution chain).
• Simulate Battles with turn-by-turn logs, including type effectiveness, critical hits, accuracy, and status effects (burn, paralysis, poison).
• Deterministic Battles (results repeatable with the same random seed).
• FastAPI Server – Runs locally, no external accounts needed.
• Unit Tests – Ensure everything works correctly.
• Postman Support – Ready-to-use sample requests.

Installation (Step by Step)

1. Clone / Download Project
   Download or unzip the project into a folder (e.g., MCP_pokemon).

2. Open a terminal and navigate into the project folder:

   cd MCP_pokemon

3. Install dependencies :

   pip install -r requirements.txt

Run the Server

Start the FastAPI server with:

uvicorn app.main:app --reload --port 8000

• Server will run at: http://127.0.0.1:8000
• API docs (interactive Swagger UI): http://127.0.0.1:8000/docs

Using Postman (Simulate API Calls)

Discover Capabilities

Request

GET http://127.0.0.1:8000/mcp/capabilities

Response (shortened example)

{
  "capabilities": [
    {
      "id": "pokemon-data",
      "type": "resource",
      "name": "Pokémon Data Resource",
      "entrypoint": {
        "method": "POST",
        "url": "/mcp/resource/pokemon/query"
      }
    },
    {
      "id": "battle-simulator",
      "type": "tool",
      "name": "Battle Simulation Tool",
      "entrypoint": {
        "method": "POST",
        "url": "/mcp/tool/simulate_battle"
      }
    }
  ]
}

Fetch Pokémon Data

Request (POST → http://127.0.0.1:8000/mcp/resource/pokemon/query)

{
  "pokemon": "pikachu",
  "fields": ["base_stats", "types", "abilities", "moves"],
  "limit_moves": 5
}

Response (example)

{
  "id": 25,
  "name": "pikachu",
  "base_stats": {"hp": 35, "attack": 55, "defense": 40, "sp_attack": 50, "sp_defense": 50, "speed": 90},
  "types": ["Electric"],
  "abilities": [{"name": "static", "effect": "May cause paralysis on contact."}],
  "moves": [
    {"name": "thunder-shock", "type": "electric", "power": 40, "accuracy": 100},
    {"name": "quick-attack", "type": "normal", "power": 40, "accuracy": 100}
  ]
}

Simulate a Battle

Request (POST → http://127.0.0.1:8000/mcp/tool/simulate_battle)

{
  "pokemon_a": {"name": "charizard", "level": 50, "moves": ["flamethrower", "air-slash", "dragon-claw", "roost"]},
  "pokemon_b": {"name": "blastoise", "level": 50, "moves": ["hydro-pump", "ice-beam", "dark-pulse", "rapid-spin"]},
  "seed": 42,
  "max_turns": 50
}

Response (shortened battle log)

{
  "log": [
    "Turn 1: Charizard used Flamethrower → It's not very effective. Blastoise lost 25 HP.",
    "Turn 1: Blastoise used Hydro Pump → It's super effective! Charizard lost 120 HP.",
    "Charizard fainted."
  ],
  "result": {
    "winner": "blastoise",
    "turns": 1
  }
}

Run Tests

To run all automated tests:

pytest

To run just one test file:

python -m tests.test_battle_api

Package as ZIP

To create a distributable ZIP:

bash scripts/package_zip.sh

This will create pokemon_mcp_server.zip in your project folder.

Example Prompts for AI/LLMs

• LLM Prompt: “Fetch full details for Charizard”
  → Calls Pokémon Data Resource.

• LLM Prompt: “Simulate a battle between Pikachu and Charizard at level 50”
  → Calls Battle Simulation Tool.

Summary

This project lets you explore Pokémon data and run battle simulations through an easy-to-use API.
Non-technical users can use Postman to test everything without writing code.