@farm3/claude-plugin 0.0.0-stage → 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "farm3",
+  "version": "1.0.0",
+  "description": "farm3 (CDP) no Claude Code via MCP: consultar e gerenciar perfis, eventos, segmentos, funis, ativações (e-mail, anúncios, webhooks), análises, conectores, LGPD, recomendações do agente e configurações do tenant. Autenticado por API key com escopo mcp:read ou mcp:write.",
+  "author": { "name": "farm3" },
+  "homepage": "https://farm3.io",
+  "license": "MIT",
+  "userConfig": {
+    "api_key": {
+      "type": "string",
+      "title": "API key do farm3",
+      "description": "Chave cdp_live_... com escopo \"MCP — leitura\" ou \"MCP — leitura e escrita\", criada em Configurações > API no painel do farm3.",
+      "required": true,
+      "sensitive": true
+    },
+    "api_url": {
+      "type": "string",
+      "title": "URL do farm3",
+      "description": "Endereço do painel do farm3. Mude só para desenvolvimento local (ex.: http://localhost:3000).",
+      "default": "https://app.farm3.io"
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "farm3": {
+      "type": "http",
+      "url": "${user_config.api_url}/api/v1/mcp",
+      "headers": {
+        "Authorization": "Bearer ${user_config.api_key}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 farm3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# farm3 para o Claude Code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Este plugin conecta o **farm3** ao **Claude Code**. Depois de instalar, você pede em português e o
+Claude consulta e gerencia o seu tenant: perfis, segmentos, funis, ativações, campanhas,
+conectores, LGPD, recomendações do agente e configurações.
+
+O plugin instala duas coisas:
+
+- **Servidor MCP `farm3`** — as tools da plataforma (leitura e, com a chave certa, escrita).
+- **Skill `farm3`** — ensina o Claude a usar as tools: mapa por espaço, fluxos típicos e o que só
+  pode ser feito no painel.
+
+> Ainda não tem o Claude Code? Instale pelo guia oficial em https://claude.com/claude-code.
+
+## Instalação
+
+### 1. Crie uma chave de API com escopo MCP
+
+No painel do farm3, vá em **Configurações > API > Criar chave** e marque **um** destes escopos:
+
+- **MCP — leitura**: o Claude só consulta.
+- **MCP — leitura e escrita**: o Claude também cria e altera (sempre pedindo sua confirmação).
+
+A chave aparece uma vez só; o próprio painel mostra os comandos de instalação já com ela.
+Uma chave MCP não pode ter o escopo de ingestão (SDK) junto: use chaves separadas.
+
+A chave age com o **papel atual** de quem a criou no tenant (VIEWER, EDITOR ou ADMIN). Se essa
+pessoa perder acesso ao tenant, a chave para de funcionar.
+
+### 2. Instale o plugin
+
+No terminal:
+
+```bash
+claude plugin marketplace add https://farm3.io/claude/marketplace.json
+claude plugin install farm3@farm3 --config api_key=cdp_live_...
+```
+
+Ou, dentro do Claude Code, `/plugin marketplace add https://farm3.io/claude/marketplace.json` e
+`/plugin install farm3@farm3`: o Claude Code pede a chave na instalação.
+
+A chave fica no armazenamento seguro do Claude Code (não em arquivo de configuração). Para trocá-la
+depois: `claude plugin configure farm3@farm3` (ou `/plugin` → Installed → Configure options).
+
+O plugin é público: vem do pacote npm [`@farm3/claude-plugin`](https://www.npmjs.com/package/@farm3/claude-plugin),
+e nenhuma conta no GitHub é necessária.
+
+### 3. Confira
+
+```
+/mcp
+```
+
+O servidor **`farm3`** deve aparecer conectado. Depois é só pedir, por exemplo:
+
+- "Resuma o Hoje do farm3 e liste as recomendações pendentes."
+- "Quantos clientes compraram nos últimos 30 dias e não abriram e-mail? Monte um segmento."
+- "Algum conector está com erro?"
+- "Tem pedido de titular LGPD aberto?"
+
+## Ambiente local (desenvolvimento)
+
+Por padrão o plugin fala com `https://app.farm3.io`. Para usar a API local, troque a URL nas
+opções do plugin:
+
+```bash
+claude plugin configure farm3@farm3 --config api_url=http://localhost:3000 --config api_key=cdp_live_...
+```
+
+Para testar mudanças do próprio plugin sem publicar, use o marketplace do repositório (fonte
+local): `claude plugin marketplace add /caminho/para/farm3`.
+
+## Publicação (time farm3)
+
+1. Suba a versão em `plugins/farm3/package.json` **e** em `.claude-plugin/plugin.json` (o Claude Code
+   usa a versão do `plugin.json` para atualizar).
+2. `pnpm plugin:release:dry` para conferir o pacote (valida o plugin antes).
+3. `pnpm plugin:release` no seu terminal (autenticação web do npm, org `farm3`).
+4. O marketplace público é `apps/site/public/claude/marketplace.json`, publicado com o site em
+   `https://farm3.io/claude/marketplace.json`. Ele aceita `^1.0.0`, então versões compatíveis
+   chegam sem mudar o JSON; uma versão maior (2.x) exige atualizar o `version` dele.
+
+## Problemas comuns
+
+| Sintoma | Causa provável |
+| --- | --- |
+| `401` ao conectar | A chave configurada no plugin está errada (reconfigure com `claude plugin configure farm3@farm3`); ou não tem escopo MCP; ou foi revogada/expirou; ou quem a criou foi removido do tenant. |
+| Só aparecem tools de leitura | A chave é **MCP — leitura**. Crie uma com **MCP — leitura e escrita**. |
+| Escrita recusada por permissão | O papel atual de quem criou a chave não permite essa ação (ex.: VIEWER). |
+| "Não encontrado" | O id é de outro tenant ou não existe. Tudo é do tenant da chave. |
+| Algo que não existe como tool | Criar API keys, conectar conector por OAuth, excluir perfil/tenant/conector/membro, checkout, coprodução e admin são feitos no painel. |
+
+Trate a chave como senha: não a coloque em arquivos versionados nem no histórico do shell compartilhado.

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@farm3/claude-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Plugin do farm3 para o Claude Code: servidor MCP (perfis, segmentos, funis, ativações, análises, conectores, LGPD) e a skill farm3",
+  "keywords": [
+    "farm3",
+    "cdp",
+    "claude-code",
+    "claude-plugin",
+    "mcp"
+  ],
+  "homepage": "https://farm3.io",
+  "author": "farm3",
+  "license": "MIT",
+  "files": [
+    ".claude-plugin",
+    ".mcp.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "validate": "claude plugin validate .",
+    "prepublishOnly": "npm run validate",
+    "release": "npm publish --auth-type=web",
+    "release:dry": "npm publish --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/farm3/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: farm3
+description: >-
+  Opera o farm3 (CDP para infoprodutores) pelo servidor MCP `farm3` (tools `mcp__farm3__*`).
+  Use quando a pessoa quiser consultar ou gerenciar perfis de clientes, identidades, eventos,
+  segmentos, funis, ativações (destinos de e-mail, públicos de anúncios, webhooks de saída),
+  campanhas e ROAS, análises (receita, RFM, LTV, retenção), conectores e saúde da ingestão de
+  dados, LGPD (solicitações de titulares, consentimentos, auditoria), recomendações e alertas do
+  agente (o "Hoje"), notificações, equipe, plano/cobrança ou configurações do tenant — ou quando
+  mencionar "farm3", "CDP", "meu tenant", "montar um segmento", "mandar público para o Meta/Google",
+  "o que o agente recomendou", "por que o conector parou", "pedido de titular". Requer o servidor
+  `farm3` conectado (`/mcp` → farm3 conectado), configurado com uma API key de escopo MCP.
+---
+
+# farm3 via MCP
+
+Tudo acontece no **tenant da API key**. Um recurso de outro tenant (ou inexistente) volta como
+**"não encontrado"** — não insista com o mesmo id; liste de novo para achar o certo.
+
+## Mapa: espaços do produto → tools
+
+| Espaço | Prefixos das tools |
+| --- | --- |
+| **Hoje** | `today_overview`, `recommendations_*`, `action_*`, `signals_*`, `forecasts_list`, `metrics_*`, `intelligence_*`, `notifications_*` |
+| **Clientes** | `profiles_*`/`profile_*`, `identity_*`, `events_*`/`event_*`, `segments_*`/`segment_*`, `funnels_*`/`funnel_*` |
+| **Ações** | `email_destinations_*`, `ads_*`, `outbound_webhooks_*` |
+| **Análises** | `analytics_*`, `rfm_*`, `ltv_*`, `campaign_*` |
+| **Dados** | `connectors_*`/`connector_*`, `ingest_*`, `bi_access_*` |
+| **Governança** | `lgpd_*`, `audit_*` |
+| **Configurações** | `tenant_get`, `settings_*`, `team_*`, `onboarding_get`, `billing_*`, `coproductions_*` |
+
+Os nomes exatos e os parâmetros estão no catálogo do servidor; confira-os antes de chamar.
+
+## Fluxos típicos
+
+**Montar um segmento e ativá-lo**
+1. `segments_list` para ver se já existe algo parecido.
+2. `segment_preview` com as condições (QueryGroup) — mostre à pessoa a contagem e a amostra.
+3. Com o "ok", `segment_create`.
+4. Ative: `ads_activation_create` (público em plataforma de anúncio) ou um destino de e-mail
+   (`email_destinations_*`).
+
+**Revisar o Hoje**
+1. `today_overview` para o resumo.
+2. `recommendations_list` para as propostas do agente; detalhe a que interessar.
+3. Só depois de a pessoa decidir: `action_approve` (ou rejeitar/adiar).
+
+**Saúde dos dados**
+1. `connectors_list` e o status de cada conector (`connectors_status`).
+2. Se um conector estiver atrasado ou com erro, ofereça `connector_sync`.
+3. `ingest_overview` para o volume e os erros da ingestão pelo SDK.
+
+**Atender um titular (LGPD)**
+1. `lgpd_requests_list` para as solicitações pendentes; detalhe a escolhida.
+2. Explique o que a aprovação faz (exportar, corrigir, anonimizar) e confirme.
+3. `lgpd_request_approve` ou `lgpd_request_reject` com o motivo.
+
+## Regras
+
+1. **Leia antes de escrever.** Liste/detalhe o recurso antes de alterá-lo; em segmentos, sempre
+   `segment_preview` antes de `segment_create`.
+2. **Confirme com a pessoa antes de qualquer escrita**, dizendo o que vai mudar e o alcance
+   (quantos perfis, qual plataforma, qual custo). Em ações destrutivas ou irreversíveis
+   (arquivar, revogar, anonimizar, enviar público, disparar sync), peça confirmação explícita.
+3. **"Não encontrado"** = id de outro tenant ou inexistente. Não é falha do servidor.
+4. **Chave só de leitura não vê tools de escrita.** Se a tool de escrita não aparece, a chave é
+   `mcp:read`; a pessoa precisa de uma chave `mcp:write` (Configurações > API). Mesmo com
+   `mcp:write`, cada escrita respeita o papel atual (VIEWER/EDITOR/ADMIN) de quem criou a chave,
+   e toda escrita fica na auditoria.
+5. **Respostas grandes são truncadas:** use filtros e paginação (`page`/`limit`).
+
+## Fora do MCP (faça no painel)
+
+Por decisão de segurança, isto **não** existe como tool — oriente a pessoa a usar o painel do farm3:
+
+- Criar, revogar ou rotacionar API keys e credenciais de acesso BI.
+- Conectar conectores por OAuth — `connector_connect_url` devolve o link para a pessoa abrir.
+- Excluir perfil (anonimização LGPD), tenant, conector ou membro da equipe.
+- Checkout / troca de plano.
+- Aceitar ou propor coprodução.
+- Administração da plataforma e Marketplace.