aicrm-mcp 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicrm-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP server for AICRM — operate your CRM from Claude, Opencode and other MCP clients.",
   "type": "module",
   "bin": {
@@ -10,25 +10,27 @@
     "dist",
     "skill"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
     "papaparse": "^5.7.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@aicrm/shared": "workspace:*",
     "@types/node": "^22.20.5",
     "@types/papaparse": "^5.3.16",
     "tsup": "^9.0.0",
     "tsx": "^4.23.15",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5",
+    "@aicrm/shared": "0.1.0"
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}

package/skill/aicrm/SKILL.md

@@ -48,7 +48,7 @@ npx -y aicrm-mcp skill > AGENTS-aicrm.md  # imprime, para agentes que leem outro
 
 ### 1.5 Primeiro uso
 
-1. `list_workspaces` — confirma quem está logado (`you`), o papel (admin/member) e o que existe.
+1. `list_workspaces` — confirma quem está logado (`you`), o papel (admin, manager = Master, member = vendedor) e o que existe.
 2. Se for admin e a conta for nova, `get_setup_status` diz o que falta configurar e qual ferramenta resolve cada passo.
 
 Se qualquer ferramenta responder "Não autenticado" ou "Sessão expirada", peça à pessoa para rodar o `login` de novo.
@@ -71,27 +71,33 @@ Se qualquer ferramenta responder "Não autenticado" ou "Sessão expirada", peça
 
 O servidor aplica as regras do usuário logado. Nunca tente contornar uma negação.
 
-| Ação | member (vendedor) | admin |
-|---|---|---|
-| Ver leads | dos workspaces em que está (só os próprios se visibilidade `own`) | todos |
-| Criar lead | para si mesmo | para qualquer pessoa |
-| Editar, mover, ganhar/perder, reabrir | os próprios e os sem responsável | todos |
-| Notas | em leads que vê | todos |
-| Importar CSV | com ele mesmo como responsável | qualquer modo de distribuição |
-| Mover em massa | os próprios | todos, e reatribuir |
-| Excluir lead | — | sim |
-| Campos, campos padrão visíveis | só consulta | criar, editar, remover |
-| Modelos de importação | usa todos; altera/apaga os que criou | todos |
-| Workspaces, funis, etapas | só consulta | tudo |
-| Usuários e convites | só lista | convidar, alterar papel/workspaces, desativar |
-| Metas e comissão | consulta e dashboard | definir metas e planos |
-| Modo TV | — | criar, listar, revogar links |
-| Tokens de API | os próprios | os próprios |
+Há também o papel **developer** (Desenvolvedor), que integra outros sistemas pela API e não vê leads nem o time. Logado com ele, o MCP mostra só as ferramentas de integração. Para esse trabalho, use o skill `aicrm-integrate` (`npx -y aicrm-mcp skill install aicrm-integrate --project`).
+
+| Ação | member (vendedor) | manager (Master) — só nos workspaces dele | admin |
+|---|---|---|---|
+| Ver leads | dos workspaces em que está (só os próprios se visibilidade `own`) | todos, mesmo com `own` | todos |
+| Criar lead | para si mesmo | para qualquer vendedor; sem `owner` vai para a distribuição | idem Master |
+| Editar, mover, ganhar/perder, reabrir | os próprios e os sem responsável | todos | todos |
+| Notas | em leads que vê | todos | todos |
+| Importar CSV | com ele mesmo como responsável | qualquer modo; padrão `auto` | qualquer modo; padrão `auto` |
+| Mover em massa | os próprios | todos, e reatribuir | todos, e reatribuir |
+| Excluir lead | — | sim | sim |
+| Distribuição (pausar/liberar, entregar sem dono), leads em risco | — | sim | sim |
+| Plano do dia de outra pessoa | — | dos vendedores do time | de todos |
+| Campos, campos padrão visíveis | só consulta | só consulta | criar, editar, remover |
+| Modelos de importação | usa todos; altera/apaga os que criou | todos | todos |
+| Workspaces, funis, etapas | só consulta | só consulta | tudo |
+| Usuários e convites | só lista | convida **vendedores** para os workspaces dele; ajusta workspaces e desativa vendedores do time; não muda papel | convidar qualquer papel, alterar papel/workspaces, desativar |
+| Metas e comissão | consulta e dashboard | define metas; planos de comissão só consulta | definir metas e planos |
+| Modo TV | — | criar, listar, revogar links dos funis dele | criar, listar, revogar links |
+| Tokens de API | os próprios | os próprios | os próprios |
+
+**Quem recebe leads automaticamente:** só vendedores (`member`). Admins e Masters nunca entram na distribuição por desempenho nem no rodízio (`round_robin`); podem assumir um lead de propósito (`update_lead` com `owner` = eles mesmos).
 
 Como ler as respostas de erro:
