MCP Browser Debugger

# Estrutura do Projeto ``` mcp-browser-debugger/ ├── src/ │ ├── index.ts # Ponto de entrada do servidor MCP │ ├── browser.ts # Gerenciamento do Puppeteer e estado do browser │ ├── browserTools.ts # Implementação dos handlers das 15 ferramentas │ ├── tools.ts # Definição das ferramentas MCP (schemas JSON) │ └── types.ts # Interfaces e tipos TypeScript ├── dist/ # Código compilado (gerado pelo build) ├── node_modules/ ├── .gitignore ├── .nvmrc # Versão do Node.js recomendada ├── .prettierrc # Configuração do Prettier ├── eslint.config.js # Configuração do ESLint ├── tsconfig.json # Configuração do TypeScript ├── package.json ├── README.md ├── ARCHITECTURE.md # Este arquivo └── MIGRATION.md # Guia de migração JavaScript → TypeScript ``` ## 📋 Requisitos - **Node.js >= 18.0.0** (recomendado: 18.x ou superior) - npm ou yarn ## 🏗️ Arquitetura ### Módulos Principais #### **src/index.ts** (135 linhas) Servidor MCP principal que: - Inicializa o servidor MCP com StdioServerTransport - Registra handlers para `ListToolsRequestSchema` e `CallToolRequestSchema` - Roteia requisições de ferramentas para os handlers apropriados em `browserTools.ts` - Gerencia tratamento de erros e cleanup (SIGINT handler) - **Responsabilidade**: Orquestração e roteamento, não implementação #### **src/browser.ts** (95 linhas) Gerenciamento do Puppeteer que: - Mantém uma instância global do browser e página (`browserState`) - Configura listeners para console logs e requisições de rede - Fornece funções helper: `initBrowser()`, `closeBrowser()`, `clearConsoleLogs()`, `clearNetworkRequests()` - **Responsabilidade**: Estado e lifecycle do browser #### **src/browserTools.ts** (622 linhas) Implementação dos handlers das ferramentas que: - Exporta 15 funções handler individuais (uma para cada ferramenta MCP) - Cada handler recebe `args` e opcionalmente `currentPage: Page` - Implementa toda a lógica de negócio das ferramentas - Retorna objetos `ToolResponse` compatíveis com MCP SDK - **Responsabilidade**: Lógica de negócio das ferramentas **Handlers disponíveis**: - `handleNavigate` - Navegação de URLs - `handleGetDom` - Extração do DOM - `handleGetElement` - Inspeção de elementos - `handleExecuteJs` - Execução de JavaScript - `handleScreenshot` - Captura de tela - `handleGetConsoleLogs` - Logs do console - `handleGetNetworkActivity` - Atividade de rede - `handleGetPageSource` - Código fonte completo - `handleQuerySelectorAll` - Busca múltipla de elementos - `handleGetPageInfo` - Informações da página - `handleClickElement` - Interação com cliques - `handleTypeText` - Digitação de texto - `handleGetLocalStorage` - Dados do localStorage - `handleGetCookies` - Cookies da página - `handleEvaluateXPath` - Queries XPath #### **src/tools.ts** (380 linhas) Definições das 15 ferramentas MCP com schemas JSON: - Array exportado com objetos de definição de ferramentas - Cada ferramenta possui: `name`, `description`, `inputSchema` (JSON Schema) - **Responsabilidade**: Contrato da API (schemas) #### **src/types.ts** (130 linhas) Interfaces TypeScript para type safety completo: - `BrowserState` - Estado global do Puppeteer - `ConsoleLog`, `NetworkRequest` - Tipos de monitoramento - Interfaces de argumentos para cada ferramenta (`NavigateArgs`, `GetDomArgs`, etc.) - Tipos de resposta (`ElementInfo`, `PageInfo`, `PageSource`, etc.) - **Responsabilidade**: Type safety e contratos de dados ## 💡 Desenvolvimento ### Padrões de Código - **TypeScript strict mode** habilitado - **ESLint** para qualidade de código - **Prettier** para formatação consistente - **Type safety** em todas as funções ### Adicionando Nova Ferramenta 1. **Defina os tipos** em `src/types.ts`: ```typescript export interface MinhaFerramentaArgs { parametro: string; opcional?: boolean; } ``` 2. **Adicione o schema JSON** em `src/tools.ts`: ```typescript { name: 'minha_ferramenta', description: 'Descrição da ferramenta', inputSchema: { type: 'object', properties: { parametro: { type: 'string', description: 'Descrição' }, opcional: { type: 'boolean', description: 'Opcional' }, }, required: ['parametro'], }, } ``` 3. **Implemente o handler** em `src/browserTools.ts`: ```typescript export async function handleMinhaFerramenta( args: unknown, currentPage: Page ): Promise<ToolResponse> { const typedArgs = args as unknown as MinhaFerramentaArgs; const { parametro, opcional = false } = typedArgs; // Implementação... return { content: [{ type: 'text', text: JSON.stringify(resultado, null, 2) }], }; } ``` 4. **Adicione ao roteador** em `src/index.ts`: ```typescript // No import import { handleMinhaFerramenta } from './browserTools.js'; // No switch case 'minha_ferramenta': return await handleMinhaFerramenta(args, currentPage); ``` 5. **Compile e teste**: ```bash npm run build npm start ``` ### Testando Localmente ```bash # Modo desenvolvimento (recompila automaticamente) npm run dev # Build e execução npm run build npm start # Formatação de código npm run format # Verificação de tipos npm run build ``` ## 🎯 Fluxo de Requisição ``` Cliente MCP ↓ [StdioServerTransport] ↓ src/index.ts (Servidor MCP) ↓ [CallToolRequestSchema handler] ↓ [Switch/Case por nome da ferramenta] ↓ src/browserTools.ts (Handler específico) ↓ [Acessa src/browser.ts para Puppeteer] ↓ [Retorna ToolResponse] ↓ Cliente MCP recebe resultado ``` ## 📊 Separação de Responsabilidades | Arquivo | Responsabilidade | Linhas | Exporta | | ----------------- | ---------------------- | ------ | ------------------------------------------------------- | | `index.ts` | Orquestração MCP | 135 | Nada (executa servidor) | | `browser.ts` | Estado Puppeteer | 95 | `browserState`, `initBrowser()`, `closeBrowser()`, etc. | | `browserTools.ts` | Lógica das ferramentas | 622 | 15 funções `handle*()` | | `tools.ts` | Schemas JSON | 380 | Array `tools` | | `types.ts` | Contratos TypeScript | 130 | Interfaces e tipos | ## 🔧 Configurações - **TypeScript**: Strict mode, ES2022 target, ESNext modules, DOM lib - **ESLint**: typescript-eslint com regras recomendadas - **Prettier**: Single quotes, 100 char width, 2 spaces, semicolons - **Node**: Engine >= 18.0.0 (funciona em 16.x mas lint requer 18+)