MCP Feedback Enhanced

Um servidor MCP para feedback interativo do usuário e execução de comandos no desenvolvimento assistido por IA, suportando interfaces Web e Desktop.

GitHub

3.8k

Experimente este MCPPatrocinado

Documentação

MCP Feedback Enhanced

🌐 Idioma / 語言切換: Português | 繁體中文 | 简体中文

Autor Original: Fábio Ferreira | Projeto Original ⭐ Fork Aprimorado: Minidoracat Referência de Design de UI: sanshao85/mcp-feedback-collector

📢 Status de Manutenção (2026-08)

O projeto está sendo mantido novamente. Atualize para v2.6.1 — corrige uma vulnerabilidade de execução de comandos:
uvx mcp-feedback-enhanced@latest
O que mudou na v2.6.1:

🔒 Execução de comandos removida — corrige #219 (WebSocket não autenticado podia executar programas arbitrários). A antiga lista de bloqueio só capturava metacaracteres de shell, mas como a execução usava shell=False, metacaracteres nunca foram o risco — cat, curl, wget, python passavam direto, e o comando automático estava habilitado por padrão. O recurso foi removido definitivamente. Veja SECURITY.md.

🔒 Sequestro de WebSocket entre sites corrigido (relatado em privado como GHSA-cmr5-gpm3-79vf, GHSA-2wx7-r4rh-f663): navegadores não são restringidos pela política de mesma origem ao abrir um WebSocket, então uma página maliciosa podia fazer seu navegador conectar ao /ws local. Origin agora é validado antes de accept(), e tentativas de origens cruzadas são rejeitadas com 403.

