poke-mcp docs

01. Visao Geral

O poke-mcp e um servidor que implementa o Model Context Protocol (MCP) — protocolo aberto criado pela Anthropic que padroniza a comunicacao entre aplicacoes de IA e fontes de dados externas.

O servidor expoe 10 ferramentas que permitem a agentes de IA consultar dados de Pokemon diretamente da PokeAPI v2 — stats, tipos, moves, abilities, itens, berries, locais de encontro e cadeias de evolucao.

02. Arquitetura

Transporte: stdio

O servidor usa transporte stdio com JSON-RPC 2.0. A IDE lanca o processo e se comunica via stdin/stdout. Logging vai exclusivamente para stderr — stdout e reservado para o protocolo.

Camadas do Sistema

Estrutura de Diretorio

poke-mcp/
├── src/poke_mcp/
│   ├── __init__.py        # Versao do pacote
│   ├── __main__.py        # python -m poke_mcp
│   ├── server.py          # FastMCP + httpx client
│   └── tools.py           # 10 tools registradas
├── tests/
│   └── test_tools.py      # Testes com mock
├── docs/
│   └── index.html         # Esta pagina
├── build.py               # PyInstaller build
├── install.py             # Instalador multi-IDE
└── pyproject.toml         # Config do projeto

03. Padroes de Design

@asynccontextmanager
async def lifespan(server: FastMCP):
    global api_client
    api_client = httpx.AsyncClient(
        base_url=BASE_URL,
        timeout=30.0,
        limits=httpx.Limits(max_connections=20, max_keepalive_connections=5),
    )
    try:
        yield
    finally:
        await api_client.aclose()

async def fetch(endpoint: str) -> dict[str, Any] | None:
    """GET a PokeAPI endpoint. Returns None on any error."""
    url = f"/{endpoint}"
    resp = await api_client.get(url)
    resp.raise_for_status()
    return resp.json()

@dataclass
class IDETarget:
    name: str
    config_path_fn: Callable[[], Path]
    detect_fn: Callable[[], bool]

IDE_TARGETS = [
    IDETarget("Claude Desktop", _claude_desktop_config, _claude_desktop_detected),
    IDETarget("Cursor", _cursor_config, _cursor_detected),
    ...
]

@mcp.tool()
async def get_pokemon(name_or_id: str) -> str:
    """Get Pokemon details including stats, types, abilities, and sprites."""
    data = await fetch(f"pokemon/{name_or_id}")
    if not data:
        return f"Pokemon '{name_or_id}' not found."

04. Ferramentas MCP

Pokemon

Batalha

Itens, Berries e Evolucao

05. Instalador Multi-IDE

O instalador detecta automaticamente quais IDEs estao instaladas e apresenta um menu interativo com checkboxes para selecao.

Fluxo do Instalador

====================================================
     PokeAPI MCP Server — Installer v2.0
====================================================
  MCP server for AI IDEs | pokeapi.co/api/v2

  Status: Not installed

  [I] Install / Reinstall
  [U] Uninstall
  [Q] Exit

  >>> Choose an option (I/U/Q): I

  Select IDEs to configure:

  [1] [x] Claude Desktop     (Detected)
  [2] [x] Cursor              (Detected)
  [3] [ ] Windsurf            (Not found)
  [4] [ ] Claude Code CLI     (Not found)

  Toggle: type numbers (e.g. 1,3) | Enter: confirm | 0: cancelTerminal Output

06. Testes

Estrategia

Mock no nivel do httpx.AsyncClient — o client real nunca e chamado nos testes. Uma fixture autouse injeta o mock em server.api_client antes de cada teste. O helper _mock_response() cria respostas HTTP mockadas com status configuravel.

Cobertura por Tool

$ pytest -v
tests/test_tools.py::test_get_pokemon_success       PASSED
tests/test_tools.py::test_get_pokemon_not_found      PASSED
tests/test_tools.py::test_get_type_success           PASSED
tests/test_tools.py::test_list_pokemon_success       PASSED
tests/test_tools.py::test_list_pokemon_clamps_limit  PASSED
tests/test_tools.py::test_get_evolution_chain        PASSED
tests/test_tools.py::test_get_move                   PASSED
tests/test_tools.py::test_get_item                   PASSED
tests/test_tools.py::test_get_berry                  PASSED
tests/test_tools.py::test_get_pokemon_species        PASSED

10 passed in 0.42spytest output

07. Stack Tecnica

Competencias Demonstradas

08. Build e Deploy

Pipeline de Build

O build.py gera dois executaveis via PyInstaller:

Comandos

# Setup
python -m venv .venv && .venv/Scripts/activate
pip install -e ".[dev]"

# Dev
python -m poke_mcp          # Run server
pytest                       # Run tests
ruff check src/ tests/       # Lint
ruff format src/ tests/      # Format

# Build & Release
python build.py              # Generate .exe files
gh release create v2.0.0     # Create GitHub Release
gh release upload v2.0.0 dist/*.exebash