-- **"… (seu usuário não tem permissão para isso — peça a um admin)"** → explique em uma frase que essa ação é de admin.
+- **"… (seu usuário não tem permissão para isso — peça a um admin ou Master)"** → explique em uma frase que essa ação é de admin (ou de Master, se for operação do time).
 - **"Lead não encontrado" / "Workspace não encontrado"** → pode não existir **ou** a pessoa não ter acesso (o servidor não diferencia, de propósito). Não insista.
-- **"Só o responsável pelo lead (ou um admin) pode editá-lo"** → o lead é de outra pessoa.
+- **"Só o responsável pelo lead (ou um admin/Master) pode editá-lo"** → o lead é de outra pessoa.
 
 ## 4. Regras de uso
 
@@ -121,12 +127,12 @@ Como ler as respostas de erro:
 | `handoff_lead` | Continuar um lead **ganho** em outro funil (pós-venda, relacionamento): cria um lead novo ligado ao original, na 1ª etapa (ou `stage`), valor R$ 0 (ou `value`), mesmo responsável (ou `owner`). O `get_lead` mostra o vínculo em `came_from` / `continues_in`. |
 | `add_note` | Registrar conversa, ligação, contexto. |
 | `bulk_update_leads` | Mover e/ou reatribuir vários leads de uma vez (ids do `search_leads`). |
-| `delete_lead` | Apagar com histórico (admin, destrutivo). |
+| `delete_lead` | Apagar com histórico (admin ou Master, destrutivo). |
 
 ### Importação de CSV
 | Ferramenta | Para quê |
 |---|---|
-| `import_leads_csv` | Importar um arquivo local. `dry_run: true` só mostra o plano; `columns` força o destino de colunas; `template_name` salva o mapeamento; `duplicate`: `skip` ou `update` (pelo email); `owner_mode`: `me`, `auto` (por desempenho, admin), `round_robin` (igualmente), `column`. |
+| `import_leads_csv` | Importar um arquivo local. `dry_run: true` só mostra o plano; `columns` força o destino de colunas; `template_name` salva o mapeamento; `duplicate`: `skip` ou `update` (pelo email); `owner_mode`: `me`, `auto` (por desempenho entre os vendedores), `round_robin` (igualmente entre os vendedores), `column`. Sem `owner_mode`, admin e Master usam `auto` (não ficam com a base) e vendedor usa `me`. |
 | `rename_import_template` / `delete_import_template` | Manter os modelos salvos. |
 
 ### Campos do workspace
@@ -139,30 +145,30 @@ Como ler as respostas de erro:
 ### Metas, comissão e previsão
 | Ferramenta | Para quê |
 |---|---|
