ploomes-mcp

# 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