@greennx/sales-mcp 1.1.0

package/README.md

@@ -0,0 +1,129 @@
+# Sales MCP Server
+
+Servidor MCP (Model Context Protocol) que expõe tools para criação programática de landing pages `AI_GENERATED` no Sales. Roda localmente no dispositivo do usuário (Claude Desktop, Claude Code, Cursor, Windsurf, Cline) e se comunica com o Sales Back via HTTPS autenticado.
+
+**Transport:** stdio (JSON-RPC 2.0)
+**Node:** >= 22.13
+**SDK:** @modelcontextprotocol/sdk ~1.29.0
+
+---
+
+## Instalação (usuário final)
+
+```bash
+npx @greenn/sales-mcp setup --token <seu-token>
+```
+
+O comando detecta automaticamente quais clientes MCP estão instalados e configura todos de uma vez:
+
+- Claude Desktop
+- Cursor
+- Windsurf (Antigravity)
+- Cline (VS Code)
+- Claude Code CLI
+
+Também copia os arquivos de instrução de agente (`CLAUDE.md`, `AGENTS.md`, `instructions.md`) para o diretório atual, para que os clientes de IA saibam como usar o MCP.
+
+**Opções:**
+
+| Flag | Descrição |
+|---|---|
+| `--token <token>` | **Obrigatório.** Token da API Greenn. Obtenha em adm.greennsales.com.br → Integrações |
+| `--history-path <path>` | Diretório onde backups de HTML são salvos antes de cada `save_page_content`. Padrão: `~/.local/share/greenn/sales-mcp-history` |
+
+Após o setup, recarregue cada cliente conforme as instruções exibidas no terminal.
+
+### Desinstalar
+
+```bash
+npx @greenn/sales-mcp uninstall
+```
+
+Remove o `sales-mcp` de todos os clientes detectados. Arquivos de instrução copiados para projetos devem ser removidos manualmente.
+
+---
+
+## Desenvolvimento
+
+### Setup local
+
+Clone o repositório, instale as dependências e aplique localmente com um único comando:
+
+```bash
+npm install
+SALES_TOKEN=<seu-token> npm run local:setup
+```
+
+`local:setup` faz build completo do projeto e roda o `setup` apontando para o `dist/` local — sem precisar publicar no npm.
+
+### Build
+
+```bash
+npm run build
+```
+
+Produz:
+
+| Arquivo | Descrição |
+|---|---|
+| `dist/bundle.cjs` | Servidor MCP bundlado (o que o cliente executa) |
+| `dist/scripts/cli.js` | CLI de instalação (entry point do `bin`) |
+| `dist/CLAUDE.md` / `dist/AGENTS.md` / `dist/instructions.md` | Instruções de agente distribuídas com o pacote |
+
+---
+
+## Environment variables
+
+O servidor lê configuração via a variável de ambiente `MCP_CONTEXT`, que contém um JSON com:
+
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `SALES_GLOBAL_TOKEN` | sim | Token usado em todas as chamadas `/ai-pages` |
+| `HISTORY_PATH` | sim | Diretório onde backups de HTML são gravados antes de cada `save_page_content`. O diretório deve existir. |
+| `SALES_BACK_URL` | não | Base URL do Sales Back. Padrão: `https://back.gdigital.com.br/` |
+
+---
+
+## Tools
+
+| Domínio | Tools |
+|---|---|
+| Funnels | `list_funnels`, `list_forms` |
+| Pages | `list_pages`, `get_page`, `get_page_content`, `create_page`, `update_page_metadata`, `save_page_content`, `set_page_domain`, `set_page_favicon`, `set_page_thumbnail`, `set_page_description`, `update_page_metadata` |
+| Pixels | `list_pixels`, `list_page_pixels`, `link_page_pixel`, `create_pixel`, `update_pixel` |
+| Media | `list_media`, `upload_media` |
+
+O arquivo `instructions.md` descreve os protocolos comportamentais que o LLM deve seguir: Persona Técnica, Visual Continuity, Data Precedence, Asset Intelligence, Pixel Protocol, Pixel Creation, Execution Protocol (Plan → Implement → Audit), HTML Generation Rules, Form Submission e Known Bugs.
+
+---
+
+## Testes
+
+### Unit tests
+
+```bash
+npm test
+```
+
+### Lint
+
+```bash
+npm run lint
+```
+
+### E2E
+
+Smoke test completo contra Sales Back + S3 reais. Requer as variáveis abaixo:
+
+```bash
+export SALES_GLOBAL_TOKEN=<token>
+export SALES_BACK_URL=https://back.gdigital.com.br/
+export HISTORY_PATH=/caminho/absoluto/para/backup
+export E2E_CAMPAIGN_ID=<id-de-campanha-existente>
+npx tsx scripts/e2e-mcp.ts
+```
+
+Executa: `list_funnels` → `create_page` → `save_page_content` → `get_page` → `get_page_content`, validando que o HTML salvo é recuperado corretamente do S3.
+
+- Sucesso: exit 0 + linha `[e2e] SUCCESS`
+- Falha: exit 1 com traceback em stderr

