MCP do Novasce Tenancy

O conector que liga a IA de cada pessoa (Claude Code, Codex, Antigravity, Claude Desktop, Cursor) ao Novasce Tenancy, pela chave de IA dela. Cada ferramenta é uma chamada à API que já existe; toda escrita entra no AuditLog como MCP, com o nome da chave.

Como a pessoa liga (Novasce AI Tools, fase 1)

Tudo começa na tela IA › Novasce AI Tools do Tenancy: a pessoa cria a própria chave em Chaves (vale 90 dias, só nasce depois de ela confirmar que desligou o treino na ferramenta e leu a regra de dados) e a aba Conectar mostra o passo da ferramenta dela, com a chave já no lugar. A chave fica só na configuração da ferramenta, nunca no pacote nem no brain.

O que a IA pode fazer é o que o administrador escolheu em Configurações › Usuários, coluna IA:

| Nível | O que a IA faz | |---|---| | Sem acesso (padrão) | nada: a API recusa a chave | | Leitura | só consulta; a API recusa toda escrita | | Leitura e escrita | o que o papel da pessoa já faz na tela | | + Financeiro no agente | caixa, cofres, cobranças, lançamentos e sócios (desligado por padrão, inclusive para ADMIN) |

Ao subir, o conector pergunta o acesso (GET /auth/me) e esconde o que a pessoa não pode usar (src/acesso.ts). Quem trava é a API; esconder só evita a IA oferecer o que vai ser recusado. Sem conseguir ler o acesso, mostra todas, e a primeira chamada devolve a frase da API dizendo o que fazer.

Os comandos de cada ferramenta

# Claude Code
claude mcp add tenancy -s user -e TENANCY_AGENT_TOKEN=nvat_… -- npx -y @novasce/tenancy-mcp
# Codex
codex mcp add tenancy --env TENANCY_AGENT_TOKEN=nvat_… -- npx -y @novasce/tenancy-mcp
# Antigravity
agy mcp add --env TENANCY_AGENT_TOKEN=nvat_… tenancy npx -y @novasce/tenancy-mcp

