┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code                               │
│                             │                                    │
│                             ▼                                    │
│                    ┌────────────────┐                           │
│                    │   MCP Server   │                           │
│                    │   (qa-agent)   │                           │
│                    └───────┬────────┘                           │
│                            │                                     │
│         ┌──────────────────┼──────────────────┐                 │
│         ▼                  ▼                  ▼                 │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│  │   Context   │   │  Playwright │   │    Flow     │           │
│  │   Loader    │   │   Runner    │   │   Manager   │           │
│  │ (docs/*.md) │   │  (browser)  │   │   (yaml)    │           │
│  └─────────────┘   └─────────────┘   └─────────────┘           │
│                            │                                     │
│                            ▼                                     │
│                    ┌─────────────┐                              │
│                    │  Resultados │                              │
│                    │  + Análise  │                              │
│                    └─────────────┘                              │
└─────────────────────────────────────────────────────────────────┘

seu-monorepo/
├── apps/
│   └── frontend/
├── packages/
├── docs/                    # Documentação existente do projeto
│   ├── arquitetura.md
│   ├── fluxos.md
│   └── ...
└── tools/
    └── mcp-qa-agent/        # ← MCP Server aqui
        ├── src/
        │   ├── index.ts
        │   ├── server.ts
        │   ├── tools/
        │   │   ├── index.ts
        │   │   ├── load-context.ts
        │   │   ├── validate-page.ts
        │   │   ├── run-flow.ts
        │   │   └── manage-flows.ts
        │   ├── playwright/
        │   │   ├── browser-manager.ts
        │   │   └── page-analyzer.ts
        │   ├── context/
        │   │   └── docs-parser.ts
        │   └── types/
        │       └── index.ts
        ├── flows/
        │   ├── _template.yaml
        │   ├── login.yaml
        │   └── criar-licitacao.yaml
        ├── screenshots/
        ├── package.json
        ├── tsconfig.json
        └── README.md

# Na raiz do seu monorepo
mkdir -p tools/mcp-qa-agent/{src/{tools,playwright,context,types},flows,screenshots}
cd tools/mcp-qa-agent

npm init -y

npm install @modelcontextprotocol/sdk playwright yaml glob gray-matter zod
npm install -D typescript @types/node tsx

{
  "name": "mcp-qa-agent",
  "version": "1.0.0",
  "description": "MCP Server para QA automatizado com Playwright",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js",
    "postinstall": "npx playwright install chromium"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "glob": "^10.3.10",
    "gray-matter": "^4.0.3",
    "playwright": "^1.40.0",
    "yaml": "^2.3.4",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
    "tsx": "^4.6.2",
    "typescript": "^5.3.2"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// src/types/index.ts

/**
 * Configuração do MCP QA Agent
 */
export interface QAAgentConfig {
  /** Caminho raiz do projeto monorepo */
  projectRoot: string;
  /** Caminho relativo para pasta de docs (padrão: "docs") */
  docsPath: string;
  /** URL base do frontend (padrão: "http://localhost:3000") */
  baseUrl: string;
  /** Caminho para salvar screenshots */
  screenshotsPath: string;
  /** Caminho para os fluxos de teste */
  flowsPath: string;
  /** Executar em modo headless (padrão: false para debug) */
  headless: boolean;
  /** Timeout padrão em ms (padrão: 30000) */
  defaultTimeout: number;
}

/**
 * Contexto do projeto carregado dos docs
 */
export interface ProjectContext {
  /** Nome do projeto */
  name: string;
  /** Descrição geral */
  description: string;
  /** Módulos identificados */
  modules: ProjectModule[];
  /** Entidades/Models do sistema */
  entities: string[];
  /** Rotas do frontend identificadas */
  routes: RouteInfo[];
  /** Arquivos de doc processados */
  docsProcessed: string[];
  /** Timestamp do carregamento */
  loadedAt: Date;
}

export interface ProjectModule {
  name: string;
  description: string;
  features: string[];
  relatedDocs: string[];
}

export interface RouteInfo {
  path: string;
  name: string;
  module?: string;
  requiresAuth: boolean;
}

/**
 * Definição de um fluxo de teste
 */
export interface TestFlow {
  /** Identificador único do fluxo */
  id: string;
  /** Nome legível */
  name: string;
  /** Descrição do que o fluxo testa */
  description: string;
  /** Módulo relacionado */
  module?: string;
  /** Se requer autenticação */
  requiresAuth: boolean;
  /** Role do usuário para o teste */
  userRole?: string;
  /** Credenciais de teste (se requiresAuth) */
  credentials?: {
    email: string;
    password: string;
  };
  /** Pré-condições descritas */
  preconditions: string[];
  /** URL inicial (relativa ao baseUrl) */
  startUrl: string;
  /** Passos do teste */
  steps: TestStep[];
  /** Validações finais */
  validations: string[];
}

export interface TestStep {
  /** Nome descritivo do passo */
  name: string;
  /** Tipo de ação */
  action: TestAction;
  /** Seletor CSS ou data-testid */
  selector?: string;
  /** URL para navegação */
  url?: string;
  /** Valor para input */
  value?: string;
  /** Campos para fill-form */
  fields?: Record<string, string>;
  /** Timeout específico deste step em ms */
  timeout?: number;
  /** Se deve tirar screenshot após este step */
  screenshot?: boolean;
  /** Se o step é opcional (não falha o fluxo se der erro) */
  optional?: boolean;
}

export type TestAction =
  | 'navigate'
  | 'click'
  | 'fill'
  | 'fill-form'
  | 'select'
  | 'check'
  | 'uncheck'
  | 'wait'
  | 'wait-url'
  | 'assert-visible'
  | 'assert-hidden'
  | 'assert-text'
  | 'assert-url'
  | 'screenshot'
  | 'scroll'
  | 'hover'
  | 'press-key';

/**
 * Log capturado do console do navegador
 */
export interface CapturedLog {
  /** Tipo: log, warn, error, info, debug */
  type: 'log' | 'warn' | 'error' | 'info' | 'debug';
  /** Conteúdo da mensagem */
  message: string;
  /** URL onde ocorreu */
  url: string;
  /** Linha e coluna se disponível */
  location?: {
    url: string;
    lineNumber: number;
    columnNumber: number;
  };
  /** Timestamp */
  timestamp: Date;
  /** Stack trace se for erro */
  stack?: string;
}

/**
 * Requisição de rede capturada
 */
export interface CapturedRequest {
  url: string;
  method: string;
  status?: number;
  statusText?: string;
  /** Se a requisição falhou */
  failed: boolean;
  /** Motivo da falha */
  failureText?: string;
  /** Tempo de resposta em ms */
  timing?: number;
  /** Tipo de recurso */
  resourceType: string;
  /** Timestamp */
  timestamp: Date;
}

/**
 * Resultado de um step executado
 */
export interface StepResult {
  /** Nome do step */
  name: string;
  /** Se passou */
  success: boolean;
  /** Tempo de execução em ms */
  duration: number;
  /** Mensagem de erro se falhou */
  error?: string;
  /** Caminho do screenshot se capturado */
  screenshot?: string;
  /** Se foi pulado */
  skipped: boolean;
}

/**
 * Resultado completo de um fluxo de teste
 */
export interface FlowResult {
  /** ID do fluxo */
  flowId: string;
  /** Nome do fluxo */
  flowName: string;
  /** Se passou completamente */
  success: boolean;
  /** Timestamp de início */
  startedAt: Date;
  /** Timestamp de fim */
  finishedAt: Date;
  /** Duração total em ms */
  totalDuration: number;
  /** Resultados de cada step */
  steps: StepResult[];
  /** Total de steps que passaram */
  passedSteps: number;
  /** Total de steps que falharam */
  failedSteps: number;
  /** Total de steps pulados */
  skippedSteps: number;
  /** Logs do console capturados */
  consoleLogs: CapturedLog[];
  /** Erros de console (filtrados) */
  consoleErrors: CapturedLog[];
  /** Warnings de console (filtrados) */
  consoleWarnings: CapturedLog[];
  /** Requisições capturadas */
  networkRequests: CapturedRequest[];
  /** Requisições que falharam */
  failedRequests: CapturedRequest[];
  /** Screenshots capturados */
  screenshots: string[];
  /** URL final */
  finalUrl: string;
  /** Análise automática dos problemas */
  analysis: ProblemAnalysis;
}

/**
 * Análise automática dos problemas encontrados
 */
export interface ProblemAnalysis {
  /** Resumo geral */
  summary: string;
  /** Problemas identificados */
  problems: IdentifiedProblem[];
  /** Sugestões de correção */
  suggestions: string[];
  /** Severidade geral: passed, warning, failed */
  severity: 'passed' | 'warning' | 'failed';
}

export interface IdentifiedProblem {
  /** Tipo do problema */
  type: 'js-error' | 'vue-warning' | 'react-error' | 'network-error' | 'assertion-failed' | 'timeout';
  /** Descrição */
  description: string;
  /** Onde ocorreu */
  location?: string;
  /** Severidade */
  severity: 'low' | 'medium' | 'high' | 'critical';
  /** Possível causa */
  possibleCause?: string;
  /** Sugestão de fix */
  suggestedFix?: string;
}

/**
 * Resultado de validação rápida de página
 */
export interface PageValidationResult {
  url: string;
  /** Se a página carregou sem erros críticos */
  success: boolean;
  /** Título da página */
  pageTitle: string;
  /** Tempo de carregamento em ms */
  loadTime: number;
  /** Erros de console */
  consoleErrors: CapturedLog[];
  /** Warnings de console */
  consoleWarnings: CapturedLog[];
  /** Requisições com falha */
  failedRequests: CapturedRequest[];
  /** Screenshot da página */
  screenshot: string;
  /** Análise */
  analysis: ProblemAnalysis;
}

// src/context/docs-parser.ts

import { glob } from 'glob';
import { readFileSync } from 'fs';
import { join, basename } from 'path';
import matter from 'gray-matter';
import type { ProjectContext, ProjectModule, RouteInfo } from '../types/index.js';

/**
 * Parser de documentação do projeto
 * Lê arquivos .md da pasta docs e extrai informações estruturadas
 */
export class DocsParser {
  private projectRoot: string;
  private docsPath: string;

  constructor(projectRoot: string, docsPath: string = 'docs') {
    this.projectRoot = projectRoot;
    this.docsPath = docsPath;
  }

  /**
   * Carrega e processa toda a documentação do projeto
   */
  async loadProjectContext(): Promise<ProjectContext> {
    const docsFullPath = join(this.projectRoot, this.docsPath);
    const mdFiles = await glob('**/*.md', { cwd: docsFullPath });
    
    const modules: ProjectModule[] = [];
    const entities: Set<string> = new Set();
    const routes: RouteInfo[] = [];
    let projectName = '';
    let projectDescription = '';

    for (const file of mdFiles) {
      const fullPath = join(docsFullPath, file);
      const content = readFileSync(fullPath, 'utf-8');
      const { data: frontmatter, content: markdown } = matter(content);

      // Extrair nome do projeto do README ou doc principal
      if (file.toLowerCase() === 'readme.md' || file.toLowerCase() === 'index.md') {
        projectName = this.extractProjectName(markdown) || frontmatter.title || 'Projeto';
        projectDescription = this.extractDescription(markdown) || frontmatter.description || '';
      }

      // Identificar módulos
      const moduleInfo = this.extractModuleInfo(file, markdown, frontmatter);
      if (moduleInfo) {
        modules.push(moduleInfo);
      }

      // Extrair entidades mencionadas
      const foundEntities = this.extractEntities(markdown);
      foundEntities.forEach(e => entities.add(e));

      // Extrair rotas
      const foundRoutes = this.extractRoutes(markdown);
      routes.push(...foundRoutes);
    }

    return {
      name: projectName,
      description: projectDescription,
      modules: this.deduplicateModules(modules),
      entities: Array.from(entities),
      routes: this.deduplicateRoutes(routes),
      docsProcessed: mdFiles,
      loadedAt: new Date()
    };
  }

  /**
   * Gera um resumo formatado do contexto para o Claude
   */
  formatContextSummary(context: ProjectContext): string {
    let summary = `# Contexto do Projeto: ${context.name}\n\n`;
    
    if (context.description) {
      summary += `## Descrição\n${context.description}\n\n`;
    }

    if (context.modules.length > 0) {
      summary += `## Módulos Identificados (${context.modules.length})\n\n`;
      for (const mod of context.modules) {
        summary += `### ${mod.name}\n`;
        if (mod.description) {
          summary += `${mod.description}\n`;
        }
        if (mod.features.length > 0) {
          summary += `**Features:** ${mod.features.join(', ')}\n`;
        }
        summary += '\n';
      }
    }

    if (context.entities.length > 0) {
      summary += `## Entidades do Sistema\n`;
      summary += context.entities.join(', ') + '\n\n';
    }

    if (context.routes.length > 0) {
      summary += `## Rotas do Frontend (${context.routes.length})\n\n`;
      const authRoutes = context.routes.filter(r => r.requiresAuth);
      const publicRoutes = context.routes.filter(r => !r.requiresAuth);
      
      if (publicRoutes.length > 0) {
        summary += `**Rotas Públicas:**\n`;
        for (const route of publicRoutes) {
          summary += `- \`${route.path}\` - ${route.name}\n`;
        }
        summary += '\n';
      }
      
      if (authRoutes.length > 0) {
        summary += `**Rotas Autenticadas:**\n`;
        for (const route of authRoutes) {
          summary += `- \`${route.path}\` - ${route.name}${route.module ? ` (${route.module})` : ''}\n`;
        }
        summary += '\n';
      }
    }

    summary += `\n---\n`;
    summary += `*Documentos processados: ${context.docsProcessed.length}*\n`;
    summary += `*Carregado em: ${context.loadedAt.toISOString()}*\n`;

    return summary;
  }

  // Métodos auxiliares de extração

  private extractProjectName(markdown: string): string | null {
    const h1Match = markdown.match(/^#\s+(.+)$/m);
    return h1Match ? h1Match[1].trim() : null;
  }

  private extractDescription(markdown: string): string | null {
    // Pega o primeiro parágrafo após o título
    const lines = markdown.split('\n');
    let foundTitle = false;
    let description = '';
    
    for (const line of lines) {
      if (line.startsWith('# ')) {
        foundTitle = true;
        continue;
      }
      if (foundTitle && line.trim() && !line.startsWith('#')) {
        description = line.trim();
        break;
      }
    }
    
    return description || null;
  }

  private extractModuleInfo(
    filename: string, 
    markdown: string, 
    frontmatter: Record<string, any>
  ): ProjectModule | null {
    // Ignora arquivos genéricos
    const genericFiles = ['readme.md', 'index.md', 'changelog.md', 'contributing.md'];
    if (genericFiles.includes(filename.toLowerCase())) {
      return null;
    }

    const name = frontmatter.module || 
                 frontmatter.title || 
                 this.extractProjectName(markdown) ||
                 basename(filename, '.md');

    const features: string[] = [];
    
    // Extrai features de listas após "Features" ou "Funcionalidades"
    const featureSection = markdown.match(/##\s*(Features|Funcionalidades|Recursos)\s*\n([\s\S]*?)(?=\n##|$)/i);
    if (featureSection) {
      const listItems = featureSection[2].match(/^[-*]\s+(.+)$/gm);
      if (listItems) {
        features.push(...listItems.map(item => item.replace(/^[-*]\s+/, '').trim()));
      }
    }

    return {
      name,
      description: frontmatter.description || this.extractDescription(markdown) || '',
      features,
      relatedDocs: [filename]
    };
  }

  private extractEntities(markdown: string): string[] {
    const entities: string[] = [];
    
    // Padrões comuns para identificar entidades
    const patterns = [
      /(?:model|entidade|entity|tabela|table):\s*`?(\w+)`?/gi,
      /##\s*(?:Model|Entidade|Entity):\s*(\w+)/gi,
      /`(\w+)(?:Model|Entity|Table)`/g
    ];

    for (const pattern of patterns) {
      let match;
      while ((match = pattern.exec(markdown)) !== null) {
        entities.push(match[1]);
      }
    }

    // Entidades comuns em sistemas de licitação
    const commonEntities = [
      'Licitacao', 'Licitação', 'Proposta', 'Fornecedor', 
      'Produtor', 'Usuario', 'Usuário', 'Categoria',
      'Item', 'Lance', 'Contrato', 'Documento'
    ];
    
    for (const entity of commonEntities) {
      if (markdown.includes(entity) && !entities.includes(entity)) {
        entities.push(entity);
      }
    }

    return [...new Set(entities)];
  }

  private extractRoutes(markdown: string): RouteInfo[] {
    const routes: RouteInfo[] = [];
    
    // Padrão: /rota/path ou `rota/path`
    const routePatterns = [
      /`(\/[\w\-\/\:\[\]]+)`/g,
      /(?:rota|route|path|url):\s*`?(\/[\w\-\/\:\[\]]+)`?/gi
    ];

    for (const pattern of routePatterns) {
      let match;
      while ((match = pattern.exec(markdown)) !== null) {
        const path = match[1];
        // Ignora rotas de API
        if (path.startsWith('/api/')) continue;
        
        routes.push({
          path,
          name: this.routePathToName(path),
          requiresAuth: this.guessRequiresAuth(path, markdown),
          module: this.guessRouteModule(path)
        });
      }
    }

    return routes;
  }

  private routePathToName(path: string): string {
    return path
      .split('/')
      .filter(Boolean)
      .map(segment => {
        if (segment.startsWith(':') || segment.startsWith('[')) return '';
        return segment.charAt(0).toUpperCase() + segment.slice(1);
      })
      .filter(Boolean)
      .join(' > ') || 'Home';
  }

  private guessRequiresAuth(path: string, markdown: string): boolean {
    const protectedPaths = ['dashboard', 'admin', 'painel', 'minha', 'meu', 'profile', 'configurac'];
    const publicPaths = ['login', 'registro', 'cadastro', 'home', 'sobre', 'contato', 'public'];
    
    const pathLower = path.toLowerCase();
    
    if (publicPaths.some(p => pathLower.includes(p))) return false;
    if (protectedPaths.some(p => pathLower.includes(p))) return true;
    
    // Verifica contexto no markdown
    const pathContext = markdown.substring(
      Math.max(0, markdown.indexOf(path) - 100),
      markdown.indexOf(path) + path.length + 100
    ).toLowerCase();
    
    if (pathContext.includes('autenticad') || pathContext.includes('logado') || pathContext.includes('protected')) {
      return true;
    }
    
    return false;
  }

  private guessRouteModule(path: string): string | undefined {
    const segments = path.split('/').filter(Boolean);
    if (segments.length > 0) {
      const first = segments[0].toLowerCase();
      const moduleMap: Record<string, string> = {
        'licitacoes': 'Licitações',
        'licitacao': 'Licitações',
        'propostas': 'Propostas',
        'proposta': 'Propostas',
        'dashboard': 'Dashboard',
        'admin': 'Administração',
        'config': 'Configurações',
        'relatorios': 'Relatórios',
        'usuarios': 'Usuários'
      };
      return moduleMap[first];
    }
    return undefined;
  }

  private deduplicateModules(modules: ProjectModule[]): ProjectModule[] {
    const map = new Map<string, ProjectModule>();
    for (const mod of modules) {
      const existing = map.get(mod.name);
      if (existing) {
        existing.features = [...new Set([...existing.features, ...mod.features])];
        existing.relatedDocs = [...new Set([...existing.relatedDocs, ...mod.relatedDocs])];
      } else {
        map.set(mod.name, mod);
      }
    }
    return Array.from(map.values());
  }

  private deduplicateRoutes(routes: RouteInfo[]): RouteInfo[] {
    const map = new Map<string, RouteInfo>();
    for (const route of routes) {
      if (!map.has(route.path)) {
        map.set(route.path, route);
      }
    }
    return Array.from(map.values());
  }
}

// src/playwright/browser-manager.ts

import { chromium, Browser, BrowserContext, Page } from 'playwright';
import type { QAAgentConfig } from '../types/index.js';

/**
 * Gerencia a instância do browser Playwright
 * Singleton para reutilização entre testes
 */
export class BrowserManager {
  private static instance: BrowserManager;
  private browser: Browser | null = null;
  private config: QAAgentConfig;

  private constructor(config: QAAgentConfig) {
    this.config = config;
  }

  static getInstance(config: QAAgentConfig): BrowserManager {
    if (!BrowserManager.instance) {
      BrowserManager.instance = new BrowserManager(config);
    }
    return BrowserManager.instance;
  }

  /**
   * Obtém ou cria a instância do browser
   */
  async getBrowser(): Promise<Browser> {
    if (!this.browser || !this.browser.isConnected()) {
      this.browser = await chromium.launch({
        headless: this.config.headless,
        args: [
          '--disable-web-security',
          '--disable-features=IsolateOrigins,site-per-process'
        ]
      });
    }
    return this.browser;
  }

  /**
   * Cria um novo contexto de navegação
   */
  async createContext(): Promise<BrowserContext> {
    const browser = await this.getBrowser();
    return await browser.newContext({
      viewport: { width: 1920, height: 1080 },
      ignoreHTTPSErrors: true,
      locale: 'pt-BR',
      timezoneId: 'America/Sao_Paulo'
    });
  }

  /**
   * Cria um novo contexto com autenticação
   */
  async createAuthenticatedContext(
    loginUrl: string,
    credentials: { email: string; password: string }
  ): Promise<BrowserContext> {
    const context = await this.createContext();
    const page = await context.newPage();
    
    try {
      await page.goto(`${this.config.baseUrl}${loginUrl}`, {
        waitUntil: 'networkidle',
        timeout: this.config.defaultTimeout
      });

      // Tenta diferentes seletores comuns de login
      const emailSelectors = [
        'input[name="email"]',
        'input[type="email"]',
        '#email',
        '[data-testid="email-input"]'
      ];
      
      const passwordSelectors = [
        'input[name="password"]',
        'input[type="password"]',
        '#password',
        '[data-testid="password-input"]'
      ];

      const submitSelectors = [
        'button[type="submit"]',
        '[data-testid="login-button"]',
        'button:has-text("Entrar")',
        'button:has-text("Login")'
      ];

      // Encontra e preenche email
      for (const selector of emailSelectors) {
        const element = await page.$(selector);
        if (element) {
          await element.fill(credentials.email);
          break;
        }
      }

      // Encontra e preenche senha
      for (const selector of passwordSelectors) {
        const element = await page.$(selector);
        if (element) {
          await element.fill(credentials.password);
          break;
        }
      }

      // Clica em submit
      for (const selector of submitSelectors) {
        const element = await page.$(selector);
        if (element) {
          await element.click();
          break;
        }
      }

      // Aguarda navegação após login
      await page.waitForNavigation({
        waitUntil: 'networkidle',
        timeout: this.config.defaultTimeout
      }).catch(() => {
        // Ignora timeout se já navegou
      });

      await page.close();
      return context;
    } catch (error) {
      await context.close();
      throw new Error(`Falha na autenticação: ${error}`);
    }
  }

  /**
   * Fecha o browser
   */
  async close(): Promise<void> {
    if (this.browser) {
      await this.browser.close();
      this.browser = null;
    }
  }
}

// src/playwright/page-analyzer.ts

import { Page, ConsoleMessage, Request, Response } from 'playwright';
import { writeFileSync, mkdirSync, existsSync } from 'fs';
import { join } from 'path';
import type {
  CapturedLog,
  CapturedRequest,
  ProblemAnalysis,
  IdentifiedProblem
} from '../types/index.js';

/**
 * Analisa páginas e captura logs, erros e métricas
 */
export class PageAnalyzer {
  private consoleLogs: CapturedLog[] = [];
  private networkRequests: CapturedRequest[] = [];
  private screenshotsPath: string;
  private screenshotCounter = 0;

  constructor(screenshotsPath: string) {
    this.screenshotsPath = screenshotsPath;
    if (!existsSync(screenshotsPath)) {
      mkdirSync(screenshotsPath, { recursive: true });
    }
  }

  /**
   * Anexa os listeners de captura à página
   */
  attachListeners(page: Page): void {
    // Captura logs do console
    page.on('console', (msg: ConsoleMessage) => {
      this.consoleLogs.push({
        type: this.mapConsoleType(msg.type()),
        message: msg.text(),
        url: page.url(),
        location: msg.location(),
        timestamp: new Date()
      });
    });

    // Captura erros de página (JS errors)
    page.on('pageerror', (error: Error) => {
      this.consoleLogs.push({
        type: 'error',
        message: error.message,
        url: page.url(),
        timestamp: new Date(),
        stack: error.stack
      });
    });

    // Captura requisições
    page.on('requestfinished', async (request: Request) => {
      const response = await request.response();
      const timing = request.timing();
      
      this.networkRequests.push({
        url: request.url(),
        method: request.method(),
        status: response?.status(),
        statusText: response?.statusText(),
        failed: false,
        timing: timing.responseEnd - timing.requestStart,
        resourceType: request.resourceType(),
        timestamp: new Date()
      });
    });

    // Captura requisições que falharam
    page.on('requestfailed', (request: Request) => {
      this.networkRequests.push({
        url: request.url(),
        method: request.method(),
        failed: true,
        failureText: request.failure()?.errorText || 'Unknown error',
        resourceType: request.resourceType(),
        timestamp: new Date()
      });
    });
  }

  /**
   * Tira screenshot e salva
   */
  async takeScreenshot(page: Page, name: string): Promise<string> {
    this.screenshotCounter++;
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const filename = `${this.screenshotCounter.toString().padStart(3, '0')}-${name}-${timestamp}.png`;
    const filepath = join(this.screenshotsPath, filename);
    
    await page.screenshot({
      path: filepath,
      fullPage: false
    });
    
    return filepath;
  }

  /**
   * Retorna logs capturados
   */
  getLogs(): CapturedLog[] {
    return [...this.consoleLogs];
  }

  /**
   * Retorna erros de console
   */
  getErrors(): CapturedLog[] {
    return this.consoleLogs.filter(log => log.type === 'error');
  }

  /**
   * Retorna warnings de console
   */
  getWarnings(): CapturedLog[] {
    return this.consoleLogs.filter(log => log.type === 'warn');
  }

  /**
   * Retorna requisições capturadas
   */
  getRequests(): CapturedRequest[] {
    return [...this.networkRequests];
  }

  /**
   * Retorna requisições que falharam
   */
  getFailedRequests(): CapturedRequest[] {
    return this.networkRequests.filter(req => req.failed || (req.status && req.status >= 400));
  }

  /**
   * Limpa os dados capturados
   */
  clear(): void {
    this.consoleLogs = [];
    this.networkRequests = [];
    this.screenshotCounter = 0;
  }

  /**
   * Analisa os problemas encontrados
   */
  analyzeProblems(): ProblemAnalysis {
    const problems: IdentifiedProblem[] = [];
    const suggestions: string[] = [];
    
    // Analisa erros de console
    for (const error of this.getErrors()) {
      const problem = this.categorizeError(error);
      if (problem) {
        problems.push(problem);
      }
    }

    // Analisa warnings
    for (const warning of this.getWarnings()) {
      const problem = this.categorizeWarning(warning);
      if (problem) {
        problems.push(problem);
      }
    }

    // Analisa requisições com falha
    for (const request of this.getFailedRequests()) {
      problems.push(this.categorizeNetworkError(request));
    }

    // Gera sugestões
    suggestions.push(...this.generateSuggestions(problems));

    // Determina severidade geral
    const hasCritical = problems.some(p => p.severity === 'critical');
    const hasHigh = problems.some(p => p.severity === 'high');
    const hasErrors = this.getErrors().length > 0 || this.getFailedRequests().length > 0;

    let severity: 'passed' | 'warning' | 'failed';
    if (hasCritical || hasHigh || hasErrors) {
      severity = 'failed';
    } else if (problems.length > 0) {
      severity = 'warning';
    } else {
      severity = 'passed';
    }

    return {
      summary: this.generateSummary(problems, severity),
      problems,
      suggestions,
      severity
    };
  }

  // Métodos auxiliares

  private mapConsoleType(type: string): CapturedLog['type'] {
    const map: Record<string, CapturedLog['type']> = {
      'log': 'log',
      'warning': 'warn',
      'error': 'error',
      'info': 'info',
      'debug': 'debug'
    };
    return map[type] || 'log';
  }

  private categorizeError(log: CapturedLog): IdentifiedProblem | null {
    const message = log.message.toLowerCase();

    // Vue warnings/errors
    if (message.includes('[vue warn]') || message.includes('vue')) {
      return {
        type: 'vue-warning',
        description: log.message,
        location: log.location?.url || log.url,
        severity: 'high',
        possibleCause: this.guessVueCause(log.message),
        suggestedFix: this.suggestVueFix(log.message)
      };
    }

    // React errors
    if (message.includes('react') || message.includes('cannot read prop')) {
      return {
        type: 'react-error',
        description: log.message,
        location: log.location?.url || log.url,
        severity: 'high',
        possibleCause: 'Tentativa de acessar propriedade de objeto null/undefined',
        suggestedFix: 'Adicionar verificação de null/undefined ou optional chaining (?.) antes do acesso'
      };
    }

    // Erro JS genérico
    return {
      type: 'js-error',
      description: log.message,
      location: log.location?.url || log.url,
      severity: 'high',
      possibleCause: this.guessJsErrorCause(log.message),
      suggestedFix: this.suggestJsErrorFix(log.message)
    };
  }

  private categorizeWarning(log: CapturedLog): IdentifiedProblem | null {
    const message = log.message.toLowerCase();

    // Vue deprecation ou warning
    if (message.includes('vue') || message.includes('deprecat')) {
      return {
        type: 'vue-warning',
        description: log.message,
        severity: 'medium',
        possibleCause: 'API deprecated ou uso incorreto de feature Vue'
      };
    }

    // Performance warning
    if (message.includes('performance') || message.includes('slow')) {
      return {
        type: 'js-error',
        description: log.message,
        severity: 'low',
        possibleCause: 'Problema de performance detectado pelo browser'
      };
    }

    return null;
  }

  private categorizeNetworkError(request: CapturedRequest): IdentifiedProblem {
    let severity: IdentifiedProblem['severity'] = 'high';
    let possibleCause = '';
    let suggestedFix = '';

    if (request.status === 401) {
      possibleCause = 'Token de autenticação ausente ou expirado';
      suggestedFix = 'Verificar se o token está sendo enviado no header Authorization';
    } else if (request.status === 403) {
      possibleCause = 'Usuário não tem permissão para este recurso';
      suggestedFix = 'Verificar roles/permissions do usuário';
    } else if (request.status === 404) {
      possibleCause = 'Endpoint não existe ou URL incorreta';
      suggestedFix = 'Verificar se a rota está definida no backend e se a URL está correta';
    } else if (request.status === 422) {
      possibleCause = 'Dados enviados inválidos (validação falhou)';
      suggestedFix = 'Verificar o formato dos dados enviados na requisição';
      severity = 'medium';
    } else if (request.status === 500) {
      possibleCause = 'Erro interno no servidor';
      suggestedFix = 'Verificar logs do backend para identificar o erro';
      severity = 'critical';
    } else if (request.failed) {
      if (request.failureText?.includes('CORS')) {
        possibleCause = 'Bloqueio por política CORS';
        suggestedFix = 'Configurar headers CORS no backend para permitir a origem do frontend';
      } else if (request.failureText?.includes('net::ERR')) {
        possibleCause = 'Falha de conexão de rede';
        suggestedFix = 'Verificar se o servidor backend está rodando e acessível';
      }
    }

    return {
      type: 'network-error',
      description: `${request.method} ${request.url} - ${request.status || request.failureText}`,
      severity,
      possibleCause,
      suggestedFix
    };
  }

  private guessVueCause(message: string): string {
    if (message.includes('Invalid prop')) {
      return 'Prop recebendo tipo diferente do esperado';
    }
    if (message.includes('not defined')) {
      return 'Variável ou método não definido no componente';
    }
    if (message.includes('reactive')) {
      return 'Problema com reatividade Vue';
    }
    return 'Erro no componente Vue';
  }

  private suggestVueFix(message: string): string {
    if (message.includes('Invalid prop')) {
      return 'Verificar o tipo da prop no componente pai e adicionar validação ou valor default';
    }
    if (message.includes('not defined')) {
      return 'Declarar a variável/método no setup() ou data()';
    }
    return 'Revisar o código do componente mencionado no erro';
  }

  private guessJsErrorCause(message: string): string {
    if (message.includes('undefined') || message.includes('null')) {
      return 'Tentativa de acessar propriedade de valor null/undefined';
    }
    if (message.includes('not a function')) {
      return 'Tentativa de chamar como função algo que não é função';
    }
    if (message.includes('not defined')) {
      return 'Variável não declarada ou fora do escopo';
    }
    return 'Erro de JavaScript em runtime';
  }

  private suggestJsErrorFix(message: string): string {
    if (message.includes('undefined') || message.includes('null')) {
      return 'Usar optional chaining (?.) ou verificar se o valor existe antes de acessar';
    }
    if (message.includes('not a function')) {
      return 'Verificar se o método existe e está sendo importado corretamente';
    }
    return 'Analisar o stack trace para identificar a linha com problema';
  }

  private generateSuggestions(problems: IdentifiedProblem[]): string[] {
    const suggestions: string[] = [];
    
    const hasNetworkErrors = problems.some(p => p.type === 'network-error');
    const hasJsErrors = problems.some(p => p.type === 'js-error');
    const hasVueWarnings = problems.some(p => p.type === 'vue-warning');

    if (hasNetworkErrors) {
      suggestions.push('Verificar se o backend está rodando e acessível');
      suggestions.push('Conferir se as variáveis de ambiente de API estão configuradas');
    }

    if (hasJsErrors) {
      suggestions.push('Revisar os componentes mencionados nos erros');
      suggestions.push('Adicionar tratamento de erros (try/catch) em operações assíncronas');
    }

    if (hasVueWarnings) {
      suggestions.push('Revisar props e suas tipagens nos componentes afetados');
      suggestions.push('Verificar se todos os dados reativos estão declarados corretamente');
    }

    // Remove sugestões duplicadas dos problemas individuais
    const uniqueSuggestions = [...new Set(suggestions)];
    return uniqueSuggestions;
  }

  private generateSummary(problems: IdentifiedProblem[], severity: 'passed' | 'warning' | 'failed'): string {
    if (severity === 'passed') {
      return 'Nenhum problema detectado. A página está funcionando corretamente.';
    }

    const errorCount = problems.filter(p => p.severity === 'high' || p.severity === 'critical').length;
    const warningCount = problems.filter(p => p.severity === 'medium' || p.severity === 'low').length;

    if (severity === 'failed') {
      return `Encontrados ${errorCount} erro(s) crítico(s) que precisam ser corrigidos${warningCount > 0 ? ` e ${warningCount} warning(s)` : ''}.`;
    }

    return `Encontrados ${warningCount} warning(s) que podem ser melhorados.`;
  }
}

// src/tools/load-context.ts

import { DocsParser } from '../context/docs-parser.js';
import type { QAAgentConfig, ProjectContext } from '../types/index.js';

let cachedContext: ProjectContext | null = null;

/**
 * Carrega o contexto do projeto a partir da documentação
 */
export async function loadProjectContext(config: QAAgentConfig): Promise<{
  success: boolean;
  context?: ProjectContext;
  summary?: string;
  error?: string;
}> {
  try {
    const parser = new DocsParser(config.projectRoot, config.docsPath);
    const context = await parser.loadProjectContext();
    
    // Cache para uso em outras tools
    cachedContext = context;

    const summary = parser.formatContextSummary(context);

    return {
      success: true,
      context,
      summary
    };
  } catch (error) {
    return {
      success: false,
      error: `Erro ao carregar contexto: ${error}`
    };
  }
}

/**
 * Retorna o contexto em cache
 */
export function getCachedContext(): ProjectContext | null {
  return cachedContext;
}

// src/tools/validate-page.ts

import { BrowserManager } from '../playwright/browser-manager.js';
import { PageAnalyzer } from '../playwright/page-analyzer.js';
import type { QAAgentConfig, PageValidationResult } from '../types/index.js';

/**
 * Valida uma página específica - teste rápido sem fluxo
 */
export async function validatePage(
  config: QAAgentConfig,
  url: string,
  options: {
    waitForSelector?: string;
    timeout?: number;
    authenticate?: {
      loginUrl: string;
      email: string;
      password: string;
    };
  } = {}
): Promise<PageValidationResult> {
  const browserManager = BrowserManager.getInstance(config);
  const analyzer = new PageAnalyzer(config.screenshotsPath);
  
  const fullUrl = url.startsWith('http') ? url : `${config.baseUrl}${url}`;
  const timeout = options.timeout || config.defaultTimeout;

  let context;
  
  try {
    // Cria contexto (autenticado ou não)
    if (options.authenticate) {
      context = await browserManager.createAuthenticatedContext(
        options.authenticate.loginUrl,
        {
          email: options.authenticate.email,
          password: options.authenticate.password
        }
      );
    } else {
      context = await browserManager.createContext();
    }

    const page = await context.newPage();
    analyzer.attachListeners(page);

    const startTime = Date.now();
    
    // Navega para a página
    await page.goto(fullUrl, {
      waitUntil: 'networkidle',
      timeout
    });

    // Espera seletor específico se fornecido
    if (options.waitForSelector) {
      await page.waitForSelector(options.waitForSelector, { timeout });
    }

    // Pequena pausa para capturar logs atrasados
    await page.waitForTimeout(1000);

    const loadTime = Date.now() - startTime;
    const pageTitle = await page.title();
    
    // Tira screenshot
    const screenshot = await analyzer.takeScreenshot(page, 'validation');

    // Analisa problemas
    const analysis = analyzer.analyzeProblems();

    await context.close();

    return {
      url: fullUrl,
      success: analysis.severity !== 'failed',
      pageTitle,
      loadTime,
      consoleErrors: analyzer.getErrors(),
      consoleWarnings: analyzer.getWarnings(),
      failedRequests: analyzer.getFailedRequests(),
      screenshot,
      analysis
    };
  } catch (error) {
    if (context) {
      await context.close();
    }
    
    return {
      url: fullUrl,
      success: false,
      pageTitle: '',
      loadTime: 0,
      consoleErrors: [{
        type: 'error',
        message: `Erro ao carregar página: ${error}`,
        url: fullUrl,
        timestamp: new Date()
      }],
      consoleWarnings: [],
      failedRequests: [],
      screenshot: '',
      analysis: {
        summary: `Falha crítica ao carregar a página: ${error}`,
        problems: [{
          type: 'js-error',
          description: `${error}`,
          severity: 'critical'
        }],
        suggestions: ['Verificar se a URL está correta', 'Verificar se o servidor está rodando'],
        severity: 'failed'
      }
    };
  }
}

/**
 * Formata o resultado para exibição
 */
export function formatValidationResult(result: PageValidationResult): string {
  const statusIcon = result.success ? '✅' : '❌';
  
  let output = `${statusIcon} Validação de Página\n\n`;
  output += `**URL:** ${result.url}\n`;
  output += `**Título:** ${result.pageTitle}\n`;
  output += `**Tempo de carregamento:** ${result.loadTime}ms\n\n`;

  if (result.consoleErrors.length > 0) {
    output += `### 🔴 Erros de Console (${result.consoleErrors.length})\n\n`;
    for (const error of result.consoleErrors) {
      output += `- \`${error.message}\`\n`;
      if (error.location) {
        output += `  📍 ${error.location.url}:${error.location.lineNumber}\n`;
      }
    }
    output += '\n';
  }

  if (result.consoleWarnings.length > 0) {
    output += `### 🟡 Warnings (${result.consoleWarnings.length})\n\n`;
    for (const warning of result.consoleWarnings) {
      output += `- \`${warning.message}\`\n`;
    }
    output += '\n';
  }

  if (result.failedRequests.length > 0) {
    output += `### 🔴 Requisições com Falha (${result.failedRequests.length})\n\n`;
    for (const req of result.failedRequests) {
      output += `- \`${req.method} ${req.url}\` → ${req.status || req.failureText}\n`;
    }
    output += '\n';
  }

  output += `### 📋 Análise\n\n`;
  output += `**Severidade:** ${result.analysis.severity}\n`;
  output += `**Resumo:** ${result.analysis.summary}\n\n`;

  if (result.analysis.problems.length > 0) {
    output += `**Problemas Identificados:**\n`;
    for (const problem of result.analysis.problems) {
      output += `- [${problem.severity.toUpperCase()}] ${problem.description}\n`;
      if (problem.possibleCause) {
        output += `  💡 Causa: ${problem.possibleCause}\n`;
      }
      if (problem.suggestedFix) {
        output += `  🔧 Fix: ${problem.suggestedFix}\n`;
      }
    }
    output += '\n';
  }

  if (result.analysis.suggestions.length > 0) {
    output += `**Sugestões Gerais:**\n`;
    for (const suggestion of result.analysis.suggestions) {
      output += `- ${suggestion}\n`;
    }
    output += '\n';
  }

  if (result.screenshot) {
    output += `📸 Screenshot: \`${result.screenshot}\`\n`;
  }

  return output;
}