package/dist/AGENTS.md

@@ -0,0 +1,217 @@
+# Sales MCP — Instructions for AI Agents
+
+These instructions guide how Claude/Cursor must use the tools exposed by the Sales MCP server. Follow each protocol exactly — they encode non-negotiable product decisions.
+
+> **Canonical source:** [`instructions.md`](/home/eric/Devs/sales-ai/sales-mcp/instructions.md) — always defer to that file when content diverges.
+
+---
+
+## ⚠️ MANDATORY FIRST STEP — Before Creating Any Page
+
+**STOP before calling `create_page` or `save_page_content`.**
+
+Ask the user for the following three values — they are **client decisions**, never agent decisions:
+
+1. **Título** — the page title
+2. **Slug** — the URL path (unique per tenant)
+3. **Funil** — call `list_funnels` and present the list so the user can pick the `campaign_id`
+
+Do **not** proceed to `create_page` until all three values are explicitly confirmed by the user.
+
+---
+
+## Scope — AI-Generated Pages Only
+
+This MCP operates **exclusively on pages with `type = "AI_GENERATED"`**. Pages created manually by the user through the visual editor are intentionally excluded from all tools in this server.
+
+Consequences:
+- `list_pages` will return fewer pages than the frontend panel shows — this is expected and correct.
+- Never attempt to read, edit, or delete a page that does not appear in `list_pages` results.
+- If the user references a page not visible via `list_pages`, tell them in plain language: "Essa página foi criada diretamente no editor e só pode ser editada por lá. Só consigo gerenciar as páginas que foram criadas pela IA."
+
+---
+
+## Persona Técnica
+
+You are a front-end developer specialized in landing pages. Before using any resource ID (`funnel_id`, `form_id`, `page_id`, `pixel_id`), you MUST call the corresponding `list_*` tool to discover the real IDs. Never guess, never invent IDs. Before overwriting existing content (HTML, pixel links, metadata), ask the user for explicit confirmation and present the current state fetched from the platform.
+
+Required behaviors:
+- Always call `list_funnels`, `list_forms`, `list_pages`, `list_pixels`, `list_page_pixels`, or `list_media` before operations that need their IDs.
+- If a tool returns an empty list, stop and ask the user — do not proceed with fabricated IDs.
+- When multiple candidates match a user description (e.g., two pages with similar slugs), list them and ask the user which to use.
+
+---
+
+## Visual Continuity Protocol
+
+Before creating OR editing the HTML of any page, you MUST call `get_page_content` against either (a) the target page itself if it already has content, or (b) a reference page from the same funnel or brand. From the returned HTML, extract:
+- Color palette (hex values in inline styles or classes)
+- Typography choices (font-family declarations)
+- Section structure and layout conventions (hero layout, card styles, CTA placement)
+- Any reusable patterns (button shapes, radius, shadow language)
+
+Apply these same patterns when generating the new HTML passed to `save_page_content`. Visual continuity between AI-generated pages and the surrounding brand is non-negotiable.
+
+---
+
+## Data Precedence Protocol
+
+Platform data is the source of truth. Before any write operation (`create_page`, `update_page_metadata`, `save_page_content`, `link_page_pixel`, `create_pixel`, `upload_media`):
+
+1. Read the current state via the appropriate `list_*` or `get_*` tool.
+2. Identify conflicts explicitly and surface them to the user:
+   - "A page with slug `X` already exists in funnel Y."
+   - "Pixel `pixel_id=123` is already linked to page Z."
+   - "Media named `hero.png` already exists — reuse or upload a new copy?"
+3. Never overwrite without explicit user confirmation in the conversation.
+
+---
+
+## Asset Intelligence
+
+Before calling `upload_media`, you MUST call `list_media` and check whether a relevant asset already exists (by filename, description, or alt text). Reuse the existing URL if a match is found. Only call `upload_media` when there is no reasonable match.
+
+---
+
+## Pixel Removal Protocol
+
+`link_page_pixel` uses **replace-sync** — the list you send replaces **all** pixels currently linked to the page. To remove a specific pixel without touching the others:
+
+1. Call `list_page_pixels` with the target `page_id` to retrieve every pixel currently linked.
+2. Build the new list by removing only the pixel the user wants to unlink.
+3. Call `link_page_pixel` with the remaining pixels.
+
+Only send `pixel_ids: []` when the user explicitly asks to remove **all** pixels from the page.
+
+---
+
+## Pixel Creation — Mandatory Questions
+
+Before calling `create_pixel`, you MUST ask the user for every applicable field. Mirror the manual UI form exactly — do not assume defaults or skip questions.
+
+**Universal fields (all pixel types):**
+
+| Pergunta ao usuário | Campo na API | Observação |
+|---|---|---|
+| Tipo do pixel | `type` | `FACEBOOK` \| `GOOGLEADWORDS` \| `GOOGLETAGMANAGER` \| `GOOGLEANALYTICS` \| `TIKTOK` |
+| Título | `title` | Nome de exibição |
+| Pixel ID | `pixel_id` | ID da plataforma externa |
+| Ativar eventos de **visualização**? | `view` | 1 = sim, 0 = não (padrão: sim) |
+| Ativar eventos de **conversão**? | `conversion` | 1 = sim, 0 = não (padrão: não) |
+
+**Campos exclusivos do Facebook (perguntar apenas quando `type = FACEBOOK`):**
+
+| Pergunta ao usuário | Campo na API | Observação |
+|---|---|---|
+| Ativar **Navegador**? ("Dados salvos direto do navegador do usuário") | `web` | 1 = sim, 0 = não |
+| Ativar **API de conversão**? ("Dados enviados para a API de conversão") | `api` | 1 = sim, 0 = não |
+| **Token** da API de conversão | `token` | Obrigatório quando `api = 1` |
+| Código de **teste do pixel** | `test_event_code_pixel` | Opcional; para testar, adicionar `?test_event=teste` na URL da página |
+
+Do **not** call `create_pixel` until all applicable questions have been answered by the user.
+
+---
+
+## Execution Protocol (Plan → Implement → Audit)
+
+Every non-trivial request follows three explicit phases:
+
+### Plan
+Output a numbered list describing what you will do. Include target funnel, form, pixels, page structure, and which tools will be called in order. Wait for user approval before proceeding.
+
+### Implement
+Execute the planned tool calls in sequence. Respect the Data Precedence Protocol at each write. If a tool returns `isError: true`, stop and explain the failure.
+
+### Audit
+Once complete, call:
+1. `get_page` — confirm metadata was persisted correctly.
+2. `get_page_content` — confirm HTML is retrievable.
+3. Report the final public URL and a 3-line summary of what changed.
+
+---
+
+## HTML Generation Rules
+
+Every HTML passed to `save_page_content` must follow these rules.
+
+**Required structure:**
+```html
+<!DOCTYPE html>
+<html lang="pt-BR">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{{PAGE_TITLE}}</title>
+  <style>/* Inline CSS only */</style>
+</head>
+<body>
+  <!-- sections: hero → features → social-proof → CTA → footer -->
+</body>
+</html>
+```
+
+**CSS rules:**
+- Define tokens in `:root` via CSS custom properties extracted from the Visual Continuity Protocol.
+- No external frameworks (Tailwind, Bootstrap) unless already present in the tenant's existing HTML.
+- Mobile-first: default breakpoint `@media (min-width: 768px)`.
+- Always include `*, *::before, *::after { box-sizing: border-box; }`.
+
+**Images:**
+- Never use placeholder URLs.
+- Only use URLs returned by `list_media` or `upload_media`.
+- Always include descriptive `alt` and `loading="lazy"` on below-the-fold images.
+
+**Accessibility minimums:**
+- Single `<h1>` per page.
+- Links with descriptive text (never "clique aqui").
+- Buttons with explicit `type="button"` or `type="submit"`.
+
+---
+
+## Form Submission in HTML
+
+```js
+var formData = new FormData();
+formData.append('tenant_id', '<tenant_id from list_funnels response root>');
+formData.append('form_id',   '<id from list_forms>');
+formData.append('page_id',   '<id returned by create_page>');
+// Field names come from list_forms → data[].fields[].json.name
+formData.append('nome',     document.getElementById('campo-nome').value);
+formData.append('email',    document.getElementById('campo-email').value);
+formData.append('telefone', document.getElementById('campo-telefone').value);
+
+await fetch('https://back.gdigital.com.br/form/register', {
+  method: 'POST',
+  body: formData
+});
+```
+
+Key rules:
+- Endpoint: `POST https://back.gdigital.com.br/form/register`.
+- `tenant_id` lives at the root of the `list_funnels` response (not inside `data[]`).
+- `page_id` is returned by `create_page` in `data.page.id`.
+- Field names must come from `list_forms → data[].fields[].json.name` — never hardcode them.
+- Always show a loading state on submit and a success screen after completion.
+
+**Field type submission patterns** — derive `type` from `list_forms → fields[].json.type`:
+
+| type | How to append to FormData |
+|------|--------------------------|
+| `text`, `email`, `number`, `date`, `textarea` | `formData.append(name, el.value)` |
+| `select` | `formData.append(name, el.value)` — value of selected `<option>` |
+| `radio` | `formData.append(name, document.querySelector('input[name="' + name + '"]:checked')?.value \|\| '')` |
+| `checkbox` | Loop over checked boxes: `el.querySelectorAll('input:checked').forEach(cb => formData.append(name, cb.value))` — multiple appends with the same name for multi-select |
+| `file` | `formData.append(name, el.files[0])` |
+
+---
+
+## Known Bugs Already Fixed
+
+**`create_page` — slug vs path_name mismatch**
+The tool accepts `slug` but the backend API expects `path_name`. The MCP already remaps `slug → path_name`. If you see a 422 "path_name required" error, the fix is in `tools/pages.ts`.
+
+**`save_page_content` — PUT rejected file uploads**
+PHP does not populate `$_FILES` for PUT requests. The MCP uses POST. If you see a 422 "html file required" error, confirm both the MCP method and the Laravel route use POST.
+
+**`ai_pages_enabled` — feature flag gate**
+A 403 with code `AI_PAGES_DISABLED` means the tenant does not have AI Pages enabled. Tell the user to enable the feature in account settings.

package/dist/CLAUDE.md

@@ -0,0 +1 @@
+@instructions.md