mcp-lab-agent 2.1.4 → 2.1.6

package/slack-bot/TROUBLESHOOTING.md

@@ -0,0 +1,73 @@
+# Troubleshooting — QA Lab Slack Bot
+
+## Bot não responde quando envio mensagem
+
+### 1. Bot foi convidado para o canal?
+
+**Muito comum.** O bot precisa estar no canal para receber menções.
+
+- No canal: digite `/invite @NomeDoSeuBot`
+- Ou mencione em DM: abra DM com o bot e teste `@Bot analise o projeto`
+
+### 2. Configuração no Slack (api.slack.com)
+
+Seguindo a [documentação oficial](https://docs.slack.dev/app-management/quickstart-app-settings):
+
+#### Se usa **Socket Mode** (PC corporativo, sem ngrok):
+
+1. **Socket Mode** → Enable Socket Mode → ON
+2. **Basic Information** → App-Level Tokens → Generate → scope: `connections:write` → copie (`xapp-...`)
+3. **Event Subscriptions** → Enable Events → Subscribe to bot events → `app_mention`
+4. **OAuth & Permissions** → Bot Token Scopes: `app_mentions:read`, `chat:write`, `channels:read`, `channels:history`
+5. **Install App** → **Reinstall to Workspace** (obrigatório após alterar scopes ou eventos)
+
+#### Se usa **HTTP** (ngrok):
+
+1. **Event Subscriptions** → Enable Events → Request URL: `https://SEU_NGROK.ngrok.io/slack/events`
+2. Subscribe to bot events: `app_mention`
+3. **Basic Information** → App Credentials → Signing Secret (Show)
+
+### 3. Config correta no mcp.json
+
+O `~/.cursor/mcp.json` precisa ter a seção `qa-lab-agent.slack`:
+
+```json
+{
+  "qa-lab-agent": {
+    "slack": {
+      "botToken": "xoxb-...",
+      "appToken": "xapp-...",
+      "useLocal": true
+    }
+  }
+}
+```
+
+- `botToken` — OAuth & Permissions → OAuth Tokens → Bot User OAuth Token (começa com `xoxb-`)
+- `appToken` — Basic Information → App-Level Tokens (scope `connections:write`, começa com `xapp-`) — só para Socket Mode
+- `useLocal: true` — analisa o projeto local (pasta atual) em vez de clonar um repo
+
+### 4. Rodar o diagnóstico
+
+```bash
+cd slack-bot
+npm run check
+```
+
+Corrija qualquer item marcado com ❌.
+
+### 5. Conferir se o bot está rodando
+
+Ao subir com `npm start`, deve aparecer:
+
+- Socket Mode: `QA Lab Slack Bot rodando em Socket Mode (sem URL pública necessária)`
+- HTTP: `QA Lab Slack Bot rodando em http://localhost:3000`
+
+Se der erro ao iniciar, leia a mensagem — geralmente indica token inválido ou faltando.
+
+### 6. Firewall / proxy corporativo
+
+Em redes corporativas, às vezes o WebSocket (Socket Mode) é bloqueado. Tente:
+
+- Socket Mode primeiro (não precisa de URL pública)
+- Se não funcionar, use ngrok em outra máquina e configure HTTP

package/slack-bot/check-config.js

@@ -3,54 +3,74 @@
  * Verifica se a config do Slack está correta.
  * Rode: node check-config.js
  */
+import { config } from "dotenv";
 import { readFileSync, existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const home = process.env.HOME || process.env.USERPROFILE;
-const mcpPath = home ? path.join(home, ".cursor", "mcp.json") : null;
-
-console.log("\n🔧 QA Lab Slack Bot - Diagnóstico\n");
-console.log("1. mcp.json:");
-if (!mcpPath || !existsSync(mcpPath)) {
-  console.log("   ❌ Não encontrado em", mcpPath || "(HOME não definido)");
-  process.exit(1);
+// check-config.js fica em slack-bot/, então __dirname já é a pasta slack-bot
+const SLACK_BOT_DIR = __dirname;
+// Carrega .env na mesma ordem do config.js (QA_LAB_ENV override, cwd, slack-bot)
+const envPaths = [
+  process.env.QA_LAB_ENV,
+  path.join(process.cwd(), ".env"),
+  path.join(SLACK_BOT_DIR, ".env"),
+].filter(Boolean);
+for (const p of envPaths) {
+  if (p && existsSync(p)) {
+    config({ path: p });
+    break;
+  }
+}
+function getMcpJsonPath() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  return home ? path.join(home, ".cursor", "mcp.json") : null;
 }
-console.log("   ✅ Encontrado:", mcpPath);
+const mcpPath = process.env.QA_LAB_MCP_CONFIG || getMcpJsonPath();
 
-let mcp;
-try {
-  mcp = JSON.parse(readFileSync(mcpPath, "utf8"));
-} catch (e) {
-  console.log("   ❌ Erro ao ler JSON:", e.message);
-  process.exit(1);
+console.log("\n🔧 QA Lab Slack Bot - Diagnóstico\n");
+console.log("1. Origens de config (mcp.json ou .env):");
+let mcp = null;
+if (mcpPath && existsSync(mcpPath)) {
+  console.log("   ✅ mcp.json:", mcpPath);
+  try {
+    mcp = JSON.parse(readFileSync(mcpPath, "utf8"));
+  } catch (e) {
+    console.log("   ❌ Erro ao ler mcp.json:", e.message);
+  }
+} else {
+  console.log("   ⊘ mcp.json não encontrado (use .env na pasta do slack-bot ou cwd)");
 }
 
-const slack = mcp?.["qa-lab-agent"]?.slack;
-if (!slack) {
-  console.log("   ❌ Seção 'qa-lab-agent.slack' não encontrada");
-  console.log("   Estrutura esperada:");
-  console.log('   { "qa-lab-agent": { "slack": { "botToken": "xoxb-...", "signingSecret": "..." } } }');
-  process.exit(1);
+const slack = mcp?.["qa-lab-agent"]?.slack || {};
+const hasMcpSlack = !!mcp?.["qa-lab-agent"]?.slack;
+if (!hasMcpSlack) {
+  console.log("   ⚠️  Seção 'qa-lab-agent.slack' não encontrada no mcp.json");
+  console.log("   Usando .env como fallback (SLACK_BOT_TOKEN, SLACK_APP_TOKEN ou SLACK_SIGNING_SECRET)");
 }
-console.log("   ✅ Config slack encontrada");
+if (hasMcpSlack) console.log("   ✅ Config slack encontrada no mcp.json");
 
 console.log("\n2. botToken:");
-const token = slack.botToken || slack.SLACK_BOT_TOKEN;
+const token = slack.botToken || slack.SLACK_BOT_TOKEN || process.env.SLACK_BOT_TOKEN;
 if (!token) {
   console.log("   ❌ Ausente. Adicione 'botToken' ou 'SLACK_BOT_TOKEN'");
 } else if (!token.startsWith("xoxb-")) {
   console.log("   ⚠️  Deve começar com 'xoxb-'. Você usou o Client Secret?");
-  console.log("   Use: OAuth & Permissions → Bot User OAuth Token (depois de Install to Workspace)");
+  console.log("   Onde: OAuth & Permissions → OAuth Tokens → Bot User OAuth Token");
 } else {
   console.log("   ✅ OK (xoxb-...)");
 }
 
-console.log("\n3. signingSecret:");
-const secret = slack.signingSecret || slack.SLACK_SIGNING_SECRET;
-if (!secret) {
-  console.log("   ❌ Ausente. Adicione 'signingSecret'");
+const appToken = slack.appToken || slack.slack_app_token || slack.SLACK_APP_TOKEN || process.env.SLACK_APP_TOKEN;
+const useSocketMode = !!(appToken && appToken.startsWith("xapp-"));
+
+console.log("\n3. signingSecret (só para modo HTTP):");
+const secret = slack.signingSecret || slack.SLACK_SIGNING_SECRET || process.env.SLACK_SIGNING_SECRET;
+if (useSocketMode) {
+  console.log("   ⊘ Não necessário (você está usando Socket Mode)");
+} else if (!secret) {
+  console.log("   ❌ Ausente. Adicione 'signingSecret' ou use appToken para Socket Mode");
   console.log("   Onde: Basic Information → App Credentials → Signing Secret (Show)");
 } else if (secret === "..." || secret.length < 20) {
   console.log("   ⚠️  Parece placeholder ou inválido. Use o valor real do Signing Secret.");
@@ -58,17 +78,40 @@ if (!secret) {
   console.log("   ✅ OK");
 }
 
-console.log("\n4. Event Subscriptions (api.slack.com):");
-console.log("   • Request URL deve ser: https://SEU_DOMINIO/slack/events");
-console.log("   • Se local: use ngrok → ngrok http 3000");
-console.log("   • Bot event: app_mention");
+console.log("\n4. appToken (slack_app_token) para Socket Mode:");
+if (appToken) {
+  if (appToken.startsWith("xapp-")) {
+    console.log("   ✅ OK (xapp-...) — bot funcionará sem URL pública");
+  } else {
+    console.log("   ⚠️  Deve começar com 'xapp-'. Onde: Basic Information → App-Level Tokens (scope: connections:write)");
+  }
+} else {
+  console.log("   ⊘ Não configurado. Onde: Basic Information → App-Level Tokens (scope: connections:write)");
+}
+
+console.log("\n5. Resumo do modo:");
+if (useSocketMode) {
+  console.log("   ✅ Socket Mode (appToken xapp-) — não precisa de URL pública");
+  console.log("   • Em api.slack.com: Socket Mode → Enable");
+  console.log("   • Basic Information → App-Level Tokens → Generate com scope connections:write");
+} else {
+  console.log("   HTTP (Event Subscriptions):");
+  console.log("   • Request URL: https://SEU_DOMINIO/slack/events");
+  console.log("   • Se local: ngrok http 3000");
+  console.log("   • Bot event: app_mention");
+  console.log("   💡 Para PC corporativo: use appToken (Socket Mode) e não precisa de ngrok!");
+}
 
-console.log("\n5. Bot no canal:");
-console.log("   • Mencione o bot no canal ou use /invite @NomeDoBot");
+console.log("\n6. Bot no canal:");
+console.log("   • /invite @NomeDoBot (obrigatório!) ou mencione em DM");
 
-if (token && secret && token.startsWith("xoxb-")) {
-  console.log("\n✅ Config parece OK. Rode: npm start");
+if (token && token.startsWith("xoxb-") && (useSocketMode || secret)) {
+  console.log("\n✅ Config OK. Rode: npm start");
+  console.log("   Modo:", useSocketMode ? "Socket (qualquer ambiente)" : "HTTP (ngrok)");
 } else {
-  console.log("\n❌ Corrija os itens acima e tente novamente.");
+  console.log("\n❌ Corrija os itens acima.");
+  if (!token) console.log("   Dica: botToken ou SLACK_BOT_TOKEN obrigatório.");
+  if (!useSocketMode && !secret) console.log("   Dica: use appToken (Socket) OU signingSecret (HTTP).");
+  console.log("   Onde obter: slack-bot/CREDENTIALS.md | https://docs.slack.dev/app-management/quickstart-app-settings");
 }
 console.log("");

package/slack-bot/setup.js

@@ -14,21 +14,27 @@ console.log("\n🔧 QA Lab Slack Bot - Setup\n");
 
 if (!existsSync(envPath)) {
   copyFileSync(path.join(__dirname, ".env.example"), envPath);
-  console.log("✅ .env criado. Edite e preencha:");
-  console.log("   - SLACK_BOT_TOKEN (api.slack.com → sua app → OAuth)");
-  console.log("   - SLACK_SIGNING_SECRET (api.slack.com → Basic Information)\n");
+  console.log("✅ .env criado. Edite e preencha:\n");
+  console.log("   OBRIGATÓRIO: SLACK_BOT_TOKEN (xoxb-...)\n");
+  console.log("   Escolha UM modo:\n");
+  console.log("   • Socket Mode (qualquer ambiente): SLACK_APP_TOKEN (xapp-...)");
+  console.log("   • HTTP (ngrok): SLACK_SIGNING_SECRET\n");
   process.exit(0);
 }
 
 const env = readFileSync(envPath, "utf8");
 const hasToken = /SLACK_BOT_TOKEN=xoxb-/.test(env);
+const hasAppToken = /SLACK_APP_TOKEN=xapp-/.test(env);
 const hasSecret = /SLACK_SIGNING_SECRET=.{20,}/.test(env);
 
-if (!hasToken || !hasSecret) {
-  console.log("⚠️  .env existe mas faltam valores:");
-  if (!hasToken) console.log("   - SLACK_BOT_TOKEN");
-  if (!hasSecret) console.log("   - SLACK_SIGNING_SECRET");
-  console.log("\nEdite slack-bot/.env e preencha os valores.\n");
+if (!hasToken) {
+  console.log("⚠️  .env existe mas falta SLACK_BOT_TOKEN (xoxb-...)\n");
+  process.exit(1);
+}
+if (!hasAppToken && !hasSecret) {
+  console.log("⚠️  Configure um modo de conexão:");
+  console.log("   • Socket Mode (recomendado): SLACK_APP_TOKEN=xapp-...");
+  console.log("   • HTTP: SLACK_SIGNING_SECRET=...\n");
   process.exit(1);
 }
 

package/slack-bot/src/config.js

@@ -7,7 +7,19 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "../..");
 const SLACK_BOT_DIR = path.dirname(__dirname);
 
-config({ path: path.join(SLACK_BOT_DIR, ".env") });
+// Carrega .env de múltiplos locais (funciona em pessoal, corporativo, npx, etc.)
+// Ordem: cwd primeiro (override), depois package dir, depois QA_LAB_ENV
+const envPaths = [
+  process.env.QA_LAB_ENV,
+  path.join(process.cwd(), ".env"),
+  path.join(SLACK_BOT_DIR, ".env"),
+].filter(Boolean);
+for (const p of envPaths) {
+  if (p && existsSync(p)) {
+    config({ path: p });
+    break;
+  }
+}
 
 function getMcpJsonPath() {
   const home = process.env.HOME || process.env.USERPROFILE;
@@ -33,6 +45,7 @@ function getSlackConfigFromMcp() {
   return {
     id: slack.id || slack.channelId,
     botToken: slack.botToken || slack.SLACK_BOT_TOKEN,
+    appToken: slack.appToken || slack.slack_app_token || slack.SLACK_APP_TOKEN,
     signingSecret: slack.signingSecret || slack.SLACK_SIGNING_SECRET,
     repo: slack.repo || slack.REPO_URL,
     branch: slack.branch || slack.REPO_BRANCH || "main",
@@ -54,13 +67,10 @@ function loadSlackConfig() {
 
 function getSlackTokens() {
   const fromMcp = getSlackConfigFromMcp();
-  if (fromMcp?.botToken && fromMcp?.signingSecret) {
-    return { token: fromMcp.botToken, signingSecret: fromMcp.signingSecret };
-  }
-  return {
-    token: process.env.SLACK_BOT_TOKEN,
-    signingSecret: process.env.SLACK_SIGNING_SECRET,
-  };
+  const token = fromMcp?.botToken || process.env.SLACK_BOT_TOKEN;
+  const signingSecret = fromMcp?.signingSecret || process.env.SLACK_SIGNING_SECRET;
+  const appToken = fromMcp?.appToken || process.env.SLACK_APP_TOKEN;
+  return { token, signingSecret, appToken };
 }
 
 function getRepoForChannel() {

package/slack-bot/src/index.js

@@ -4,28 +4,62 @@
  * Recebe @mentions no Slack, executa mcp-lab-agent e posta relatório.
  *
  * Config: ~/.cursor/mcp.json (qa-lab-agent.slack) ou .env
+ *
+ * Dois modos:
+ * 1) Socket Mode (recomendado para PC corporativo): botToken + appToken (slack_app_token)
+ *    Não precisa de URL pública. Funciona atrás de firewall.
+ * 2) HTTP (Event Subscriptions): botToken + signingSecret
+ *    Precisa de URL pública (ngrok) em api.slack.com.
  */
 import { App } from "@slack/bolt";
 import { getSlackTokens } from "./config.js";
 import { registerAppMention } from "./handlers/app-mention.js";
 
-const { token, signingSecret } = getSlackTokens();
+const { token, signingSecret, appToken } = getSlackTokens();
+
+const useSocketMode = !!(appToken && appToken.startsWith("xapp-"));
+
+if (!token || !token.startsWith("xoxb-")) {
+  console.error(
+    "Configure botToken (xoxb-...) no ~/.cursor/mcp.json ou .env (SLACK_BOT_TOKEN).\n" +
+    "Onde: api.slack.com → sua app → OAuth & Permissions → Bot User OAuth Token"
+  );
+  process.exit(1);
+}
 
-if (!token || !signingSecret) {
-  console.error("Configure no ~/.cursor/mcp.json:\n  \"qa-lab-agent\": { \"slack\": { \"botToken\": \"xoxb-...\", \"signingSecret\": \"...\" } }\n\nOu use .env (SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET)");
+if (useSocketMode) {
+  // Socket Mode: funciona sem URL pública (ideal para PC corporativo)
+  if (!appToken.startsWith("xapp-")) {
+    console.error("appToken (slack_app_token) deve começar com 'xapp-' para Socket Mode.");
+    process.exit(1);
+  }
+} else if (!signingSecret) {
+  console.error(
+    "Modo HTTP: configure signingSecret no ~/.cursor/mcp.json ou .env (SLACK_SIGNING_SECRET).\n" +
+    "Modo Socket: adicione appToken (xapp-...) para funcionar sem URL pública."
+  );
   process.exit(1);
 }
 
-const app = new App({
+const appOptions = {
   token,
-  signingSecret,
-});
+  ...(useSocketMode
+    ? { socketMode: true, appToken }
+    : { signingSecret }),
+};
 
+const app = new App(appOptions);
 registerAppMention(app);
 
-const port = process.env.PORT || 3000;
-const server = await app.start(port);
-console.log(`QA Lab Slack Bot rodando em http://localhost:${port}`);
-console.log("Configure Event Subscriptions em api.slack.com com:");
-console.log(`  Request URL: https://SEU_DOMINIO/slack/events`);
-console.log("  Bot event: app_mention");
+if (useSocketMode) {
+  await app.start();
+  console.log("QA Lab Slack Bot rodando em Socket Mode (sem URL pública necessária)");
+  console.log("Mencione o bot em um canal para usar.");
+} else {
+  const port = process.env.PORT || 3000;
+  await app.start(port);
+  console.log(`QA Lab Slack Bot rodando em http://localhost:${port}`);
+  console.log("Configure Event Subscriptions em api.slack.com:");
+  console.log(`  Request URL: https://SEU_DOMINIO/slack/events`);
+  console.log("  Bot event: app_mention");
+}