mcp-lab-agent 1.1.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,242 +1,310 @@
1
1
  # mcp-lab-agent
2
2
 
3
- MCP server + AI agents para QA automation em **qualquer projeto**. Detecta automaticamente frameworks de teste e estrutura do projeto.
3
+ [![npm version](https://img.shields.io/npm/v/mcp-lab-agent.svg)](https://www.npmjs.com/package/mcp-lab-agent)
4
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
6
 
5
- ## 📚 Documentação Rápida
7
+ **Agente autônomo de QA que aprende com os próprios erros.**
6
8
 
7
- | Guia | Descrição |
8
- |------|-----------|
9
- | 🚀 **[Quick Start](QUICKSTART.md)** | Instale em 2 minutos e comece a usar |
10
- | 📖 **[Como Usar](COMO_USAR.md)** | Guia completo de uso com exemplos |
11
- | 🧪 **[Teste Comigo](TESTE_COMIGO.md)** | Roteiro para testar e dar feedback |
12
- | 🔧 **[Instalação](INSTALL.md)** | Opções detalhadas de instalação |
13
- | ⚙️ **[Setup Cursor](CURSOR_SETUP.md)** | Configuração passo a passo |
14
- | 🚨 **[Troubleshooting](TROUBLESHOOTING.md)** | Solução de problemas |
15
- | 🎯 **[Frameworks](FRAMEWORKS.md)** | Frameworks suportados |
9
+ Não é um assistente: é um agente que **lê seu projeto, gera testes, executa, corrige falhas automaticamente e aprende** para cada vez acertar mais na primeira tentativa.
16
10
 
17
- ## Features
18
-
19
- - **Detecção automática** de frameworks:
20
- - **E2E/UI**: Cypress, Playwright, WebdriverIO
21
- - **Unit/Integration**: Jest, Vitest, Mocha, Jasmine
22
- - **Mobile**: Appium, Detox
23
- - **API**: Supertest, Pactum
24
- - **Python**: Robot Framework, pytest, Behave
25
- - **Execução de testes** com output estruturado (backend, frontend, mobile, API)
26
- - **Geração de testes** via LLM (Groq, Gemini, OpenAI)
27
- - **Análise de falhas** e sugestões de correção inteligentes
28
- - **Bug reports** automáticos em Markdown
29
- - **Linter** e **coverage** integrados
30
- - **Templates de teste** para API, UI e Unit
31
- - **Zero configuração**: funciona em projetos Node.js e Python
32
-
33
- ## Instalação e Uso no Cursor
11
+ ---
34
12
 
35
- ### 🚀 Instalação Rápida (Recomendado)
13
+ ## O diferencial
36
14
 
37
- **1. Configure o MCP no Cursor:**
15
+ | Outras ferramentas | **mcp-lab-agent** |
16
+ |-------------------|-------------------|
17
+ | Geram testes | **Gera, roda, corrige e aprende** |
18
+ | Você corrige erros | **Auto-correção com retry inteligente** |
19
+ | Sem memória | **Aprende com erros passados** |
20
+ | Configuração complexa | **Zero config: detecta 15+ frameworks** |
21
+ | Sem métricas | **Taxa de sucesso, correções, aprendizados** |
38
22
 
39
- Edite ou crie o arquivo `~/.cursor/mcp.json`:
23
+ **Modo autônomo:**
40
24
 
41
25
  ```bash
42
- mkdir -p ~/.cursor
43
- nano ~/.cursor/mcp.json
44
- ```
45
-
46
- **2. Adicione a configuração:**
47
-
48
- ```json
49
- {
50
- "mcpServers": {
51
- "qa-lab-agent": {
52
- "command": "npx",
53
- "args": ["-y", "mcp-lab-agent"],
54
- "cwd": "${workspaceFolder}"
55
- }
56
- }
57
- }
26
+ npx mcp-lab-agent auto "login flow" --max-retries 5
58
27
  ```
59
28
 
60
- **3. Reinicie o Cursor**
29
+ O agente:
30
+ 1. Detecta seu projeto (Cypress, Playwright, Jest, etc.)
31
+ 2. Gera o teste com base em aprendizados anteriores
32
+ 3. Executa o teste
33
+ 4. Se falhar: analisa, corrige e tenta de novo
34
+ 5. Aprende com cada correção para melhorar nas próximas
61
35
 
62
- **4. Pronto!** Abra qualquer projeto e use normalmente no chat.
36
+ **Resultado:** Testes que passam na primeira tentativa aumentam com o tempo.
63
37
 
64
38
  ---
65
39
 
66
- ### 📦 Outras Opções de Instalação
40
+ ## Quick Start
67
41
 
68
- <details>
69
- <summary>Opção 1: Build Local (para desenvolvimento)</summary>
42
+ ### Modo autônomo (CLI)
70
43
 
71
44
  ```bash
72
- # Clone e instale
73
- git clone https://github.com/Wesley-Gomes93/mcp-lab-agent
74
- cd mcp-lab-agent
75
- npm install
76
- npm run build
45
+ # Gera, roda, corrige e aprende automaticamente
46
+ npx mcp-lab-agent auto "login flow" --max-retries 5
47
+
48
+ # Ver métricas de aprendizado
49
+ npx mcp-lab-agent stats
50
+
51
+ # Detectar estrutura do projeto
52
+ npx mcp-lab-agent detect
77
53
  ```
78
54
 
79
- Configure no `~/.cursor/mcp.json`:
55
+ ### Integração com IDE (Cursor/Cline/Windsurf)
56
+
57
+ **1. Configure o MCP** (`~/.cursor/mcp.json`):
80
58
 
81
59
  ```json
82
60
  {
83
61
  "mcpServers": {
84
62
  "qa-lab-agent": {
85
- "command": "node",
86
- "args": ["/caminho/completo/para/mcp-lab-agent/dist/index.js"],
63
+ "command": "npx",
64
+ "args": ["-y", "mcp-lab-agent"],
87
65
  "cwd": "${workspaceFolder}"
88
66
  }
89
67
  }
90
68
  }
91
69
  ```
92
70
 
93
- **Nota:** Substitua `/caminho/completo/para/mcp-lab-agent` pelo caminho real no seu sistema.
94
-
95
- </details>
71
+ **2. Use no chat:**
96
72
 
97
- <details>
98
- <summary>Opção 2: Instalação Global com npm link</summary>
99
-
100
- ```bash
101
- cd mcp-lab-agent
102
- sudo npm link
73
+ ```
74
+ "Detecte a estrutura do meu projeto"
75
+ "Modo autônomo: gere teste para login"
76
+ "Rode os testes"
77
+ "Por que o teste falhou?"
78
+ "Avalie http://localhost:3000 no browser"
79
+ "Mostre as estatísticas de aprendizado"
103
80
  ```
104
81
 
105
- Configure no `~/.cursor/mcp.json`:
82
+ ---
106
83
 
107
- ```json
108
- {
109
- "mcpServers": {
110
- "qa-lab-agent": {
111
- "command": "mcp-lab-agent",
112
- "cwd": "${workspaceFolder}"
113
- }
114
- }
115
- }
84
+ ## Architecture
85
+
86
+ O diagrama abaixo mostra como o agente autônomo funciona:
87
+
88
+ ```mermaid
89
+ flowchart TB
90
+ subgraph IDE["🖥️ IDE (Cursor, Cline, Windsurf)"]
91
+ Chat[Chat do usuário]
92
+ end
93
+
94
+ subgraph CLI["💻 CLI (Terminal)"]
95
+ Auto["mcp-lab-agent auto"]
96
+ Stats["mcp-lab-agent stats"]
97
+ end
98
+
99
+ subgraph MCP["MCP Protocol (stdio)"]
100
+ Transport[Stdio Transport]
101
+ end
102
+
103
+ subgraph Agent["mcp-lab-agent"]
104
+ Router[qa_route_task]
105
+ AutoTool["qa_auto<br/>(Loop autônomo)"]
106
+
107
+ subgraph Agents["Agentes Especializados"]
108
+ D[detection<br/>detect_project, read_project, list_test_files]
109
+ E[execution<br/>run_tests, watch_tests, get_test_coverage]
110
+ G[generation<br/>generate_tests, write_test]
111
+ A[analysis<br/>analyze_failures, por_que_falhou, suggest_selector_fix]
112
+ B[browser<br/>web_eval_browser]
113
+ R[reporting<br/>create_bug_report, get_business_metrics]
114
+ L[learning<br/>qa_learning_stats]
115
+ end
116
+
117
+ subgraph Brain["🧠 Núcleo Inteligente"]
118
+ MR[Model Router<br/>simples → Groq/Flash | complexo → 70B/Pro]
119
+ PM[Project Memory<br/>.qa-lab-memory.json]
120
+ FD[Flaky Detection<br/>timing, selector, network]
121
+ LS[Learning System<br/>salva correções bem-sucedidas]
122
+ end
123
+ end
124
+
125
+ subgraph External["Externo"]
126
+ LLM[LLM: Groq / Gemini / OpenAI]
127
+ PW[Playwright optional]
128
+ Proj[Seu projeto]
129
+ end
130
+
131
+ Chat --> Transport
132
+ Transport --> Router
133
+ Router --> AutoTool
134
+ Router --> D & E & G & A & B & R & L
135
+
136
+ Auto --> AutoTool
137
+ Stats --> L
138
+
139
+ AutoTool --> G
140
+ AutoTool --> E
141
+ AutoTool --> A
142
+ AutoTool --> LS
143
+
144
+ D & E & G & A & R --> Proj
145
+ B --> PW
146
+ B --> Proj
147
+
148
+ G & A --> MR
149
+ MR --> LLM
150
+ G & A & AutoTool --> PM
151
+ A & AutoTool --> FD
152
+ AutoTool --> LS
153
+ LS --> PM
116
154
  ```
117
155
 
118
- </details>
156
+ **Fluxo autônomo (qa_auto):**
157
+ 1. **Detecta** projeto (frameworks, pastas, fluxos)
158
+ 2. **Gera** teste usando LLM + memória de aprendizados
159
+ 3. **Executa** o teste
160
+ 4. **Se falhar:** analisa (flaky detection), corrige e tenta de novo
161
+ 5. **Aprende:** salva correções bem-sucedidas na memória
162
+ 6. **Repete** até passar ou atingir max_retries
163
+
164
+ **Fluxo resumido (IDE):**
165
+ 1. **Usuário** fala no chat do IDE
166
+ 2. **MCP** entrega a mensagem ao `mcp-lab-agent`
167
+ 3. **qa_route_task** sugere o agente certo (detection, execution, generation, etc.)
168
+ 4. **Ferramentas** executam no projeto (detectar, rodar, gerar, analisar)
169
+ 5. **Model Router** escolhe o modelo: tarefas simples → barato; complexas → mais capaz
170
+ 6. **Project Memory** guarda padrões e fluxos para próximas gerações
171
+ 7. **Flaky Detection** identifica testes intermitentes e sugere correções
172
+
173
+ ---
119
174
 
120
- ## Ferramentas disponíveis
175
+ ## Features
121
176
 
122
- ### Core Tools
177
+ | Categoria | O que faz |
178
+ |-----------|-----------|
179
+ | **🤖 Autônomo** | `qa_auto` — loop completo: gera, roda, corrige, aprende (até passar ou max_retries) |
180
+ | **📊 Learning** | Salva correções bem-sucedidas, taxa de sucesso na 1ª tentativa, métricas de aprendizado |
181
+ | **Detecção** | Cypress, Playwright, WebdriverIO, Jest, Vitest, Mocha, Robot, pytest, Behave, Appium, Detox |
182
+ | **Execução** | run_tests, watch, coverage (Jest/Vitest) |
183
+ | **Geração** | Testes via LLM (Groq, Gemini, OpenAI), templates |
184
+ | **Análise** | analyze_failures, por_que_falhou, suggest_fix, suggest_selector_fix |
185
+ | **Browser** | web_eval_browser — screenshots, network, console (Playwright opcional) |
186
+ | **Relatórios** | Bug reports em Markdown, métricas de negócio |
187
+ | **Flaky-aware** | Detecta timing, selector, network; sugere retries |
188
+ | **Model routing** | Tarefas simples → modelo barato; complexas → modelo forte |
189
+ | **Memória** | Cache em .qa-lab-memory.json, qa-lab-flows.json |
123
190
 
124
- | Tool | Descrição |
125
- |------|-----------|
126
- | `detect_project` | Detecta frameworks, pastas de teste, backend, frontend |
127
- | `run_tests` | Executa testes (Cypress, Playwright, Jest, npm test) |
128
- | `read_project` | Lê package.json, specs existentes |
129
- | `generate_tests` | Gera spec com LLM (requer API key) |
130
- | `write_test` | Grava spec no disco |
131
- | `analyze_failures` | Analisa output de falhas e extrai stack traces |
191
+ ---
132
192
 
133
- ### Novas Ferramentas (v2.0)
193
+ ## CLI
134
194
 
135
- | Tool | Descrição |
136
- |------|-----------|
137
- | `suggest_fix` | Sugere correções para falhas detectadas (seletores, asserções, rede) |
138
- | `create_bug_report` | Gera bug report estruturado em Markdown a partir de falhas |
139
- | `list_test_files` | Lista todos os arquivos de teste (filtro por framework/pattern) |
140
- | `run_linter` | Executa ESLint/Prettier com auto-fix opcional |
141
- | `install_dependencies` | Instala dependências (npm/yarn/pnpm - detecta automaticamente) |
142
- | `get_test_coverage` | Gera relatório de cobertura de testes (Jest) |
143
- | `watch_tests` | Inicia testes em watch mode (Jest/Vitest) |
144
- | `create_test_template` | Gera boilerplate de teste (API/UI/Unit) para qualquer framework |
145
- | `suggest_selector_fix` | **Self-healing:** Sugere seletor alternativo quando UI muda (element not found) |
146
- | `get_business_metrics` | **Métricas de negócio:** Tempo até bug, custo por defeito, cobertura por fluxo |
147
- | `suggest_selector_fix` | **Self-healing:** Sugere correção de seletor quando UI muda (LLM) |
148
- | `get_business_metrics` | **Métricas de negócio:** Tempo até bug, custo por defeito, cobertura por fluxo |
195
+ ```bash
196
+ mcp-lab-agent [comando]
197
+ ```
149
198
 
150
- ## Variáveis de ambiente (opcional)
199
+ | Comando | Descrição |
200
+ |---------|-----------|
201
+ | *(sem args)* | Inicia o servidor MCP (modo padrão para o IDE) |
202
+ | `auto <descrição> [--max-retries N]` | **[NOVO]** Modo autônomo: gera, roda, corrige e aprende (default: 3 tentativas) |
203
+ | `stats` | **[NOVO]** Mostra estatísticas de aprendizado (taxa de sucesso, correções, etc.) |
204
+ | `detect [--json]` | Detecta frameworks e estrutura do projeto |
205
+ | `route <tarefa>` | Sugere qual ferramenta usar |
206
+ | `list` | Lista agentes e ferramentas disponíveis |
207
+ | `--help` | Mostra ajuda |
208
+
209
+ **Exemplos:**
210
+ ```bash
211
+ mcp-lab-agent auto "login flow" --max-retries 5
212
+ mcp-lab-agent stats
213
+ mcp-lab-agent detect
214
+ mcp-lab-agent route "rodar os testes"
215
+ mcp-lab-agent list
216
+ ```
151
217
 
152
- Para usar `generate_tests`, configure no `.env` do projeto:
218
+ Referência completa do CLI: `mcp-lab-agent --help`
153
219
 
154
- - **GROQ_API_KEY** — Groq (gratuito): https://console.groq.com/keys
155
- - **GEMINI_API_KEY** — Google Gemini (gratuito): https://aistudio.google.com/apikey
156
- - **OPENAI_API_KEY** — OpenAI (pago): https://platform.openai.com/api-keys
220
+ ---
157
221
 
158
- ## Como Usar
222
+ ## Escalabilidade
159
223
 
160
- ### 💬 Conversação Natural
224
+ ### Como o mcp-lab-agent escala para empresas
161
225
 
162
- **Você não precisa saber comandos especiais!** Apenas converse naturalmente com o Cursor:
226
+ **1. Multi-projeto:**
227
+ - Cada projeto tem sua própria memória (`.qa-lab-memory.json`)
228
+ - Aprendizados são isolados por contexto
229
+ - Suporte a monorepos (detecta múltiplos frameworks)
163
230
 
164
- ```
165
- "Detecte a estrutura do meu projeto"
166
- "Gere um teste para o fluxo de login"
167
- "Rode os testes"
168
- "Analise as falhas e sugira correções"
169
- "Crie um bug report das falhas"
231
+ **2. CI/CD:**
232
+ ```yaml
233
+ # .github/workflows/qa.yml
234
+ - run: npx mcp-lab-agent auto "smoke tests" --max-retries 2
235
+ - run: npx mcp-lab-agent stats
170
236
  ```
171
237
 
172
- O Cursor **automaticamente** identifica quando usar as ferramentas do MCP. Você não precisa mencionar nomes de ferramentas ou fazer configurações especiais.
238
+ **3. Métricas exportáveis:**
239
+ - `.qa-lab-memory.json` pode ser lido por dashboards
240
+ - `stats` retorna JSON estruturado
241
+ - Integração com Grafana/DataDog via script
173
242
 
174
- ### 🎯 Exemplos Práticos
243
+ **4. Aprendizado compartilhado (roadmap):**
244
+ - Exportar/importar memórias entre projetos
245
+ - Central de aprendizados da empresa
246
+ - Padrões globais + overrides locais
175
247
 
176
- **Começando em um projeto novo:**
177
- ```
178
- Você: "Quais frameworks de teste estão instalados aqui?"
179
- Cursor: [usa detect_project automaticamente]
248
+ **5. Customização:**
249
+ - `qa-lab-flows.json` para fluxos de negócio específicos
250
+ - Variáveis de ambiente para modelos customizados
251
+ - Extensível via MCP tools
180
252
 
181
- Você: "Gere um teste E2E para o cadastro de usuários"
182
- Cursor: [usa generate_tests + write_test]
253
+ ---
183
254
 
184
- Você: "Rode os testes"
185
- Cursor: [usa run_tests]
186
- ```
255
+ ## Configuração
187
256
 
188
- **Analisando falhas:**
189
- ```
190
- Você: "Os testes falharam, me ajude a entender o que aconteceu"
191
- Cursor: [usa analyze_failures + suggest_fix]
257
+ ### Variáveis de ambiente (opcional)
192
258
 
193
- Você: "Crie um relatório dessas falhas"
194
- Cursor: [usa create_bug_report]
195
- ```
259
+ | Variável | Uso |
260
+ |----------|-----|
261
+ | `GROQ_API_KEY` | Groq (gratuito, rápido) |
262
+ | `GEMINI_API_KEY` | Google Gemini |
263
+ | `OPENAI_API_KEY` | OpenAI |
264
+ | `QA_LAB_LLM_SIMPLE` | Modelo para tarefas simples (ex: gemini-1.5-flash) |
265
+ | `QA_LAB_LLM_COMPLEX` | Modelo para tarefas complexas (ex: gpt-4o) |
196
266
 
197
- **Manutenção do projeto:**
198
- ```
199
- Você: "Liste todos os testes de Cypress"
200
- Cursor: [usa list_test_files]
267
+ ### Modo browser (opcional)
201
268
 
202
- Você: "Rode o linter e corrija os problemas"
203
- Cursor: [usa run_linter com auto-fix]
269
+ Para `web_eval_browser`:
204
270
 
205
- Você: "Gere um relatório de cobertura"
206
- Cursor: [usa get_test_coverage]
271
+ ```bash
272
+ npm install playwright
207
273
  ```
208
274
 
209
- ### 🔧 Ferramentas Disponíveis (para referência)
210
-
211
- Você não precisa chamar essas ferramentas diretamente, mas é útil saber o que está disponível:
275
+ ---
212
276
 
213
- | Categoria | Ferramentas |
214
- |-----------|-------------|
215
- | **Detecção** | `detect_project`, `read_project`, `list_test_files` |
216
- | **Execução** | `run_tests`, `watch_tests`, `get_test_coverage` |
217
- | **Geração** | `generate_tests`, `write_test`, `create_test_template` |
218
- | **Análise** | `analyze_failures`, `suggest_fix`, `suggest_selector_fix`, `create_bug_report` |
219
- | **Métricas** | `get_business_metrics` |
220
- | **Manutenção** | `run_linter`, `install_dependencies` |
277
+ ## Documentação
221
278
 
222
- ## Publicar no npm
279
+ - **[PITCH.md](PITCH.md)** Apresentação executiva (use para apresentar ao time)
280
+ - **[EXEMPLO_EVOLUCAO.md](EXEMPLO_EVOLUCAO.md)** — Como a taxa de sucesso melhora com o tempo
281
+ - **[ARQUITETURA_LEARNING.md](ARQUITETURA_LEARNING.md)** — Detalhes técnicos do sistema de learning
282
+ - **[CHANGELOG.md](CHANGELOG.md)** — Histórico de versões
283
+ - **[MIGRATION_V2.md](MIGRATION_V2.md)** — Guia de migração da v1.x
223
284
 
224
- ```bash
225
- npm run build
226
- npm login
227
- npm publish
228
- ```
285
+ Documentação completa (local): `docs/`
229
286
 
230
- Se o nome `mcp-lab-agent` já estiver em uso, use escopo: `@seu-usuario/mcp-lab-agent`.
287
+ ---
231
288
 
232
- ## Desenvolvimento local
289
+ ## Desenvolvimento
233
290
 
234
291
  ```bash
292
+ git clone https://github.com/Wesley-Gomes93/mcp-lab-agent
293
+ cd mcp-lab-agent
235
294
  npm install
236
295
  npm run build
237
- node dist/index.js # testa o servidor
296
+ npm test
238
297
  ```
239
298
 
299
+ | Script | Descrição |
300
+ |--------|-----------|
301
+ | `npm run build` | Build com tsup |
302
+ | `npm test` | Testes (Vitest) |
303
+ | `npm run test:coverage` | Cobertura |
304
+ | `npm run dev` | Build em watch |
305
+
306
+ ---
307
+
240
308
  ## Licença
241
309
 
242
- MIT
310
+ MIT © Wesley Gomes