aicrm-mcp 0.3.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicrm-mcp",
-  "version": "0.3.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
 
@@ -112,7 +118,7 @@ Como ler as respostas de erro:
 | Ferramenta | Para quê |
 |---|---|
 | `list_workspaces` | Quem sou, workspaces, funis, etapas, KPI e vendedores. Comece por aqui. |
-| `search_leads` | Buscar por texto, funil, etapa, responsável, status; `filter`: `mine`, `stale` (parados 14+ dias), `no_next_step`; `field_filters` por campo personalizado. |
+| `search_leads` | Buscar por texto, funil, etapa, responsável, status; `filter`: `mine`, `stale` (passaram do prazo da etapa), `no_next_step`; `field_filters` por campo personalizado. |
 | `get_lead` | Todos os campos (inclusive personalizados) e o histórico. |
 | `create_lead` | Criar (nome obrigatório; demais opcionais, inclusive `custom_fields`). |
 | `update_lead` | Alterar só o que for informado; `owner: "none"` tira o responsável; `""` limpa um campo padrão. |
@@ -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`, `round_robin`, `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,26 +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. 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
@@ -188,6 +198,14 @@ 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 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`.
+
 ### Metas do mês
 1. `get_goals` para ver o que já existe; `list_commission_plans` se houver comissão.
 2. `set_goals` com os alvos (em R$ se o KPI for receita; em unidades caso contrário).
@@ -213,7 +231,7 @@ Como ler as respostas de erro:
 - **Plano do dia** (`get_today_plan`):
   - **chance**: probabilidade de o lead contar na meta — a % da etapa; em funis de "leads que chegaram à etapa", a chance de chegar à etapa‑alvo (pelo histórico do funil). Leads que já passaram da etapa‑alvo não aparecem: já contaram.
   - **worth_for_goal**: valor × chance ("R$ 10.000 com 40% ≈ R$ 4.000"); **share_of_missing**: quanto isso representa do que falta.
-  - **Por que esta ordem**: chance × valor para a meta (no máximo o que falta) × urgência (passo atrasado ou marcado para hoje, parado há 14+ dias, data de fechamento passada ou dentro do mês, sem próximo passo). Leads com passo já marcado para outro dia ou previsão de fechar depois do mês descem na lista.
+  - **Por que esta ordem**: chance × valor para a meta (no máximo o que falta) × urgência (passo atrasado ou marcado para hoje, passou do prazo da etapa, data de fechamento passada ou dentro do mês, sem próximo passo). Leads com passo já marcado para outro dia ou previsão de fechar depois do mês descem na lista.
   - **done_today**: leads em que o vendedor registrou algo hoje (nota, próximo passo, etapa, fechamento).
 
 ## 8. Problemas comuns

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`.