# Cartola FC MCP

Um servidor MCP que conecta o Cartola FC ao Claude (e outros agentes de IA). Com ele você pode perguntar ao Claude coisas como:

- "Quais jogos têm nesta rodada?"
- "Quem foram os 10 melhores jogadores da rodada?"
- "Me monta um time com C$ 120 no orçamento?"
- "Qual o status do Gabigol no mercado?"

---

## O que você precisa ter instalado

Antes de começar, instale:

1. **Python 3.11 ou mais novo**
   - Baixe em: https://www.python.org/downloads/
   - Para verificar se já tem: abra o terminal e digite `python3 --version`
   - Se você usa Mac com Homebrew, também pode instalar via `brew install python@3.13`

2. **Claude Desktop** (para usar o MCP com o Claude)
   - Baixe em: https://claude.ai/download

---

## Instalação

### 1. Abra o terminal na pasta do projeto

Se você recebeu o projeto como arquivo ZIP, extraia e abra o terminal dentro da pasta `cartola_mcp`.

No Mac: clique com o botão direito na pasta → "Abrir Terminal aqui"

### 2. Instale as dependências

```bash
./mcp install
```

> Esse comando cria um ambiente virtual isolado e instala tudo automaticamente. Você só precisa rodar uma vez.

### 3. Teste se o servidor funciona

```bash
./mcp rdev
```

Se tudo estiver certo, você verá algo como:
```
Starting MCP inspector...
MCP server running at stdio
```

Pressione `Ctrl+C` para parar.

---

## Configurando no Claude Desktop

Para que o Claude Desktop use este MCP, você precisa informar onde o servidor está.

### 1. Encontre o arquivo de configuração do Claude Desktop

- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

No Mac, abra o Finder, pressione `Cmd+Shift+G` e cole o caminho acima.

### 2. Edite o arquivo de configuração

Abra o arquivo `claude_desktop_config.json` em um editor de texto (pode ser o Bloco de Notas ou TextEdit).

Se o arquivo estiver vazio ou não existir, crie com o conteúdo abaixo.
Se já tiver conteúdo, adicione apenas o bloco `"cartola"` dentro de `"mcpServers"`.

```json
{
  "mcpServers": {
    "cartola": {
      "command": "/CAMINHO/COMPLETO/PARA/cartola_mcp/.venv/bin/python",
      "args": [
        "/CAMINHO/COMPLETO/PARA/cartola_mcp/server.py"
      ]
    }
  }
}
```

**Importante:** Substitua `/CAMINHO/COMPLETO/PARA/cartola_mcp` pelo caminho real da pasta no seu computador (em dois lugares).

Para descobrir o caminho no Mac:
1. Abra o terminal na pasta `cartola_mcp`
2. Digite `pwd` e pressione Enter
3. Copie o resultado

Exemplo: se `pwd` retornou `/Users/joao/projetos/cartola_mcp`, a configuração ficará assim:

```json
{
  "mcpServers": {
    "cartola": {
      "command": "/Users/joao/projetos/cartola_mcp/.venv/bin/python",
      "args": [
        "/Users/joao/projetos/cartola_mcp/server.py"
      ]
    }
  }
}
```

### 3. Reinicie o Claude Desktop

Feche completamente o Claude Desktop e abra de novo. O ícone de ferramenta deve aparecer na interface, indicando que o MCP está ativo.

---

## Usando com o Claude

Depois de configurado, abra uma conversa no Claude Desktop e pergunte diretamente:

| Pergunta | O que o Claude fará |
|---|---|
| "Em que rodada estamos?" | Consulta o status atual do Cartola |
| "Quais jogos têm esta rodada?" | Lista todas as partidas com horário e placar |
| "Quem foram os melhores desta rodada?" | Retorna o top 10 de pontuadores |
| "Quais atacantes estão disponíveis até C$ 15?" | Filtra o mercado por posição e preço |
| "Busca informações sobre o Endrick" | Detalha preço, média e status do atleta |
| "Monta um time com C$ 100 em 4-4-2" | Sugestão de escalação dentro do orçamento |

---

## Ferramentas disponíveis

| Ferramenta | O que faz |
|---|---|
| `rodada_atual` | Status e número da rodada em andamento |
| `listar_rodadas` | Todas as rodadas do campeonato |
| `listar_partidas` | Partidas de uma rodada (com placar se já aconteceu) |
| `atletas_pontuados` | Todos os atletas com pontuação na rodada atual |
| `top_pontuadores` | Ranking dos melhores da rodada (filtrável por posição) |
| `listar_mercado` | Atletas disponíveis (filtrável por posição, status e preço) |
| `buscar_atleta` | Busca detalhada de um atleta pelo nome |
| `buscar_time` | Escalação e pontuação de um time do Cartola |

---

## Problemas comuns

**O Claude não está vendo as ferramentas do Cartola**
- Verifique se o caminho no `claude_desktop_config.json` está correto
- Reinicie o Claude Desktop completamente (feche pelo ícone na barra de tarefas)

**Erro "mercado fechado"**
- O mercado do Cartola só fica aberto entre as rodadas. Durante os jogos ele fecha. Tente novamente depois que a rodada terminar.

**Erro ao buscar time**
- O slug do time fica na URL do Cartola FC quando você acessa o seu time. Exemplo: `cartola.globo.com/time/meu-time-123` → slug é `meu-time-123`

**Erro de instalação**
- Certifique-se de ter o Python 3.11+ instalado: `python3 --version`
- Tente reinstalar o uv e repetir o passo de instalação

---

## Testando sem o Claude Desktop

Se quiser testar as ferramentas diretamente (sem o Claude), use o MCP Inspector:

```bash
./mcp rdev
```

Isso abre uma interface web onde você pode chamar cada ferramenta manualmente e ver as respostas.

---

## Estrutura do projeto

```
cartola_mcp/
├── server.py          # Ponto de entrada do servidor MCP
├── client.py          # Configuração das chamadas à API do Cartola
├── tools/
│   ├── rodadas.py     # Rodadas e partidas
│   ├── atletas.py     # Mercado e pontuações
│   └── times.py       # Times dos cartoleiros
├── resources/
│   └── clubes.py      # Dados dos clubes do Brasileirão
├── .env               # Configurações (URL e timeout da API)
└── requirements.txt   # Dependências Python
```