dexMCP

<p align='center'> <img src='https://raw.githubusercontent.com/RajeevAtla/dexMCP/main/assets/logo.png'/> </P>

dexMCP is a Model Context Protocol (MCP) server that wraps the community maintained pypokedex client for the PokeAPI. It exposes curated tools so MCP compatible applications can fetch Pokedex data without custom API plumbing.

Key capabilities

• Query any Pokemon by name or national number and receive metric aware base stats.
• Pull localized flavor text so agents can present in universe descriptions for each game version.
• Inspect move learnsets for a chosen game so automation chains pick the right actions.
• Map evolution chains, encounter locations, and breeding requirements without bespoke glue code.
• Run roster analysis with coverage reports and simple moveset tips for battle planning.

Available tools

• get_pokemon
  • Required: name_or_dex
  • Optional: none
  • Returns: PokemonSummary with stats, types, height, weight, and base experience.
• get_moves
  • Required: name_or_dex, game
  • Optional: none
  • Returns: list of Move entries with learn method and optional level.
• get_sprites
  • Required: name_or_dex
  • Optional: side (front or back), variant (default, shiny, female, female_shiny)
  • Returns: SpriteURL containing the resolved image link.
• get_descriptions
  • Required: name_or_dex
  • Optional: language (defaults to en)
  • Returns: mapping of game version to flavor text strings.
• analyze_type_coverage
  • Required: names_or_dexes list
  • Optional: none
  • Returns: TypeCoverageReport summarizing defensive matchups.
• explore_abilities
  • Required: name_or_dex
  • Optional: none
  • Returns: AbilityExplorerResult with effect text and hidden ability flag.
• plan_evolutions
  • Required: name_or_dex
  • Optional: none
  • Returns: EvolutionReport that enumerates triggers and branching paths.
• find_encounters
  • Required: name_or_dex
  • Optional: none
  • Returns: EncounterReport grouped by location and game version.
• get_breeding_info
  • Required: name_or_dex
  • Optional: game to scope egg moves
  • Returns: BreedingInfo with egg groups, hatch steps, gender split, and egg moves.
• suggest_moveset
  • Required: name_or_dex, game
  • Optional: limit (default 4), include_tm (default false)
  • Returns: MovesetRecommendation ordered by heuristic score.

Getting started

Prerequisites

• Python 3.10 or newer.
• uv for dependency management and running scripts.
• An MCP aware client (or the Python mcp package) that can launch stdio servers.
• Internet access so pypokedex can query PokeAPI the first time a Pokemon is requested.

Clone and install dependencies

git clone https://github.com/RajeevAtla/dexMCP.git
cd dexMCP
uv venv
uv sync

The runtime requirements are mcp (for FastMCP), pypokedex, requests, dspy-ai, langchain, langchain-openai, gradio, and the transitive pydantic dependency.

Run the MCP server

uv run python -m dexmcp.server

The server speaks MCP over stdio. Configure an MCP client to launch the command above and it will auto discover the tools listed earlier.

Example: run the DSPy demo agent

The repository ships dspy_client.py, a minimal DSPy client that connects to this server and calls the appropriate tools to satisfy natural language requests. Activate your virtual environment and run the curated demo suite:

uv run python dspy_client.py --demo

The agent chains several tools to:

• Retrieve Garchomp stats and ORAS level up moves.

• Audit defensive coverage for Pikachu, Garchomp, and Gyarados.

• Surface Gengar abilities and Eevee evolution branches.

• List Dratini encounter methods in FireRed and LeafGreen.

• Summarize Sylveon breeding info and egg moves in Sword and Shield.

• Recommend a Greninja moveset for Sun and Moon.

Provide your own prompt with:

uv run python dspy_client.py \
  "Compare Charizard and Tyranitar defensive coverage in scarlet-violet."

Add --demo alongside the prompt to run the canned sequence afterward.

Example: run the LangChain demo agent

Ensure OPENAI_API_KEY (or another provider key supported by your LangChain LLM) is present in the environment. Then launch the demo:

uv run python langchain_client.py --demo

The LangChain agent mirrors the DSPy scenarios, exercising the coverage, ability, evolution, encounter, breeding, and moveset tools.

Supply a custom prompt with:

uv run python langchain_client.py \
  "Plan a battle ready moveset for gardevoir in scarlet-violet."

Use --demo with a prompt to run it first before the guided walkthrough.

Example: run the Gradio demo

The Gradio UI wraps the LangChain agent and calls DexMCP tools over stdio. Ensure OPENAI_API_KEY (or another provider key supported by your LangChain LLM) is set.

uv run python gradio_demo.py

Optionally select a different model or share a public link:

uv run python gradio_demo.py --model gpt-4o-mini --share

Gradio hot reload

Use Gradio's reload mode to auto-restart on changes. On Windows, set GRADIO_SERVER_NAME and GRADIO_SERVER_PORT for the host/port:

set PYTHONPATH=C:\dexMCP
set GRADIO_SERVER_NAME=127.0.0.1
set GRADIO_SERVER_PORT=7860
uv run gradio gradio_demo.py

Testing

uv sync --group dev
uv run pytest

Pytest configuration (including coverage flags) lives in pyproject.toml.

Project structure

.
|-- dexmcp/
|   |-- abilities.py       # Ability lookup helper
|   |-- api.py             # PokeAPI + pypokedex helpers and caching
|   |-- breeding.py        # Egg group and breeding helpers
|   |-- coverage.py        # Type coverage analysis
|   |-- encounters.py      # Wild encounter lookups
|   |-- evolution.py       # Evolution chain traversal
|   |-- models.py          # Pydantic schemas
|   |-- moveset.py         # Moveset recommendation logic
|   |-- pokemon.py         # Core Pokemon lookup helpers
|   `-- server.py          # FastMCP server and tool wrappers
|-- assets/
|   `-- logo.png           # Logo used in the README banner
|-- dspy_client.py         # DSPy demo agent that consumes the server
|-- gradio_demo.py         # Gradio + LangChain demo UI
|-- langchain_client.py    # LangChain demo agent for the same tools
|-- LICENSE.md             # MIT License
|-- README.md

Data source and caching

pypokedex wraps PokeAPI and caches responses on disk under the user cache folder. The first lookup for a Pokemon may take a second while data is fetched; subsequent calls are served from the local cache.

License

DexMCP is distributed under the MIT License. See LICENSE.md for full terms.