🐛 Corrigida a mudança incompatível do Starlette que fazia a interface Web retornar 500 (#213, #217, #221, #228).

🐛 Corrigida a serialização de imagens (#154 e relacionadas) ao mudar para o padrão mcp.types.ImageContent.

Escopo atual de manutenção: problemas de segurança e quebras de compatibilidade que tornam as instalações inutilizáveis (atualizações de dependências, mudanças incompatíveis upstream). Qualquer coisa além disso será decidida a partir do feedback da comunidade — veja a discussão fixada.

Uma coisa que vale a pena dizer claramente: o argumento de venda original era "consolidar múltiplas idas e voltas em uma única solicitação do Cursor para economizar cota". O Cursor mudou para precificação baseada em tokens em junho de 2025, então essa premissa não é mais válida (veja #115, #200). O posicionamento agora é "inserir pontos de verificação humanos em tarefas de longa duração" — não uma ferramenta de economia de cota.

Observe também que o MCP e seus clientes agora suportam nativamente Elicitação (solicitações iniciadas pelo servidor para entrada do usuário) e Aplicativos MCP (ferramentas que retornam UI interativa). Se os recursos nativos atenderem às suas necessidades, use-os — se houver algo que o nativo não possa fazer, por favor, informe na discussão. É isso que decidirá o que será corrigido em seguida.

🎯 Conceito Central

Este é um servidor MCP que estabelece fluxos de trabalho de desenvolvimento orientados a feedback, fornecendo opções de interface dupla Web UI e Aplicativo Desktop, adaptando-se perfeitamente a ambientes locais, SSH Remoto e WSL (Subsistema Windows para Linux). Ao guiar a IA para confirmar com os usuários em vez de fazer operações especulativas, insere pontos de verificação humanos em tarefas de longa duração, reduzindo desvios e retrabalho.

🌐 Vantagens da Arquitetura de Interface Dupla:

🌐 Web UI: Sem dependências de GUI, adequada para ambientes locais, remotos e WSL (a interface principal mantida)
🖥️ Aplicativo Desktop: Um shell Tauri que carrega a mesma Web UI, suportando Windows, macOS, Linux (somente manutenção desde v2.8.0, sem novos recursos, remoção programada para v3 — veja "Status de manutenção do aplicativo desktop" abaixo)
📦 Funcionalidade Unificada: Ambas as interfaces fornecem exatamente a mesma experiência funcional

Plataformas Suportadas: Cursor | Cline | Windsurf | Augment | Trae

🔄 Fluxo de Trabalho

Chamada da IA → ferramenta mcp-feedback-enhanced
Inicialização da Interface → Abre automaticamente o aplicativo desktop ou interface do navegador (com base na configuração)
Interação Inteligente → Seleção de prompt, entrada de texto, upload de imagem, envio automático
Feedback em Tempo Real → Conexão WebSocket entrega informações à IA instantaneamente
Rastreamento de Sessão → Registro automático do histórico e estatísticas da sessão
Continuação do Processo → A IA ajusta o comportamento ou encerra a tarefa com base no feedback

🌟 Recursos Principais

🖥️ Suporte a Interface Dupla

Aplicativo Desktop: Aplicativo nativo multiplataforma baseado em Tauri, suportando Windows, macOS, Linux
Interface Web UI: Interface leve de navegador, adequada para ambientes remotos e WSL
Detecção Automática de Ambiente: Reconhece inteligentemente SSH Remoto, WSL e outros ambientes especiais
Experiência de Recursos Unificada: Ambas as interfaces fornecem exatamente a mesma funcionalidade

📝 Fluxo de Trabalho Inteligente

Gerenciamento de Prompts: Operações CRUD para prompts comuns, estatísticas de uso, ordenação inteligente
Envio Automático com Temporizador: Temporizador flexível de 1 a 86400 segundos, suporta pausar, retomar, cancelar com novos controles de botão de pausa/retomada
Gerenciamento e Rastreamento de Sessão: Armazenamento em arquivos locais, controles de privacidade, exportação de histórico (suporta formatos JSON, CSV, Markdown), estatísticas em tempo real, configurações flexíveis de tempo limite
Monitoramento de Conexão: Monitoramento de status do WebSocket, reconexão automática, indicadores de qualidade
Exibição de Resumo de Trabalho da IA em Markdown: Suporte à renderização de sintaxe Markdown rica, incluindo cabeçalhos, texto em negrito, blocos de código, listas, links e outros formatos para melhorar a legibilidade do conteúdo

🎨 Experiência Moderna

Design Responsivo: Adapta-se a diferentes tamanhos de tela, arquitetura JavaScript modular
Notificações de Áudio: Vários efeitos sonoros integrados, suporte a upload de áudio personalizado, controle de volume
Notificações do Sistema (v2.6.0): Alertas em tempo real em nível de sistema para eventos importantes (como envio automático, tempo limite de sessão)
Memória Inteligente: Memória de altura da caixa de entrada, cópia com um clique, configurações persistentes
Suporte a Múltiplos Idiomas: Chinês Tradicional, Inglês, Chinês Simplificado, troca instantânea

🖼️ Imagens e Mídia

Suporte a Formatos Completos: PNG, JPG, JPEG, GIF, BMP, WebP
Upload Conveniente: Arrastar e soltar arquivos, colar da área de transferência (Ctrl+V)
Processamento Ilimitado: Suporte a imagens de qualquer tamanho, processamento inteligente automático

🌐 Pré-visualização da Interface

Interface Web UI (v2.5.0 - Suporte a Aplicativo Desktop)

Web UI Main Interface - Prompt Management & Auto Submit

📱 Clique para ver capturas de tela completas da interface

Web UI Complete Interface - Session Management & Settings

Interface Web UI - Suporta aplicativo desktop e interface Web, fornecendo gerenciamento de prompts, envio automático, rastreamento de sessão e outros recursos inteligentes

Interface do Aplicativo Desktop (Novo Recurso v2.5.0)

Desktop Application - Native Cross-platform Desktop Experience

Aplicativo Desktop - Aplicativo desktop nativo multiplataforma baseado no framework Tauri, suportando Windows, macOS, Linux com exatamente a mesma funcionalidade da Web UI

Suporte a Atalhos

Ctrl+Enter（Windows/Linux）/ Cmd+Enter（macOS）：Enviar feedback (teclado principal e teclado numérico suportados)
Ctrl+V（Windows/Linux）/ Cmd+V（macOS）：Colar imagens diretamente da área de transferência
Ctrl+I（Windows/Linux）/ Cmd+I（macOS）：Foco rápido na caixa de entrada (Agradecimentos a @penn201500)

🚀 Início Rápido

1. Instalação e Teste

# Install uv (if not already installed)
pip install uv

2. Configurar MCP

Configuração Básica (adequada para a maioria dos usuários):

{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Configuração Avançada (requer ambiente personalizado):

{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DEBUG": "false",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_LANGUAGE": "en"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Configuração do Aplicativo Desktop (novo recurso v2.5.0 - usando aplicativo desktop nativo):

{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

⚠️ Status de manutenção do aplicativo desktop (desde v2.8.0)

O aplicativo desktop está em modo somente manutenção: sem novos recursos (sempre no topo, permanecer residente, manter a janela após o envio), apenas correções de segurança e correções de compatibilidade de "não consegue iniciar"; sua remoção está programada para v3, e as notas de versão nomearão a última versão que ainda inclui os binários desktop. Por quê: é um shell Tauri fino ao redor da Web UI, mas representa ~80% do tamanho do pacote, precisa de CI para três plataformas além de assinatura de código, e a maioria dos problemas relatados são problemas de compatibilidade de plataforma que não podem ser reproduzidos no CI (falsos positivos de antivírus, glibc, Gatekeeper, alta densidade de pixels, múltiplos monitores).

Para continuar usando o modo desktop: altere o args na configuração MCP do seu IDE de mcp-feedback-enhanced@latest para uma versão fixada (ex.: mcp-feedback-enhanced@2.8.0) e mantenha MCP_DESKTOP_MODE=true. Desde 2.8.0, se o shell desktop não conseguir iniciar (colocado em quarentena por antivírus, glibc muito antigo, bloqueado pelo Gatekeeper, sair com erro logo após o início), essa chamada abre automaticamente o navegador e imprime a URL no stderr em vez de esperar silenciosamente até o tempo limite; reiniciar o servidor MCP tenta novamente o shell desktop. Não fixe em 2.6.0 ou anterior (execução de comandos não autenticada, veja SECURITY.md).

Para mudar para o modo web: remova MCP_DESKTOP_MODE. A funcionalidade é idêntica, a aba permanece aberta após o envio e atualiza na próxima chamada. Se você quiser uma janela independente, abra a página de feedback no Chrome/Edge e escolha "Instalar como aplicativo" — mas isso é um recurso do navegador, não um equivalente ao shell desktop: o backend ainda é iniciado pela chamada MCP, uma vez que a janela do aplicativo é fechada, a próxima chamada abre uma aba normal do navegador em vez da janela do aplicativo, o aplicativo deve ser reinstalado se a porta mudar, e a permissão de notificação deve ser concedida novamente; use uma ferramenta de nível de sistema operacional para sempre no topo.

Exemplos de Arquivos de Configuração:

Modo Desktop: examples/mcp-config-desktop.json
Modo Web: examples/mcp-config-web.json

3. Configuração de Engenharia de Prompts

Para obter resultados ideais, adicione as seguintes regras ao seu assistente de IA:

# MCP Interactive Feedback Rules

follow mcp-feedback-enhanced instructions

⚙️ Configurações Avançadas

Variáveis de Ambiente

Variável	Finalidade	Valores	Padrão
`MCP_DEBUG`	Modo de depuração	`true`/`false`	`false`
`MCP_WEB_HOST`	Vinculação de host da Web UI	Endereço IP ou nome de host	`127.0.0.1`
`MCP_WEB_PORT`	Porta da Web UI	`1024-65535`	`8765`
`MCP_DESKTOP_MODE`	Modo do aplicativo desktop	`true`/`false`	`false`
`MCP_LANGUAGE`	Forçar idioma da interface	`zh-TW`/`zh-CN`/`en`	Detecção automática

Explicação do MCP_WEB_HOST:

127.0.0.1 (padrão): Acesso somente local — mantenha esta configuração
0.0.0.0: Vincula todas as interfaces. ⚠️ Não recomendado: a Web UI e o endpoint /ws não têm autenticação, então qualquer pessoa que possa alcançar a porta pode ler o conteúdo da sessão (incluindo caminhos de projeto e resumos da IA) e enviar feedback. Use encaminhamento de porta SSH (veja Problemas Comuns).

Explicação do MCP_LANGUAGE:

Usado para forçar o idioma da interface, substituindo a detecção automática do sistema
Códigos de idioma suportados:
- zh-TW: Chinês Tradicional
- zh-CN: Chinês Simplificado
- en: Inglês
Prioridade de detecção de idioma:
1. Variável de ambiente MCP_LANGUAGE (maior prioridade; quando definida, o seletor de idioma na interface se aplica apenas à sessão atual)
2. Configurações de idioma salvas pelo usuário na interface
3. Variáveis de ambiente do sistema (LANG, LC_ALL, etc.)
4. Idioma padrão do sistema
5. Fallback para o idioma padrão (Chinês Tradicional)

Opções de Teste

# Version check
uvx mcp-feedback-enhanced@latest version       # Check version

# Interface testing
uvx mcp-feedback-enhanced@latest test --web    # Test Web UI (auto continuous running)
uvx mcp-feedback-enhanced@latest test --desktop # Test desktop application (v2.5.0 new feature)

# Debug mode
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test

# Specify language for testing
MCP_LANGUAGE=en uvx mcp-feedback-enhanced@latest test --web    # Force English interface
MCP_LANGUAGE=zh-TW uvx mcp-feedback-enhanced@latest test --web  # Force Traditional Chinese
MCP_LANGUAGE=zh-CN uvx mcp-feedback-enhanced@latest test --web  # Force Simplified Chinese

Instalação para Desenvolvedores

git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
cd mcp-feedback-enhanced
uv sync

Métodos de Teste Local

# Functional testing
make test-func                                           # Standard functional testing
make test-web                                            # Web UI testing (continuous running)
make test-desktop-func                                   # Desktop application functional testing

# Or use direct commands
uv run python -m mcp_feedback_enhanced test              # Standard functional testing
uvx --no-cache --with-editable . mcp-feedback-enhanced test --web   # Web UI testing (continuous running)
uvx --no-cache --with-editable . mcp-feedback-enhanced test --desktop # Desktop application testing

# Desktop application build (v2.5.0 new feature)
make build-desktop                                       # Build desktop application (debug mode)
make build-desktop-release                               # Build desktop application (release mode)
make test-desktop                                        # Test desktop application
make clean-desktop                                       # Clean desktop build artifacts

# Unit testing
make test                                                # Run all unit tests
make test-fast                                          # Fast testing (skip slow tests)
make test-cov                                           # Test and generate coverage report

# Code quality checks
make check                                              # Complete code quality check
make quick-check                                        # Quick check and auto-fix

Descrições de Testes

Teste Funcional: Testar o fluxo completo de funcionalidade das ferramentas MCP
Teste Unitário: Testar a funcionalidade de módulos individuais
Teste de Cobertura: Gerar relatório de cobertura HTML para o diretório htmlcov/
Verificações de Qualidade: Incluir linting, formatação e verificação de tipos

🆕 Histórico de Versões

📋 Histórico Completo de Versões: RELEASE_NOTES/CHANGELOG.en.md

Destaques da Última Versão (v2.6.0)

📊 Recurso de Exportação de Sessão: Suporte para exportar registros de sessão em vários formatos para facilitar o compartilhamento e arquivamento
⏸️ Controle de Auto-commit: Botões de pausar e retomar adicionados para melhor controle sobre o momento do auto-commit
🔔 Notificações do Sistema: Notificações em nível de sistema para eventos importantes com alertas em tempo real
⏱️ Otimização de Tempo Limite de Sessão: Gerenciamento de sessão redesenhado com opções de configuração mais flexíveis
🌏 Aprimoramento de I18n: Arquitetura de internacionalização refatorada com suporte multilíngue completo para notificações
🎨 Simplificação da Interface: Interface do usuário significativamente simplificada para melhorar a experiência do usuário

🐛 Problemas Comuns

🌐 Problemas em Ambientes Remotos SSH

P: O navegador não consegue iniciar ou acessar no ambiente remoto SSH R: Use o encaminhamento de porta SSH (seguro, nada exposto):

Use a configuração padrão (MCP_WEB_HOST: 127.0.0.1)
Configure o encaminhamento de porta SSH:
- VS Code Remote SSH: Pressione Ctrl+Shift+P → "Encaminhar uma Porta" → Digite 8765
- Cursor SSH Remote: Adicione manualmente a regra de encaminhamento de porta (porta 8765)
Abra no navegador local: http://localhost:8765

⚠️ READMEs mais antigos recomendavam MCP_WEB_HOST=0.0.0.0 para expor o serviço diretamente. Não é mais recomendado: a interface web e o endpoint /ws não possuem autenticação, então vincular publicamente permite que qualquer pessoa na rede leia sua sessão e envie feedback.

Para soluções detalhadas, consulte: Guia de Uso em Ambiente Remoto SSH

P: Por que não estou recebendo novos feedbacks do MCP? R: Provavelmente é um problema de conexão WebSocket. Solução: Atualize diretamente a página do navegador.

P: Por que o MCP não está sendo chamado? R: Confirme se o status da ferramenta MCP mostra luz verde. Solução: Alterne repetidamente a ferramenta MCP liga/desliga, aguarde alguns segundos para a reconexão do sistema.

P: O Augment não consegue iniciar o MCP R: Solução: Feche completamente e reinicie o VS Code ou Cursor, reabra o projeto.

🔧 Problemas Gerais

P: Como usar o aplicativo de desktop? R: A v2.5.0 introduz suporte a aplicativos de desktop multiplataforma. Defina "MCP_DESKTOP_MODE": "true" na configuração do MCP para habilitar:

{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_PORT": "8765"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Exemplo de Arquivo de Configuração: examples/mcp-config-desktop.json

P: Como usar a interface GUI legada do PyQt6? R: A v2.4.0 removeu completamente as dependências da GUI PyQt6. Para usar a GUI legada, especifique v2.3.0 ou anterior: uvx mcp-feedback-enhanced@2.3.0 Nota: Versões legadas não incluem novos recursos (gerenciamento de prompts, envio automático, gerenciamento de sessão, aplicativo de desktop, etc.).

P: O erro "Unexpected token 'D'" aparece R: Interferência na saída de depuração. Defina MCP_DEBUG=false ou remova a variável de ambiente.

P: Texto chinês com caracteres corrompidos R: Corrigido na v2.0.3. Atualize para a versão mais recente: uvx mcp-feedback-enhanced@latest

P: A janela desaparece ou ocorrem erros de posicionamento em ambiente multi-monitor R: Corrigido na v2.1.1. Vá para a aba "⚙️ Configurações", marque "Sempre mostrar janela no centro da tela principal" para resolver. Especialmente adequado para arranjos de tela em forma de T e outras configurações complexas de múltiplos monitores.

P: Falha no upload de imagem R: Verifique o formato do arquivo (PNG/JPG/JPEG/GIF/BMP/WebP). O sistema suporta arquivos de imagem de qualquer tamanho.

P: A interface web não inicia R: Verifique as configurações do firewall ou tente usar portas diferentes.

P: O cache UV ocupa muito espaço em disco R: Devido ao uso frequente de comandos uvx, o cache pode acumular dezenas de GB. Recomenda-se limpeza regular:

# View cache size and detailed information
python scripts/cleanup_cache.py --size

# Preview cleanup content (no actual cleanup)
python scripts/cleanup_cache.py --dry-run

# Execute standard cleanup
python scripts/cleanup_cache.py --clean

# Force cleanup (attempts to close related programs, solving Windows file occupation issues)
python scripts/cleanup_cache.py --force

# Or directly use uv command
uv cache clean

Para instruções detalhadas, consulte: Guia de Gerenciamento de Cache

P: Modelos de IA não conseguem analisar imagens R: Vários modelos de IA (incluindo Gemini Pro 2.5, Claude, etc.) podem ter instabilidade na análise de imagens, às vezes reconhecendo corretamente e às vezes não conseguindo analisar o conteúdo da imagem enviada. Esta é uma limitação conhecida da tecnologia de compreensão visual de IA. Recomendações: