mirror of
https://github.com/Minidoracat/mcp-feedback-enhanced.git
synced 2025-07-27 10:42:25 +08:00
📖 更新 README.md，新增繁體中文版本及相關功能介紹，並調整原有內容以提升可讀性。
This commit is contained in:
Minidoracat
parent
cdce55b5d6
commit
4ac9637108
446
README.md
446
README.md
@ -1,101 +1,83 @@
|
|||||||
# Interactive Feedback MCP（互動回饋 MCP）
|
# Interactive Feedback MCP
|
||||||
|
|
||||||
**原作者：** [Fábio Ferreira](https://x.com/fabiomlferreira)
|
**🌐 Language / 語言切換:** **English** | [繁體中文](README.zh-TW.md)
|
||||||
**分支版本：** [Minidoracat](https://github.com/Minidoracat)
|
|
||||||
**UI 設計參考：** [sanshao85/mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector) - 感謝提供現代化界面設計靈感
|
|
||||||
**相關資源：** [dotcursorrules.com](https://dotcursorrules.com/) 提供更多 AI 開發增強工具
|
|
||||||
|
|
||||||
這是一個簡單的 [MCP 伺服器](https://modelcontextprotocol.io/)，用於在 AI 輔助開發工具（如 [Cursor](https://www.cursor.com)）中實現人在回路（human-in-the-loop）的工作流程。該伺服器允許您執行命令、查看輸出並直接向 AI 提供文字回饋和圖片。同時支援 [Cline](https://cline.bot) 和 [Windsurf](https://windsurf.com)。
|
**Original Author:** [Fábio Ferreira](https://x.com/fabiomlferreira)
|
||||||
|
**Enhanced Fork:** [Minidoracat](https://github.com/Minidoracat)
|
||||||
|
**UI Design Reference:** [sanshao85/mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector) - Thanks for modern interface design inspiration
|
||||||
|
**Related Resources:** [dotcursorrules.com](https://dotcursorrules.com/) for more AI development workflow tools
|
||||||
|
|
||||||
## ✨ 新功能特色
|
A simple [MCP server](https://modelcontextprotocol.io/) for implementing human-in-the-loop workflows in AI-assisted development tools (like [Cursor](https://www.cursor.com)). This server allows you to execute commands, view output, and provide text feedback and images directly to the AI. Also supports [Cline](https://cline.bot) and [Windsurf](https://windsurf.com).
|
||||||
|
|
||||||
### 🌐 完整的 SSH Remote 支援
|
## ✨ New Features
|
||||||
- **自動環境檢測**：智能檢測運行環境並選擇適當介面
|
|
||||||
- **本地環境**：使用原有的 Qt GUI 介面
|
|
||||||
- **SSH Remote 環境**：自動切換到現代化 Web UI
|
|
||||||
- **即時通訊**：基於 WebSocket 的即時命令輸出和回饋
|
|
||||||
- **深色主題**：提供現代化的深色主題界面
|
|
||||||
|
|
||||||
### 🖼️ 圖片上傳支援
|
### 🌐 Full SSH Remote Support
|
||||||
- **多格式支援**：PNG、JPG、JPEG、GIF、BMP、WebP
|
- **Automatic Environment Detection**: Intelligently detects runtime environment and selects appropriate interface
|
||||||
- **拖拽上傳**：支援拖拽文件到介面
|
- **Local Environment**: Uses original Qt GUI interface
|
||||||
- **剪貼板支援**：直接從剪貼板粘貼圖片
|
- **SSH Remote Environment**: Automatically switches to modern Web UI
|
||||||
- **自動壓縮**：智能壓縮大圖片以符合 1MB 限制
|
- **Real-time Communication**: WebSocket-based real-time command output and feedback
|
||||||
- **MCP 整合**：圖片自動轉換為 MCP Image 對象
|
- **Dark Theme**: Provides modern dark theme interface
|
||||||
|
|
||||||
### 🛡️ 穩定性改善
|
### 🖼️ Image Upload Support
|
||||||
- **編碼修復**：完全解決中文字符亂碼問題
|
- **Multi-format Support**: PNG, JPG, JPEG, GIF, BMP, WebP
|
||||||
- **調試控制**：可控制的調試輸出，避免 JSON 解析錯誤
|
- **Drag & Drop Upload**: Support for dragging files to interface
|
||||||
- **錯誤處理**：強化錯誤處理，確保程序穩定運行
|
- **Clipboard Support**: Direct paste from clipboard
|
||||||
- **輸出隔離**：嚴格隔離調試輸出與 MCP 通信
|
- **Auto Compression**: Smart compression for large images to meet 1MB limit
|
||||||
|
- **MCP Integration**: Images automatically converted to MCP Image objects
|
||||||
|
|
||||||
## 🖥️ 介面預覽
|
### 🛡️ Stability Improvements
|
||||||
|
- **Encoding Fix**: Complete resolution of Chinese character garbled text issues
|
||||||
|
- **Debug Control**: Controllable debug output, avoiding JSON parsing errors
|
||||||
|
- **Error Handling**: Enhanced error handling ensuring stable program operation
|
||||||
|
- **Output Isolation**: Strict isolation of debug output from MCP communication
|
||||||
|
|
||||||
### Qt GUI 介面（本地環境）
|
## 🖥️ Interface Preview
|
||||||
|
|
||||||
|
### Qt GUI Interface (Local Environment)
|
||||||
|
|
||||||
|
|
||||||
### Web UI 介面（SSH Remote 環境）
|
### Web UI Interface (SSH Remote Environment)
|
||||||
|
|
||||||
|
|
||||||
兩種介面都支援：
|
Both interfaces support:
|
||||||
- 💬 文字回饋輸入
|
- 💬 Text feedback input
|
||||||
- 🖼️ 圖片上傳（支援拖拽、剪貼板粘貼）
|
- 🖼️ Image upload (supports drag & drop, clipboard paste)
|
||||||
- ⚡ 即時命令執行
|
- ⚡ Real-time command execution
|
||||||
- 🎨 現代化深色主題
|
- 🎨 Modern dark theme
|
||||||
- 📱 響應式設計（Web UI）
|
- 📱 Responsive design (Web UI)
|
||||||
|
|
||||||
## 🎯 為什麼使用這個工具？
|
## 🎯 Why Use This Tool?
|
||||||
|
|
||||||
透過引導 AI 助手與用戶進行確認，而非進行推測性的高成本工具調用，此模組可以大幅減少平台（如 Cursor）上的付費請求次數。在某些情況下，它可以將多達 25 次工具調用合併為單次回饋導向的請求，節省資源並提升效能。
|
By guiding AI assistants to confirm with users rather than making speculative high-cost tool calls, this module can significantly reduce the number of paid requests on platforms like Cursor. In some cases, it can consolidate up to 25 tool calls into a single feedback-oriented request, saving resources and improving performance.
|
||||||
|
|
||||||
## 📝 提示工程設定
|
## 📝 Prompt Engineering Setup
|
||||||
|
|
||||||
為了獲得最佳效果，請在您的 AI 助手中添加以下自訂提示（例如在 Cursor 的規則或提示中）：
|
For best results, add the following custom prompts to your AI assistant (e.g., in Cursor's rules or prompts):
|
||||||
|
|
||||||
### 基本提示
|
### Basic Prompt
|
||||||
> 每當你想要詢問問題時，請務必調用 MCP `mcp-feedback-enhanced`。
|
> Whenever you want to ask a question, be sure to call MCP `mcp-feedback-enhanced`.
|
||||||
> 每當你即將完成用戶請求時，請調用 MCP `mcp-feedback-enhanced` 而不是直接結束流程。
|
> Whenever you're about to complete a user request, call MCP `mcp-feedback-enhanced` instead of ending the process directly.
|
||||||
> 持續調用 MCP 直到用戶的回饋為空，然後才結束請求。
|
> Continue calling MCP until the user's feedback is empty, then end the request.
|
||||||
|
|
||||||
### 完整規則範例
|
### Complete Rules Example
|
||||||
```
|
```
|
||||||
# MCP Interactive Feedback 規則
|
# MCP Interactive Feedback Rules
|
||||||
|
|
||||||
1. 在任何流程、任務、對話進行時，無論是詢問、回覆、或完成階段性任務，皆必須呼叫 MCP mcp-feedback-enhanced。
|
1. During any process, task, or conversation, whether asking, responding, or completing stage tasks, must call MCP mcp-feedback-enhanced.
|
||||||
2. 每當收到使用者回饋，若回饋內容非空，必須再次呼叫 MCP mcp-feedback-enhanced，並根據回饋內容調整行為。
|
2. When receiving user feedback, if feedback content is not empty, must call MCP mcp-feedback-enhanced again and adjust behavior based on feedback.
|
||||||
3. 僅當使用者明確表示「結束」或「不再需要互動」時，才可停止呼叫 MCP mcp-feedback-enhanced，流程才算結束。
|
3. Only when user explicitly indicates "end" or "no more interaction needed" can you stop calling MCP mcp-feedback-enhanced, then the process is complete.
|
||||||
4. 除非收到結束指令，否則所有步驟都必須重複呼叫 MCP mcp-feedback-enhanced。
|
4. Unless receiving end command, all steps must repeatedly call MCP mcp-feedback-enhanced.
|
||||||
```
|
```
|
||||||
|
|
||||||
這將確保您的 AI 助手在標記任務完成前使用此 MCP 伺服器請求用戶回饋。
|
This ensures your AI assistant uses this MCP server to request user feedback before marking tasks as complete.
|
||||||
|
|
||||||
## 🔧 環境檢測與配置
|
## 🚀 Installation
|
||||||
|
|
||||||
系統會自動檢測運行環境並選擇適當的介面：
|
### Method 1: uvx Installation (Recommended)
|
||||||
|
|
||||||
### Qt GUI（本地環境）
|
**This is the simplest method, no need to manually manage dependencies or virtual environments:**
|
||||||
- 使用 Qt 的 `QSettings` 按專案基礎儲存配置
|
|
||||||
- 包含命令設定、自動執行選項、視窗幾何狀態等
|
|
||||||
- 設定通常儲存在平台特定位置（Windows 登錄檔、macOS plist 檔案、Linux 配置目錄）
|
|
||||||
|
|
||||||
### Web UI（SSH Remote 環境）
|
1. **Install uv** (if not already installed)
|
||||||
- 基於 FastAPI 和 WebSocket 的現代化界面
|
|
||||||
- 支援即時命令執行和輸出顯示
|
|
||||||
- 自動瀏覽器啟動和會話管理
|
|
||||||
- 深色主題和響應式設計
|
|
||||||
|
|
||||||
### 調試模式控制
|
|
||||||
- **生產模式**：默認關閉所有調試輸出，確保與 MCP 客戶端完美兼容
|
|
||||||
- **調試模式**：設置 `MCP_DEBUG=true` 啟用詳細調試信息
|
|
||||||
- **輸出隔離**：所有調試信息輸出到 stderr，不干擾 MCP 通信
|
|
||||||
|
|
||||||
## 🚀 安裝說明
|
|
||||||
|
|
||||||
### 方法 1：uvx 安裝（推薦）
|
|
||||||
|
|
||||||
**這是最簡單的方法，無需手動管理依賴項或虛擬環境：**
|
|
||||||
|
|
||||||
1. **安裝 uv**（如果尚未安裝）
|
|
||||||
```bash
|
```bash
|
||||||
# Windows
|
# Windows
|
||||||
pip install uv
|
pip install uv
|
||||||
@ -104,52 +86,52 @@
|
|||||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **測試安裝**
|
2. **Test Installation**
|
||||||
```bash
|
```bash
|
||||||
# 查看版本信息（推薦使用 @latest 確保最新版本）
|
# View version info (recommend using @latest for latest version)
|
||||||
uvx mcp-feedback-enhanced@latest version
|
uvx mcp-feedback-enhanced@latest version
|
||||||
|
|
||||||
# 執行測試
|
# Run tests
|
||||||
uvx mcp-feedback-enhanced@latest test
|
uvx mcp-feedback-enhanced@latest test
|
||||||
|
|
||||||
# 持久化測試模式（可在瀏覽器中實際測試）
|
# Persistent test mode (can actually test in browser)
|
||||||
uvx mcp-feedback-enhanced@latest test --persistent
|
uvx mcp-feedback-enhanced@latest test --persistent
|
||||||
```
|
```
|
||||||
|
|
||||||
### 方法 2：從源碼安裝（開發者）
|
### Method 2: Install from Source (Developers)
|
||||||
|
|
||||||
適合需要修改代碼或貢獻開發的用戶：
|
Suitable for users who need to modify code or contribute to development:
|
||||||
|
|
||||||
1. **取得程式碼**
|
1. **Get the Code**
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
|
git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
|
||||||
cd mcp-feedback-enhanced
|
cd mcp-feedback-enhanced
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **安裝依賴項**
|
2. **Install Dependencies**
|
||||||
```bash
|
```bash
|
||||||
uv sync
|
uv sync
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **測試安裝**
|
3. **Test Installation**
|
||||||
```bash
|
```bash
|
||||||
# 基本功能測試
|
# Basic functionality test
|
||||||
uv run python -m mcp_feedback_enhanced test
|
uv run python -m mcp_feedback_enhanced test
|
||||||
|
|
||||||
# 持久化測試模式（可在瀏覽器中實際測試）
|
# Persistent test mode (can actually test in browser)
|
||||||
uv run python -m mcp_feedback_enhanced test --persistent
|
uv run python -m mcp_feedback_enhanced test --persistent
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **運行 MCP 伺服器**
|
4. **Run MCP Server**
|
||||||
```bash
|
```bash
|
||||||
uv run python -m mcp_feedback_enhanced
|
uv run python -m mcp_feedback_enhanced
|
||||||
```
|
```
|
||||||
|
|
||||||
## ⚙️ AI 助手配置
|
## ⚙️ AI Assistant Configuration
|
||||||
|
|
||||||
### 推薦配置（使用 uvx）
|
### Recommended Configuration (using uvx)
|
||||||
|
|
||||||
在 Cursor 的設定中配置自訂 MCP 伺服器，或手動編輯 `mcp.json`：
|
Configure custom MCP server in Cursor settings, or manually edit `mcp.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@ -168,9 +150,9 @@
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 替代配置（從源碼運行）
|
### Alternative Configuration (running from source)
|
||||||
|
|
||||||
如果您需要使用源碼版本或想要自訂環境變數：
|
If you need to use source version or want to customize environment variables:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@ -198,283 +180,83 @@
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**記得將路徑修改為您實際的專案目錄！**
|
**Remember to modify the path to your actual project directory!**
|
||||||
|
|
||||||
### Cline / Windsurf 配置
|
## 🧪 Testing and Development
|
||||||
|
|
||||||
類似的設定原則：在各工具的 MCP 設定中配置伺服器命令，使用 `mcp-feedback-enhanced` 作為伺服器識別符。
|
### Testing with uvx
|
||||||
|
|
||||||
## 🧪 測試和開發
|
|
||||||
|
|
||||||
### 使用 uvx 測試
|
|
||||||
```bash
|
```bash
|
||||||
# 完整功能測試（推薦）
|
# Complete functionality test (recommended)
|
||||||
uvx mcp-feedback-enhanced@latest test
|
uvx mcp-feedback-enhanced@latest test
|
||||||
|
|
||||||
# Qt GUI 專門測試
|
# Qt GUI specific test
|
||||||
uvx mcp-feedback-enhanced@latest test --gui
|
uvx mcp-feedback-enhanced@latest test --gui
|
||||||
|
|
||||||
# Web UI 專門測試
|
# Web UI specific test
|
||||||
uvx mcp-feedback-enhanced@latest test --web
|
uvx mcp-feedback-enhanced@latest test --web
|
||||||
|
|
||||||
# 持久化測試模式（測試完不關閉，可互動測試）
|
# Persistent test mode (doesn't close after test, allows interactive testing)
|
||||||
uvx mcp-feedback-enhanced@latest test --persistent
|
uvx mcp-feedback-enhanced@latest test --persistent
|
||||||
uvx mcp-feedback-enhanced@latest test --gui --persistent
|
|
||||||
uvx mcp-feedback-enhanced@latest test --web --persistent
|
|
||||||
|
|
||||||
# 查看版本
|
# View version
|
||||||
uvx mcp-feedback-enhanced@latest version
|
uvx mcp-feedback-enhanced@latest version
|
||||||
|
|
||||||
# 啟用調試模式測試
|
# Enable debug mode testing
|
||||||
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
||||||
```
|
```
|
||||||
|
|
||||||
### 從源碼測試
|
## 🛠️ Environment Variables
|
||||||
```bash
|
|
||||||
# 完整功能測試
|
|
||||||
uv run python -m mcp_feedback_enhanced test
|
|
||||||
|
|
||||||
# Qt GUI 專門測試
|
### Core Environment Variables
|
||||||
uv run python -m mcp_feedback_enhanced test --gui
|
|
||||||
|
|
||||||
# Web UI 專門測試
|
| Environment Variable | Purpose | Available Values | Default |
|
||||||
uv run python -m mcp_feedback_enhanced test --web
|
|---------------------|---------|------------------|---------|
|
||||||
|
| `FORCE_WEB` | Force use Web UI | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
||||||
|
| `MCP_DEBUG` | Enable debug mode | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
||||||
|
| `INCLUDE_BASE64_DETAIL` | Include full Base64 in image feedback | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
||||||
|
|
||||||
# 持久化測試模式
|
## 🐛 Troubleshooting
|
||||||
uv run python -m mcp_feedback_enhanced test --persistent
|
|
||||||
|
|
||||||
# 啟用調試模式
|
### Common Issues
|
||||||
MCP_DEBUG=true uv run python -m mcp_feedback_enhanced test
|
|
||||||
```
|
|
||||||
|
|
||||||
### 開發模式
|
**Q: Getting "Unexpected token 'D'" error**
|
||||||
使用 FastMCP 開發模式運行伺服器並開啟測試界面：
|
A: This is usually caused by debug output interference. Ensure `MCP_DEBUG=false` is set in production environment or don't set this environment variable.
|
||||||
```bash
|
|
||||||
# 從源碼
|
|
||||||
uv run fastmcp dev src/mcp_feedback_enhanced/server.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### 測試選項說明
|
**Q: Chinese characters display as garbled text**
|
||||||
- **無參數 `test`**：執行完整測試套件（環境檢測、參數驗證、MCP 整合、Web UI）
|
A: Completely fixed in v2.0.3. If still having issues, please update to latest version: `uvx mcp-feedback-enhanced@latest`
|
||||||
- **`--gui`**：專門測試 Qt GUI 功能和介面
|
|
||||||
- **`--web`**：專門測試 Web UI 功能和 WebSocket 通訊
|
|
||||||
- **`--persistent`**：持久化模式，測試完成後保持運行，方便互動測試
|
|
||||||
|
|
||||||
## 🌟 功能特色
|
**Q: Image upload fails**
|
||||||
|
A: Check if image size exceeds 1MB limit and ensure format is supported (PNG, JPG, JPEG, GIF, BMP, WebP).
|
||||||
|
|
||||||
### 🖥️ 雙介面支援
|
**Q: Web UI won't start**
|
||||||
- **Qt GUI**：適用於本地開發環境，提供原生體驗
|
A: Ensure firewall allows local port access, or try setting `FORCE_WEB=true` environment variable.
|
||||||
- **Web UI**：適用於 SSH remote 開發環境，現代化界面
|
|
||||||
|
|
||||||
### 🔍 智慧環境檢測
|
## 🙏 Acknowledgments & Contact
|
||||||
- 自動檢測 SSH 連線環境變數
|
|
||||||
- 檢測 DISPLAY 設定（Linux）
|
|
||||||
- 檢測 VSCode Remote 開發環境
|
|
||||||
- 自動選擇最適合的介面
|
|
||||||
|
|
||||||
### 💻 命令執行功能
|
### Original Author
|
||||||
- 即時命令執行和輸出顯示
|
|
||||||
- 支援命令中斷和程序樹終止
|
|
||||||
- 自動工作目錄設定
|
|
||||||
- 命令歷史記錄
|
|
||||||
|
|
||||||
### 🎨 現代化介面
|
|
||||||
- 深色主題設計
|
|
||||||
- 響應式佈局（支援手機瀏覽器）
|
|
||||||
- WebSocket 即時通訊
|
|
||||||
- 載入動畫和視覺回饋
|
|
||||||
|
|
||||||
### 🖼️ 圖片處理功能
|
|
||||||
- 支援多種圖片格式（PNG、JPG、JPEG、GIF、BMP、WebP）
|
|
||||||
- 智能文件大小檢測和壓縮
|
|
||||||
- 拖拽上傳和剪貼板支援
|
|
||||||
- 自動轉換為 MCP Image 對象
|
|
||||||
- Base64 編碼和預覽
|
|
||||||
|
|
||||||
## 🛠️ 環境變數配置
|
|
||||||
|
|
||||||
### 核心環境變數
|
|
||||||
|
|
||||||
| 環境變數 | 用途 | 可用值 | 默認值 |
|
|
||||||
|---------|------|--------|--------|
|
|
||||||
| `FORCE_WEB` | 強制使用 Web UI | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
|
||||||
| `MCP_DEBUG` | 啟用調試模式 | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
|
||||||
| `INCLUDE_BASE64_DETAIL` | 圖片回饋包含完整 Base64 | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
|
||||||
|
|
||||||
### 使用範例
|
|
||||||
|
|
||||||
**在 MCP 配置中設定**：
|
|
||||||
```json
|
|
||||||
"env": {
|
|
||||||
"FORCE_WEB": "true", // 強制使用 Web UI
|
|
||||||
"MCP_DEBUG": "false", // 關閉調試輸出（推薦生產環境）
|
|
||||||
"INCLUDE_BASE64_DETAIL": "true" // 包含完整圖片 Base64 數據
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**在命令行中設定**：
|
|
||||||
```bash
|
|
||||||
# 啟用調試模式測試
|
|
||||||
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
|
||||||
|
|
||||||
# 強制使用 Web UI
|
|
||||||
FORCE_WEB=true uvx mcp-feedback-enhanced@latest test
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📖 使用範例
|
|
||||||
|
|
||||||
### 1. **推薦 MCP 配置（uvx）**
|
|
||||||
|
|
||||||
使用 uvx 的簡潔配置：
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"mcp-feedback-enhanced": {
|
|
||||||
"command": "uvx",
|
|
||||||
"args": [
|
|
||||||
"mcp-feedback-enhanced@latest"
|
|
||||||
],
|
|
||||||
"timeout": 600,
|
|
||||||
"env": {
|
|
||||||
"MCP_DEBUG": "false"
|
|
||||||
},
|
|
||||||
"autoApprove": [
|
|
||||||
"interactive_feedback"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. **自訂環境變數配置**
|
|
||||||
|
|
||||||
如需要自訂環境變數（例如強制使用 Web UI）：
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"mcp-feedback-enhanced": {
|
|
||||||
"command": "uv",
|
|
||||||
"args": [
|
|
||||||
"--directory",
|
|
||||||
"/path/to/mcp-feedback-enhanced",
|
|
||||||
"run",
|
|
||||||
"python",
|
|
||||||
"-m",
|
|
||||||
"mcp_feedback_enhanced"
|
|
||||||
],
|
|
||||||
"timeout": 600,
|
|
||||||
"env": {
|
|
||||||
"FORCE_WEB": "true",
|
|
||||||
"MCP_DEBUG": "false",
|
|
||||||
"INCLUDE_BASE64_DETAIL": "true"
|
|
||||||
},
|
|
||||||
"autoApprove": [
|
|
||||||
"interactive_feedback"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. **工具調用範例**
|
|
||||||
|
|
||||||
AI 助手會如此調用 `mcp-feedback-enhanced` 工具：
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<use_mcp_tool>
|
|
||||||
<server_name>mcp-feedback-enhanced</server_name>
|
|
||||||
<tool_name>interactive_feedback</tool_name>
|
|
||||||
<arguments>
|
|
||||||
{
|
|
||||||
"project_directory": "/path/to/your/project",
|
|
||||||
"summary": "我已經實現了您請求的更改並重構了主模組。請查看結果並提供回饋。"
|
|
||||||
}
|
|
||||||
</arguments>
|
|
||||||
</use_mcp_tool>
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔄 工作流程
|
|
||||||
|
|
||||||
1. **AI 助手調用** - AI 完成任務後調用 `mcp-feedback-enhanced`
|
|
||||||
2. **環境檢測** - 系統自動檢測運行環境
|
|
||||||
3. **介面啟動** - 根據環境啟動 Qt GUI 或 Web UI
|
|
||||||
4. **用戶互動** - 用戶可以執行命令、查看輸出、提供文字回饋、上傳圖片
|
|
||||||
5. **回饋傳遞** - 用戶回饋（包括圖片）傳回給 AI 助手
|
|
||||||
6. **流程繼續** - AI 根據回饋繼續或結束任務
|
|
||||||
|
|
||||||
## 🆕 版本更新
|
|
||||||
|
|
||||||
### v2.0.3 - 穩定性改善
|
|
||||||
- 🛡️ **完全修復中文字符編碼問題**：支援完美的中文顯示
|
|
||||||
- 🔧 **解決 JSON 解析錯誤**：修復 MCP 客戶端的 "Unexpected token" 錯誤
|
|
||||||
- 🎛️ **可控調試模式**：透過 `MCP_DEBUG` 環境變數控制調試輸出
|
|
||||||
- 🖼️ **強化圖片支援**：改善圖片處理和 Base64 編碼
|
|
||||||
- 🚀 **輸出隔離**：嚴格分離調試輸出與 MCP 通信
|
|
||||||
- 📦 **套件優化**：改善 uvx 安裝體驗和依賴管理
|
|
||||||
|
|
||||||
### v2.0 - Web UI 支援
|
|
||||||
- ✅ 新增 Web UI 介面支援 SSH remote 開發
|
|
||||||
- ✅ 自動環境檢測和介面選擇
|
|
||||||
- ✅ WebSocket 即時通訊
|
|
||||||
- ✅ 現代化深色主題
|
|
||||||
- ✅ 響應式設計支援
|
|
||||||
- ✅ 持久化測試模式
|
|
||||||
|
|
||||||
### v1.0 - 基礎版本（原作者）
|
|
||||||
- ✅ Qt GUI 介面
|
|
||||||
- ✅ 命令執行功能
|
|
||||||
- ✅ MCP 協議支援
|
|
||||||
- ✅ 多平台支援
|
|
||||||
|
|
||||||
## 🐛 故障排除
|
|
||||||
|
|
||||||
### 常見問題
|
|
||||||
|
|
||||||
**Q: 出現 "Unexpected token 'D'" 錯誤**
|
|
||||||
A: 這通常是調試輸出干擾造成的。確保在生產環境中設置 `MCP_DEBUG=false` 或不設置該環境變數。
|
|
||||||
|
|
||||||
**Q: 中文字符顯示為亂碼**
|
|
||||||
A: 已在 v2.0.3 中完全修復。如果仍有問題，請更新到最新版本：`uvx mcp-feedback-enhanced@latest`
|
|
||||||
|
|
||||||
**Q: 圖片上傳失敗**
|
|
||||||
A: 檢查圖片大小是否超過 1MB 限制，並確保格式為支援的類型（PNG、JPG、JPEG、GIF、BMP、WebP）。
|
|
||||||
|
|
||||||
**Q: Web UI 無法啟動**
|
|
||||||
A: 確保防火牆允許本地端口訪問，或嘗試設置 `FORCE_WEB=true` 環境變數。
|
|
||||||
|
|
||||||
### 調試模式
|
|
||||||
|
|
||||||
如需詳細調試信息，請啟用調試模式：
|
|
||||||
```bash
|
|
||||||
# 設置調試環境變數
|
|
||||||
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🙏 致謝與聯繫
|
|
||||||
|
|
||||||
### 原作者
|
|
||||||
**Fábio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira)
|
**Fábio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira)
|
||||||
如果您覺得 Interactive Feedback MCP 有用，最好的支持方式是關注原作者的 X 帳號。
|
If you find Interactive Feedback MCP useful, the best way to support is by following the original author's X account.
|
||||||
|
|
||||||
### UI 設計靈感
|
### UI Design Inspiration
|
||||||
**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)
|
**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)
|
||||||
感謝提供現代化界面設計靈感，讓本專案的 UI 更加美觀和易用。
|
Thanks for providing modern interface design inspiration, making this project's UI more beautiful and user-friendly.
|
||||||
|
|
||||||
### 分支維護者
|
### Fork Maintainer
|
||||||
如有關於 Web UI 功能、圖片支援或其他問題，歡迎在 [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues) 中提出。
|
For questions about Web UI functionality, image support, or other issues, please submit at [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues).
|
||||||
|
|
||||||
### 社群支援
|
### Community Support
|
||||||
加入我們的 Discord 社群獲得即時協助和討論：
|
Join our Discord community for real-time assistance and discussions:
|
||||||
**Discord 社群：** [https://discord.gg/Gur2V67](https://discord.gg/Gur2V67)
|
**Discord Community:** [https://discord.gg/Gur2V67](https://discord.gg/Gur2V67)
|
||||||
有任何問題都可以到社群中尋求幫助！
|
Feel free to ask any questions in the community!
|
||||||
|
|
||||||
### 相關資源
|
### Related Resources
|
||||||
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 官方文件
|
- [dotcursorrules.com](https://dotcursorrules.com/) - More AI-assisted development workflow resources
|
||||||
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation
|
||||||
|
|
||||||
## 📄 授權條款
|
## 📄 License
|
||||||
|
|
||||||
本專案採用 MIT 授權條款。詳見 [LICENSE](LICENSE) 檔案。
|
This project is licensed under the MIT License. See [LICENSE](LICENSE) file for details.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**🌟 歡迎 Star 此專案並分享給更多開發者！**
|
**🌟 Welcome to Star this project and share it with more developers!**
|
||||||
482
README.zh-TW.md
Normal file
482
README.zh-TW.md
Normal file
@ -0,0 +1,482 @@
|
|||||||
|
# Interactive Feedback MCP（互動回饋 MCP）
|
||||||
|
|
||||||
|
**🌐 語言切換 / Language:** [English](README.md) | **繁體中文**
|
||||||
|
|
||||||
|
**原作者：** [Fábio Ferreira](https://x.com/fabiomlferreira)
|
||||||
|
**分支版本：** [Minidoracat](https://github.com/Minidoracat)
|
||||||
|
**UI 設計參考：** [sanshao85/mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector) - 感謝提供現代化界面設計靈感
|
||||||
|
**相關資源：** [dotcursorrules.com](https://dotcursorrules.com/) 提供更多 AI 開發增強工具
|
||||||
|
|
||||||
|
這是一個簡單的 [MCP 伺服器](https://modelcontextprotocol.io/)，用於在 AI 輔助開發工具（如 [Cursor](https://www.cursor.com)）中實現人在回路（human-in-the-loop）的工作流程。該伺服器允許您執行命令、查看輸出並直接向 AI 提供文字回饋和圖片。同時支援 [Cline](https://cline.bot) 和 [Windsurf](https://windsurf.com)。
|
||||||
|
|
||||||
|
## ✨ 新功能特色
|
||||||
|
|
||||||
|
### 🌐 完整的 SSH Remote 支援
|
||||||
|
- **自動環境檢測**：智能檢測運行環境並選擇適當介面
|
||||||
|
- **本地環境**：使用原有的 Qt GUI 介面
|
||||||
|
- **SSH Remote 環境**：自動切換到現代化 Web UI
|
||||||
|
- **即時通訊**：基於 WebSocket 的即時命令輸出和回饋
|
||||||
|
- **深色主題**：提供現代化的深色主題界面
|
||||||
|
|
||||||
|
### 🖼️ 圖片上傳支援
|
||||||
|
- **多格式支援**：PNG、JPG、JPEG、GIF、BMP、WebP
|
||||||
|
- **拖拽上傳**：支援拖拽文件到介面
|
||||||
|
- **剪貼板支援**：直接從剪貼板粘貼圖片
|
||||||
|
- **自動壓縮**：智能壓縮大圖片以符合 1MB 限制
|
||||||
|
- **MCP 整合**：圖片自動轉換為 MCP Image 對象
|
||||||
|
|
||||||
|
### 🛡️ 穩定性改善
|
||||||
|
- **編碼修復**：完全解決中文字符亂碼問題
|
||||||
|
- **調試控制**：可控制的調試輸出，避免 JSON 解析錯誤
|
||||||
|
- **錯誤處理**：強化錯誤處理，確保程序穩定運行
|
||||||
|
- **輸出隔離**：嚴格隔離調試輸出與 MCP 通信
|
||||||
|
|
||||||
|
## 🖥️ 介面預覽
|
||||||
|
|
||||||
|
### Qt GUI 介面（本地環境）
|
||||||
|
|
||||||
|
|
||||||
|
### Web UI 介面（SSH Remote 環境）
|
||||||
|
|
||||||
|
|
||||||
|
兩種介面都支援：
|
||||||
|
- 💬 文字回饋輸入
|
||||||
|
- 🖼️ 圖片上傳（支援拖拽、剪貼板粘貼）
|
||||||
|
- ⚡ 即時命令執行
|
||||||
|
- 🎨 現代化深色主題
|
||||||
|
- 📱 響應式設計（Web UI）
|
||||||
|
|
||||||
|
## 🎯 為什麼使用這個工具？
|
||||||
|
|
||||||
|
透過引導 AI 助手與用戶進行確認，而非進行推測性的高成本工具調用，此模組可以大幅減少平台（如 Cursor）上的付費請求次數。在某些情況下，它可以將多達 25 次工具調用合併為單次回饋導向的請求，節省資源並提升效能。
|
||||||
|
|
||||||
|
## 📝 提示工程設定
|
||||||
|
|
||||||
|
為了獲得最佳效果，請在您的 AI 助手中添加以下自訂提示（例如在 Cursor 的規則或提示中）：
|
||||||
|
|
||||||
|
### 基本提示
|
||||||
|
> 每當你想要詢問問題時，請務必調用 MCP `mcp-feedback-enhanced`。
|
||||||
|
> 每當你即將完成用戶請求時，請調用 MCP `mcp-feedback-enhanced` 而不是直接結束流程。
|
||||||
|
> 持續調用 MCP 直到用戶的回饋為空，然後才結束請求。
|
||||||
|
|
||||||
|
### 完整規則範例
|
||||||
|
```
|
||||||
|
# MCP Interactive Feedback 規則
|
||||||
|
|
||||||
|
1. 在任何流程、任務、對話進行時，無論是詢問、回覆、或完成階段性任務，皆必須呼叫 MCP mcp-feedback-enhanced。
|
||||||
|
2. 每當收到使用者回饋，若回饋內容非空，必須再次呼叫 MCP mcp-feedback-enhanced，並根據回饋內容調整行為。
|
||||||
|
3. 僅當使用者明確表示「結束」或「不再需要互動」時，才可停止呼叫 MCP mcp-feedback-enhanced，流程才算結束。
|
||||||
|
4. 除非收到結束指令，否則所有步驟都必須重複呼叫 MCP mcp-feedback-enhanced。
|
||||||
|
```
|
||||||
|
|
||||||
|
這將確保您的 AI 助手在標記任務完成前使用此 MCP 伺服器請求用戶回饋。
|
||||||
|
|
||||||
|
## 🔧 環境檢測與配置
|
||||||
|
|
||||||
|
系統會自動檢測運行環境並選擇適當的介面：
|
||||||
|
|
||||||
|
### Qt GUI（本地環境）
|
||||||
|
- 使用 Qt 的 `QSettings` 按專案基礎儲存配置
|
||||||
|
- 包含命令設定、自動執行選項、視窗幾何狀態等
|
||||||
|
- 設定通常儲存在平台特定位置（Windows 登錄檔、macOS plist 檔案、Linux 配置目錄）
|
||||||
|
|
||||||
|
### Web UI（SSH Remote 環境）
|
||||||
|
- 基於 FastAPI 和 WebSocket 的現代化界面
|
||||||
|
- 支援即時命令執行和輸出顯示
|
||||||
|
- 自動瀏覽器啟動和會話管理
|
||||||
|
- 深色主題和響應式設計
|
||||||
|
|
||||||
|
### 調試模式控制
|
||||||
|
- **生產模式**：默認關閉所有調試輸出，確保與 MCP 客戶端完美兼容
|
||||||
|
- **調試模式**：設置 `MCP_DEBUG=true` 啟用詳細調試信息
|
||||||
|
- **輸出隔離**：所有調試信息輸出到 stderr，不干擾 MCP 通信
|
||||||
|
|
||||||
|
## 🚀 安裝說明
|
||||||
|
|
||||||
|
### 方法 1：uvx 安裝（推薦）
|
||||||
|
|
||||||
|
**這是最簡單的方法，無需手動管理依賴項或虛擬環境：**
|
||||||
|
|
||||||
|
1. **安裝 uv**（如果尚未安裝）
|
||||||
|
```bash
|
||||||
|
# Windows
|
||||||
|
pip install uv
|
||||||
|
|
||||||
|
# Linux/Mac
|
||||||
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **測試安裝**
|
||||||
|
```bash
|
||||||
|
# 查看版本信息（推薦使用 @latest 確保最新版本）
|
||||||
|
uvx mcp-feedback-enhanced@latest version
|
||||||
|
|
||||||
|
# 執行測試
|
||||||
|
uvx mcp-feedback-enhanced@latest test
|
||||||
|
|
||||||
|
# 持久化測試模式（可在瀏覽器中實際測試）
|
||||||
|
uvx mcp-feedback-enhanced@latest test --persistent
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方法 2：從源碼安裝（開發者）
|
||||||
|
|
||||||
|
適合需要修改代碼或貢獻開發的用戶：
|
||||||
|
|
||||||
|
1. **取得程式碼**
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
|
||||||
|
cd mcp-feedback-enhanced
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **安裝依賴項**
|
||||||
|
```bash
|
||||||
|
uv sync
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **測試安裝**
|
||||||
|
```bash
|
||||||
|
# 基本功能測試
|
||||||
|
uv run python -m mcp_feedback_enhanced test
|
||||||
|
|
||||||
|
# 持久化測試模式（可在瀏覽器中實際測試）
|
||||||
|
uv run python -m mcp_feedback_enhanced test --persistent
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **運行 MCP 伺服器**
|
||||||
|
```bash
|
||||||
|
uv run python -m mcp_feedback_enhanced
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚙️ AI 助手配置
|
||||||
|
|
||||||
|
### 推薦配置（使用 uvx）
|
||||||
|
|
||||||
|
在 Cursor 的設定中配置自訂 MCP 伺服器，或手動編輯 `mcp.json`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"mcp-feedback-enhanced": {
|
||||||
|
"command": "uvx",
|
||||||
|
"args": [
|
||||||
|
"mcp-feedback-enhanced@latest"
|
||||||
|
],
|
||||||
|
"timeout": 600,
|
||||||
|
"autoApprove": [
|
||||||
|
"interactive_feedback"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 替代配置（從源碼運行）
|
||||||
|
|
||||||
|
如果您需要使用源碼版本或想要自訂環境變數：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"mcp-feedback-enhanced": {
|
||||||
|
"command": "uv",
|
||||||
|
"args": [
|
||||||
|
"--directory",
|
||||||
|
"/path/to/mcp-feedback-enhanced",
|
||||||
|
"run",
|
||||||
|
"python",
|
||||||
|
"-m",
|
||||||
|
"mcp_feedback_enhanced"
|
||||||
|
],
|
||||||
|
"timeout": 600,
|
||||||
|
"env": {
|
||||||
|
"FORCE_WEB": "true",
|
||||||
|
"MCP_DEBUG": "false"
|
||||||
|
},
|
||||||
|
"autoApprove": [
|
||||||
|
"interactive_feedback"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**記得將路徑修改為您實際的專案目錄！**
|
||||||
|
|
||||||
|
### Cline / Windsurf 配置
|
||||||
|
|
||||||
|
類似的設定原則：在各工具的 MCP 設定中配置伺服器命令，使用 `mcp-feedback-enhanced` 作為伺服器識別符。
|
||||||
|
|
||||||
|
## 🧪 測試和開發
|
||||||
|
|
||||||
|
### 使用 uvx 測試
|
||||||
|
```bash
|
||||||
|
# 完整功能測試（推薦）
|
||||||
|
uvx mcp-feedback-enhanced@latest test
|
||||||
|
|
||||||
|
# Qt GUI 專門測試
|
||||||
|
uvx mcp-feedback-enhanced@latest test --gui
|
||||||
|
|
||||||
|
# Web UI 專門測試
|
||||||
|
uvx mcp-feedback-enhanced@latest test --web
|
||||||
|
|
||||||
|
# 持久化測試模式（測試完不關閉，可互動測試）
|
||||||
|
uvx mcp-feedback-enhanced@latest test --persistent
|
||||||
|
uvx mcp-feedback-enhanced@latest test --gui --persistent
|
||||||
|
uvx mcp-feedback-enhanced@latest test --web --persistent
|
||||||
|
|
||||||
|
# 查看版本
|
||||||
|
uvx mcp-feedback-enhanced@latest version
|
||||||
|
|
||||||
|
# 啟用調試模式測試
|
||||||
|
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
||||||
|
```
|
||||||
|
|
||||||
|
### 從源碼測試
|
||||||
|
```bash
|
||||||
|
# 完整功能測試
|
||||||
|
uv run python -m mcp_feedback_enhanced test
|
||||||
|
|
||||||
|
# Qt GUI 專門測試
|
||||||
|
uv run python -m mcp_feedback_enhanced test --gui
|
||||||
|
|
||||||
|
# Web UI 專門測試
|
||||||
|
uv run python -m mcp_feedback_enhanced test --web
|
||||||
|
|
||||||
|
# 持久化測試模式
|
||||||
|
uv run python -m mcp_feedback_enhanced test --persistent
|
||||||
|
|
||||||
|
# 啟用調試模式
|
||||||
|
MCP_DEBUG=true uv run python -m mcp_feedback_enhanced test
|
||||||
|
```
|
||||||
|
|
||||||
|
### 開發模式
|
||||||
|
使用 FastMCP 開發模式運行伺服器並開啟測試界面：
|
||||||
|
```bash
|
||||||
|
# 從源碼
|
||||||
|
uv run fastmcp dev src/mcp_feedback_enhanced/server.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### 測試選項說明
|
||||||
|
- **無參數 `test`**：執行完整測試套件（環境檢測、參數驗證、MCP 整合、Web UI）
|
||||||
|
- **`--gui`**：專門測試 Qt GUI 功能和介面
|
||||||
|
- **`--web`**：專門測試 Web UI 功能和 WebSocket 通訊
|
||||||
|
- **`--persistent`**：持久化模式，測試完成後保持運行，方便互動測試
|
||||||
|
|
||||||
|
## 🌟 功能特色
|
||||||
|
|
||||||
|
### 🖥️ 雙介面支援
|
||||||
|
- **Qt GUI**：適用於本地開發環境，提供原生體驗
|
||||||
|
- **Web UI**：適用於 SSH remote 開發環境，現代化界面
|
||||||
|
|
||||||
|
### 🔍 智慧環境檢測
|
||||||
|
- 自動檢測 SSH 連線環境變數
|
||||||
|
- 檢測 DISPLAY 設定（Linux）
|
||||||
|
- 檢測 VSCode Remote 開發環境
|
||||||
|
- 自動選擇最適合的介面
|
||||||
|
|
||||||
|
### 💻 命令執行功能
|
||||||
|
- 即時命令執行和輸出顯示
|
||||||
|
- 支援命令中斷和程序樹終止
|
||||||
|
- 自動工作目錄設定
|
||||||
|
- 命令歷史記錄
|
||||||
|
|
||||||
|
### 🎨 現代化介面
|
||||||
|
- 深色主題設計
|
||||||
|
- 響應式佈局（支援手機瀏覽器）
|
||||||
|
- WebSocket 即時通訊
|
||||||
|
- 載入動畫和視覺回饋
|
||||||
|
|
||||||
|
### 🖼️ 圖片處理功能
|
||||||
|
- 支援多種圖片格式（PNG、JPG、JPEG、GIF、BMP、WebP）
|
||||||
|
- 智能文件大小檢測和壓縮
|
||||||
|
- 拖拽上傳和剪貼板支援
|
||||||
|
- 自動轉換為 MCP Image 對象
|
||||||
|
- Base64 編碼和預覽
|
||||||
|
|
||||||
|
## 🛠️ 環境變數配置
|
||||||
|
|
||||||
|
### 核心環境變數
|
||||||
|
|
||||||
|
| 環境變數 | 用途 | 可用值 | 默認值 |
|
||||||
|
|---------|------|--------|--------|
|
||||||
|
| `FORCE_WEB` | 強制使用 Web UI | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
||||||
|
| `MCP_DEBUG` | 啟用調試模式 | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
||||||
|
| `INCLUDE_BASE64_DETAIL` | 圖片回饋包含完整 Base64 | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` | `false` |
|
||||||
|
|
||||||
|
### 使用範例
|
||||||
|
|
||||||
|
**在 MCP 配置中設定**：
|
||||||
|
```json
|
||||||
|
"env": {
|
||||||
|
"FORCE_WEB": "true", // 強制使用 Web UI
|
||||||
|
"MCP_DEBUG": "false", // 關閉調試輸出（推薦生產環境）
|
||||||
|
"INCLUDE_BASE64_DETAIL": "true" // 包含完整圖片 Base64 數據
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**在命令行中設定**：
|
||||||
|
```bash
|
||||||
|
# 啟用調試模式測試
|
||||||
|
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
||||||
|
|
||||||
|
# 強制使用 Web UI
|
||||||
|
FORCE_WEB=true uvx mcp-feedback-enhanced@latest test
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📖 使用範例
|
||||||
|
|
||||||
|
### 1. **推薦 MCP 配置（uvx）**
|
||||||
|
|
||||||
|
使用 uvx 的簡潔配置：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"mcp-feedback-enhanced": {
|
||||||
|
"command": "uvx",
|
||||||
|
"args": [
|
||||||
|
"mcp-feedback-enhanced@latest"
|
||||||
|
],
|
||||||
|
"timeout": 600,
|
||||||
|
"env": {
|
||||||
|
"MCP_DEBUG": "false"
|
||||||
|
},
|
||||||
|
"autoApprove": [
|
||||||
|
"interactive_feedback"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. **自訂環境變數配置**
|
||||||
|
|
||||||
|
如需要自訂環境變數（例如強制使用 Web UI）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"mcp-feedback-enhanced": {
|
||||||
|
"command": "uv",
|
||||||
|
"args": [
|
||||||
|
"--directory",
|
||||||
|
"/path/to/mcp-feedback-enhanced",
|
||||||
|
"run",
|
||||||
|
"python",
|
||||||
|
"-m",
|
||||||
|
"mcp_feedback_enhanced"
|
||||||
|
],
|
||||||
|
"timeout": 600,
|
||||||
|
"env": {
|
||||||
|
"FORCE_WEB": "true",
|
||||||
|
"MCP_DEBUG": "false",
|
||||||
|
"INCLUDE_BASE64_DETAIL": "true"
|
||||||
|
},
|
||||||
|
"autoApprove": [
|
||||||
|
"interactive_feedback"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. **工具調用範例**
|
||||||
|
|
||||||
|
AI 助手會如此調用 `mcp-feedback-enhanced` 工具：
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<use_mcp_tool>
|
||||||
|
<server_name>mcp-feedback-enhanced</server_name>
|
||||||
|
<tool_name>interactive_feedback</tool_name>
|
||||||
|
<arguments>
|
||||||
|
{
|
||||||
|
"project_directory": "/path/to/your/project",
|
||||||
|
"summary": "我已經實現了您請求的更改並重構了主模組。請查看結果並提供回饋。"
|
||||||
|
}
|
||||||
|
</arguments>
|
||||||
|
</use_mcp_tool>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔄 工作流程
|
||||||
|
|
||||||
|
1. **AI 助手調用** - AI 完成任務後調用 `mcp-feedback-enhanced`
|
||||||
|
2. **環境檢測** - 系統自動檢測運行環境
|
||||||
|
3. **介面啟動** - 根據環境啟動 Qt GUI 或 Web UI
|
||||||
|
4. **用戶互動** - 用戶可以執行命令、查看輸出、提供文字回饋、上傳圖片
|
||||||
|
5. **回饋傳遞** - 用戶回饋（包括圖片）傳回給 AI 助手
|
||||||
|
6. **流程繼續** - AI 根據回饋繼續或結束任務
|
||||||
|
|
||||||
|
## 🆕 版本更新
|
||||||
|
|
||||||
|
### v2.0.3 - 穩定性改善
|
||||||
|
- 🛡️ **完全修復中文字符編碼問題**：支援完美的中文顯示
|
||||||
|
- 🔧 **解決 JSON 解析錯誤**：修復 MCP 客戶端的 "Unexpected token" 錯誤
|
||||||
|
- 🎛️ **可控調試模式**：透過 `MCP_DEBUG` 環境變數控制調試輸出
|
||||||
|
- 🖼️ **強化圖片支援**：改善圖片處理和 Base64 編碼
|
||||||
|
- 🚀 **輸出隔離**：嚴格分離調試輸出與 MCP 通信
|
||||||
|
- 📦 **套件優化**：改善 uvx 安裝體驗和依賴管理
|
||||||
|
|
||||||
|
### v2.0 - Web UI 支援
|
||||||
|
- ✅ 新增 Web UI 介面支援 SSH remote 開發
|
||||||
|
- ✅ 自動環境檢測和介面選擇
|
||||||
|
- ✅ WebSocket 即時通訊
|
||||||
|
- ✅ 現代化深色主題
|
||||||
|
- ✅ 響應式設計支援
|
||||||
|
- ✅ 持久化測試模式
|
||||||
|
|
||||||
|
### v1.0 - 基礎版本（原作者）
|
||||||
|
- ✅ Qt GUI 介面
|
||||||
|
- ✅ 命令執行功能
|
||||||
|
- ✅ MCP 協議支援
|
||||||
|
- ✅ 多平台支援
|
||||||
|
|
||||||
|
## 🐛 故障排除
|
||||||
|
|
||||||
|
### 常見問題
|
||||||
|
|
||||||
|
**Q: 出現 "Unexpected token 'D'" 錯誤**
|
||||||
|
A: 這通常是調試輸出干擾造成的。確保在生產環境中設置 `MCP_DEBUG=false` 或不設置該環境變數。
|
||||||
|
|
||||||
|
**Q: 中文字符顯示為亂碼**
|
||||||
|
A: 已在 v2.0.3 中完全修復。如果仍有問題，請更新到最新版本：`uvx mcp-feedback-enhanced@latest`
|
||||||
|
|
||||||
|
**Q: 圖片上傳失敗**
|
||||||
|
A: 檢查圖片大小是否超過 1MB 限制，並確保格式為支援的類型（PNG、JPG、JPEG、GIF、BMP、WebP）。
|
||||||
|
|
||||||
|
**Q: Web UI 無法啟動**
|
||||||
|
A: 確保防火牆允許本地端口訪問，或嘗試設置 `FORCE_WEB=true` 環境變數。
|
||||||
|
|
||||||
|
### 調試模式
|
||||||
|
|
||||||
|
如需詳細調試信息，請啟用調試模式：
|
||||||
|
```bash
|
||||||
|
# 設置調試環境變數
|
||||||
|
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🙏 致謝與聯繫
|
||||||
|
|
||||||
|
### 原作者
|
||||||
|
**Fábio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira)
|
||||||
|
如果您覺得 Interactive Feedback MCP 有用，最好的支持方式是關注原作者的 X 帳號。
|
||||||
|
|
||||||
|
### UI 設計靈感
|
||||||
|
**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)
|
||||||
|
感謝提供現代化界面設計靈感，讓本專案的 UI 更加美觀和易用。
|
||||||
|
|
||||||
|
### 分支維護者
|
||||||
|
如有關於 Web UI 功能、圖片支援或其他問題，歡迎在 [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues) 中提出。
|
||||||
|
|
||||||
|
### 社群支援
|
||||||
|
加入我們的 Discord 社群獲得即時協助和討論：
|
||||||
|
**Discord 社群：** [https://discord.gg/Gur2V67](https://discord.gg/Gur2V67)
|
||||||
|
有任何問題都可以到社群中尋求幫助！
|
||||||
|
|
||||||
|
### 相關資源
|
||||||
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 官方文件
|
||||||
|
|
||||||
|
## 📄 授權條款
|
||||||
|
|
||||||
|
本專案採用 MIT 授權條款。詳見 [LICENSE](LICENSE) 檔案。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**🌟 歡迎 Star 此專案並分享給更多開發者！**
|
||||||
Loading…
x
Reference in New Issue
Block a user