mcp-lab-agent

v2.3.1

Published

11 days ago

Sistema de Inteligência em Qualidade de Software: executa, analisa, prevê, recomenda e aprende. Memória local + Learning Hub.

mcp-lab-agent

PT-BR | English

Português (PT-BR)

Sistema de QA autônomo com IA. Reduz tempo de debug de testes, elimina flaky e mantém seletores estáveis — com um sistema de aprendizado que melhora a cada correção.

TL;DR para recrutadores: QA autônomo que explica por que os testes falharam em linguagem clara e aplica correções automaticamente. Testes que se autocorrigem e aprendem a cada fix. Integra com IDE (Cursor) e Slack. Feito para QA Engineers, SDETs e roles de Automação/IA.

Por que isso importa

| Problema real | Impacto no mercado | O que o mcp-lab-agent faz | |---------------|--------------------|---------------------------| | Testes flaky | Times gastam 5–10h/semana. Microsoft: ~25% das falhas em CI são flaky; Slack tinha 56% antes de remediar. | Detecta padrões flaky, sugere correções, retry automático com fixes | | "Por que falhou?" | QAs e devs perdem horas lendo stack traces e logs. "Teste falhou" genérico não ajuda. | Causa + correção em 30 segundos. Diagnóstico em linguagem clara: o que aconteceu, por que e como corrigir | | Seletores quebrados | Refactors de UI quebram testes. Seletores frágeis (classes CSS, XPath longo) exigem manutenção manual. | Auto-fix de seletores, sugere data-testid, aplica correções e tenta de novo |

O WOW: Testes que se autocorrigem e aprendem

Quando um teste falha, você recebe a causa e a correção em 30 segundos. Sem cavar em stack traces.

Cada correção bem-sucedida é salva e reutilizada. Na próxima falha similar, o agente aplica o padrão aprendido automaticamente. A taxa de sucesso na primeira tentativa melhora ao longo do tempo — mensurável via mcp-lab-agent stats.

npx mcp-lab-agent auto "login flow" --max-retries 5

Um comando. Análise completa. Autocorreção. Aprendizado.

Principais resultados

Reduz tempo de debug — "Por que falhou?" em linguagem clara, não stack traces
Corta manutenção de flaky — Detecção, diagnóstico e sugestões de correção
Escala QA sem escalar headcount — Agente no IDE + Slack bot; funciona com Cypress, Playwright, Appium, Jest e 11+ frameworks
Pronto para enterprise — Socket Mode (sem URL pública), Ollama (offline), Learning Hub para times

Como funciona

🤖 Agente no IDE (Cursor, Cline, Windsurf) — Pergunte no chat: "Gere teste para login", "Por que o teste falhou?", "Roda o teste X". O agente detecta o projeto, executa testes, analisa falhas, aplica correções e aprende.

💬 Slack Bot — Mencione o bot em qualquer canal — ele executa testes e posta o relatório. Funciona em ambiente corporativo (Socket Mode, sem ngrok). QA no fluxo da conversa.

Para quem é

| Perfil | Benefício | |--------|-----------| | QAs e SDETs | Geração assistida de testes, análise de falhas com sugestões de correção, detecção de flaky | | Desenvolvedores | "Por que falhou?" em segundos, análise de arquivos/métodos, integração direta no IDE | | Tech leads | Visão de risco por área, métricas de estabilidade, relatórios para decisão | | Times | Learning Hub, Slack bot para QA no chat, CI/CD, Ollama (offline) |

Como é diferente

| Outras ferramentas | mcp-lab-agent | |--------------------|---------------| | Só executam testes | Executa, analisa causa, sugere fix, aplica correção | | "Teste falhou" genérico | Linguagem clara: "Login falha 30% das vezes (timing). Adicione waitForDisplayed." | | Sem memória entre execuções | Learning system: cada fix melhora as próximas gerações | | Uma ferramenta por tarefa | End-to-end: gera, executa, analisa, reporta, aprende |

English

AI-powered autonomous QA system. Reduces test debugging time, eliminates flaky tests, and keeps selectors stable — with a learning system that gets smarter with every fix.

TL;DR for recruiters: Autonomous QA that explains why tests fail in plain language and applies fixes automatically. Self-healing tests that learn from each fix. Integrates with IDE (Cursor) and Slack. Built for QA Engineers, SDETs, and AI/Automation roles.

