MCP/mcp-feedback-enhanced

Fork 0

mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-07-27 02:22:26 +08:00

Minidoracat 47dbdcd96c 🔥 移除 Qt GUI 支援，更新專案描述及依賴配置

2025-06-10 05:43:49 +08:00

11 KiB

Raw Blame History

MCP Feedback Enhanced（互動回饋 MCP）

🌐 語言切換 / Language: English | 繁體中文 | 简体中文

原作者： Fábio Ferreira | 原始專案 ⭐ 分支版本： Minidoracat UI 設計參考： sanshao85/mcp-feedback-collector

🎯 核心概念

這是一個 MCP 伺服器，建立回饋導向的開發工作流程，完美適配本地、SSH 遠端開發環境與 WSL (Windows Subsystem for Linux) 環境。透過引導 AI 與用戶確認而非進行推測性操作，可將多次工具調用合併為單次回饋導向請求，大幅節省平台成本並提升開發效率。

支援平台： Cursor | Cline | Windsurf | Augment | Trae

🔄 工作流程

AI 調用 → mcp-feedback-enhanced
環境檢測 → 自動選擇合適介面
用戶互動 → 命令執行、文字回饋、圖片上傳
回饋傳遞 → 資訊返回 AI
流程繼續 → 根據回饋調整或結束

🌟 主要功能

🌐 Web UI 介面系統

Web UI：適用於所有環境的現代化界面，全新架構
通用相容性：支援本地、SSH Remote 和 WSL 環境
自動適配：智能環境檢測與最佳配置

🎨 現代化界面設計（v2.1.0）

模組化架構：Web UI 採用模組化設計
集中管理：資料夾結構重新組織，維護更容易
現代化主題：改進的視覺設計和用戶體驗
響應式布局：適應不同螢幕尺寸和視窗大小

🖼️ 圖片支援

格式支援：PNG、JPG、JPEG、GIF、BMP、WebP
上傳方式：拖拽檔案 + 剪貼板粘貼（Ctrl+V）
自動處理：智能壓縮確保符合 1MB 限制

🌏 多語言

三語支援：繁體中文、英文、簡體中文
智能偵測：根據系統語言自動選擇
即時切換：介面內可直接切換語言

✨ WSL 環境支援（v2.2.5）

自動檢測：智能識別 WSL (Windows Subsystem for Linux) 環境
瀏覽器整合：WSL 環境下自動啟動 Windows 瀏覽器
多種啟動方式：支援 cmd.exe、powershell.exe、wslview 等多種瀏覽器啟動方法
無縫體驗：WSL 用戶可直接使用 Web UI，無需額外配置

🌐 SSH Remote 環境支援（v2.3.0 新功能）

智能檢測：自動識別 SSH Remote 環境（Cursor SSH Remote、VS Code Remote SSH 等）
瀏覽器啟動指引：當無法自動啟動瀏覽器時，提供清晰的解決方案
端口轉發支援：完整的端口轉發設定指引和故障排除
MCP 整合優化：改善與 MCP 系統的整合，提供更穩定的連接體驗
詳細文檔：SSH Remote 環境使用指南

🌐 介面預覽

Web UI 介面（現代版）

Web UI 介面 - 現代化架構，適合所有環境

快捷鍵支援

Ctrl+Enter（Windows/Linux）/ Cmd+Enter（macOS）：提交回饋（主鍵盤與數字鍵盤皆支援）
Ctrl+V（Windows/Linux）/ Cmd+V（macOS）：直接粘貼剪貼板圖片

🚀 快速開始

1. 安裝與測試

# 安裝 uv（如果尚未安裝）
pip install uv

# 快速測試
uvx mcp-feedback-enhanced@latest test

2. 配置 MCP

基本配置（適合大多數用戶）：

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

進階配置（需要自訂環境）：

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

3. 設定提示工程

為了獲得最佳效果，請在 AI 助手中添加以下規則：

# MCP Interactive Feedback 規則

1. 在任何流程、任務、對話進行時，無論是詢問、回覆、或完成階段性任務，皆必須呼叫 MCP mcp-feedback-enhanced。
2. 每當收到使用者回饋，若回饋內容非空，必須再次呼叫 MCP mcp-feedback-enhanced，並根據回饋內容調整行為。
3. 僅當使用者明確表示「結束」或「不再需要互動」時，才可停止呼叫 MCP mcp-feedback-enhanced，流程才算結束。
4. 除非收到結束指令，否則所有步驟都必須重複呼叫 MCP mcp-feedback-enhanced。
5. 完成任務前，必須使用 MCP mcp-feedback-enhanced 工具向使用者詢問回饋。

⚙️ 進階設定

環境變數

變數	用途	值	默認
`MCP_DEBUG`	調試模式	`true`/`false`	`false`
`MCP_WEB_PORT`	Web UI 端口	`1024-65535`	`8765`

