# MCP UI Research

Servidor MCP via **stdio**, em Python/FastMCP, que ajuda agentes a pesquisar referências de um nicho, extrair padrões visuais, sintetizar componentes HTML/CSS originais e lembrar o que foi pesquisado e entregue.

Ele deliberadamente **não clona código de terceiros**. O servidor coleta sinais agregados — cores, tipografia declarada, estrutura semântica, labels e métricas CSS — e gera componentes novos. Isso reduz riscos autorais, de segurança e de qualidade associados a copiar páginas arbitrárias.

## Ferramentas

- `research_niche`: pesquisa referências, inspeciona páginas, recomenda decisões e devolve componentes.
- `inspect_reference`: analisa uma URL pública específica.
- `remember_delivery`: registra o que o agente implementou.
- `recall_project`: recupera pesquisa, entregas e revisões do SQLite.
- `review_implementation`: avalia HTML com verificações de semântica, responsividade e acessibilidade.

## Instalação e execução

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
mcp-ui-research
```

O protocolo MCP usa stdout; logs e mensagens de aplicação nunca devem ser impressos nele.

## Configuração JSON em clientes MCP

Depois de instalar as dependências, clientes compatíveis com o formato `mcpServers` podem iniciar o servidor diretamente pelo executável criado no ambiente virtual:

```json
{
  "mcpServers": {
    "ui-research": {
      "command": "/caminho/absoluto/MCPUIResearch/.venv/bin/mcp-ui-research",
      "args": [],
      "env": {
        "MCP_UI_DATA_DIR": "/caminho/absoluto/MCPUIResearch/.mcp-ui-research",
        "MCP_UI_HTTP_TIMEOUT": "12"
      }
    }
  }
}
```

Também é possível executar o módulo Python explicitamente. Essa forma é útil quando o cliente exige `command` e `args` separados:

```json
{
  "mcpServers": {
    "ui-research": {
      "command": "/caminho/absoluto/MCPUIResearch/.venv/bin/python",
      "args": ["-m", "mcp_ui_research.server"],
      "env": {
        "MCP_UI_DATA_DIR": "/caminho/absoluto/MCPUIResearch/.mcp-ui-research"
      }
    }
  }
}
```

Use sempre caminhos absolutos. No Windows, aponte `command` para `.venv\\Scripts\\python.exe` e utilize caminhos JSON escapados, como `C:\\Projetos\\MCPUIResearch`.

## Configuração direta no LM Studio

No LM Studio, abra a aba **Program** na barra lateral direita e selecione **Install > Edit mcp.json**. O LM Studio utiliza o formato `mcpServers` compatível com servidores MCP locais via stdio.

Para este repositório, instalado no caminho atual, adicione ao `mcp.json`:

```json
{
  "mcpServers": {
    "ui-research": {
      "command": "/home/wanbnn/Projetos/MCPUIResearch/.venv/bin/python",
      "args": ["-m", "mcp_ui_research.server"],
      "env": {
        "MCP_UI_DATA_DIR": "/home/wanbnn/Projetos/MCPUIResearch/.mcp-ui-research",
        "MCP_UI_HTTP_TIMEOUT": "12"
      }
    }
  }
}
```

Salve o `mcp.json`, ative o servidor `ui-research` na tela de MCPs e selecione um modelo com suporte adequado a tool calling. Se o LM Studio já estava com uma conversa aberta, inicie uma nova conversa para garantir que a lista de ferramentas seja carregada.

Exemplo de solicitação no chat do LM Studio:

```text
Crie uma landing page responsiva em HTML e CSS para uma loja de carros premium.
Antes de implementar, use ui-research para pesquisar o nicho com o project_id
"loja-carros-premium". Aplique os padrões relevantes, registre a entrega e revise
o HTML final usando as ferramentas do MCP.
```

O fluxo esperado de chamadas é:

```text
research_niche → implementação pelo agente → remember_delivery
               → review_implementation → correções finais
```

## Fluxo recomendado ao agente

1. Chame `research_niche(niche, project_id)` antes de desenhar a página.
2. Escolha apenas os padrões coerentes com público, marca e objetivo.
3. Adapte os componentes devolvidos; não trate o código como página completa.
4. Chame `remember_delivery` ao implementar.
5. Envie o HTML final para `review_implementation`, corrija os pontos relevantes e registre novamente.

## Limites e operação responsável

- A busca padrão usa a página HTML do DuckDuckGo e pode sofrer rate limit ou mudança de markup.
- O coletor limita tamanho, tempo e quantidade de conexões e bloqueia destinos locais/privados.
- Sites muito dependentes de JavaScript podem expor poucos sinais sem um navegador headless.
- Respeite termos de uso, `robots.txt`, direitos autorais e marcas antes de uso comercial.
- Resultados da web são dados não confiáveis; o servidor não executa scripts encontrados.

## Testes

```bash
pytest
ruff check .
```