-| `get_today_plan` | **Plano do dia**: os 5–10 leads abertos que mais ajudam a bater a meta hoje, em ordem, cada um com o motivo (`why`) e a ação sugerida (WhatsApp, próximo passo ou mover de etapa). Padrão: quem está logado; admins passam `seller`. |
+| `get_today_plan` | **Plano do dia**: os 5–10 leads abertos que mais ajudam a bater a meta hoje, em ordem, cada um com o motivo (`why`) e a ação sugerida (WhatsApp, próximo passo ou mover de etapa). Padrão: quem está logado; admins e Masters passam `seller`. |
 | `get_dashboard` | Mês do funil: realizado vs meta do time e de cada vendedor, chance de bater, projeção, cobertura de pipeline, taxa de conversão, comissão. |
 | `get_forecast` | Detalhe de um vendedor: vai bater a meta? |
 | `get_goals` / `set_goals` | Ver/definir metas por vendedor e mês (`target: 0` remove). |
 | `list_commission_plans` / `save_commission_plan` / `delete_commission_plan` | Planos com faixas. `percent`: % da receita (funis de receita). `per_unit`: R$ por unidade (funis de quantidade). |
 
-### Time e estrutura (admin)
+### Time e estrutura (admin; Master: convites de vendedores, distribuição e riscos do time dele)
 | Ferramenta | Para quê |
 |---|---|
 | `list_users` | Pessoas, papel, status (ativo, convite pendente, desativado), workspaces. |
 | `invite_user` / `resend_invite` | Convidar e gerar link (vale 7 dias; gerar outro invalida o anterior). Entregue o link à pessoa que pediu — você não envia emails. |
-| `update_user` | Nome, papel, workspaces (lista completa), ativar/desativar. |
+| `update_user` | Nome, papel, workspaces (lista completa), ativar/desativar. Master: só vendedores do time, sem mudar papel; os workspaces fora do time dele são mantidos. |
 | `create_workspace` / `update_workspace` / `delete_workspace` | Workspaces e visibilidade. |
 | `create_funnel` / `update_funnel` / `delete_funnel` | Funis, etapas (com `was` para renomear sem perder leads) e KPI de meta. |
 | `get_distribution` | Distribuição automática de leads no funil: a parte de cada vendedor e o motivo, quem não está recebendo e quantos leads esperam vendedor. Sem `funnel`, lista os bloqueios de todos os funis. |
 | `release_seller` / `pause_seller` | Voltar a mandar (ou parar de mandar) leads novos para um vendedor no funil. Os leads que ele já tem não mudam. |
-| `get_lead_risks` | Leads em risco: abertos que passaram do **dobro** do prazo da etapa (crítico), com valor em risco, onde trava (etapa), com quem (vendedor) e os mais atrasados; também conta quantos só passaram do prazo. Só admins. |
+| `get_lead_risks` | Leads em risco: abertos que passaram do **dobro** do prazo da etapa (crítico), com valor em risco, onde trava (etapa), com quem (vendedor) e os mais atrasados; também conta quantos só passaram do prazo. Admins e Masters. |
 | `assign_unowned_leads` | Entregar os leads abertos sem vendedor do funil, na proporção da distribuição. |
 
 ### Conta e operação
 | Ferramenta | Para quê |
 |---|---|
 | `get_setup_status` | O que falta configurar (funil, leads, time, metas, TV). |
-| `create_tv_link` / `list_tv_links` / `revoke_tv_link` | Dashboard ao vivo numa TV sem login (admin). O link funciona como senha. |
+| `create_tv_link` / `list_tv_links` / `revoke_tv_link` | Dashboard ao vivo numa TV sem login (admin ou Master). O link funciona como senha. |
 | `list_api_tokens` / `revoke_api_token` | Tokens do próprio usuário. Revogar o token em uso derruba esta conexão. |
 
 ## 6. Receitas
@@ -192,10 +198,10 @@ Como ler as respostas de erro:
 2. Confirme com a pessoa quantos leads e para quem.
 3. `bulk_update_leads` com os ids e o novo `owner`. Ao desligar alguém, faça isto **antes** de `update_user` com `active: false`.
 
