# MCP Trello

Servidor MCP (Model Context Protocol) em Python que expõe operações do Trello como ferramentas para agentes de IA (Claude Code, **OpenCode**, Claude Desktop, Cursor, etc).

## ✨ Diferenciais

- **🧠 Fuzzy Matching Inteligente** — A IA não precisa saber IDs ou nomes exatos. "Move para Sprint Atual" funciona com aproximações, em cards, listas, labels e boards.
- **🗂️ Cobertura completa de card** — cria, move, comenta, adiciona label, cria checklist e busca detalhes completos (descrição, prazo, membros, checklists) numa tool só.
- **🔀 Multi-board opcional** — todas as tools aceitam `board_name`; sem passar nada, usa o board padrão do `.env`.

## Tools

| Tool                | Descrição                                          |
| ------------------- | --------------------------------------------------- |
| `create_card`       | Cria card em uma lista (por nome)                    |
| `move_card`         | Move card entre listas                               |
| `add_comment`       | Comenta em um card                                   |
| `list_cards`        | Lista todos os cards agrupados por lista             |
| `board_status`      | Resumo: contagem de cards por lista                  |
| `add_label`         | Adiciona um label existente a um card                |
| `create_checklist`  | Cria um checklist em um card, com itens opcionais    |
| `get_card_details`  | Detalhes completos de um card (desc, prazo, labels, membros, checklists) |

Todas as tools aceitam `board_name` opcional — se omitido, usa o board padrão configurado em `TRELLO_BOARD_ID`. Passar um nome (com fuzzy matching, igual listas/labels) faz a tool operar em outro board acessível pelo mesmo token.

## Instalação

### Pré-requisito: uv

Único software que precisa estar instalado antes. Sem ele, o comando `uvx` da Opção A não existe.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

(Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`.) Não precisa instalar Python/pip à parte — o `uv` resolve isso sozinho.

### Opção A — uvx (recomendado, não exige clonar nada)

Rode o wizard interativo — ele explica onde pegar a API Key/Token do Trello e salva tudo em `~/.config/mcp-trello/.env`:

```bash
uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello setup
```

Pronto — nenhum outro passo manual de instalação é necessário. Aponte seu client MCP pro comando abaixo (veja as seções de cada client).

### Opção B — clone local (contribuindo no código)

```bash
git clone https://github.com/vick1st/mcp-trello
cd mcp-trello
python3 -m venv .venv
source .venv/bin/activate   # Linux/Mac
pip install -e .
mcp-trello setup       # mesmo wizard da opção A
```

### Validar

```bash
mcp-trello
```

Se logar `TrelloClient initialized` e `MCP Trello Server starting...`, está ok (`Ctrl+C` pra sair).

Todos os clients abaixo usam o **mesmo comando**, sem caminho absoluto e sem precisar clonar o repo:

```
command: uvx
args: ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
```

As credenciais já ficam salvas em `~/.config/mcp-trello/.env` (feito pelo `mcp-trello setup`), então não precisa repetir chave em cada client — a menos que prefira isolar por projeto (veja alternativa por variável de ambiente abaixo).

## Configurar no OpenCode

`opencode.json` (na raiz do projeto) ou `~/.config/opencode/mcp.json` (global):

```json
{
  "mcpServers": {
    "mcp-trello": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
    }
  }
}
```

Ou via CLI:

```bash
opencode mcp add mcp-trello -- uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello
```

Reinicie a sessão do OpenCode — as tools aparecem automaticamente.

## Configurar no Claude Code

`.mcp.json` (projeto) ou via CLI:

```json
{
  "mcpServers": {
    "mcp-trello": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
    }
  }
}
```

```bash
claude mcp add mcp-trello -- uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello
```

## Configurar no Claude Desktop

Último caso — exige gerenciar app nativo. Edite `~/.config/claude-desktop/claude_desktop_config.json` (Linux) ou equivalente com o mesmo bloco `command`/`args` acima.

## Alternativa: credenciais direto no client (sem rodar `setup`)

Se seu client MCP suportar um campo `env` por servidor, dá pra pular o wizard e passar as variáveis direto na config (útil pra CI ou múltiplos boards):

```json
{
  "mcpServers": {
    "mcp-trello": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"],
      "env": {
        "TRELLO_API_KEY": "...",
        "TRELLO_TOKEN": "...",
        "TRELLO_BOARD_ID": "..."
      }
    }
  }
}
```

**Como obter as credenciais:**

1. Acesse https://trello.com/power-ups/admin
2. Crie/abra seu Power-Up → copie a **API Key**
3. Gere o token abrindo no browser: `https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=SUA_API_KEY` → autorize → copie o token
4. `TRELLO_BOARD_ID`: pegue da URL do board, `https://trello.com/b/{BOARD_ID}/nome-do-board`

## Troubleshooting

**`uvx: command not found`** — Instale o uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`.

**`invalid key` ao chamar qualquer tool** — Key regenerada ou copiada do portal antigo. Confirme em https://trello.com/power-ups/admin.

**`invalid app token` / `token not found`** — Token copiado errado. Não confunda "Segredo" (API secret) com "Token" (gerado via URL de authorize).

**`LIST_NOT_FOUND` / `CARD_NOT_FOUND`** — O fuzzy matching tenta aproximações com cutoff 0.75. Se falhar, use `list_cards` para ver os nomes exatos.

**Claude/OpenCode não enxerga as tools** — Reinicie a sessão completamente após editar a config.

## Estrutura

```
src/mcp_trello/
├── cli.py             # entry point do console_script (server ou `setup`)
├── setup_wizard.py    # wizard interativo de credenciais
├── server.py          # protocolo MCP, registro de tools
├── trello/client.py   # HTTP + auth + fuzzy matching com Trello
├── tools/             # handlers async, um por tool MCP
└── config/settings.py # carrega e valida credenciais (env vars / .env)
```