Why this matters

| Real problem | Industry impact | What mcp-lab-agent does | |--------------|-----------------|-------------------------| | Flaky tests | Teams spend 5–10h/week. Microsoft: ~25% of CI failures are flaky; Slack had 56% before remediation. | Detects flaky patterns, suggests fixes, auto-retries with corrections | | "Why did it fail?" | QAs and devs lose hours reading stack traces and logs. Generic "test failed" doesn't help. | Cause + fix in 30 seconds. Plain-language diagnosis: what happened, why, and how to fix | | Broken selectors | UI refactors break tests. Fragile selectors (CSS classes, long XPath) require manual maintenance. | Auto-fix selectors, suggests data-testid, applies corrections and retries |

The WOW: Self-healing tests that learn

When a test fails, you get the cause and fix in 30 seconds. No more digging through stack traces.

Each successful fix is saved and reused. The next time a similar failure happens, the agent applies the learned pattern automatically. First-attempt success rate improves over time — measurable via mcp-lab-agent stats.

npx mcp-lab-agent auto "login flow" --max-retries 5

One command. Full analysis. Self-correction. Learning.

Key outcomes

Reduce debugging time — "Why did it fail?" in plain language, not stack traces
Cut flaky test maintenance — Detection, diagnosis, and suggested fixes
Scale QA without scaling headcount — IDE agent + Slack bot; works with Cypress, Playwright, Appium, Jest, and 11+ frameworks
Enterprise-ready — Socket Mode (no public URL), Ollama (offline), Learning Hub for teams

How it works

🤖 IDE Agent (Cursor, Cline, Windsurf) — Ask in chat: "Generate a test for login", "Why did the test fail?", "Run test X". The agent detects your project, runs tests, analyzes failures, applies fixes, and learns.

💬 Slack Bot — Mention the bot in any channel — it runs tests and posts the report. Works in corporate environments (Socket Mode, no ngrok). QA in the flow of conversation.

Who it's for

| Role | Benefit | |------|---------| | QAs & SDETs | Assisted test generation, failure analysis with fix suggestions, flaky detection | | Developers | "Why did it fail?" in seconds, file/method analysis, direct IDE integration | | Tech leads | Risk visibility by area, stability metrics, decision-ready reports | | Teams | Learning Hub, Slack bot for QA in chat, CI/CD integration, Ollama (offline) |

How it's different

| Other tools | mcp-lab-agent | |-------------|---------------| | Run tests only | Run, analyze cause, suggest fix, apply correction | | Generic "test failed" | Plain-language: "Login fails 30% of the time (timing). Add waitForDisplayed." | | No memory between runs | Learning system: each fix improves future generations | | One tool per task | End-to-end: generate, run, analyze, report, learn |

Learning System

Como aprende: O agente detecta o padrão de falha em cada execução (regex + contexto) e armazena a correção aplicada na memória. Nas próximas gerações, esses aprendizados são injetados no prompt do LLM e nas práticas obrigatórias.

Baseado em quê: Tipo de erro (classificado automaticamente), framework, trecho de correção e resultado (passou ou não).

Melhora quanto: Taxa de sucesso na primeira tentativa (%), rastreável em mcp-lab-agent stats e get_learning_report. Quanto mais correções bem-sucedidas, maior a tendência de os próximos testes passarem de primeira.

Exemplos de padrões aprendidos:

| Padrão detectado | Correção aplicada | |------------------|-------------------| | element_not_visible | waitForDisplayed(), should('be.visible') antes de interagir | | element_not_rendered | waitForSelector, waitFor({ state: 'attached' }) | | selector instável | Sugestão de data-testid, role, seletores acessíveis | | timing | Retry automático, waits explícitos, timeout ajustado | | element_stale | Re-localizar elemento antes de cada ação | | mobile_mapping_invisible | Mapeamento visível no topo do spec (Page Object) |

Cada correção bem-sucedida aumenta a taxa de sucesso futura.

Quick Start

CLI — Análise completa

# Análise completa: executa testes, analisa estabilidade, prevê riscos e recomenda ações
npx mcp-lab-agent analyze