-### Distribuição automática de leads (admin)
-- Ligar: `update_funnel` com `auto_assign: true`. A partir daí, leads que um admin cria (`create_lead` sem `owner`) ou importa (`owner_mode: "auto"`) sem vendedor vão para o time na proporção do desempenho: quem fecha mais (e, em funis de receita, negócios maiores) recebe mais; quem tem pouco histórico conta como a média; ninguém fica abaixo de uma parte mínima; carteira muito cheia recebe menos. Leads criados por um vendedor continuam dele.
-- Disciplina: todo dia útil o AICRM confere se cada vendedor com leads no funil fez **alguma ação** nele (nota, etapa, próximo passo, ganho/perda, lead novo). Quem não fez nada para de receber leads novos naquele funil até um admin liberar.
-- "Quais leads estão parados?" / "Onde o funil trava?" → `get_lead_risks`. Cada etapa tem um **prazo em dias úteis** (`limit_days` em `update_funnel`; padrão 14). Passou do prazo, o vendedor é avisado; passou do dobro, o admin também. Só mudar de etapa zera a contagem.
+### Distribuição automática de leads (admin e Master)
+- Ligar: `update_funnel` com `auto_assign: true`. Leads que um admin ou Master cria (`create_lead` sem `owner`) ou importa (`owner_mode: "auto"`, o padrão deles) sem vendedor vão para os vendedores na proporção do desempenho: quem fecha mais (e, em funis de receita, negócios maiores) recebe mais; quem tem pouco histórico conta como a média; ninguém fica abaixo de uma parte mínima; carteira muito cheia recebe menos. Leads criados por um vendedor continuam dele. Admins e Masters nunca recebem.
+- Disciplina: todo dia útil o AICRM confere se cada vendedor com leads no funil fez **alguma ação** nele (nota, etapa, próximo passo, ganho/perda, lead novo). Quem não fez nada para de receber leads novos naquele funil até um Master ou admin liberar.
+- "Quais leads estão parados?" / "Onde o funil trava?" → `get_lead_risks`. Cada etapa tem um **prazo em dias úteis** (`limit_days` em `update_funnel`; padrão 14). Passou do prazo, o vendedor é avisado; passou do dobro, o Master e o admin também. Só mudar de etapa zera a contagem.
 - "Quem está parado?" (vendedor sem ação) → `get_distribution` sem funil. Explique o motivo em uma frase e pergunte se deve liberar; só então `release_seller`.
 - Férias ou folga: `pause_seller` (confirme antes) e, na volta, `release_seller`.
 - Leads esperando vendedor (`leads_without_owner`): `assign_unowned_leads`.

