Pokémon MCP Server

Laboratório didático para aprender o que é e como funciona um MCP Server. Ele expõe dados reais da PokéAPI como Tools, um Resource e um Prompt pelo protocolo MCP, usando o transporte Streamable HTTP.

O servidor não contém um modelo de linguagem e não precisa de chave de API. Quem interpreta a pergunta e escolhe uma Tool é o cliente de IA conectado; este projeto apenas consulta, valida e resume os dados da PokéAPI.

Escolha seu caminho

Related MCP server: Pokédex MCP Server

Quickstart em cinco minutos

1. Pré-requisito

Você precisa apenas de Docker para executar o servidor:

docker --version

Para experimentar as capacidades numa interface visual, o passo 4 usa o MCP Inspector e requer Node.js. Ele é opcional: qualquer cliente compatível com Streamable HTTP pode se conectar ao mesmo endpoint.

2. Execute a imagem publicada

docker run -d --name pokemon-mcp-server \
  -p 127.0.0.1:8000:8000 \
  higorcamposs/pokemon-mcp-server:0.1.2

A imagem é distribuída em dois registries. Use o que preferir:

docker pull higorcamposs/pokemon-mcp-server:0.1.2          # Docker Hub
docker pull ghcr.io/higorcamposs/pokemon-mcp-server:0.1.2  # GHCR

São a mesma imagem, não duas: o mesmo build multiarch (linux/amd64 e linux/arm64), publicado nos dois lugares com o mesmo digest. Prefira a tag de versão a latest quando reprodutibilidade importar — uma versão publicada nunca é regravada, enquanto latest anda a cada release estável.

O mapeamento começa com 127.0.0.1 de propósito: o servidor fica disponível somente na sua máquina. Ele não tem autenticação e não deve ser exposto à rede ou à internet.

3. Confirme que o processo está no ar

docker ps
curl http://localhost:8000/health

Resposta esperada do curl:

{"status":"ok","server":"pokemon-mcp-server"}

O endpoint MCP é:

http://localhost:8000/mcp

/health prova que o processo respondeu. A próxima etapa prova que o protocolo MCP e as capacidades do servidor estão funcionando.

4. Conecte o MCP Inspector

Com Node.js instalado, execute:

npx @modelcontextprotocol/inspector \
  --server-url http://localhost:8000/mcp \
  --transport http

Abra no navegador a URL impressa pelo comando. No Inspector:

1. conecte ao servidor;

2. abra Tools;

3. selecione get_pokemon;

4. preencha name_or_id com pikachu;

5. execute a Tool.

O resultado estruturado contém dados como estes:

{
  "id": 25,
  "name": "pikachu",
  "types": ["electric"],
  "height_m": 0.4,
  "weight_kg": 6.0,
  "abilities": [
    {"name": "static", "is_hidden": false, "slot": 1},
    {"name": "lightning-rod", "is_hidden": true, "slot": 3}
  ],
  "base_stats": {
    "hp": 35,
    "attack": 55,
    "defense": 40,
    "special-attack": 50,
    "special-defense": 50,
    "speed": 90
  },
  "source_url": "https://pokeapi.co/api/v2/pokemon/pikachu/"
}

Confira também os logs:

docker logs pokemon-mcp-server

Eles devem mostrar a consulta à PokéAPI ou um cache hit se o mesmo Pokémon já tiver sido consultado dentro do TTL.

5. Encerre o servidor

docker rm -f pokemon-mcp-server

Para receitas específicas de VS Code, Codex e MCP Inspector, consulte o guia de conexão.

Como funciona em 60 segundos

Usuário
  │ pergunta em linguagem natural
  ▼
Aplicação de IA / Host
  └── modelo escolhe uma Tool
        │ chamada MCP por Streamable HTTP
        ▼
      Pokémon MCP Server
        ├── valida o argumento
        ├── consulta e guarda cache
        ├── converte unidades
        └── valida o JSON recebido
              │ HTTPS / REST
              ▼
            PokéAPI

PokéAPI → resposta bruta → MCP Server → resposta estruturada → cliente → usuário

O protocolo MCP fica entre o cliente e este servidor. Entre o servidor e a PokéAPI continua existindo HTTP/REST comum. Publicar a imagem num registry distribui o programa, mas não cria um endpoint público: o contêiner roda na máquina de quem o iniciou.