Cursor: o botão "Adicionar ao Cursor" da aba Conectar (link cursor://anysphere.cursor-deeplink/mcp/install). Claude Desktop: o arquivo Novasce Tenancy.mcpb, que já traz o Node; a pessoa cola a chave na tela de instalação do Claude.

Publicar uma versão

1. Subir a versão em package.json e manifest.json (as duas iguais).
2. npm publish (o prepublishOnly compila e roda os testes). Pacote público, sem segredo dentro.
3. npm run pacote gera pacote/Novasce Tenancy.mcpb; copiar para o app em public/downloads/novasce-tenancy.mcpb.

Rodar pelo repositório (quem desenvolve)

cd novasce-tenancy-api/tools/mcp
npm install
npm run build
TENANCY_API_URL=https://novasce-tenancy-api-production.up.railway.app/api/v1 npm run token

npm run token pergunta e-mail, senha (sem eco, nada gravado) e as duas confirmações, cria a SUA chave pelo mesmo caminho da tela (POST /ai-tools/keys) e imprime o claude mcp add tenancy … pronto, rodando o dist/ local.

O contrato é fechado

Campo que uma tool não declara falha na chamada (additionalProperties: false), em vez de sumir calado. Foi o que custou caro em 25/09/2026: create_task recebeu startAt/endAt, respondeu "Tarefa criada" e gravou a tarefa sem horário. Hora sem fuso (2026-09-25T14:00) é hora de Maceió; com Z ou ±hh:mm, passa como veio.

Ferramentas

Leitura: dashboard_hoje · caixa (caixa por conta, ponto mais baixo das 13 semanas) · fila_de_pagamento · search_customers · get_customer · list_tasks · list_tickets_abertos · get_ticket (com a lista de anexos) · download_task_file (baixa um anexo de tarefa ou chamado para uma pasta local; escreve no disco, nunca no ERP) · get_task (a ficha: descrição com o checklist, mãe, filhas e comentários) · get_error_group (o erro de produção por dentro: rota, topo da pilha, quantas vezes, quantas empresas e os últimos eventos com requestId; o id é o erro= do link da aba Técnico) · list_invoices · get_pricing · list_products · compose_site_quote (só calcula).

Escrita (as ações do "+"): create_lead · create_proposal · fechou (aceite + esteira) · reply_ticket (ao cliente) · create_task (com assigneeId, collaboratorIds, labels, parentId, campaignId e, em reunião, startAt/endAt) · update_task (edita título, descrição, tipo, responsável, co-responsáveis, etiquetas, mãe, campanha, produto, cliente, vencimento, prioridade, horário da reunião e lembrete; null solta o vínculo) · move_task · archive_task (arquiva ou restaura: a saída do quadro sem apagar nada, e a única saída do cartão nascido de um fato, que não aceita FEITO) · comment_task (interno) · create_release_note · lancamento · transferencia (entre contas: fatura do cartão, devolução ao sócio, saque do Asaas; nunca despesa/receita) · entreguei · create_product · update_product (inclui a régua de acesso do atraso: readOnlyFromDay, suspendedFromDay, cancelFromDay, 1 a 90, pausa 0 = sem pausa, null = padrão 8/16/31; e multa e juros do atraso: lateFinePct, lateInterestPct, 0 a 10 %).

Apagar uma tarefa (delete_task, decisão do founder em 21/10/2026): não tem volta nem lixeira, e a cascata leva anexos, conversa, co-responsáveis e a reunião pendurada; as filhas ficam sem mãe. Só ADMIN. Tarefa que ainda está no quadro, ou que tem filhas, exige confirm: true; tarefa nascida de um fato e chamado a API recusa sempre (a de fato o robô recria, e o chamado é o registro do atendimento do cliente). Uma por chamada, nunca em lote, e o rastro fica no AuditLog com a linha inteira no before. Para limpar o quadro, o caminho é archive_tasks.

Quadro em lote (cartões 5f183f30 e 35525273, 21/10/2026): move_tasks e archive_tasks recebem uma LISTA de ids (até 200 por chamada) e devolvem resultado por item — a recusada aparece com o motivo da API e as outras seguem. As regras são as mesmas da ação de uma: FEITO é do founder, e tarefa de fato não aceita FEITO. Para ver as arquivadas, list_tasks com archived: true (a rota lê ?archived=1); sem o campo, a lista é a do quadro. São duas listas, nunca as duas juntas.

Marketing (empresa/marketing-sistema.md): create_content_line (a linha da semana: tarefa-mãe + peças por dia, com etiquetas sN, feed|story|bastidor, hero|hub|help; sem descricao, a peça nasce no modelo da casa a partir de legenda, arte, link: dia · Arte · Legenda · Link · Checklist · Story do dia, em Markdown curto que a ficha renderiza. Título curto: IG · #id · Manchete) · publish_task (a peça foi ao ar: link + data, só em FEITO; agenda medir em D+7) · report_metrics (D+7 da peça ou os 3 números do mês na tarefa numeros:AAAA-MM). list_tasks filtra por label, parentId, dueFrom/dueTo. Mover CONTEUDO pra FEITO é só do ADMIN (é "aprovado pra ir ao ar").

Marca (aba Marca do produto, produtos/tenancy-aba-marca-spec.md): get_brand (kit, manual, arquivos, números lidos dos Planos, pendências) · update_brand (cores, fontes, voz, canais, fatos — preço nunca: é dos Planos) · publish_brand_asset (um arquivo final, idempotente por sha256, nome por uso) · publish_brand_manual (HTML self-contained com versão e sha). Pra publicar a marca inteira use design/publicar-tenancy.sh <marca> no repo novasce-design; as tools servem pra consulta e ajuste pontual.

Direção criativa (referências como registro, painel Direção da aba Marca): list_brand_references (por estado) · add_brand_reference (captura: título, crédito, por quê, imagem por caminho; abre a tarefa "Ler referência NN") · read_brand_reference (a leitura no molde: DNA, faixa, cuidado, virou, esboços por caminho; marca em prancha) · decide_brand_reference (só ADMIN: entrou com semana · fila · não · guardar, com porquê; vira evento no log). ref aceita o número (10) ou o id. Review mensal: brand_review (o rascunho do período, nada gravado) · close_brand_review (grava números, parágrafo e próxima data). Encerrar temporada é pela tela (só o founder). Mercado e Pesquisas (produtos/tenancy-mercado-pesquisas-set2026.md): market_search (a base do CNPJ antes do funil: texto, UF, cidade, porte, status, lista, ICP mínimo; telefone mascarado) · market_mark_contact (ligação/WhatsApp/e-mail/DM/visita + resultado; RESPONDEU sobe o status) · market_promote (a única porta pro funil: vira lead com origem mercado:<segmento>-<base>; quarentena e funil devolvem o motivo) · list_surveys · survey_results (recorte por região, porte, papel; contagem até 50 respostas). Sem market_discard de propósito: descarte e quarentena são decisão de gente, na gaveta.

Mercado › Estudos (produtos/tenancy-mercado-estudos.md): list_market_studies (situação, pede decisão, produtos, tabelas e anexos; sem status esconde arquivado) · get_market_study (resumo, decisão, tabelas, anexos, links e corpo) · publish_market_study (cria ou atualiza pelo slug da pasta do brain; corpo e fontes por texto ou caminho local; tabelas por CSV local, uma chamada por tabela) · attach_market_study_file (PDF, CSV e afins até 25 MB, idempotente por sha256). Sem tool de apagar: arquivar é status: ARQUIVADO.

Time › Enquetes (enquete interna, opinião do time com prazo; cliente é create_survey): create_team_poll (perguntas single, number ou text e quadros de contexto list, table ou text; avisa no sino quem foi chamado) · list_team_polls · team_poll_results (com nome para quem criou, a qualquer momento; sem nome para quem participou, só depois de fechar). Responder é só na tela, na sessão da pessoa: token de agente recebe 403. Fechar, lembrar quem falta e apagar (sem resposta) também são pela tela.

Não existe, de propósito: apagar (fora detach_task_file e retirar_lancamento, cercados) · faturar, cobrar, emitir boleto/Pix, marcar paga, cancelar cobrança · cofre de senhas · pessoas/RH · usuários, convites, chaves.

Revogar

A pessoa revoga as dela em IA › Novasce AI Tools › Chaves (DELETE /ai-tools/keys/:id); o administrador vê e revoga todas (GET /admin/agent-tokens, DELETE /admin/agent-tokens/:id). Revogada ou vencida, a chave recebe 401 na hora. Desativar a pessoa revoga todas as chaves dela.

Testar

npm test                      # ferramentas com fetch mockado e o filtro do acesso
node scripts/fumaca.mjs       # contra uma API local (ver o script)