package/skill/aicrm-integrate/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: aicrm-integrate
+description: Integrar um sistema (site, landing page, formulário, checkout, webhook de pagamento, ERP, app) ao AICRM para que os leads caiam no funil de vendas, usando o SDK @aicrm/sdk e as ferramentas de integração do MCP aicrm (get_integration_schema, create_api_key, send_test_lead, list_api_logs). Use quando a pessoa pedir para mandar leads, contatos, cadastros ou pedidos para o AICRM ou para o CRM, conectar um formulário ao funil, ou criar/depurar uma integração com o AICRM, mesmo sem dizer "SDK" ou "API".
+---
+
+# Integrar com o AICRM
+
+O AICRM é um CRM de vendas. Workspaces têm **funis**, funis têm **etapas**, e cada lead entra numa etapa. A integração faz os leads do sistema da pessoa caírem no funil certo, identificados como vindos da API. Seu trabalho é entregar isso funcionando, com o mínimo de esforço para ela.
+
+Regras que valem sempre:
+- **Nunca peça, mostre ou escreva uma chave no código ou no chat.** Chaves só vão para o `.env`, pela ferramenta `create_api_key`.
+- **Chave secreta (`aicrm_sk_`) só no servidor.** No navegador, use uma chave pública (`aicrm_pk_`). O SDK e a API recusam uma chave secreta no navegador.
+- **Comece em modo teste.** Leads de teste caem no funil com o selo "Teste" e não atrapalham as metas do time. Produção só com o ok explícito da pessoa.
+- **Mostre o mapeamento de campos antes de escrever o código** e espere a confirmação.
+
+## 1. Conexão
+
+Confira se as ferramentas `get_integration_schema` e `create_api_key` estão disponíveis. Se não estiverem, peça à pessoa para rodar no terminal dela (a senha não passa por você):
+
+```bash
+npx -y aicrm-mcp login --url https://aicrm.dev   # ou o endereço do AICRM da empresa
+claude mcp add aicrm -- npx -y aicrm-mcp
+```
+
+Ela precisa estar convidada no AICRM com o papel **Desenvolvedor** (ou ser admin). Depois de conectar, o cliente MCP precisa ser reiniciado.
+
+## 2. Roteiro
+
+### Passo 1: entender o CRM
+Rode `get_integration_schema`. Anote:
+- o funil onde os leads devem entrar (pergunte se houver mais de um e o pedido não deixar claro);
+- as etapas (o lead entra na primeira, a não ser que se mande `stage`);
+- os campos **obrigatórios**, porque sem eles a API recusa o lead.
+
+### Passo 2: achar de onde vêm os leads
+Procure no código da pessoa o ponto em que um lead nasce:
+- **Formulário no site** (contato, orçamento, newsletter): o handler de submit, a action, a rota de API que recebe o form.
+- **Checkout ou pagamento:** o webhook do provedor (Stripe, Mercado Pago, Pagar.me, Asaas…), a criação de pedido.
+- **Cadastro de usuário:** o signup, o onboarding.
+- **Outro sistema:** jobs, filas, integrações com ERP.
+
+Prefira integrar **no servidor** sempre que existir um backend: é mais seguro e permite atualizar o lead depois (pagamento aprovado → ganho). Use a chave pública só quando o site não tem backend (site estático, landing page).
+
+### Passo 3: propor o mapeamento e confirmar
+Mostre uma tabela curta e peça o ok:
+
+| No sistema | No AICRM | Observação |
+|---|---|---|
+| `form.nome` | `name` | obrigatório |
+| `form.email` | `email` | |
+| `form.cidade` | `fields.Cidade` | obrigatório no workspace |
+| `pedido.id` | `externalId` | evita duplicar em reenvios |
+| `pedido.total` | `value` | em reais |
+
+Se faltar um dado obrigatório no sistema, diga e sugira de onde tirar, ou um valor padrão combinado com a pessoa.
+
+### Passo 4: chave de teste no `.env`
+Chame `create_api_key` com `mode: "test"`:
+- `kind: "secret"` para o servidor;
+- `kind: "publishable"` com `funnel` (e `allowed_origins`, se já souber o domínio) para o navegador;
+- `env_file` com o arquivo de variáveis do projeto (`.env`, `.env.local`…);
+- `env_var` no padrão do framework quando a chave for usada no navegador (`VITE_AICRM_KEY`, `NEXT_PUBLIC_AICRM_KEY`).
+
+A ferramenta grava a chave, grava `AICRM_API_URL` quando a API não é a padrão (`https://api.aicrm.dev`) e põe o `.env` no `.gitignore`. Você recebe só o prefixo. Se o projeto tiver um `.env.example`, acrescente lá o nome da variável **sem valor**.
+
+### Passo 5: escrever o código
+Instale com o gerenciador do projeto (`npm i @aicrm/sdk`, `pnpm add @aicrm/sdk`, `yarn add @aicrm/sdk` ou `bun add @aicrm/sdk`). Depois de instalar, a referência completa do SDK está em `node_modules/@aicrm/sdk/README.md`.
+
+Servidor (Node, Next.js route handler, Express, edge):
+
+```ts
+import { AICRM } from "@aicrm/sdk";
+
+const aicrm = new AICRM(); // lê AICRM_API_KEY (e AICRM_API_URL, se houver) do ambiente
+
+export async function onLead(input: { nome: string; email: string; cidade: string; pedidoId: string; total: number }) {
+  const { data, error } = await aicrm.leads.create({
+    funnel: "Vendas",              // nome ou id, do get_integration_schema
+    name: input.nome,
+    email: input.email,
+    value: input.total,            // em reais
+    fields: { Cidade: input.cidade },
+    externalId: input.pedidoId,    // mesmo id = mesmo lead
+    metadata: { origem: "checkout" },
+  });
+  if (error) console.error(`[aicrm] ${error.code}: ${error.message}`);
+  return data;
+}
+```
+
+Navegador, com chave pública (o funil já vem da chave):
+
+```ts
+import { AICRM } from "@aicrm/sdk";
+const aicrm = new AICRM(import.meta.env.VITE_AICRM_KEY);
+const { error } = await aicrm.leads.create({ name, email, phone, metadata: { pagina: location.pathname } });
+```
+
+Boas práticas:
+- O SDK **não lança exceção** por erro da API: confira `error` e registre `error.code`. Uma falha no CRM não deve quebrar o fluxo principal da pessoa, então não bloqueie o checkout por causa do lead.
+- Use `externalId` sempre que houver um id estável. Webhooks são reenviados e isso evita duplicatas.
+- Depois que o lead existe: `aicrm.leads.move(id, "Proposta")`, `aicrm.leads.win(id, { value })`, `aicrm.leads.lose(id, "price")` e `aicrm.leads.addNote(id, "texto")`. Para achar pelo id do sistema: `aicrm.leads.find({ externalId })`.
+- Não envie dados que a pessoa não pediu para mandar ao CRM (senha, cartão, documentos).
+
+### Passo 6: testar de verdade
+Rode o fluxo real: o teste do projeto, o servidor local com um `curl` no endpoint, ou o próprio formulário. Em seguida chame `list_api_logs`:
+- **201/200:** o lead entrou. Diga em que funil e etapa caiu.
+- **Erro:** leia `error_code` e `how_to_fix`, corrija e rode de novo. Para ver o que foi enviado, use `get_api_log`.
+
+Para conferir só a estrutura, sem o código, `send_test_lead` manda o payload de exemplo. Não use isso como prova de que o código funciona.
+
+### Passo 7: produção (com o ok da pessoa)
+Explique que os leads passarão a ir para o time de verdade e pergunte se pode. Com o sim:
+1. Chame `create_api_key` com `mode: "live"` e `confirm_live: true`, gravando no arquivo de produção que a pessoa indicar, ou oriente-a a pôr a variável no provedor de hospedagem (Vercel, Railway…).
+2. Ofereça `clear_test_leads` para tirar do funil os leads de teste.
+3. Resuma o que foi feito, os arquivos alterados e como desligar (`revoke_api_key`).
+
+## 3. Erros mais comuns
+
+| `code` | O que fazer |
+|---|---|
+| `required_field_missing` | Mande o campo citado em `field`. Veja os obrigatórios em `get_integration_schema` |
+| `field_not_found` / `stage_not_found` / `funnel_not_found` | Use os nomes listados na mensagem |
+| `ambiguous_funnel` | Mande também `workspace` ou use o id do funil |
+| `secret_key_in_browser` | Mova a chamada para o servidor, ou crie uma chave `publishable` |
+| `origin_not_allowed` | O domínio não está na chave pública: crie uma com o domínio certo |
+| `invalid_api_key` | Variável errada ou chave revogada: confira o `.env` e o nome da variável |
+| `rate_limited` | Muitas chamadas por minuto: para cargas grandes, use a importação de planilha do CRM |
+
+A lista completa, com como resolver cada um, também está em `how_to_fix` nos logs e em `https://aicrm.dev/llms.txt`.