# kommo-integration-mcp

Servidor MCP que fecha o loop entre o **Mapeador de Funil** (a IA que desenha o
funil) e o **Kommo CRM**: você valida o funil gerado e, com aprovação
explícita, uma IA cria o pipeline, as etapas e os campos personalizados
diretamente no Kommo — sem trabalho manual na interface do CRM.

Suporta **múltiplos clientes/contas Kommo** num único servidor: cada chamada
informa qual cliente usar, então basta cadastrar credenciais uma vez em
`clients.json` — sem reiniciar nada ao adicionar um cliente novo.

## Fluxo

1. O Mapeador de Funil gera um JSON no formato descrito abaixo.
2. Você (ou a IA, via `validate_funnel`/`preview_funnel`) revisa etapas e campos.
3. A IA confirma qual cliente é (via `list_clients`).
4. Com o JSON aprovado, `create_funnel` (com `confirm: true`) cria tudo no Kommo daquele cliente.

## Ferramentas MCP expostas

| Ferramenta | O que faz | Grava no Kommo? |
|---|---|---|
| `list_clients` | Lista os clientes cadastrados em `clients.json` (chave, nome, subdomínio) | Não |
| `validate_funnel` | Valida o JSON do funil contra o schema, retorna erros/avisos | Não |
| `preview_funnel` | Gera um resumo legível do que será criado | Não |
| `list_pipelines` | Lista funis já existentes na conta de um cliente (evita duplicar) | Não |
| `list_custom_fields` | Lista campos personalizados já existentes por entidade de um cliente | Não |
| `create_funnel` | Cria o pipeline + etapas + campos personalizados para um cliente. Exige `confirm: true` | **Sim** |

`list_pipelines`, `list_custom_fields` e `create_funnel` recebem um parâmetro
`client` com a chave cadastrada em `clients.json` (ex: `"cliente-a"`).

## Formato do funil (contrato de entrada)

```jsonc
{
  "name": "Funil de Vendas - Novos Clientes",
  "stages": [
    { "name": "Novo lead", "color": "#99ccff" },
    { "name": "Contato realizado" },
    { "name": "Proposta enviada" }
  ],
  "fields": [
    {
      "name": "Origem do lead",
      "type": "select",
      "entity": "leads",
      "required": true,
      "options": ["Site", "Indicação", "Anúncio pago"]
    }
  ]
}
```

Veja um exemplo completo em [`examples/funnel.example.json`](examples/funnel.example.json).

Notas:
- O Kommo sempre cria automaticamente a etapa "Entrada de leads" no início e
  "Ganho"/"Perdido" no fim de todo pipeline — declare só as etapas intermediárias.
- `color` é opcional (hex, ex: `#99ccff`); se omitido o Kommo usa uma cor padrão.
- Tipos de campo suportados: `text`, `textarea`, `numeric`, `checkbox`, `select`,
  `multiselect`, `date`, `url`, `radiobutton`. `select`/`multiselect`/`radiobutton`
  exigem `options`.
- `entity` define onde o campo aparece: `leads` (padrão), `contacts`, `companies`
  ou `customers`.

## Setup

### 1. Instalar e buildar

```bash
npm install
npm run build
```

### 2. Cadastrar os clientes

Copie o exemplo e preencha um bloco por cliente:

```bash
cp clients.example.json clients.json
```

```jsonc
// clients.json
{
  "cliente-a": {
    "label": "Cliente A Ltda",
    "subdomain": "clientea",       // clientea.kommo.com
    "accessToken": "token-de-longa-duracao-do-cliente-a"
  },
  "cliente-b": {
    "label": "Cliente B S.A.",
    "subdomain": "clienteb",
    "accessToken": "token-de-longa-duracao-do-cliente-b"
  }
}
```

O token de longa duração de cada conta é gerado em: **Kommo → Configurações →
Integrações → sua integração → "Token de longa duração"**.

Para adicionar um cliente novo depois, só edite `clients.json` e chame
`list_clients` de novo — não precisa reiniciar o servidor nem o Claude
Desktop.

`clients.json` já está no `.gitignore`: nunca commite esse arquivo, ele
concentra os tokens de todos os clientes.

### 3. Registrar o servidor MCP no Claude

No `claude_desktop_config.json` (ou config equivalente do Claude Code):

```json
{
  "mcpServers": {
    "kommo-integration": {
      "command": "node",
      "args": ["/caminho/absoluto/para/kommo-integration-mcp/dist/index.js"]
    }
  }
}
```

Por padrão o servidor procura `clients.json` na raiz do projeto. Para usar
outro caminho (ex: um cofre de segredos fora do repositório), defina
`KOMMO_CLIENTS_FILE`:

```json
{
  "mcpServers": {
    "kommo-integration": {
      "command": "node",
      "args": ["/caminho/absoluto/para/kommo-integration-mcp/dist/index.js"],
      "env": {
        "KOMMO_CLIENTS_FILE": "/caminho/seguro/clients.json"
      }
    }
  }
}
```

Reinicie o Claude Desktop/Code. As ferramentas `list_clients`,
`validate_funnel`, `preview_funnel`, `list_pipelines`, `list_custom_fields` e
`create_funnel` ficam disponíveis na conversa.

## Desenvolvimento

```bash
npm run dev         # roda via tsx sem build
npm run typecheck    # checagem de tipos
npm run build         # compila para dist/
```

## Segurança

- `create_funnel` só executa se o parâmetro `confirm` vier `true` — trate isso
  como o "sim, pode criar" do humano que validou o funil.
- Cada token de longa duração dá acesso total à respectiva conta Kommo
  conforme as permissões da integração. `clients.json` concentra os tokens de
  todos os clientes — trate como segredo (já está no `.gitignore`; considere
  restringir permissões do arquivo, ex: `chmod 600 clients.json`).