mirror of
https://github.com/Minidoracat/mcp-feedback-enhanced.git
synced 2025-07-27 10:42:25 +08:00
📄 更新 README.md，新增 Web UI 支援及環境檢測說明，強調 SSH 遠端開發的使用情境與安裝步驟，並整合命令執行功能與即時回饋收集。
This commit is contained in:
Minidoracat
parent
f93a6f9d87
commit
3af277adff
218
README.md
218
README.md
@ -1,61 +1,93 @@
|
||||
# Interactive Feedback MCP
|
||||
# Interactive Feedback MCP（互動回饋 MCP）
|
||||
|
||||
Developed by Fábio Ferreira ([@fabiomlferreira](https://x.com/fabiomlferreira)).
|
||||
Check out [dotcursorrules.com](https://dotcursorrules.com/) for more AI development enhancements.
|
||||
**原作者：** [Fábio Ferreira](https://x.com/fabiomlferreira)
|
||||
**分支版本：** [Minidoracat](https://github.com/Minidoracat)
|
||||
**相關資源：** [dotcursorrules.com](https://dotcursorrules.com/) 提供更多 AI 開發增強工具
|
||||
|
||||
Simple [MCP Server](https://modelcontextprotocol.io/) to enable a human-in-the-loop workflow in AI-assisted development tools like [Cursor](https://www.cursor.com). This server allows you to run commands, view their output, and provide textual feedback directly to the AI. It is also compatible with [Cline](https://cline.bot) and [Windsurf](https://windsurf.com).
|
||||
這是一個簡單的 [MCP 伺服器](https://modelcontextprotocol.io/)，用於在 AI 輔助開發工具（如 [Cursor](https://www.cursor.com)）中實現人在回路（human-in-the-loop）的工作流程。該伺服器允許您執行命令、查看輸出並直接向 AI 提供文字回饋。同時支援 [Cline](https://cline.bot) 和 [Windsurf](https://windsurf.com)。
|
||||
|
||||
|
||||
|
||||
## ✨ 新功能：Web UI 支援
|
||||
|
||||
## Prompt Engineering
|
||||
**🌐 支援 SSH Remote 開發環境**
|
||||
此分支版本新增了 Web UI 功能，完美解決了 SSH remote 開發環境中無法使用 GUI 的問題：
|
||||
|
||||
For the best results, add the following to your custom prompt in your AI assistant, you should add it on a rule or directly in the prompt (e.g., Cursor):
|
||||
- **自動環境檢測**：系統會自動檢測運行環境
|
||||
- **本地環境**：使用原有的 Qt GUI 介面
|
||||
- **SSH Remote 環境**：自動切換到現代化 Web UI
|
||||
- **即時通訊**：基於 WebSocket 的即時命令輸出和回饋
|
||||
- **深色主題**：提供現代化的深色主題界面
|
||||
|
||||
> Whenever you want to ask a question, always call the MCP `interactive_feedback`.
|
||||
> Whenever you’re about to complete a user request, call the MCP `interactive_feedback` instead of simply ending the process.
|
||||
> Keep calling MCP until the user’s feedback is empty, then end the request.
|
||||
|
||||
|
||||
This will ensure your AI assistant uses this MCP server to request user feedback before marking the task as completed.
|
||||
## 🎯 為什麼使用這個工具？
|
||||
|
||||
## 💡 Why Use This?
|
||||
By guiding the assistant to check in with the user instead of branching out into speculative, high-cost tool calls, this module can drastically reduce the number of premium requests (e.g., OpenAI tool invocations) on platforms like Cursor. In some cases, it helps consolidate what would be up to 25 tool calls into a single, feedback-aware request — saving resources and improving performance.
|
||||
透過引導 AI 助手與用戶進行確認，而非進行推測性的高成本工具調用，此模組可以大幅減少平台（如 Cursor）上的付費請求次數。在某些情況下，它可以將多達 25 次工具調用合併為單次回饋導向的請求，節省資源並提升效能。
|
||||
|
||||
## Configuration
|
||||
## 📝 提示工程設定
|
||||
|
||||
This MCP server uses Qt's `QSettings` to store configuration on a per-project basis. This includes:
|
||||
* The command to run.
|
||||
* Whether to execute the command automatically on the next startup for that project (see "Execute automatically on next run" checkbox).
|
||||
* The visibility state (shown/hidden) of the command section (this is saved immediately when toggled).
|
||||
* Window geometry and state (general UI preferences).
|
||||
為了獲得最佳效果，請在您的 AI 助手中添加以下自訂提示（例如在 Cursor 的規則或提示中）：
|
||||
|
||||
These settings are typically stored in platform-specific locations (e.g., registry on Windows, plist files on macOS, configuration files in `~/.config` or `~/.local/share` on Linux) under an organization name "FabioFerreira" and application name "InteractiveFeedbackMCP", with a unique group for each project directory.
|
||||
> 每當你想要詢問問題時，請務必調用 MCP `interactive_feedback`。
|
||||
> 每當你即將完成用戶請求時，請調用 MCP `interactive_feedback` 而不是直接結束流程。
|
||||
> 持續調用 MCP 直到用戶的回饋為空，然後才結束請求。
|
||||
|
||||
The "Save Configuration" button in the UI primarily saves the current command typed into the command input field and the state of the "Execute automatically on next run" checkbox for the active project. The visibility of the command section is saved automatically when you toggle it. General window size and position are saved when the application closes.
|
||||
這將確保您的 AI 助手在標記任務完成前使用此 MCP 伺服器請求用戶回饋。
|
||||
|
||||
## Installation (Cursor)
|
||||
## 🔧 環境檢測與配置
|
||||
|
||||
|
||||
系統會自動檢測運行環境並選擇適當的介面：
|
||||
|
||||
1. **Prerequisites:**
|
||||
* Python 3.11 or newer.
|
||||
* [uv](https://github.com/astral-sh/uv) (Python package manager). Install it with:
|
||||
* Windows: `pip install uv`
|
||||
* Linux/Mac: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
||||
2. **Get the code:**
|
||||
* Clone this repository:
|
||||
`git clone https://github.com/noopstudios/interactive-feedback-mcp.git`
|
||||
* Or download the source code.
|
||||
3. **Navigate to the directory:**
|
||||
* `cd path/to/interactive-feedback-mcp`
|
||||
4. **Install dependencies:**
|
||||
* `uv sync` (this creates a virtual environment and installs packages)
|
||||
5. **Run the MCP Server:**
|
||||
* `uv run server.py`
|
||||
6. **Configure in Cursor:**
|
||||
* Cursor typically allows specifying custom MCP servers in its settings. You'll need to point Cursor to this running server. The exact mechanism might vary, so consult Cursor's documentation for adding custom MCPs.
|
||||
* **Manual Configuration (e.g., via `mcp.json`)**
|
||||
**Remember to change the `/Users/fabioferreira/Dev/scripts/interactive-feedback-mcp` path to the actual path where you cloned the repository on your system.**
|
||||
### Qt GUI（本地環境）
|
||||
- 使用 Qt 的 `QSettings` 按專案基礎儲存配置
|
||||
- 包含命令設定、自動執行選項、視窗幾何狀態等
|
||||
- 設定通常儲存在平台特定位置（Windows 登錄檔、macOS plist 檔案、Linux 配置目錄）
|
||||
|
||||
### Web UI（SSH Remote 環境）
|
||||
- 基於 FastAPI 和 WebSocket 的現代化界面
|
||||
- 支援即時命令執行和輸出顯示
|
||||
- 自動瀏覽器啟動和會話管理
|
||||
- 深色主題和響應式設計
|
||||
|
||||
## 🚀 安裝說明
|
||||
|
||||
### 系統需求
|
||||
- Python 3.11 或更新版本
|
||||
- [uv](https://github.com/astral-sh/uv) 套件管理器
|
||||
- Windows: `pip install uv`
|
||||
- Linux/Mac: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
||||
|
||||
### 安裝步驟
|
||||
|
||||
1. **取得程式碼**
|
||||
```bash
|
||||
git clone https://github.com/Minidoracat/interactive-feedback-mcp.git
|
||||
cd interactive-feedback-mcp
|
||||
```
|
||||
|
||||
2. **安裝依賴項**
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
3. **測試安裝**
|
||||
```bash
|
||||
# 基本功能測試
|
||||
uv run python test_web_ui.py
|
||||
|
||||
# 持久化測試模式（可在瀏覽器中實際測試）
|
||||
uv run python test_web_ui.py --persistent
|
||||
```
|
||||
|
||||
4. **運行 MCP 伺服器**
|
||||
```bash
|
||||
uv run server.py
|
||||
```
|
||||
|
||||
## ⚙️ AI 助手配置
|
||||
|
||||
### Cursor 配置
|
||||
|
||||
在 Cursor 的設定中配置自訂 MCP 伺服器，或手動編輯 `mcp.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -64,7 +96,7 @@ The "Save Configuration" button in the UI primarily saves the current command ty
|
||||
"command": "uv",
|
||||
"args": [
|
||||
"--directory",
|
||||
"/Users/fabioferreira/Dev/scripts/interactive-feedback-mcp",
|
||||
"/path/to/your/interactive-feedback-mcp",
|
||||
"run",
|
||||
"server.py"
|
||||
],
|
||||
@ -76,25 +108,57 @@ The "Save Configuration" button in the UI primarily saves the current command ty
|
||||
}
|
||||
}
|
||||
```
|
||||
* You might use a server identifier like `interactive-feedback-mcp` when configuring it in Cursor.
|
||||
|
||||
### For Cline / Windsurf
|
||||
**記得將路徑修改為您實際的專案目錄！**
|
||||
|
||||
Similar setup principles apply. You would configure the server command (e.g., `uv run server.py` with the correct `--directory` argument pointing to the project directory) in the respective tool's MCP settings, using `interactive-feedback-mcp` as the server identifier.
|
||||
### Cline / Windsurf 配置
|
||||
|
||||
## Development
|
||||
類似的設定原則：在各工具的 MCP 設定中配置伺服器命令，使用 `interactive-feedback-mcp` 作為伺服器識別符。
|
||||
|
||||
To run the server in development mode with a web interface for testing:
|
||||
## 🧪 測試和開發
|
||||
|
||||
```sh
|
||||
### 測試 Web UI 功能
|
||||
```bash
|
||||
# 快速功能測試
|
||||
uv run python test_web_ui.py
|
||||
|
||||
# 互動式測試模式（持久化運行）
|
||||
uv run python test_web_ui.py --persistent
|
||||
```
|
||||
|
||||
### 開發模式
|
||||
使用 FastMCP 開發模式運行伺服器並開啟測試界面：
|
||||
```bash
|
||||
uv run fastmcp dev server.py
|
||||
```
|
||||
|
||||
This will open a web interface and allow you to interact with the MCP tools for testing.
|
||||
## 🌟 功能特色
|
||||
|
||||
## Available tools
|
||||
### 🖥️ 雙介面支援
|
||||
- **Qt GUI**：適用於本地開發環境
|
||||
- **Web UI**：適用於 SSH remote 開發環境
|
||||
|
||||
Here's an example of how the AI assistant would call the `interactive_feedback` tool:
|
||||
### 🔍 智慧環境檢測
|
||||
- 自動檢測 SSH 連線環境變數
|
||||
- 檢測 DISPLAY 設定（Linux）
|
||||
- 檢測 VSCode Remote 開發環境
|
||||
- 自動選擇最適合的介面
|
||||
|
||||
### 💻 命令執行功能
|
||||
- 即時命令執行和輸出顯示
|
||||
- 支援命令中斷和程序樹終止
|
||||
- 自動工作目錄設定
|
||||
- 命令歷史記錄
|
||||
|
||||
### 🎨 現代化介面
|
||||
- 深色主題設計
|
||||
- 響應式佈局（支援手機瀏覽器）
|
||||
- WebSocket 即時通訊
|
||||
- 載入動畫和視覺回饋
|
||||
|
||||
## 📖 使用範例
|
||||
|
||||
AI 助手會如此調用 `interactive_feedback` 工具：
|
||||
|
||||
```xml
|
||||
<use_mcp_tool>
|
||||
@ -103,16 +167,54 @@ Here's an example of how the AI assistant would call the `interactive_feedback`
|
||||
<arguments>
|
||||
{
|
||||
"project_directory": "/path/to/your/project",
|
||||
"summary": "I've implemented the changes you requested and refactored the main module."
|
||||
"summary": "我已經實現了您請求的更改並重構了主模組。"
|
||||
}
|
||||
</arguments>
|
||||
</use_mcp_tool>
|
||||
```
|
||||
|
||||
## Acknowledgements & Contact
|
||||
## 🔄 工作流程
|
||||
|
||||
If you find this Interactive Feedback MCP useful, the best way to show appreciation is by following Fábio Ferreira on [X @fabiomlferreira](https://x.com/fabiomlferreira).
|
||||
1. **AI 助手調用** - AI 完成任務後調用 `interactive_feedback`
|
||||
2. **環境檢測** - 系統自動檢測運行環境
|
||||
3. **介面啟動** - 根據環境啟動 Qt GUI 或 Web UI
|
||||
4. **用戶互動** - 用戶可以執行命令、查看輸出、提供回饋
|
||||
5. **回饋傳遞** - 用戶回饋傳回給 AI 助手
|
||||
6. **流程繼續** - AI 根據回饋繼續或結束任務
|
||||
|
||||
For any questions, suggestions, or if you just want to share how you're using it, feel free to reach out on X!
|
||||
## 🆕 版本更新
|
||||
|
||||
Also, check out [dotcursorrules.com](https://dotcursorrules.com/) for more resources on enhancing your AI-assisted development workflow.
|
||||
### v2.0 - Web UI 支援
|
||||
- ✅ 新增 Web UI 介面支援 SSH remote 開發
|
||||
- ✅ 自動環境檢測和介面選擇
|
||||
- ✅ WebSocket 即時通訊
|
||||
- ✅ 現代化深色主題
|
||||
- ✅ 響應式設計支援
|
||||
- ✅ 持久化測試模式
|
||||
|
||||
### v1.0 - 基礎版本（原作者）
|
||||
- ✅ Qt GUI 介面
|
||||
- ✅ 命令執行功能
|
||||
- ✅ MCP 協議支援
|
||||
- ✅ 多平台支援
|
||||
|
||||
## 🙏 致謝與聯繫
|
||||
|
||||
### 原作者
|
||||
**Fábio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira)
|
||||
如果您覺得 Interactive Feedback MCP 有用，最好的支持方式是關注原作者的 X 帳號。
|
||||
|
||||
### 分支維護者
|
||||
如有關於 Web UI 功能的問題或建議，歡迎在 [GitHub Issues](https://github.com/Minidoracat/interactive-feedback-mcp/issues) 中提出。
|
||||
|
||||
### 相關資源
|
||||
- [dotcursorrules.com](https://dotcursorrules.com/) - 更多 AI 輔助開發工作流程資源
|
||||
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 官方文件
|
||||
|
||||
## 📄 授權條款
|
||||
|
||||
本專案採用 MIT 授權條款。詳見 [LICENSE](LICENSE) 檔案。
|
||||
|
||||
---
|
||||
|
||||
**🌟 歡迎 Star 此專案並分享給更多開發者！**
|
||||
Loading…
x
Reference in New Issue
Block a user