O fluxo completo, incluindo os arquivos envolvidos em cada etapa, está em docs/como-funciona.md.

O que o servidor oferece

Tools

• get_pokemon: tipos, unidades, habilidades e atributos base.

• get_ability: descrição em inglês e origem do texto.

• get_type: seis relações de dano de um tipo isolado.

As Tools aceitam nomes canônicos (pikachu, mr-mime) ou identificadores positivos (25). Espaços nas extremidades e letras maiúsculas são normalizados. Toda resposta traz source_url, a URL exata consultada.

Resource e Prompt

• pokemon://guide explica as capacidades, a origem dos dados e os limites do laboratório.

• compare_pokemon(pokemon_a, pokemon_b) devolve instruções para o cliente consultar dois Pokémon e compará-los sem inventar um vencedor de batalha.

Obter o Prompt não executa Tools e não chama um modelo. O servidor devolve apenas o template; a aplicação conectada decide o que fazer com ele.

Estudar e desenvolver

1. Clone e suba o projeto

git clone https://github.com/higorcamposs/pokemon-mcp-server.git
cd pokemon-mcp-server
docker compose up -d --build
docker compose ps

O status deve ficar healthy. O endpoint continua sendo http://localhost:8000/mcp.

2. Execute os testes automatizados

docker compose --profile test run --build --rm tests

Os testes usam respostas gravadas e transporte HTTP simulado; a disponibilidade da PokéAPI não faz parte da suíte automatizada.

3. Execute o smoke test MCP

Com o servidor no ar:

docker compose --profile test run --build --rm smoke

O smoke test conecta pelo protocolo MCP, descobre as capacidades, chama as três Tools, lê o Resource e obtém o Prompt. Ele faz poucas consultas reais à PokéAPI.

4. Localize cada responsabilidade

Dentro de src/pokemon_mcp/:

Leia Como o servidor funciona para acompanhar uma requisição por esses quatro módulos e entender como adaptar o laboratório.

Para encerrar o ambiente de desenvolvimento:

docker compose down

Configuração essencial

Todas as variáveis são opcionais. .env.example documenta porta, URL da PokéAPI, timeout, cache, logs e allowlists com seus respectivos padrões.

Se a porta 8000 estiver ocupada:

MCP_HOST_PORT=8001 docker compose up -d --build

O endpoint passa a ser http://localhost:8001/mcp, e o Compose ajusta as allowlists. Veja a configuração de Host, Origin e porta.

Limites e segurança

• O servidor não simula batalhas nem determina vencedores.

• Relações de tipo não combinam os dois tipos de um Pokémon nem consideram habilidades, itens, movimentos ou condições de campo.

• Habilidades são possibilidades da espécie; um indivíduo usa uma por vez.

• Descrições de habilidade vêm em inglês e não são traduzidas pelo servidor.

• O cache existe apenas em memória e desaparece quando o contêiner reinicia.

• O servidor depende da PokéAPI e devolve erro quando ela está indisponível.

• Não há autenticação. O serviço deve permanecer no loopback e não deve ser publicado em rede, túnel público ou internet.

Diagnóstico rápido

• Contêiner não fica saudável: leia docker logs pokemon-mcp-server.

• Porta 8000 ocupada: use MCP_HOST_PORT=8001 com o Compose.

• HTTP 421: use localhost ou autorize o Host exato mostrado no log.

• HTTP 403: autorize a Origin completa mostrada no log.

• PokéAPI indisponível: confira a internet do contêiner e tente depois.

Se /health funciona, mas o cliente não conecta, execute o smoke test para separar um problema do servidor de um problema específico do cliente. Veja o diagnóstico detalhado.

Documentação

Para usar o servidor

• Conectar MCP Inspector, VS Code ou Codex

• Como o servidor funciona

Para estudar o projeto

• Versões, decisões e referências oficiais

• Registro de validações executadas

• Roteiro para capturar evidências da apresentação

Para manter e publicar

• Publicar uma nova imagem (GHCR e Docker Hub)

• compose.ghcr.yaml: executar a imagem publicada sem clonar o repositório

• .env.example: referência completa das variáveis de ambiente

Distribuído sob a licença MIT. Consulte LICENSE.