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.

Related MCP server: PokeMCP

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

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):

• Blackout: return to start, party healed