chatflux-gestao-agente 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# `gestao` — o portal pela linha de comando e por agente (MCP)
+
+Deixa um agente (Claude Code, Claude Desktop, qualquer harness que fale MCP)
+operar o Gestão **com a sua identidade e o seu papel** — nada além do que você já
+faz na tela, e tudo no histórico com o seu nome.
+
+## Instalar (equipe — um comando, sem clonar nada)
+
+```sh
+claude mcp add --scope user gestao -- npx -y chatflux-gestao-agente mcp
+```
+
+Pronto. Abra o Claude Code e peça qualquer coisa do portal: na primeira vez ele
+mesmo abre o navegador para você autorizar. **Você não digita mais nenhum
+comando** — nem `login`, nem `status`.
+
+### Instalar (desenvolvimento, dentro deste repo)
+
+```sh
+npm link
+claude mcp add --scope user gestao -- gestao mcp
+```
+
+**`--scope user` é o ponto:** registra no seu `~/.claude.json` e vale em
+**qualquer diretório**. Não crie `.mcp.json` na raiz de um repo — aquilo é escopo
+`project`, viaja no git e amarra o Gestão a um repositório só.
+
+Para apontar ao dev: `claude mcp add --scope user -e GESTAO_ENV=dev gestao -- gestao mcp`.
+
+No Claude Desktop (que não tem a CLI), a mesma coisa em
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{ "mcpServers": { "gestao": { "command": "gestao", "args": ["mcp"] } } }
+```
+
+## Como a identidade funciona
+
+```
+gestao login
+  └─ sobe um listener em 127.0.0.1:<porta efêmera>
+  └─ abre  <portal>/agente/login?port=…&state=…
+       └─ a página (só staff) mostra quem você é e pede confirmação
+       └─ o browser — que JÁ tem sua sessão do Clerk — emite o JWT do
+          template `convex` e entrega no loopback
+  └─ guarda no Keychain (macOS) ou em ~/.config/gestao/token.json (0600)
+```
+
+Vale **1 hora**. E na prática você não faz nada disso à mão: o próprio agente
+chama a tool `gestao_conectar` quando precisa, o navegador abre, você clica em
+**Autorizar** e ele refaz a ação. O `gestao login` no terminal existe como
+alternativa, não como o caminho normal.
+
+**O servidor NÃO morre quando a sessão expira.** Ele sobe sempre: lista as tools a
+partir do último contrato buscado (cache em `~/.config/gestao/`), e `gestao_conectar`
+fica SEMPRE disponível — é justamente quando a sessão vence que ela precisa existir.
+Sem isso, a pessoa veria "Failed to connect — Connection closed" de hora em hora,
+sem pista do motivo.
+
+O cache é conveniência, nunca fonte: qualquer ação de verdade exige token válido.
+
+**Sem segredo compartilhado.** Este pacote nunca vê secret key nem chave de
+serviço. O que ele guarda é um token seu, de vida curta, que o Convex valida
+sozinho. Arquivar sua conta (`active:false`) revoga o agente junto.
+
+Por que não OAuth: o Clerk não documenta caminho de credencial OAuth → JWT com
+`aud: "convex"`, e emitir pelo backend exigiria secret key **mais** um
+`session_id` que o token OAuth não carrega. O browser é o único lugar que já tem
+sessão — daí o loopback.
+
+## As tools não estão aqui
+
+Elas vêm do **contrato servido pelo deployment** (`/chatflux/contrato`), montado a
+partir das capacidades do L2. Consequências:
+
+- capacidade nova no portal vira tool **sem release deste pacote**;
+- nunca há cópia do contrato para apodrecer;
+- o `inputSchema` de cada tool é o JSON Schema gerado do validador Convex real —
+  enums de verdade, não `string` solta.
+
+Uma tool por **endpoint**, nomeada pela **capacidade** (`gestao_projeto_criar`).
+Capacidade com mais de um endpoint dá o nome limpo ao principal e sufixo aos
+outros (`gestao_projeto_editar` e `gestao_projeto_editar_generate_cover_upload_url`).
+
+Tools de `efeito: destrutivo` vêm com `destructiveHint` e um aviso no texto:
+arquivar empresa e encerrar projeto **cascateiam e não têm desfazer**.
+
+## Arquivos
+
+| arquivo | o quê |
+|---|---|
+| `bin/gestao.mjs` | CLI: `login`, `status`, `logout`, `mcp` |
+| `lib/login.mjs` | loopback + `state` + abre o navegador |
+| `lib/config.mjs` | ambientes e guarda do token (Keychain / arquivo 0600) |
+| `lib/gestao.mjs` | busca o contrato e chama o Convex por nome |
+| `lib/tools.mjs` | contrato → lista de tools MCP |
+| `lib/mcp.mjs` | servidor MCP (stdio, JSON-RPC) |
+
+Zero dependências de propósito: isto roda na máquina de cada pessoa, e cada
+dependência é superfície.

package/bin/gestao.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// CLI do Gestão. Três verbos: `login`, `status`, `mcp`.
+
+import { login } from "../lib/login.mjs";
+import { servir } from "../lib/mcp.mjs";
+import { contrato, euSou, NaoAutenticado } from "../lib/gestao.mjs";
+import {
+  ambiente, lerToken, apagarToken, expiraEm, tokenValido,
+} from "../lib/config.mjs";
+import { montarTools } from "../lib/tools.mjs";
+
+const AJUDA = `gestao — portal Gestão pela linha de comando e por agente (MCP)
+
+  gestao login     autoriza este computador a agir como você (abre o navegador)
+  gestao status    mostra quem está conectado e quanto tempo falta
+  gestao logout    esquece a credencial desta máquina
+  gestao mcp       roda o servidor MCP (é o que o Claude Code/Desktop chama)
+
+Ambiente: ${ambiente().nome}  (GESTAO_ENV=dev para apontar ao dev)
+
+No Claude Code/Desktop, registre assim:
+  { "mcpServers": { "gestao": { "command": "gestao", "args": ["mcp"] } } }
+`;
+
+const [, , verbo] = process.argv;
+
+try {
+  switch (verbo) {
+    case "login": {
+      const { email, onde } = await login();
+      const eu = await euSou();
+      console.log(
+        `Conectado como ${eu?.name ?? email ?? "?"} (${eu?.role ?? "?"}) no ambiente ${ambiente().nome}.`,
+      );
+      console.log(`Credencial guardada em: ${onde}`);
+      console.log("Vale por 1 hora. Quando expirar, rode `gestao login` de novo.");
+      break;
+    }
+
+    case "status": {
+      const dados = lerToken();
+      if (!dados) {
+        console.log("Sem credencial nesta máquina. Rode `gestao login`.");
+        process.exit(1);
+      }
+      const restaMin = Math.round((expiraEm(dados.token) - Date.now()) / 60000);
+      if (!tokenValido(dados)) {
+        console.log(`Credencial EXPIRADA (${dados.email ?? "?"}). Rode \`gestao login\`.`);
+        process.exit(1);
+      }
+      const eu = await euSou();
+      const tools = montarTools(await contrato());
+      console.log(`Conectado: ${eu?.name ?? "?"} <${eu?.email ?? "?"}> — papel ${eu?.role ?? "?"}`);
+      console.log(`Ambiente:  ${ambiente().nome}`);
+      console.log(`Expira em: ${restaMin} min`);
+      console.log(`Tools:     ${tools.length} (do contrato servido pelo deployment)`);
+      break;
+    }
+
+    case "logout":
+      apagarToken();
+      console.log("Credencial removida desta máquina.");
+      break;
+
+    case "mcp":
+      await servir();
+      break;
+
+    default:
+      console.log(AJUDA);
+      process.exit(verbo ? 1 : 0);
+  }
+} catch (e) {
+  if (e instanceof NaoAutenticado) {
+    console.error(e.message);
+    process.exit(1);
+  }
+  console.error(`Erro: ${e.message}`);
+  process.exit(1);
+}