# Modo autônomo: gera, roda, corrige e aprende (até passar ou max_retries)
npx mcp-lab-agent auto "login flow" --max-retries 5

# Métricas de aprendizado e taxa de sucesso
npx mcp-lab-agent stats

# Relatório de evolução com recomendações para aprimorar o código
npx mcp-lab-agent report --full

IDE — Cursor, Cline, Windsurf

Adicione ao ~/.cursor/mcp.json:

{
  "mcpServers": {
    "qa-lab-agent": {
      "command": "npx",
      "args": ["-y", "mcp-lab-agent@latest"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Use no chat: "Detecte a estrutura do meu projeto", "Gere teste para login", "Por que o teste falhou?", "Avalie http://localhost:3000 no browser".

run_tests com device e auto-fix: Ao pedir "Roda o teste X", o agente detecta o device (de qa-lab-agent.config.json, wdio.conf ou .detoxrc), executa o fluxo e, se falhar por seletor, aplica correção automaticamente e tenta novamente.

Slack Bot

npx mcp-lab-agent slack-bot

Funciona em ambiente corporativo (Socket Mode, sem URL pública). Configure botToken e appToken em ~/.cursor/mcp.json. Onde obter: slack-bot/CREDENTIALS.md. Detalhes: slack-bot/README.md.

Learning Hub — Inteligência centralizada

npx mcp-lab-agent learning-hub

API e Dashboard em http://localhost:3847. Configure no .env do projeto:

LEARNING_HUB_URL=http://localhost:3847
LEARNING_HUB_PROJECT_ID=meu-projeto

O agente envia learnings automaticamente. O Hub agrega padrões e fornece recomendações. Detalhes: learning-hub/README.md.

Arquitetura

flowchart TB
    subgraph Input["Entrada"]
        CLI[CLI: auto, stats, report]
        IDE[IDE: Cursor, Cline, Windsurf]
        Slack[Slack Bot]
    end

    subgraph Agent["mcp-lab-agent"]
        Router[qa_route_task]
        Auto[qa_auto]
        MR[Model Router]
        FD[Flaky Detection]
        PM[Project Memory]
        LS[Learning System]
    end

    subgraph Tools["Ferramentas"]
        D[detect_project, list_test_files]
        G[generate_tests, write_test, map_mobile_elements]
        E[run_tests, get_test_coverage]
        A[analyze_failures, suggest_fix, por_que_falhou]
        R[create_bug_report, get_learning_report]
    end

    subgraph Ext["Externo"]
        LLM[LLM: Groq, Gemini, OpenAI, Ollama]
        Hub[Learning Hub]
    end

    Input --> Router
    Router --> Auto
    Auto --> G & E & A
    G & A --> MR --> LLM
    A --> FD
    Auto --> LS --> PM
    PM -.-> Hub
    Router --> D & G & E & A & R

Fluxo qa_auto:

Detecta projeto (frameworks, pastas, fluxos)
Gera teste com LLM + memória de aprendizados
Executa o teste
Se falhar: analisa (flaky detection), corrige e tenta novamente
Aprende e salva correções na memória
Repete até passar ou atingir max_retries

Capacidades

Automação e geração

Modo autônomo (qa_auto): gera, executa, analisa, corrige e aprende em loop
Geração com LLM: Groq, Gemini, OpenAI ou Ollama (100% offline)
Mapeamento mobile (map_mobile_elements): elementos em Appium/Detox
Templates: waits inteligentes e assert final obrigatório em todo teste gerado

Análise e diagnóstico

Detecção de falhas: timing, selector, element_not_rendered, element_not_visible, element_stale, mobile_mapping_invisible
Mensagens contextualizadas: cada tipo de erro tem explicação e sugestão específica
Análise de estabilidade: taxa de falha por teste, identificação de flaky
Predição de flakiness (qa_predict_flaky): risco antes de o problema aparecer
Análise de métodos (analyze_file_methods): varredura por método do arquivo

Relatórios e métricas

Bug reports em Markdown
Métricas de negócio (se qa-lab-flows.json configurado)
Relatório de evolução (get_learning_report): padrões por tipo, recomendações
Benchmark (qa_compare_with_industry): comparação com padrões do mercado

Memória e Learning Hub

Memória local: .qa-lab-memory.json por projeto
Learning Hub: API central (POST /learning, GET /patterns), Dashboard, sync automático entre projetos

Frameworks suportados

11+ frameworks: Cypress, Playwright, WebdriverIO, Jest, Vitest, Mocha, Robot Framework, pytest, Behave, Appium, Detox.

CLI

| Comando | Descrição | |---------|-----------| | (sem args) | Inicia servidor MCP (modo IDE) | | learning-hub | API + Dashboard (porta 3847) | | slack-bot | Bot Slack (Socket Mode) | | analyze | Análise completa do projeto | | auto <descrição> [--max-retries N] | Modo autônomo (default: 3 tentativas) | | stats | Estatísticas de aprendizado | | report [--full] | Relatório de evolução | | detect [--json] | Detecta frameworks e estrutura | | route <tarefa> | Sugere ferramenta | | list | Lista agentes e ferramentas |

# Exemplos de uso
mcp-lab-agent learning-hub          # Inicia Hub (porta 3847)
mcp-lab-agent analyze              # Análise completa
mcp-lab-agent auto "login flow"     # Modo autônomo
mcp-lab-agent stats                 # Taxa de sucesso, aprendizados
mcp-lab-agent report --full        # Relatório com recomendações

Escalabilidade e uso em produção

Por projeto: memória local (.qa-lab-memory.json) isolada por repositório
Entre times: Learning Hub agrega padrões por projectId; Dashboard compartilhado
Entre empresas: um Hub pode servir múltiplas organizações; padrões cross-org (ex.: "Playwright + selector instável" em 15 projetos) viram recomendações globais
CI/CD: integração em GitHub Actions, GitLab CI, Jenkins
Métricas exportáveis: JSON estruturado para Grafana, DataDog, dashboards internos
Ollama: 100% offline; adequado para ambientes corporativos restritivos
LLM interno: endpoint customizado da empresa

Configuração

Variáveis de ambiente (opcionais)

| Variável | Uso | |----------|-----| | GROQ_API_KEY | Groq | | GEMINI_API_KEY | Google Gemini | | OPENAI_API_KEY | OpenAI | | OLLAMA_BASE_URL | Ollama (default: http://localhost:11434) | | QA_LAB_LLM_BASE_URL | LLM customizado (empresa) | | QA_LAB_LLM_API_KEY | API key do LLM | | QA_LAB_LLM_SIMPLE | Modelo para tarefas simples | | QA_LAB_LLM_COMPLEX | Modelo para tarefas complexas | | LEARNING_HUB_URL | URL do Learning Hub | | LEARNING_HUB_PROJECT_ID | ID do projeto no Hub |

Ollama (offline)

brew install ollama
ollama pull llama3.1:8b
ollama serve
npx mcp-lab-agent auto "login flow"

Modo browser (Playwright)

npm install playwright

Documentação

CHANGELOG.md — Histórico de versões
slack-bot/README.md — Slack Bot
learning-hub/README.md — Learning Hub
docs/PORTFOLIO_COPY_PT-BR.md — Copy em PT-BR para portfólio (Vercel)

Desenvolvimento

git clone https://github.com/Wesley-Gomes93/mcp-lab-agent
cd mcp-lab-agent
npm install
npm run build
npm test

| Script | Descrição | |--------|-----------| | npm run build | Build (tsup) | | npm test | Testes (Vitest) | | npm run test:coverage | Cobertura | | npm run dev | Build em watch |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

mcp-lab-agent

Português (PT-BR)

Por que isso importa

O WOW: Testes que se autocorrigem e aprendem

Principais resultados

Como funciona

Para quem é

Como é diferente

English

Why this matters

The WOW: Self-healing tests that learn

Key outcomes

How it works

Who it's for

How it's different

Learning System

Quick Start

CLI — Análise completa

IDE — Cursor, Cline, Windsurf

Slack Bot

Learning Hub — Inteligência centralizada

Arquitetura

Capacidades

Automação e geração

Análise e diagnóstico

Relatórios e métricas

Memória e Learning Hub

Frameworks suportados

CLI

Escalabilidade e uso em produção

Configuração

Variáveis de ambiente (opcionais)

Ollama (offline)

Modo browser (Playwright)

Documentação

Desenvolvimento

Licença