測試選項

# 版本查詢
uvx mcp-feedback-enhanced@latest version       # 檢查版本

# 介面測試
uvx mcp-feedback-enhanced@latest test --web    # 測試 Web UI (自動持續運行)
uvx mcp-feedback-enhanced@latest test --enhanced # 增強測試套件

# 調試模式
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test

開發者安裝

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

本地測試方式

# 方式一：標準測試（推薦）
uv run python -m mcp_feedback_enhanced test

# 方式二：完整測試套件（macOS 和 windows 通用開發環境）
uvx --with-editable . mcp-feedback-enhanced test

# 方式三：介面測試
uvx --with-editable . mcp-feedback-enhanced test --web    # 測試 Web UI (自動持續運行)
uvx --with-editable . mcp-feedback-enhanced test --enhanced # 增強測試套件

測試說明

標準測試：執行完整的功能檢查，適合日常開發驗證
完整測試：包含所有組件的深度測試，適合發布前驗證
Web UI 測試：啟動 Web 服務器並保持運行，便於完整測試 Web 功能
增強測試：完整的測試套件，包含進階場景

🆕 版本更新記錄

📋 完整版本更新記錄： RELEASE_NOTES/CHANGELOG.zh-TW.md

🐛 常見問題

🌐 SSH Remote 環境問題

Q: SSH Remote 環境下瀏覽器無法啟動 A: 這是正常現象。SSH Remote 環境沒有圖形界面，需要手動在本地瀏覽器開啟。詳細解決方案請參考：SSH Remote 環境使用指南

Q: 為什麼沒有接收到 MCP 新的反饋？ A: 可能是 WebSocket 連接問題。解決方法：直接重新整理瀏覽器頁面。

Q: 為什麼沒有呼叫出 MCP？ A: 請確認 MCP 工具狀態為綠燈。解決方法：反覆開關 MCP 工具，等待幾秒讓系統重新連接。

Q: Augment 無法啟動 MCP A: 解決方法：完全關閉並重新啟動 VS Code 或 Cursor，重新開啟專案。

🔧 一般問題

Q: 出現 "Unexpected token 'D'" 錯誤 A: 調試輸出干擾。設置 MCP_DEBUG=false 或移除該環境變數。

Q: 中文字符亂碼 A: 已在 v2.0.3 修復。更新到最新版本：uvx mcp-feedback-enhanced@latest

Q: 多螢幕環境下視窗消失或定位錯誤 A: 已在 v2.1.1 修復。進入「⚙️ 設定」分頁，勾選「總是在主螢幕中心顯示視窗」即可解決。特別適用於 T 字型螢幕排列等複雜多螢幕配置。

Q: 圖片上傳失敗 A: 檢查檔案大小（≤1MB）和格式（PNG/JPG/GIF/BMP/WebP）。

Q: Web UI 無法啟動 A: 檢查防火牆設定或嘗試使用不同的端口。

Q: UV Cache 佔用過多磁碟空間 A: 由於頻繁使用 uvx 命令，cache 可能會累積到數十 GB。建議定期清理：

# 查看 cache 大小和詳細資訊
python scripts/cleanup_cache.py --size

# 預覽清理內容（不實際清理）
python scripts/cleanup_cache.py --dry-run

# 執行標準清理
python scripts/cleanup_cache.py --clean

# 強制清理（會嘗試關閉相關程序，解決 Windows 檔案佔用問題）
python scripts/cleanup_cache.py --force

# 或直接使用 uv 命令
uv cache clean

詳細說明請參考：Cache 管理指南

Q: AI 模型無法解析圖片 A: 各種 AI 模型（包括 Gemini Pro 2.5、Claude 等）在圖片解析上可能存在不穩定性，表現為有時能正確識別、有時無法解析上傳的圖片內容。這是 AI 視覺理解技術的已知限制。建議：

確保圖片品質良好（高對比度、清晰文字）
多嘗試幾次上傳，通常重試可以成功
如持續無法解析，可嘗試調整圖片大小或格式

🙏 致謝

🌟 支持原作者

Fábio Ferreira - X @fabiomlferreira 原始專案： noopstudios/interactive-feedback-mcp

如果您覺得有用，請：

⭐ 為原專案按星星
📱 關注原作者

設計靈感

sanshao85 - mcp-feedback-collector

貢獻者

penn201500 - GitHub @penn201500

🎯 自動聚焦輸入框功能 (PR #39)

社群支援

Discord： https://discord.gg/Gur2V67
Issues： GitHub Issues

📄 授權

MIT 授權條款 - 詳見 LICENSE 檔案

🌟 歡迎 Star 並分享給更多開發者！

11 KiB Raw Blame History Unescape Escape