# Ploomes MCP Server

Servidor MCP (Model Context Protocol) que conecta assistentes de IA ao CRM Ploomes.
Expõe **153 tools** cobrindo CRUD das entidades do Ploomes, configuração de funis e
campos, CPQ (modelos de Proposta/Venda/Documento), automações e webhooks.

Histórico de mudanças em [CHANGELOG.md](CHANGELOG.md).

## Setup

```bash
uv sync
```

Crie um `.env`:

```env
# Obrigatórias
PLOOMES_API_KEY=sua_chave
PLOOMES_BASE_URL=https://api2.ploomes.com
PLOOMES_USER_ID=id_numerico

# Opcional — loga request/response completo no stderr
PLOOMES_DEBUG=1

# Opcional — apenas para o caminho "gateway" de geração de HTML de proposta
# (gerar_modelo_html_ia, identificar_campos_html_ia, criar_campos_em_massa_ia).
# É uma credencial PRÓPRIA dessa feature, diferente da PLOOMES_API_KEY.
# Sem ela, essas três tools retornam erro explicativo e o resto do servidor
# funciona normalmente — veja "Geração de HTML" abaixo para a alternativa que
# não precisa de credencial extra.
PLOOMES_AI_CLIENT_ID=
PLOOMES_AI_CLIENT_SECRET=
PLOOMES_AI_BASE_URL=https://ai.ploomes.run/api

# Opcional — debugging com LangSmith
OPENAI_API_KEY=
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=ploomes-mcp
```

Rode o servidor:

```bash
uv run python ploomes_server.py
```

## Verificação

Antes de subir o servidor ou abrir um PR, rode a verificação estática (não usa
rede nem credenciais):

```bash
uv run python tests/verificar_tools.py --strict
```

Ela detecta nome de tool duplicado, arquivo com tool não registrada em
`tools/__init__.py`, e import de símbolo inexistente — os três problemas que a
consolidação de 29/07/2026 encontrou. Em runtime, `register_all_tools` também
levanta `RuntimeError` se dois arquivos declararem o mesmo nome de tool, em vez de
deixar o FastMCP descartar um deles silenciosamente.

Roteiro de teste manual contra uma conta de **sandbox** (nunca produção):

```bash
uv run python test_novas_tools.py --etapa 1   # só leitura
uv run python test_novas_tools.py --etapa 2   # escrita, pede confirmação
```

## Geração de HTML de modelo de proposta

No Ploomes não existe editor de campo de formulário separado do HTML: os campos
que o usuário preenche ao gerar uma proposta são **derivados pelo backend** a
partir do parsing do HTML do corpo do documento (`Pages[].BodySourceCode`).
Escrever o HTML com as tags certas é a única forma de declarar um campo.

Há dois caminhos, e os dois terminam em `salvar_modelo_proposta`:

**Nativo** — só precisa da `PLOOMES_API_KEY`. O agente escreve o HTML.

1. `guia_html_modelo_proposta` — devolve as convenções de marcação.
2. O agente escreve o HTML, com `<field key="...">` para campos nativos e
   `<newfield .../>` onde precisar de campo customizado.
3. `criar_campos_novos_llm` — cria os campos customizados e devolve as Keys.
4. `aplicar_campos_novos_html_llm` — troca os `<newfield>` pelos `<field key="...">`.
5. `salvar_modelo_proposta` — cria o modelo e a primeira página.
6. `montar_bloco_produtos_proposta` — insere o bloco de itens, se houver.

**Gateway** — exige `PLOOMES_AI_CLIENT_ID`/`SECRET`, e aceita PDF, Word e imagem
como referência (o caminho nativo depende do agente ler os arquivos por conta
própria).

1. `gerar_modelo_html_ia` → 2. `identificar_campos_html_ia` →
3. `criar_campos_em_massa_ia` → 4. `aplicar_campos_no_html_ia` →
5. `salvar_modelo_proposta`

**Atalho** — para um modelo simples já com a identidade visual do cliente,
`montar_modelo_proposta_com_identidade` faz tudo numa chamada, a partir de um
brief de marca já extraído. Use os passos individuais quando precisar de layout
sob medida ou retomar de um erro no meio.

> As convenções de marcação vêm de engenharia reversa e captura de rede do app,
> não de documentação oficial da Ploomes. Valide em sandbox antes de produção.

## Add ao Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "ploomes": {
      "command": "uv",
      "args": ["run", "python", "/caminho/para/ploomes_server.py"],
      "env": {
        "PLOOMES_API_KEY": "sua_chave",
        "PLOOMES_BASE_URL": "https://api2.ploomes.com",
        "PLOOMES_USER_ID": "id_numerico"
      }
    }
  }
}
```

## Debug com LangSmith

Com as variáveis `LANGSMITH_*` definidas, as chamadas de tool são tracejadas
automaticamente. Rode `uv run python example.py` e veja o dashboard em
https://smith.langchain.com