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

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:

{
  "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:

{
  "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:

{
  "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:

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 é:

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

pytest
ruff check .