Pokémon World MCP

Agent playground: explore a small map, battle and catch real-named Pokémon via MCP tools.

• Public URL (planned): https://poke.vanscoding.com
• MCP endpoint: https://poke.vanscoding.com/mcp/ (local: http://127.0.0.1:8080/mcp/)
• Auth: same as vans-mcp — Authorization: Bearer vcr_sk_... (router Neon api_keys via DATABASE_URL) or local MCP_DEV_BYPASS_KEY
• Saves / catalog: game Neon POKEMON_DATABASE_URL (pokemon_saves, pokemon_catalog_cache); otherwise local SQLite under $HOME/.pokemon-world-mcp/
• Catalog cache: if missing or older than 24h (CATALOG_CACHE_TTL_HOURS), fetch PokéAPI and write the game DB. Fresh cache skips the API. Long-running processes re-check via ensure_fresh. API failure uses in-memory fallback and does not write fallback to DB.

This project is separate from vans-mcp-server (Notion / Calendar / Gmail).

Goal (V1)

Collect 3 different species in your party.

Starter (required): bulbasaur | charmander | squirtle at Lv5.

Progression

• Exp (official curves): each species has a PokéAPI growth_rate and cumulative total-exp table (six rates). party.exp is total experience.
• Battle yield: active Pokémon gains floor(enemy.base_experience × enemy.level / 7) on win or catch
• Level-up: when total exp reaches the next level threshold; stats scale with level; may learn moves from the species learnset
• Moves: max 4. If a new move is offered while full, resolve with battle_action(replace_move, forget_move_name=...) or skip_learn before exploring/battling again
• Evolution: automatic at species thresholds (e.g. bulbasaur → ivysaur at 16)

Tools

Tool	When
new_game(starter)	Start / reset save (starter required)
get_status	Phase, position, party summary, pending learn
look	3×3 nearby tiles (exploring)
move	N / S / E / W — grass may encounter
party	Party details (level, exp, moves)
battle_status	In battle (or pending learn)
battle_action	fight + move_name, catch, run, or replace_move / skip_learn

Tip for student agents: after each tool call, narrate the result to the human before the next action.

Local development

cd C:\Users\mz038\Desktop\peas-agent\pokemon-world-mcp
uv sync --extra dev
$env:MCP_DEV_BYPASS_KEY = "vcr_sk_dev_local_only"
# Optional — router Neon (api_keys):
# $env:DATABASE_URL = "postgresql://..."
# Optional — game Neon (saves + catalog); without this, SQLite is used:
# $env:POKEMON_DATABASE_URL = "postgresql://..."
uv run pokemon-world-mcp

Without POKEMON_DATABASE_URL, player saves and the catalog cache both live in the same SQLite file (%USERPROFILE%\.pokemon-world-mcp\pokemon_world.db, or SQLITE_PATH). Progress survives restarts.

• Health: http://127.0.0.1:8080/health (no key)
• MCP: http://127.0.0.1:8080/mcp/ with Bearer header

Production on Fly must set both DATABASE_URL (router) and POKEMON_DATABASE_URL (game) — see docs/deploy-fly.md.

Tests

uv run pytest

Cursor / student Agent config (example)

Point MCP at this server (not mcp.vanscoding.com), same course API key:

{
  "mcpServers": {
    "pokemon-world": {
      "url": "https://poke.vanscoding.com/mcp/",
      "headers": {
        "Authorization": "Bearer vcr_sk_YOUR_KEY"
      }
    }
  }
}

Local:

{
  "mcpServers": {
    "pokemon-world": {
      "url": "http://127.0.0.1:8080/mcp/",
      "headers": {
        "Authorization": "Bearer vcr_sk_dev_local_only"
      }
    }
  }
}

Map notes

• 10×10 fixed map: path, grass, water (blocked)
• ~25% encounter chance on grass steps
• Wild level ≈ party average ±2 (clamped 2–50)
• Wild species by map quadrant (no starters in the wild):

Zone	Coordinates	Pool
NW	x≤4, y≤4	pidgey, rattata, jigglypuff
NE	x≥5, y≤4	pikachu, meowth, jigglypuff
SW	x≤4, y≥5	geodude, meowth, rattata
SE	x≥5, y≥5	gastly, geodude, pidgey

• Blackout: return to start, party healed