package/lib/config.mjs

@@ -0,0 +1,102 @@
+// Endereços e armazenamento do token. Sem dependência externa de propósito:
+// este pacote roda na máquina de cada pessoa, e cada dependência é superfície.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const AMBIENTES = {
+  prod: {
+    convex: "https://dependable-stingray-656.convex.cloud",
+    site: "https://dependable-stingray-656.convex.site",
+    portal: "https://portal.chatflux.ai",
+  },
+  dev: {
+    convex: "https://agreeable-woodpecker-190.convex.cloud",
+    site: "https://agreeable-woodpecker-190.convex.site",
+    portal: "http://localhost:3000",
+  },
+};
+
+/** `GESTAO_ENV=dev` troca de ambiente inteiro. Default prod: quem usa isto é a
+ *  equipe, não o dev do portal. */
+export function ambiente() {
+  const nome = process.env.GESTAO_ENV === "dev" ? "dev" : "prod";
+  return { nome, ...AMBIENTES[nome] };
+}
+
+// ---- token ------------------------------------------------------------------
+//
+// Keychain do macOS quando houver (é onde o SO já guarda segredo e o usuário
+// controla o acesso); arquivo 0600 como fallback nos outros sistemas. O token
+// vale 1h — vazamento tem janela curta, mas ainda assim não fica em texto puro
+// no macOS, que é a máquina real da equipe.
+
+const SERVICO = "chatflux-gestao";
+const ARQUIVO = path.join(os.homedir(), ".config", "gestao", "token.json");
+const temKeychain = () => process.platform === "darwin";
+
+export function salvarToken(dados) {
+  const json = JSON.stringify(dados);
+  if (temKeychain()) {
+    try {
+      execFileSync("security", [
+        "add-generic-password", "-U",
+        "-s", SERVICO, "-a", ambiente().nome, "-w", json,
+      ], { stdio: "ignore" });
+      return "keychain";
+    } catch {
+      /* cai no arquivo */
+    }
+  }
+  fs.mkdirSync(path.dirname(ARQUIVO), { recursive: true });
+  fs.writeFileSync(ARQUIVO, json, { mode: 0o600 });
+  return ARQUIVO;
+}
+
+export function lerToken() {
+  if (temKeychain()) {
+    try {
+      const out = execFileSync("security", [
+        "find-generic-password", "-s", SERVICO, "-a", ambiente().nome, "-w",
+      ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+      return JSON.parse(out.trim());
+    } catch {
+      /* cai no arquivo */
+    }
+  }
+  try {
+    return JSON.parse(fs.readFileSync(ARQUIVO, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function apagarToken() {
+  if (temKeychain()) {
+    try {
+      execFileSync("security", [
+        "delete-generic-password", "-s", SERVICO, "-a", ambiente().nome,
+      ], { stdio: "ignore" });
+    } catch { /* pode não existir */ }
+  }
+  try { fs.unlinkSync(ARQUIVO); } catch { /* idem */ }
+}
+
+/** `exp` do JWT, em ms. Sem verificar assinatura: quem valida é o Convex — aqui
+ *  só queremos saber se já venceu, pra dar mensagem boa em vez de erro cru. */
+export function expiraEm(jwt) {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(jwt.split(".")[1], "base64url").toString("utf8"),
+    );
+    return typeof payload.exp === "number" ? payload.exp * 1000 : 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function tokenValido(dados, margemMs = 60_000) {
+  return Boolean(dados?.token) && expiraEm(dados.token) - margemMs > Date.now();
+}

package/lib/gestao.mjs

@@ -0,0 +1,125 @@
+// Cliente do Gestão: busca o contrato e chama função do Convex COMO A PESSOA.
+//
+// Chamamos por NOME (`"ops/tasks:create"`) via a HTTP API do Convex, sem o SDK e
+// sem o `_generated/api` do repo — este pacote não tem (nem quer) acoplamento com
+// o codegen do portal. As tools vêm do contrato servido; capacidade nova aparece
+// aqui sem release novo.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ambiente, lerToken, tokenValido } from "./config.mjs";
+
+const arquivoCache = () =>
+  path.join(os.homedir(), ".config", "gestao", `contrato-${ambiente().nome}.json`);
+
+export class NaoAutenticado extends Error {
+  constructor(msg = "Sessão expirada ou ausente. Rode `gestao login`.") {
+    super(msg);
+    this.name = "NaoAutenticado";
+  }
+}
+
+function token() {
+  const dados = lerToken();
+  if (!tokenValido(dados)) throw new NaoAutenticado();
+  return dados.token;
+}
+
+/** `ops.tasks.create` (id do contrato) → `ops/tasks:create` (nome no Convex). */
+export const paraNomeConvex = (id) => {
+  const p = id.split(".");
+  return `${p.slice(0, -1).join("/")}:${p[p.length - 1]}`;
+};
+
+/** Chama query/mutation/action pública. `tipo` vem do contrato (`kind`). */
+export async function chamar(id, args, tipo = "mutation") {
+  const rota = tipo === "query" ? "query" : tipo === "action" ? "action" : "mutation";
+  const res = await fetch(`${ambiente().convex}/api/${rota}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token()}`,
+    },
+    body: JSON.stringify({
+      path: paraNomeConvex(id),
+      args: args ?? {},
+      format: "json",
+    }),
+  });
+  const corpo = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(corpo?.message ?? `HTTP ${res.status} em ${id}`);
+  }
+  // A HTTP API devolve {status:"success"|"error", value|errorMessage}.
+  if (corpo.status === "error") {
+    // Erro de regra de negócio (ex.: "Empresa arquivada…") chega aqui. É
+    // informação para o modelo, não falha de transporte — propaga a mensagem.
+    throw new Error(corpo.errorMessage ?? `Erro em ${id}`);
+  }
+  return corpo.value;
+}
+
+let cache = null;
+
+/**
+ * Contrato servido pelo deployment. Nunca embarcamos cópia NO PACOTE (cópia
+ * apodrece e o gate do repo não a enxerga), mas guardamos o último buscado em
+ * disco — é cache, não fonte: só serve pra listar tools quando a credencial
+ * expirou, e qualquer chamada de verdade continua exigindo login.
+ *
+ * Isso existe porque o token vale 1h: sem o cache, a pessoa veria o servidor
+ * MCP "falhar ao conectar" toda hora, sem pista do motivo.
+ */
+export async function contrato({ permitirCache = false } = {}) {
+  const emDisco = () => {
+    if (cache) return cache;
+    try {
+      cache = JSON.parse(fs.readFileSync(arquivoCache(), "utf8"));
+      return cache;
+    } catch {
+      return null;
+    }
+  };
+
+  let jwt;
+  try {
+    jwt = token();
+  } catch (e) {
+    const c = permitirCache && emDisco();
+    if (c) return c;
+    throw e;
+  }
+
+  const atual = cache ?? emDisco();
+  const res = await fetch(
+    `${ambiente().site}/chatflux/contrato${atual ? `?versao=${atual.versao}` : ""}`,
+    { headers: { Authorization: `Bearer ${jwt}` } },
+  );
+  if (res.status === 304 && atual) return atual;
+  if (res.status === 401 || res.status === 403) {
+    const c = permitirCache && atual;
+    if (c) return c;
+    throw new NaoAutenticado(
+      "O portal recusou a credencial ao buscar o contrato. Rode `gestao login`.",
+    );
+  }
+  if (!res.ok) {
+    const c = permitirCache && atual;
+    if (c) return c;
+    throw new Error(`Falha ao buscar o contrato: HTTP ${res.status}`);
+  }
+  cache = await res.json();
+  try {
+    fs.mkdirSync(path.dirname(arquivoCache()), { recursive: true });
+    fs.writeFileSync(arquivoCache(), JSON.stringify(cache));
+  } catch {
+    /* cache é conveniência; falhar em gravar não é erro */
+  }
+  return cache;
+}
+
+/** Quem sou eu, segundo o portal (papel real, não o que o token diz). */
+export async function euSou() {
+  return await chamar("ops.users.current", {}, "query");
+}

package/lib/login.mjs

@@ -0,0 +1,95 @@
+// `gestao login` — o handshake de identidade.
+//
+// Sobe um listener em 127.0.0.1 numa porta efêmera, abre o portal com `port` e
+// `state`, e espera a página devolver o JWT do template `convex`. O browser já
+// tem a sessão do Clerk; nós nunca vemos senha, e o backend não ganha rota nova.
+//
+// Por que NÃO OAuth: o Clerk não documenta caminho de credencial OAuth → JWT com
+// `aud: "convex"`, e emitir pelo backend exigiria secret key mais um `session_id`
+// que o token OAuth não carrega. O browser é o único lugar que já tem sessão.
+
+import { createServer } from "node:http";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { ambiente, salvarToken } from "./config.mjs";
+
+const ESPERA_MS = 120_000;
+
+function abrirNavegador(url) {
+  const cmd =
+    process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "start"
+    : "xdg-open";
+  execFile(cmd, [url], () => {});
+}
+
+export function login({ silencioso = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const state = crypto.randomBytes(16).toString("hex");
+    let terminou = false;
+
+    const server = createServer((req, res) => {
+      // A página roda em outra origem — sem CORS o POST nem sai.
+      const cors = {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Headers": "Content-Type",
+        "Access-Control-Allow-Methods": "POST, OPTIONS",
+      };
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, cors);
+        return res.end();
+      }
+      if (req.method !== "POST" || !req.url.startsWith("/callback")) {
+        res.writeHead(404, cors);
+        return res.end();
+      }
+      let corpo = "";
+      req.on("data", (c) => {
+        corpo += c;
+        // Um POST legítimo tem ~2 KB. Corta qualquer coisa absurda.
+        if (corpo.length > 64_000) req.destroy();
+      });
+      req.on("end", () => {
+        let dados;
+        try {
+          dados = JSON.parse(corpo);
+        } catch {
+          res.writeHead(400, cors);
+          return res.end();
+        }
+        // O `state` amarra esta resposta ao NOSSO pedido: sem ele, outra aba (ou
+        // outro processo local) conseguiria despejar um token aqui.
+        if (dados.state !== state || typeof dados.token !== "string") {
+          res.writeHead(403, cors);
+          return res.end();
+        }
+        res.writeHead(200, { ...cors, "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true }));
+        terminou = true;
+        const onde = salvarToken({
+          token: dados.token,
+          email: dados.email ?? null,
+          env: ambiente().nome,
+        });
+        server.close();
+        resolve({ email: dados.email ?? null, onde });
+      });
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const porta = server.address().port;
+      const url = `${ambiente().portal}/agente/login?port=${porta}&state=${state}`;
+      if (!silencioso) {
+        console.error(`Abrindo o navegador para autorizar…\n  ${url}\n`);
+      }
+      abrirNavegador(url);
+    });
+
+    server.on("error", reject);
+    setTimeout(() => {
+      if (terminou) return;
+      server.close();
+      reject(new Error("Tempo esgotado (2 min) esperando a autorização."));
+    }, ESPERA_MS).unref();
+  });
+}

package/lib/mcp.mjs

@@ -0,0 +1,193 @@
+// Servidor MCP do Gestão (stdio, JSON-RPC 2.0).
+//
+// Sem SDK de propósito: a fatia do protocolo que um servidor de tools usa é
+// `initialize` + `tools/list` + `tools/call` + `ping`. Escrever isso são ~80
+// linhas e zero dependência — e este pacote roda na máquina de cada pessoa, onde
+// cada dependência é superfície e mais uma coisa pra travar numa versão.
+//
+// As tools NÃO são hardcoded: vêm do contrato servido pelo deployment. Capacidade
+// nova no L2 vira tool sem release deste pacote.
+
+import { contrato, chamar, euSou } from "./gestao.mjs";
+import { login } from "./login.mjs";
+import { ambiente } from "./config.mjs";
+import { montarTools } from "./tools.mjs";
+
+const PROTOCOLO = "2024-11-05";
+const escrever = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const ok = (id, result) => escrever({ jsonrpc: "2.0", id, result });
+const falha = (id, code, message) =>
+  escrever({ jsonrpc: "2.0", id, error: { code, message } });
+
+/** Resultado de tool: MCP quer conteúdo textual; JSON legível serve ao modelo. */
+const texto = (v) => ({
+  content: [
+    { type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) },
+  ],
+});
+
+let tools = null;
+
+/**
+ * A tool que CONECTA — não a que pede pra pessoa digitar comando.
+ *
+ * Fica SEMPRE na lista, autenticado ou não, porque a sessão vence de hora em
+ * hora: quando qualquer ação falhar por sessão, o modelo chama esta e a pessoa
+ * só clica no navegador. Ela nunca precisa saber que existe uma CLI.
+ */
+const TOOL_CONECTAR = {
+  name: "gestao_conectar",
+  description:
+    "Conecta esta máquina ao Gestão. ABRE O NAVEGADOR para a pessoa autorizar com " +
+    "o login dela (leva segundos) e vale 1 hora.\n\n" +
+    "CHAME ISTO SEM PEDIR PERMISSÃO sempre que uma ação do Gestão falhar por " +
+    "sessão expirada ou ausente, ou quando não houver nenhuma outra tool do Gestão " +
+    "disponível. Depois de conectar, refaça a ação que falhou.\n\n" +
+    "Avise a pessoa em uma frase que o navegador vai abrir e que ela precisa " +
+    "clicar em Autorizar.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: false, openWorldHint: true },
+  _endpoint: null,
+};
+
+/** Estamos no estado degradado (só a tool de conectar)? */
+const soConectar = (t) => t?.length === 1 && t[0]._endpoint === null;
+
+async function carregarTools() {
+  // Cache normal — MENOS quando estamos degradados. Ordem real das coisas: o
+  // harness sobe o servidor ao abrir, e a conexão só acontece depois. Se o
+  // fallback ficasse cacheado, a pessoa veria 1 tool até reiniciar o Claude Code
+  // inteiro, sem nenhuma pista de que era isso.
+  if (tools && !soConectar(tools)) return tools;
+  // `permitirCache`: com o token expirado (acontece de hora em hora) ainda
+  // listamos as tools do último contrato buscado. A CHAMADA continua exigindo
+  // sessão — o que muda é o modelo poder chamar `gestao_conectar` em vez de o
+  // servidor morrer com "Connection closed".
+  try {
+    tools = [TOOL_CONECTAR, ...montarTools(await contrato({ permitirCache: true }))];
+  } catch {
+    tools = [TOOL_CONECTAR];
+  }
+  return tools;
+}
+
+/** Refaz a lista após conectar e avisa o harness pra reler (senão ele fica com a
+ *  lista velha, de 1 tool, e a pessoa não entende por que nada apareceu). */
+async function recarregarEAvisar() {
+  tools = null;
+  await carregarTools();
+  escrever({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+}
+
+async function tratar(msg) {
+  const { id, method, params } = msg;
+
+  if (method === "initialize") {
+    const env = ambiente().nome;
+    // O ambiente é a PRIMEIRA coisa que o modelo lê, e em dev vem como aviso.
+    // Motivo: o dev é uma cópia do prod — mesmos clientes, mesmos nomes. Escrever
+    // no banco errado não dá erro, dá resultado plausível, e ninguém percebe.
+    const aviso =
+      env === "prod"
+        ? "AMBIENTE: PRODUÇÃO — o que você fizer aqui é real e a equipe vê."
+        : "AMBIENTE: DESENVOLVIMENTO (cópia desatualizada do portal real). " +
+          "Os nomes de cliente são reais, mas NADA daqui aparece pra equipe. " +
+          "AVISE a pessoa que está em dev antes de qualquer escrita — ela pode " +
+          "achar que está operando o portal de verdade.";
+    return ok(id, {
+      protocolVersion: PROTOCOLO,
+      capabilities: { tools: { listChanged: true } },
+      serverInfo: { name: `gestao (${env})`, version: "0.1.0" },
+      instructions:
+        `${aviso}\n\n` +
+        "Portal interno da ChatFlux: empresas-cliente → projetos → entregáveis. " +
+        "Você age COM A IDENTIDADE E O PAPEL da pessoa que autorizou (`gestao login`) — " +
+        "nada além do que ela já pode fazer na tela, e tudo fica no histórico com o nome dela. " +
+        "IDs nunca são adivinháveis: use as tools de leitura para resolver nome → id antes de escrever. " +
+        "Tools marcadas como DESTRUTIVO cascateiam e não têm desfazer — confirme com a pessoa antes.",
+    });
+  }
+  if (method === "notifications/initialized") return; // notificação: sem resposta
+  if (method === "ping") return ok(id, {});
+
+  if (method === "tools/list") {
+    const lista = await carregarTools();
+    return ok(id, {
+      tools: lista.map(({ _endpoint, _kind, _efeito, ...t }) => t),
+    });
+  }
+
+  if (method === "tools/call") {
+    const lista = await carregarTools();
+    const tool = lista.find((t) => t.name === params?.name);
+    if (!tool) return falha(id, -32602, `Tool desconhecida: ${params?.name}`);
+    // `gestao_conectar`: executa o login de verdade — abre o navegador, espera a
+    // pessoa autorizar, guarda a credencial e republica as tools.
+    if (tool._endpoint === null) {
+      try {
+        await login({ silencioso: true });
+        const eu = await euSou();
+        await recarregarEAvisar();
+        return ok(
+          id,
+          texto(
+            `Conectado ao Gestão (${ambiente().nome}) como ${eu?.name ?? "?"} ` +
+              `— papel ${eu?.role ?? "?"}. Vale 1 hora. ` +
+              `As ferramentas do Gestão já estão disponíveis: refaça a ação que falhou.`,
+          ),
+        );
+      } catch (e) {
+        return ok(id, {
+          ...texto(
+            `Não consegui conectar: ${e.message}\n` +
+              `A pessoa precisa clicar em "Autorizar" na aba que abriu no navegador. ` +
+              `Se nenhuma aba abriu, ela pode rodar \`gestao login\` no terminal.`,
+          ),
+          isError: true,
+        });
+      }
+    }
+    try {
+      const valor = await chamar(tool._endpoint, params.arguments ?? {}, tool._kind);
+      return ok(id, texto(valor ?? { ok: true }));
+    } catch (e) {
+      // Erro de REGRA (ex.: "Empresa arquivada…") volta como conteúdo, não como
+      // erro de protocolo: é informação que o modelo deve ler e agir em cima.
+      return ok(id, { ...texto(`ERRO: ${e.message}`), isError: true });
+    }
+  }
+
+  if (id !== undefined) falha(id, -32601, `Método não suportado: ${method}`);
+}
+
+export async function servir() {
+  // NUNCA sai por falta de credencial. O token vale 1h; se o servidor morresse
+  // ao expirar, a pessoa veria "Failed to connect — Connection closed" de hora
+  // em hora, sem pista do motivo. Aqui ele sobe sempre, e a falta de sessão
+  // aparece como uma tool que EXPLICA o que fazer.
+  await carregarTools();
+
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", async (chunk) => {
+    buffer += chunk;
+    let quebra;
+    while ((quebra = buffer.indexOf("\n")) !== -1) {
+      const linha = buffer.slice(0, quebra).trim();
+      buffer = buffer.slice(quebra + 1);
+      if (!linha) continue;
+      let msg;
+      try {
+        msg = JSON.parse(linha);
+      } catch {
+        continue;
+      }
+      try {
+        await tratar(msg);
+      } catch (e) {
+        if (msg.id !== undefined) falha(msg.id, -32603, e.message);
+      }
+    }
+  });
+  process.stdin.on("end", () => process.exit(0));
+}

package/lib/tools.mjs

@@ -0,0 +1,95 @@
+// Contrato → lista de tools MCP.
+//
+// GRANULARIDADE: uma tool por ENDPOINT exposto (não por capacidade). Medimos: 36
+// capacidades expostas embrulham 69 endpoints distintos, e 10 delas têm mais de
+// um endpoint de ESCRITA (`cap.trilha.esforcos` tem seis). Uma tool por
+// capacidade obrigaria um discriminador `acao` + união de schemas — mais peça,
+// pior validação, e o modelo escolhendo duas vezes. Uma por endpoint mantém o
+// JSON Schema exato de cada chamada e nenhuma máquina nova.
+//
+// A capacidade não some: ela dá o NOME, a descrição, o `efeito` e o `cuidado:` —
+// é o que faz a tool ser escolhida pela intenção da pessoa e não pelo nome da
+// função do backend.
+
+const EFEITO_AVISO = {
+  leitura: "",
+  escrita: "",
+  destrutivo:
+    "\n\n⚠️ DESTRUTIVO E EM CASCATA: desfazer NÃO restaura o que isto leva. " +
+    "CONFIRME com a pessoa, em texto, antes de chamar.",
+};
+
+/** `ops.tasks.create` → `criar`; usado como sufixo quando a capacidade tem mais
+ *  de um endpoint (senão duas tools teriam o mesmo nome). */
+const sufixo = (id) =>
+  id
+    .split(".")
+    .pop()
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+
+const base = (capId) =>
+  "gestao_" + capId.replace(/^cap\./, "").replace(/[.-]/g, "_");
+
+export function montarTools(contrato) {
+  const tools = [];
+  const vistos = new Set();
+
+  const caps = Object.values(contrato.capabilities)
+    .filter((c) => c.agente === "exposta")
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  for (const cap of caps) {
+    const ends = cap.endpoints.filter((id) => contrato.endpoints[id]);
+    // O endpoint PRINCIPAL fica com o nome limpo da capacidade; os outros ganham
+    // sufixo. `gestao_projeto_editar` lê muito melhor que
+    // `gestao_projeto_editar_update`, e é por esse nome que o modelo escolhe.
+    // Principal = a única escrita, quando há exatamente uma (o caso comum: a
+    // capacidade age e as leituras são apoio); senão, o primeiro que o autor da
+    // capacidade listou — a ordem no L2 é deliberada.
+    const escritas = ends.filter((id) => contrato.endpoints[id].kind !== "query");
+    const principal = escritas.length === 1 ? escritas[0] : ends[0];
+
+    for (const id of ends) {
+      const ep = contrato.endpoints[id];
+      // Leituras se repetem entre capacidades (`ops.companies.list` aparece em
+      // várias). Dedup por endpoint: a primeira capacidade que o cita nomeia.
+      if (vistos.has(id)) continue;
+      vistos.add(id);
+
+      const nome =
+        ends.length === 1 || id === principal
+          ? base(cap.id)
+          : `${base(cap.id)}_${sufixo(id)}`;
+
+      const descricao = [
+        cap.fala ?? cap.id,
+        "",
+        `Capacidade: ${cap.id} · papel mínimo: ${cap.papel} · ${ep.kind}`,
+        cap.cuidado ? `\nATENÇÃO: ${cap.cuidado}` : "",
+        cap.antes?.length ? `\nCostuma vir depois de: ${cap.antes.join(", ")}.` : "",
+        cap.depois?.length ? `\nCostuma levar a: ${cap.depois.join(", ")}.` : "",
+        EFEITO_AVISO[cap.efeito] ?? "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      tools.push({
+        name: nome.slice(0, 64),
+        description: descricao,
+        inputSchema: ep.inputSchema,
+        // Metadados que o servidor usa no dispatch e o harness usa pra decidir
+        // se pede confirmação.
+        _endpoint: id,
+        _kind: ep.kind,
+        _efeito: cap.efeito,
+        annotations: {
+          readOnlyHint: ep.kind === "query",
+          destructiveHint: cap.efeito === "destrutivo",
+          idempotentHint: ep.kind === "query",
+        },
+      });
+    }
+  }
+  return tools;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "chatflux-gestao-agente",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Opere o portal Gestão da ChatFlux pelo Claude Code, Claude Desktop ou qualquer harness MCP — com a sua identidade e o seu papel.",
+  "keywords": [
+    "mcp",
+    "chatflux",
+    "gestao",
+    "claude"
+  ],
+  "license": "UNLICENSED",
+  "bin": {
+    "gestao": "bin/gestao.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Danielmtex/chatflux-gestao.git",
+    "directory": "agente"
+  }
+}