MCP/mcp-feedback-enhanced
1
0
Fork 0
mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-07-27 10:42:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

📝 更新 2.3.0 相關文檔

Browse Source
This commit is contained in:
Minidoracat 2025-06-08 02:43:28 +08:00
parent df5a1a610a
commit c9555a7132
19 changed files with 587 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
README.md
View File

@ -8,7 +8,7 @@
## 🎯 Core Concept ## 🎯 Core Concept
This is an [MCP server](https://modelcontextprotocol.io/) that establishes **feedback-oriented development workflows**, perfectly adapting to local, **SSH remote development environments**, and **WSL (Windows Subsystem for Linux) environments**. By guiding AI to confirm with users rather than making speculative operations, it can consolidate multiple tool calls into a single feedback-oriented request, dramatically reducing platform costs and improving development efficiency. This is an [MCP server](https://modelcontextprotocol.io/) that establishes **feedback-oriented development workflows**, perfectly adapting to local, **SSH Remote environments** (Cursor SSH Remote, VS Code Remote SSH), and **WSL (Windows Subsystem for Linux) environments**. By guiding AI to confirm with users rather than making speculative operations, it can consolidate multiple tool calls into a single feedback-oriented request, dramatically reducing platform costs and improving development efficiency.
**Supported Platforms:** [Cursor](https://www.cursor.com) | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai) **Supported Platforms:** [Cursor](https://www.cursor.com) | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai)
@ -42,12 +42,19 @@ This is an [MCP server](https://modelcontextprotocol.io/) that establishes **fee
- **Smart Detection**: Auto-select based on system language - **Smart Detection**: Auto-select based on system language
- **Live Switching**: Change language directly within interface - **Live Switching**: Change language directly within interface
### ✨ WSL Environment Support (v2.2.5 New Feature) ### ✨ WSL Environment Support (v2.2.5)
- **Auto Detection**: Intelligently identifies WSL (Windows Subsystem for Linux) environments - **Auto Detection**: Intelligently identifies WSL (Windows Subsystem for Linux) environments
- **Browser Integration**: Automatically launches Windows browser in WSL environments - **Browser Integration**: Automatically launches Windows browser in WSL environments
- **Multiple Launch Methods**: Supports `cmd.exe`, `powershell.exe`, `wslview` and other browser launch methods - **Multiple Launch Methods**: Supports `cmd.exe`, `powershell.exe`, `wslview` and other browser launch methods
- **Seamless Experience**: WSL users can directly use Web UI without additional configuration - **Seamless Experience**: WSL users can directly use Web UI without additional configuration
### 🌐 SSH Remote Environment Support (v2.3.0 New Feature)
- **Smart Detection**: Automatically identifies SSH Remote environments (Cursor SSH Remote, VS Code Remote SSH, etc.)
- **Browser Launch Guidance**: Provides clear solutions when browser cannot launch automatically
- **Port Forwarding Support**: Complete port forwarding setup guidance and troubleshooting
- **MCP Integration Optimization**: Improved integration with MCP system for more stable connection experience
- **Detailed Documentation**: [SSH Remote Environment Usage Guide](docs/en/ssh-remote/browser-launch-issues.md)
## 🖥️ Interface Preview ## 🖥️ Interface Preview
### Qt GUI Interface (Refactored Version) ### Qt GUI Interface (Refactored Version)
@ -134,6 +141,7 @@ For best results, add these rules to your AI assistant:
|----------|---------|--------|---------| |----------|---------|--------|---------|
| `FORCE_WEB` | Force use Web UI | `true`/`false` | `false` | | `FORCE_WEB` | Force use Web UI | `true`/`false` | `false` |
| `MCP_DEBUG` | Debug mode | `true`/`false` | `false` | | `MCP_DEBUG` | Debug mode | `true`/`false` | `false` |
| `MCP_WEB_PORT` | Web UI port | `1024-65535` | `8765` |
### Testing Options ### Testing Options
```bash ```bash
@ -178,20 +186,38 @@ uvx --with-editable . mcp-feedback-enhanced test --web # Test Web UI (auto co
📋 **Complete Version History:** [RELEASE_NOTES/CHANGELOG.en.md](RELEASE_NOTES/CHANGELOG.en.md) 📋 **Complete Version History:** [RELEASE_NOTES/CHANGELOG.en.md](RELEASE_NOTES/CHANGELOG.en.md)
### Latest Version Highlights (v2.2.5) ### Latest Version Highlights (v2.3.0)
- ✨ **WSL Environment Support**: Added comprehensive support for WSL (Windows Subsystem for Linux) environments - 🌐 **SSH Remote Environment Support**: Solved Cursor SSH Remote browser launch issues with clear usage guidance
- 🌐 **Smart Browser Launching**: Automatically invokes Windows browser in WSL environments with multiple launch methods - 🛡️ **Error Message Improvements**: Provides more user-friendly error messages and solution suggestions when errors occur
- 🎯 **Environment Detection Optimization**: Improved remote environment detection logic, WSL no longer misidentified as remote environment - 🧹 **Auto-cleanup Features**: Automatically cleans temporary files and expired sessions to keep the system tidy
- 🧪 **Testing Experience Improvement**: Test mode automatically attempts browser launching for better testing experience - 📊 **Memory Monitoring**: Monitors memory usage to prevent system resource shortage
- 🔧 **Connection Stability**: Improved Web UI connection stability and error handling
## 🐛 Common Issues ## 🐛 Common Issues
### 🌐 SSH Remote Environment Issues
**Q: Browser cannot launch in SSH Remote environment**
A: This is normal behavior. SSH Remote environments have no graphical interface, requiring manual opening in local browser. For detailed solutions, see: [SSH Remote Environment Usage Guide](docs/en/ssh-remote/browser-launch-issues.md)
**Q: Why am I not receiving new MCP feedback?**
A: There might be a WebSocket connection issue. **Solution**: Simply refresh the browser page.
**Q: Why isn't MCP being called?**
A: Please confirm the MCP tool status shows green light. **Solution**: Toggle the MCP tool on/off repeatedly, wait a few seconds for system reconnection.
**Q: Augment cannot start MCP**
A: **Solution**: Completely close and restart VS Code or Cursor, then reopen the project.
### 🔧 General Issues
**Q: Getting "Unexpected token 'D'" error** **Q: Getting "Unexpected token 'D'" error**
A: Debug output interference. Set `MCP_DEBUG=false` or remove the environment variable. A: Debug output interference. Set `MCP_DEBUG=false` or remove the environment variable.
**Q: Chinese character garbled text** **Q: Chinese character garbled text**
A: Fixed in v2.0.3. Update to latest version: `uvx mcp-feedback-enhanced@latest` A: Fixed in v2.0.3. Update to latest version: `uvx mcp-feedback-enhanced@latest`
**Q: Multi-screen window disappearing or positioning errors**
A: Fixed in v2.1.1. Go to "⚙️ Settings" tab, check "Always show window at primary screen center" to resolve. Especially useful for T-shaped screen arrangements and other complex multi-monitor configurations.
**Q: Image upload fails** **Q: Image upload fails**
A: Check file size (≤1MB) and format (PNG/JPG/GIF/BMP/WebP). A: Check file size (≤1MB) and format (PNG/JPG/GIF/BMP/WebP).
@ -218,21 +244,11 @@ uv cache clean
``` ```
For detailed instructions, see: [Cache Management Guide](docs/en/cache-management.md) For detailed instructions, see: [Cache Management Guide](docs/en/cache-management.md)
**Q: Gemini Pro 2.5 cannot parse images** **Q: AI models cannot parse images**
A: Known issue. Gemini Pro 2.5 may not correctly parse uploaded image content. Testing shows Claude-4-Sonnet can properly analyze images. Recommend using Claude models for better image understanding capabilities. A: Various AI models (including Gemini Pro 2.5, Claude, etc.) may have instability in image parsing, sometimes correctly identifying and sometimes unable to parse uploaded image content. This is a known limitation of AI visual understanding technology. Recommendations:
1. Ensure good image quality (high contrast, clear text)
**Q: Multi-screen window positioning issues** 2. Try uploading multiple times, retries usually succeed
A: Fixed in v2.1.1. Go to "⚙️ Settings" tab, check "Always show window at primary screen center" to resolve window positioning issues. Especially useful for T-shaped screen arrangements and other complex multi-monitor configurations. 3. If parsing continues to fail, try adjusting image size or format
**Q: Cannot launch browser in WSL environment**
A: v2.2.5 has added WSL environment support. If issues persist:
1. Confirm WSL version (WSL 2 recommended)
2. Check if Windows browser is properly installed
3. Try manual test: run `cmd.exe /c start https://www.google.com` in WSL
4. If `wslu` package is installed, you can also try the `wslview` command
**Q: WSL environment misidentified as remote environment**
A: v2.2.5 has fixed this issue. WSL environments are now correctly identified and use Web UI with Windows browser launching, instead of being misidentified as remote environments.
## 🙏 Acknowledgments ## 🙏 Acknowledgments
@ -245,4 +261,15 @@ If you find this useful, please:
- 📱 [Follow the original author](https://x.com/fabiomlferreira) - 📱 [Follow the original author](https://x.com/fabiomlferreira)
### Design Inspiration ### Design Inspiration
**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector) **sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)
### Community Support
- **Discord:** [https://discord.gg/Gur2V67](https://discord.gg/Gur2V67)
- **Issues:** [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues)
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details
---
**🌟 Welcome to Star and share with more developers!**

61
README.zh-CN.md
View File

@ -8,7 +8,7 @@
## 🎯 核心概念 ## 🎯 核心概念
这是一个 [MCP 服务器](https://modelcontextprotocol.io/)，建立**反馈导向的开发工作流程**，完美适配本地、**SSH 远程开发环境**与 **WSL (Windows Subsystem for Linux) 环境**。通过引导 AI 与用户确认而非进行推测性操作，可将多次工具调用合并为单次反馈导向请求，大幅节省平台成本并提升开发效率。 这是一个 [MCP 服务器](https://modelcontextprotocol.io/)，建立**反馈导向的开发工作流程**，完美适配本地、**SSH Remote 环境**（Cursor SSH Remote、VS Code Remote SSH）与 **WSL (Windows Subsystem for Linux) 环境**。通过引导 AI 与用户确认而非进行推测性操作，可将多次工具调用合并为单次反馈导向请求，大幅节省平台成本并提升开发效率。
**支持平台：** [Cursor](https://www.cursor.com) | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai) **支持平台：** [Cursor](https://www.cursor.com) | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai)
@ -42,12 +42,19 @@
- **智能检测**：根据系统语言自动选择 - **智能检测**：根据系统语言自动选择
- **即时切换**：界面内可直接切换语言 - **即时切换**：界面内可直接切换语言
### ✨ WSL 环境支持（v2.2.5 新功能） ### ✨ WSL 环境支持（v2.2.5）
- **自动检测**：智能识别 WSL (Windows Subsystem for Linux) 环境 - **自动检测**：智能识别 WSL (Windows Subsystem for Linux) 环境
- **浏览器整合**：WSL 环境下自动启动 Windows 浏览器 - **浏览器整合**：WSL 环境下自动启动 Windows 浏览器
- **多种启动方式**：支持 `cmd.exe`、`powershell.exe`、`wslview` 等多种浏览器启动方法 - **多种启动方式**：支持 `cmd.exe`、`powershell.exe`、`wslview` 等多种浏览器启动方法
- **无缝体验**：WSL 用户可直接使用 Web UI，无需额外配置 - **无缝体验**：WSL 用户可直接使用 Web UI，无需额外配置
### 🌐 SSH Remote 环境支持（v2.3.0 新功能）
- **智能检测**：自动识别 SSH Remote 环境（Cursor SSH Remote、VS Code Remote SSH 等）
- **浏览器启动指引**：当无法自动启动浏览器时，提供清晰的解决方案
- **端口转发支持**：完整的端口转发设置指引和故障排除
- **MCP 整合优化**：改善与 MCP 系统的整合，提供更稳定的连接体验
- **详细文档**：[SSH Remote 环境使用指南](docs/zh-CN/ssh-remote/browser-launch-issues.md)
## 🖥️ 界面预览 ## 🖥️ 界面预览
### Qt GUI 界面（重构版） ### Qt GUI 界面（重构版）
@ -180,25 +187,43 @@ uvx --with-editable . mcp-feedback-enhanced test --web # 测试 Web UI (自
📋 **完整版本更新记录：** [RELEASE_NOTES/CHANGELOG.zh-CN.md](RELEASE_NOTES/CHANGELOG.zh-CN.md) 📋 **完整版本更新记录：** [RELEASE_NOTES/CHANGELOG.zh-CN.md](RELEASE_NOTES/CHANGELOG.zh-CN.md)
### 最新版本亮点（v2.2.5） ### 最新版本亮点（v2.3.0）
- ✨ **WSL 环境支持**: 新增 WSL (Windows Subsystem for Linux) 环境的完整支持 - 🌐 **SSH Remote 环境支持**: 解决 Cursor SSH Remote 无法启动浏览器的问题，提供清晰的使用指引
- 🌐 **智能浏览器启动**: WSL 环境下自动调用 Windows 浏览器，支持多种启动方式 - 🛡️ **错误提示改善**: 当发生错误时，提供更友善的错误信息和解决建议
- 🎯 **环境检测优化**: 改进远程环境检测逻辑，WSL 不再被误判为远程环境 - 🧹 **自动清理功能**: 自动清理临时文件和过期会话，保持系统整洁
- 🧪 **测试体验提升**: 测试模式下自动尝试启动浏览器，提供更好的测试体验 - 📊 **内存监控**: 监控内存使用情况，防止系统资源不足
- 🔧 **连接稳定性**: 改善 Web UI 的连接稳定性和错误处理
## 🐛 常见问题 ## 🐛 常见问题
### 🌐 SSH Remote 环境问题
**Q: SSH Remote 环境下浏览器无法启动**
A: 这是正常现象。SSH Remote 环境没有图形界面，需要手动在本地浏览器打开。详细解决方案请参考：[SSH Remote 环境使用指南](docs/zh-CN/ssh-remote/browser-launch-issues.md)
**Q: 为什么没有接收到 MCP 新的反馈？**
A: 可能是 WebSocket 连接问题。**解决方法**：直接重新刷新浏览器页面。
**Q: 为什么没有调用出 MCP？**
A: 请确认 MCP 工具状态为绿灯。**解决方法**：反复开关 MCP 工具，等待几秒让系统重新连接。
**Q: Augment 无法启动 MCP**
A: **解决方法**：完全关闭并重新启动 VS Code 或 Cursor，重新打开项目。
### 🔧 一般问题
**Q: 出现 "Unexpected token 'D'" 错误** **Q: 出现 "Unexpected token 'D'" 错误**
A: 调试输出干扰。设置 `MCP_DEBUG=false` 或移除该环境变量。 A: 调试输出干扰。设置 `MCP_DEBUG=false` 或移除该环境变量。
**Q: 中文字符乱码** **Q: 中文字符乱码**
A: 已在 v2.0.3 修复。更新到最新版本：`uvx mcp-feedback-enhanced@latest` A: 已在 v2.0.3 修复。更新到最新版本：`uvx mcp-feedback-enhanced@latest`
**Q: 多屏幕环境下窗口消失或定位错误**
A: 已在 v2.1.1 修复。进入「⚙️ 设置」标签页，勾选「总是在主屏幕中心显示窗口」即可解决。特别适用于 T 字型屏幕排列等复杂多屏幕配置。
**Q: 图片上传失败** **Q: 图片上传失败**
A: 检查文件大小（≤1MB）和格式（PNG/JPG/GIF/BMP/WebP）。 A: 检查文件大小（≤1MB）和格式（PNG/JPG/GIF/BMP/WebP）。
**Q: Web UI 无法启动** **Q: Web UI 无法启动**
A: 设置 `FORCE_WEB=true` 或检查火墙设定。 A: 设置 `FORCE_WEB=true` 或检查防火墙设置。
**Q: UV Cache 占用过多磁盘空间** **Q: UV Cache 占用过多磁盘空间**
A: 由于频繁使用 `uvx` 命令，cache 可能会累积到数十 GB。建议定期清理： A: 由于频繁使用 `uvx` 命令，cache 可能会累积到数十 GB。建议定期清理：
@ -220,21 +245,11 @@ uv cache clean
``` ```
详细说明请参考：[Cache 管理指南](docs/zh-CN/cache-management.md) 详细说明请参考：[Cache 管理指南](docs/zh-CN/cache-management.md)
**Q: Gemini Pro 2.5 无法解析图片** **Q: AI 模型无法解析图片**
A: 已知问题，Gemini Pro 2.5 可能无法正确解析上传的图片内容。实测 Claude-4-Sonnet 可以正常解析图片。建议使用 Claude 模型获得更好的图片理解能力。 A: 各种 AI 模型（包括 Gemini Pro 2.5、Claude 等）在图片解析上可能存在不稳定性，表现为有时能正确识别、有时无法解析上传的图片内容。这是 AI 视觉理解技术的已知限制。建议：
1. 确保图片质量良好（高对比度、清晰文字）
**Q: 多屏幕视窗定位问题** 2. 多尝试几次上传，通常重试可以成功
A: 已在 v2.1.1 修复。进入「⚙️ 设置」标签页，勾选「总是在主屏幕中心显示窗口」即可解决窗口定位问题。特别适用于 T 字型屏幕排列等复杂多屏幕配置。 3. 如持续无法解析，可尝试调整图片大小或格式
**Q: WSL 环境下无法启动浏览器**
A: v2.2.5 已新增 WSL 环境支持。如果仍有问题：
1. 确认 WSL 版本（建议使用 WSL 2）
2. 检查 Windows 浏览器是否正常安装
3. 尝试手动测试：在 WSL 中执行 `cmd.exe /c start https://www.google.com`
4. 如果安装了 `wslu` 套件，也可尝试 `wslview` 命令
**Q: WSL 环境被误判为远程环境**
A: v2.2.5 已修复此问题。WSL 环境现在会被正确识别并使用 Web UI 配合 Windows 浏览器启动，而不会被误判为远程环境。
## 🙏 致谢 ## 🙏 致谢

34
README.zh-TW.md
View File

@ -42,12 +42,19 @@
- **智能偵測**：根據系統語言自動選擇 - **智能偵測**：根據系統語言自動選擇
- **即時切換**：介面內可直接切換語言 - **即時切換**：介面內可直接切換語言
### ✨ WSL 環境支援（v2.2.5 新功能） ### ✨ WSL 環境支援（v2.2.5）
- **自動檢測**：智能識別 WSL (Windows Subsystem for Linux) 環境 - **自動檢測**：智能識別 WSL (Windows Subsystem for Linux) 環境
- **瀏覽器整合**：WSL 環境下自動啟動 Windows 瀏覽器 - **瀏覽器整合**：WSL 環境下自動啟動 Windows 瀏覽器
- **多種啟動方式**：支援 `cmd.exe`、`powershell.exe`、`wslview` 等多種瀏覽器啟動方法 - **多種啟動方式**：支援 `cmd.exe`、`powershell.exe`、`wslview` 等多種瀏覽器啟動方法
- **無縫體驗**：WSL 用戶可直接使用 Web UI，無需額外配置 - **無縫體驗**：WSL 用戶可直接使用 Web UI，無需額外配置
### 🌐 SSH Remote 環境支援（v2.3.0 新功能）
- **智能檢測**：自動識別 SSH Remote 環境（Cursor SSH Remote、VS Code Remote SSH 等）
- **瀏覽器啟動指引**：當無法自動啟動瀏覽器時，提供清晰的解決方案
- **端口轉發支援**：完整的端口轉發設定指引和故障排除
- **MCP 整合優化**：改善與 MCP 系統的整合，提供更穩定的連接體驗
- **詳細文檔**：[SSH Remote 環境使用指南](docs/zh-TW/ssh-remote/browser-launch-issues.md)
## 🖥️ 介面預覽 ## 🖥️ 介面預覽
### Qt GUI 介面（重構版） ### Qt GUI 介面（重構版）
@ -180,14 +187,29 @@ uvx --with-editable . mcp-feedback-enhanced test --web # 測試 Web UI (自
📋 **完整版本更新記錄：** [RELEASE_NOTES/CHANGELOG.zh-TW.md](RELEASE_NOTES/CHANGELOG.zh-TW.md) 📋 **完整版本更新記錄：** [RELEASE_NOTES/CHANGELOG.zh-TW.md](RELEASE_NOTES/CHANGELOG.zh-TW.md)
### 最新版本亮點（v2.2.5） ### 最新版本亮點（v2.3.0）
- ✨ **WSL 環境支援**: 新增 WSL (Windows Subsystem for Linux) 環境的完整支援 - 🌐 **SSH Remote 環境支援**: 解決 Cursor SSH Remote 無法啟動瀏覽器的問題，提供清晰的使用指引
- 🌐 **智能瀏覽器啟動**: WSL 環境下自動調用 Windows 瀏覽器，支援多種啟動方式 - 🛡️ **錯誤提示改善**: 當發生錯誤時，提供更友善的錯誤訊息和解決建議
- 🎯 **環境檢測優化**: 改進遠端環境檢測邏輯，WSL 不再被誤判為遠端環境 - 🧹 **自動清理功能**: 自動清理臨時文件和過期會話，保持系統整潔
- 🧪 **測試體驗提升**: 測試模式下自動嘗試啟動瀏覽器，提供更好的測試體驗 - 📊 **記憶體監控**: 監控記憶體使用情況，防止系統資源不足
- 🔧 **連線穩定性**: 改善 Web UI 的連線穩定性和錯誤處理
## 🐛 常見問題 ## 🐛 常見問題
### 🌐 SSH Remote 環境問題
**Q: SSH Remote 環境下瀏覽器無法啟動**
A: 這是正常現象。SSH Remote 環境沒有圖形界面，需要手動在本地瀏覽器開啟。詳細解決方案請參考：[SSH Remote 環境使用指南](docs/zh-TW/ssh-remote/browser-launch-issues.md)
**Q: 為什麼沒有接收到 MCP 新的反饋？**
A: 可能是 WebSocket 連接問題。**解決方法**：直接重新整理瀏覽器頁面。
**Q: 為什麼沒有呼叫出 MCP？**
A: 請確認 MCP 工具狀態為綠燈。**解決方法**：反覆開關 MCP 工具，等待幾秒讓系統重新連接。
**Q: Augment 無法啟動 MCP**
A: **解決方法**：完全關閉並重新啟動 VS Code 或 Cursor，重新開啟專案。
### 🔧 一般問題
**Q: 出現 "Unexpected token 'D'" 錯誤** **Q: 出現 "Unexpected token 'D'" 錯誤**
A: 調試輸出干擾。設置 `MCP_DEBUG=false` 或移除該環境變數。 A: 調試輸出干擾。設置 `MCP_DEBUG=false` 或移除該環境變數。

44
RELEASE_NOTES/CHANGELOG.en.md
View File

@ -2,38 +2,32 @@
This document records all version updates for **MCP Feedback Enhanced**. This document records all version updates for **MCP Feedback Enhanced**.
## [v2.2.5] - WSL Environment Support & Cross-Platform Enhancement ## [v2.3.0] - System Stability & Resource Management Enhancement
# Release v2.2.5 - WSL Environment Support & Cross-Platform Enhancement
## 🌟 Highlights ### 🌟 Highlights
This version introduces comprehensive support for WSL (Windows Subsystem for Linux) environments, enabling WSL users to seamlessly use this tool with automatic Windows browser launching, significantly improving cross-platform development experience. This version focuses on improving system stability and user experience, particularly solving the browser launch issue in Cursor SSH Remote environments.
## ✨ New Features ### ✨ New Features
- 🐧 **WSL Environment Detection**: Automatically identifies WSL environments and provides specialized support logic - 🌐 **SSH Remote Environment Support**: Solved Cursor SSH Remote browser launch issues with clear usage guidance
- 🌐 **Smart Browser Launching**: Automatically invokes Windows browser in WSL environments with multiple launch methods - 🛡️ **Error Message Improvements**: Provides more user-friendly error messages and solution suggestions when errors occur
- 🔧 **Cross-Platform Testing Enhancement**: Test functionality integrates WSL detection for improved test coverage - 🧹 **Auto-cleanup Features**: Automatically cleans temporary files and expired sessions to keep the system tidy
- 📊 **Memory Monitoring**: Monitors memory usage to prevent system resource shortage
## 🚀 Improvements ### 🚀 Improvements
- 🎯 **Environment Detection Optimization**: Improved remote environment detection logic, WSL no longer misidentified as remote environment - 💾 **Resource Management Optimization**: Better system resource management for improved performance
- 📊 **System Information Enhancement**: System information tool now displays WSL environment status - 🔧 **Enhanced Error Handling**: Provides clearer explanations and solutions when problems occur
- 🧪 **Testing Experience Improvement**: Test mode automatically attempts browser launching for better testing experience - 🌐 **Connection Stability**: Improved Web UI connection stability
- 🖼️ **Image Upload Optimization**: Enhanced stability of image upload functionality
## 📦 Installation & Update ### 🐛 Bug Fixes
```bash - 🌐 **Connection Issues**: Fixed WebSocket connection related problems
# Quick test latest version - 🔄 **Session Management**: Fixed session state tracking issues
uvx mcp-feedback-enhanced@latest test --gui - 🖼️ **Image Processing**: Fixed event handling issues during image upload
# Update to specific version
uvx mcp-feedback-enhanced@v2.2.5 test
```
## 🔗 Related Links
- Full Documentation: [README.md](../../README.md)
- Issue Reports: [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues)
- Project Homepage: [GitHub Repository](https://github.com/Minidoracat/mcp-feedback-enhanced)
--- ---
## [v2.2.5] - WSL Environment Support & Cross-Platform Enhancement
### ✨ New Features ### ✨ New Features
- 🐧 **WSL Environment Detection**: Automatically identifies WSL environments and provides specialized support logic - 🐧 **WSL Environment Detection**: Automatically identifies WSL environments and provides specialized support logic
- 🌐 **Smart Browser Launching**: Automatically invokes Windows browser in WSL environments with multiple launch methods - 🌐 **Smart Browser Launching**: Automatically invokes Windows browser in WSL environments with multiple launch methods

57
RELEASE_NOTES/CHANGELOG.zh-CN.md
View File

@ -2,56 +2,27 @@
本文件记录了 **MCP Feedback Enhanced** 的所有版本更新内容。 本文件记录了 **MCP Feedback Enhanced** 的所有版本更新内容。
## [v2.2.5] - WSL 环境支持与跨平台增强 ## [v2.3.0] - 系统稳定性与资源管理增强
# Release v2.2.5 - WSL 环境支持与跨平台增强
## 🌟 亮点 ### 🌟 亮点
本版本新增了 WSL (Windows Subsystem for Linux) 环境的完整支持，让 WSL 用户能够无缝使用本工具并自动启动 Windows 浏览器，大幅提升跨平台开发体验。 本版本专注于提升系统稳定性和使用体验，特别解决了 Cursor SSH Remote 环境下无法启动浏览器的问题。
## ✨ 新功能
- 🐧 **WSL 环境检测**: 自动识别 WSL 环境，提供专门的支持逻辑
- 🌐 **智能浏览器启动**: WSL 环境下自动调用 Windows 浏览器，支持多种启动方式
- 🔧 **跨平台测试增强**: 测试功能整合 WSL 检测，提升测试覆盖率
## 🚀 改进功能
- 🎯 **环境检测优化**: 改进远程环境检测逻辑，WSL 不再被误判为远程环境
- 📊 **系统信息增强**: 系统信息工具新增 WSL 环境状态显示
- 🧪 **测试体验提升**: 测试模式下自动尝试启动浏览器，提供更好的测试体验
## 📦 安装与更新
```bash
# 快速测试最新版本
uvx mcp-feedback-enhanced@latest test --gui
# 更新到特定版本
uvx mcp-feedback-enhanced@v2.2.5 test
```
## 🔗 相关链接
- 完整文档: [README.zh-CN.md](../../README.zh-CN.md)
- 问题报告: [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues)
- 项目首页: [GitHub Repository](https://github.com/Minidoracat/mcp-feedback-enhanced)
---
### ✨ 新功能 ### ✨ 新功能
- 🐧 **WSL 环境检测**: 自动识别 WSL 环境，提供专门的支持逻辑 - 🌐 **SSH Remote 环境支持**: 解决 Cursor SSH Remote 无法启动浏览器的问题，提供清晰的使用指引
- 🌐 **智能浏览器启动**: WSL 环境下自动调用 Windows 浏览器，支持多种启动方式 - 🛡️ **错误提示改善**: 当发生错误时，提供更友善的错误信息和解决建议
- 🔧 **跨平台测试增强**: 测试功能整合 WSL 检测，提升测试覆盖率 - 🧹 **自动清理功能**: 自动清理临时文件和过期会话，保持系统整洁
- 📊 **内存监控**: 监控内存使用情况，防止系统资源不足
### 🚀 改进功能 ### 🚀 改进功能
- 🎯 **环境检测优化**: 改进远程环境检测逻辑，WSL 不再被误判为远程环境 - 💾 **资源管理优化**: 更好地管理系统资源，提升运行效率
- 📊 **系统信息增强**: 系统信息工具新增 WSL 环境状态显示 - 🔧 **错误处理增强**: 遇到问题时提供更清楚的说明和解决方案
- 🧪 **测试体验提升**: 测试模式下自动尝试启动浏览器，提供更好的测试体验 - 🌐 **连接稳定性**: 改善 Web UI 的连接稳定性
- 🖼️ **图片上传优化**: 改善图片上传功能的稳定性
---
## [v2.2.4] - GUI 体验优化与问题修复
### 🐛 问题修复 ### 🐛 问题修复
- 🖼️ **图片重复粘贴修复**: 解决 GUI 界面中使用 Ctrl+V 复制粘贴图片时出现重复粘贴的问题 - 🌐 **连接问题**: 修复 WebSocket 连接的相关问题
- 🌐 **语系切换修复**: 修复图片设定区域在语言切换时文字没有正确翻译的问题 - 🔄 **会话管理**: 修复会话状态跟踪的问题
- 📝 **字体可读性改善**: 调整图片设定区域的字体大小，提升文字可读性 - 🖼️ **图片处理**: 修复图片上传时的事件处理问题
--- ---

44
RELEASE_NOTES/CHANGELOG.zh-TW.md
View File

@ -2,38 +2,32 @@
本文件記錄了 **MCP Feedback Enhanced** 的所有版本更新內容。 本文件記錄了 **MCP Feedback Enhanced** 的所有版本更新內容。
## [v2.2.5] - WSL 環境支援與跨平台增強 ## [v2.3.0] - 系統穩定性與資源管理增強
# Release v2.2.5 - WSL 環境支援與跨平台增強
## 🌟 亮點 ### 🌟 亮點
本版本新增了 WSL (Windows Subsystem for Linux) 環境的完整支援，讓 WSL 用戶能夠無縫使用本工具並自動啟動 Windows 瀏覽器，大幅提升跨平台開發體驗。 本版本專注於提升系統穩定性和使用體驗，特別解決了 Cursor SSH Remote 環境下無法啟動瀏覽器的問題。
## ✨ 新功能 ### ✨ 新功能
- 🐧 **WSL 環境檢測**: 自動識別 WSL 環境，提供專門的支援邏輯 - 🌐 **SSH Remote 環境支援**: 解決 Cursor SSH Remote 無法啟動瀏覽器的問題，提供清晰的使用指引
- 🌐 **智能瀏覽器啟動**: WSL 環境下自動調用 Windows 瀏覽器，支援多種啟動方式 - 🛡️ **錯誤提示改善**: 當發生錯誤時，提供更友善的錯誤訊息和解決建議
- 🔧 **跨平台測試增強**: 測試功能整合 WSL 檢測，提升測試覆蓋率 - 🧹 **自動清理功能**: 自動清理臨時文件和過期會話，保持系統整潔
- 📊 **記憶體監控**: 監控記憶體使用情況，防止系統資源不足
## 🚀 改進功能 ### 🚀 改進功能
- 🎯 **環境檢測優化**: 改進遠端環境檢測邏輯，WSL 不再被誤判為遠端環境 - 💾 **資源管理優化**: 更好地管理系統資源，提升運行效率
- 📊 **系統資訊增強**: 系統資訊工具新增 WSL 環境狀態顯示 - 🔧 **錯誤處理增強**: 遇到問題時提供更清楚的說明和解決方案
- 🧪 **測試體驗提升**: 測試模式下自動嘗試啟動瀏覽器，提供更好的測試體驗 - 🌐 **連線穩定性**: 改善 Web UI 的連線穩定性
- 🖼️ **圖片上傳優化**: 改善圖片上傳功能的穩定性
## 📦 安裝與更新 ### 🐛 問題修復
```bash - 🌐 **連線問題**: 修復 WebSocket 連線的相關問題
# 快速測試最新版本 - 🔄 **會話管理**: 修復會話狀態追蹤的問題
uvx mcp-feedback-enhanced@latest test --gui - 🖼️ **圖片處理**: 修復圖片上傳時的事件處理問題
# 更新到特定版本
uvx mcp-feedback-enhanced@v2.2.5 test
```
## 🔗 相關連結
- 完整文檔: [README.zh-TW.md](../../README.zh-TW.md)
- 問題回報: [GitHub Issues](https://github.com/Minidoracat/mcp-feedback-enhanced/issues)
- 專案首頁: [GitHub Repository](https://github.com/Minidoracat/mcp-feedback-enhanced)
--- ---
## [v2.2.5] - WSL 環境支援與跨平台增強
### ✨ 新功能 ### ✨ 新功能
- 🐧 **WSL 環境檢測**: 自動識別 WSL 環境，提供專門的支援邏輯 - 🐧 **WSL 環境檢測**: 自動識別 WSL 環境，提供專門的支援邏輯
- 🌐 **智能瀏覽器啟動**: WSL 環境下自動調用 Windows 瀏覽器，支援多種啟動方式 - 🌐 **智能瀏覽器啟動**: WSL 環境下自動調用 Windows 瀏覽器，支援多種啟動方式

BIN
docs/en/images/ssh-remote-connect-url.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 117 KiB

BIN
docs/en/images/ssh-remote-debug-port.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/en/images/ssh-remote-port-setting.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

115
docs/en/ssh-remote/browser-launch-issues.md Normal file
View File

@ -0,0 +1,115 @@
# SSH Remote Environment Browser Launch Issues Solution
## Problem Description
When using MCP Feedback Enhanced in SSH Remote environments (such as Cursor SSH Remote, VS Code Remote SSH, etc.), you may encounter the following issues:
- 🚫 Browser cannot launch automatically
- ❌ "Unable to launch browser" error message
- 🔗 Web UI cannot open in local browser
## Root Cause Analysis
SSH Remote environment limitations:
1. **Display Environment Isolation**: Remote server has no graphical interface environment
2. **Network Isolation**: Remote ports cannot be directly accessed locally
3. **No Browser Available**: Remote environments typically don't have browsers installed
## Solution
### Step 1: Configure Port (Optional)
MCP Feedback Enhanced uses port **8765** by default, but you can customize the port:
![Port Settings](../images/ssh-remote-port-setting.png)
### Step 2: Wait for MCP Call
**Important**: Do not manually start the Web UI. Instead, wait for the AI model to call the MCP tool to automatically start it.
When the AI model calls the `interactive_feedback` tool, the system will automatically start the Web UI.
### Step 3: Check Port and Connect
If the browser doesn't launch automatically, you need to manually connect to the Web UI:
#### Method 1: Check Port Forwarding
Check your SSH Remote environment's port forwarding settings to find the corresponding local port:
![Connect to URL](../images/ssh-remote-connect-url.png)
#### Method 2: Use Debug Mode
Enable Debug mode in your IDE, select "Output" → "MCP Log" to see the Web UI URL:
![Debug Mode Port View](../images/ssh-remote-debug-port.png)
### Step 4: Open in Local Browser
1. Copy the URL (usually `http://localhost:8765` or another port)
2. Paste and open in your local browser
3. Start using the Web UI for feedback
## Port Forwarding Setup
### VS Code Remote SSH
1. Press `Ctrl+Shift+P` in VS Code
2. Type "Forward a Port"
3. Enter the port number (default 8765)
4. Access `http://localhost:8765` in your local browser
### Cursor SSH Remote
1. Check Cursor's port forwarding settings
2. Manually add port forwarding rule (port 8765)
3. Access the forwarded port in your local browser
## Important Reminders
### ⚠️ Do Not Start Manually
**Do NOT** manually execute commands like `uvx mcp-feedback-enhanced test --web`, as this cannot integrate with the MCP system.
### ✅ Correct Process
1. Wait for AI model to call MCP tool
2. System automatically starts Web UI
3. Check port forwarding or Debug logs
4. Open corresponding URL in local browser
## Frequently Asked Questions
### Q: Why can't the browser launch automatically in SSH Remote environment?
A: SSH Remote environment is headless with no graphical interface, so browsers cannot be launched directly. You need to access through port forwarding in your local browser.
### Q: How to confirm if Web UI started successfully?
A: Check IDE's Debug output or MCP Log. If you see "Web UI started" message, it means successful startup.
### Q: What if the port is occupied?
A: Modify the port number in MCP settings, or wait for the system to automatically select another available port.
### Q: Can't find port forwarding settings?
A: Check your SSH Remote tool documentation, or use Debug mode to view the URL in MCP Log.
### Q: Why am I not receiving new MCP feedback?
A: There might be a WebSocket connection issue. **Solution**: Simply refresh the browser page to re-establish the WebSocket connection.
### Q: Why isn't MCP being called?
A: Please confirm the MCP tool status shows green light (indicating normal operation). **Solution**:
- Check the MCP tool status indicator in your IDE
- If not green, try toggling the MCP tool on/off repeatedly
- Wait a few seconds for the system to reconnect
### Q: Why can't Augment start MCP?
A: Sometimes errors may prevent the MCP tool from showing green status. **Solution**:
- Completely close and restart VS Code or Cursor
- Reopen the project
- Wait for MCP tool to reload and show green light
## v2.3.0 Improvements
Improvements for SSH Remote environments in this version:
- ✅ Automatic SSH Remote environment detection
- ✅ Clear guidance when browser cannot launch
- ✅ Display correct access URL
- ✅ Improved error messages and solution suggestions
## Related Resources
- [Main Documentation](../../README.md)

BIN
docs/zh-CN/images/ssh-remote-connect-url.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 117 KiB

BIN
docs/zh-CN/images/ssh-remote-debug-port.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/zh-CN/images/ssh-remote-port-setting.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

115
docs/zh-CN/ssh-remote/browser-launch-issues.md Normal file
View File

@ -0,0 +1,115 @@
# SSH Remote 环境浏览器启动问题解决方案
## 问题描述
在 SSH Remote 环境（如 Cursor SSH Remote、VS Code Remote SSH 等）中使用 MCP Feedback Enhanced 时，可能会遇到以下问题：
- 🚫 浏览器无法自动启动
- ❌ 显示「无法启动浏览器」错误
- 🔗 Web UI 无法在本地浏览器中打开
## 原因分析
SSH Remote 环境的限制：
1. **显示环境隔离**: 远程服务器没有图形界面环境
2. **网络隔离**: 远程端口无法直接在本地访问
3. **浏览器不存在**: 远程环境通常没有安装浏览器
## 解决方案
### 步骤一：设置端口（可选）
MCP Feedback Enhanced 默认使用端口 **8765**，您也可以自定义端口：
![设置端口](../images/ssh-remote-port-setting.png)
### 步骤二：等待 MCP 调用
**重要**：不要手动启动 Web UI，而是要等待 AI 模型调用 MCP 工具时自动启动。
当 AI 模型调用 `interactive_feedback` 工具时，系统会自动启动 Web UI。
### 步骤三：查看端口并连接
如果浏览器没有自动启动，您需要手动连接到 Web UI：
#### 方法一：查看端口转发
查看您的 SSH Remote 环境的端口转发设置，找到对应的本地端口：
![连接到 URL](../images/ssh-remote-connect-url.png)
#### 方法二：使用 Debug 模式查看
在 IDE 中开启 Debug 模式，选择「输出」→「MCP Log」，可以看到 Web UI 的 URL：
![Debug 模式查看端口](../images/ssh-remote-debug-port.png)
### 步骤四：在本地浏览器打开
1. 复制 URL（通常是 `http://localhost:8765` 或其他端口）
2. 在本地浏览器中粘贴并打开
3. 开始使用 Web UI 进行反馈
## 端口转发设置
### VS Code Remote SSH
1. 在 VS Code 中按 `Ctrl+Shift+P`
2. 输入 "Forward a Port"
3. 输入端口号（默认 8765）
4. 在本地浏览器中访问 `http://localhost:8765`
### Cursor SSH Remote
1. 查看 Cursor 的端口转发设置
2. 手动添加端口转发规则（端口 8765）
3. 在本地浏览器中访问转发的端口
## 重要提醒
### ⚠️ 不要手动启动
**请勿**手动执行 `uvx mcp-feedback-enhanced test --web` 等指令，这样无法与 MCP 系统整合。
### ✅ 正确流程
1. 等待 AI 模型调用 MCP 工具
2. 系统自动启动 Web UI
3. 查看端口转发或 Debug 日志
4. 在本地浏览器中打开对应 URL
## 常见问题
### Q: 为什么在 SSH Remote 环境中无法自动打开浏览器？
A: SSH Remote 环境是无头环境（headless），没有图形界面，因此无法直接启动浏览器。需要通过端口转发在本地浏览器中访问。
### Q: 如何确认 Web UI 是否正常启动？
A: 查看 IDE 的 Debug 输出或 MCP Log，如果看到 "Web UI 已启动" 的信息，表示启动成功。
### Q: 端口被占用怎么办？
A: 在 MCP 设置中修改端口号，或者等待系统自动选择其他可用端口。
### Q: 找不到端口转发设置怎么办？
A: 查看您的 SSH Remote 工具文档，或使用 Debug 模式查看 MCP Log 中的 URL。
### Q: 为什么没有接收到 MCP 新的反馈？
A: 可能是 WebSocket 连接有问题。**解决方法**：直接重新刷新浏览器页面，这会重新建立 WebSocket 连接。
### Q: 为什么没有调用出 MCP？
A: 请确认 MCP 工具状态为绿灯（表示正常运作）。**解决方法**：
- 检查 IDE 中的 MCP 工具状态指示灯
- 如果不是绿灯，尝试反复开关 MCP 工具
- 等待几秒钟让系统重新连接
### Q: 为什么 Augment 无法启动 MCP？
A: 有时候可能会有错误导致 MCP 工具没有显示绿灯状态。**解决方法**：
- 完全关闭并重新启动 VS Code 或 Cursor
- 重新打开项目
- 等待 MCP 工具重新加载并显示绿灯
## v2.3.0 改进
本版本针对 SSH Remote 环境的改进：
- ✅ 自动检测 SSH Remote 环境
- ✅ 在无法启动浏览器时提供清晰的指引
- ✅ 显示正确的访问 URL
- ✅ 改善错误提示和解决建议
## 相关资源
- [主要文档](../../README.zh-CN.md)

BIN
docs/zh-TW/images/ssh-remote-connect-url.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 117 KiB

BIN
docs/zh-TW/images/ssh-remote-debug-port.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/zh-TW/images/ssh-remote-port-setting.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

103
docs/zh-TW/ssh-remote/browser-launch-issues.md Normal file
View File

@ -0,0 +1,103 @@
# SSH Remote 環境瀏覽器啟動問題解決方案
## 問題描述
在 SSH Remote 環境（如 Cursor SSH Remote、VS Code Remote SSH 、WSL 等）中使用 MCP Feedback Enhanced 時，可能會遇到以下問題：
- 🚫 瀏覽器無法自動啟動
- ❌ 顯示「無法啟動瀏覽器」錯誤
- 🔗 Web UI 無法在本地瀏覽器中開啟
## 原因分析
SSH Remote 環境的限制：
1. **顯示環境隔離**: 遠端伺服器沒有圖形界面環境
2. **網路隔離**: 遠端端口無法直接在本地訪問
3. **瀏覽器不存在**: 遠端環境通常沒有安裝瀏覽器
## 解決方案
### 步驟一：設定端口（可選）
MCP Feedback Enhanced 預設使用端口 **8765**，您也可以自定義端口：
![設定端口](../images/ssh-remote-port-setting.png)
### 步驟二：等待 MCP 呼叫
**重要**：不要手動啟動 Web UI，而是要等待 AI 模型呼叫 MCP 工具時自動啟動。
當 AI 模型呼叫 `interactive_feedback` 工具時，系統會自動啟動 Web UI。
### 步驟三：查看端口並連接
如果瀏覽器沒有自動啟動，您需要手動連接到 Web UI：
#### 方法一：查看端口轉發
查看您的 SSH Remote 環境的端口轉發設定，找到對應的本地端口：
![連接到 URL](../images/ssh-remote-connect-url.png)
#### 方法二：使用 Debug 模式查看
在 IDE 中開啟 Debug 模式，選擇「輸出」→「MCP Log」，可以看到 Web UI 的 URL：
![Debug 模式查看端口](../images/ssh-remote-debug-port.png)
### 步驟四：在本地瀏覽器開啟
1. 複製 URL（通常是 `http://localhost:8765` 或其他端口）
2. 在本地瀏覽器中貼上並開啟
3. 開始使用 Web UI 進行回饋
## 端口轉發設定
### VS Code Remote SSH
1. 在 VS Code 中按 `Ctrl+Shift+P`
2. 輸入 "Forward a Port"
3. 輸入端口號（預設 8765）
4. 在本地瀏覽器中訪問 `http://localhost:8765`
### Cursor SSH Remote
1. 查看 Cursor 的端口轉發設定
2. 手動添加端口轉發規則（端口 8765）
3. 在本地瀏覽器中訪問轉發的端口
## 重要提醒
### ⚠️ 不要手動啟動
**請勿**手動執行 `uvx mcp-feedback-enhanced test --web` 等指令，這樣無法與 MCP 系統整合。
### ✅ 正確流程
1. 等待 AI 模型呼叫 MCP 工具
2. 系統自動啟動 Web UI
3. 查看端口轉發或 Debug 日誌
4. 在本地瀏覽器中開啟對應 URL
## 常見問題
### Q: 為什麼在 SSH Remote 環境中無法自動開啟瀏覽器？
A: SSH Remote 環境是無頭環境（headless），沒有圖形界面，因此無法直接啟動瀏覽器。需要通過端口轉發在本地瀏覽器中訪問。
### Q: 如何確認 Web UI 是否正常啟動？
A: 查看 IDE 的 Debug 輸出或 MCP Log，如果看到 "Web UI 已啟動" 的訊息，表示啟動成功。
### Q: 端口被占用怎麼辦？
A: 在 MCP 設定中修改端口號，或者等待系統自動選擇其他可用端口。
### Q: 找不到端口轉發設定怎麼辦？
A: 查看您的 SSH Remote 工具文檔，或使用 Debug 模式查看 MCP Log 中的 URL。
### Q: 為什麼沒有接收到 MCP 新的反饋？
A: 可能是 WebSocket 連接有問題。**解決方法**：直接重新整理瀏覽器頁面，這會重新建立 WebSocket 連接。
### Q: 為什麼沒有呼叫出 MCP？
A: 請確認 MCP 工具狀態為綠燈（表示正常運作）。**解決方法**：
- 檢查 IDE 中的 MCP 工具狀態指示燈
- 如果不是綠燈，嘗試反覆開關 MCP 工具
- 等待幾秒鐘讓系統重新連接
### Q: 為什麼 Augment 無法啟動 MCP？
A: 有時候可能會有錯誤導致 MCP 工具沒有顯示綠燈狀態。**解決方法**：
- 完全關閉並重新啟動 VS Code 或 Cursor
- 重新開啟專案
- 等待 MCP 工具重新載入並顯示綠燈

86
issues/WSL環境預設使用WebUI修復.md Normal file
View File

@ -0,0 +1,86 @@
# WSL 環境預設使用 Web UI 修復
## 任務描述
修復 WSL 環境中 MCP 服務器錯誤地偵測為可使用 GUI 的問題。WSL 環境應該預設使用 Web UI，因為大多數 WSL 安裝都是 Linux 環境，沒有桌面應用支援。
## 問題分析
根據 MCP log 顯示：
```
[SERVER] 偵測到 WSL 環境（通過 /proc/version）
[SERVER] WSL 環境不被視為遠端環境
[SERVER] 成功載入 PySide6，可使用 GUI
[SERVER] GUI 可用: True
```
問題在於 `can_use_gui()` 函數沒有考慮 WSL 環境的特殊性：
- WSL 環境不被視為遠端環境（正確）
- 但 WSL 環境中即使 PySide6 可以載入，也應該預設使用 Web UI
## 解決方案
採用方案 1：在 `can_use_gui()` 函數中直接檢查 WSL 環境
### 修改內容
1. **文件**：`src\mcp_feedback_enhanced\server.py`
2. **函數**：`can_use_gui()` (第 203-230 行)
3. **修改邏輯**：
- 保持現有的遠端環境檢查
- 在遠端環境檢查後，添加 WSL 環境檢查
- 如果是 WSL 環境，直接返回 `False`
- 保持其餘 PySide6 載入檢查邏輯不變
### 修改前後對比
**修改前**：
```python
def can_use_gui() -> bool:
if is_remote_environment():
return False
try:
from PySide6.QtWidgets import QApplication
debug_log("成功載入 PySide6，可使用 GUI")
return True
# ...
```
**修改後**：
```python
def can_use_gui() -> bool:
if is_remote_environment():
return False
# WSL 環境預設使用 Web UI
if is_wsl_environment():
debug_log("WSL 環境偵測到，預設使用 Web UI")
return False
try:
from PySide6.QtWidgets import QApplication
debug_log("成功載入 PySide6，可使用 GUI")
return True
# ...
```
## 預期結果
修改後，WSL 環境的 MCP log 應該顯示：
```
[SERVER] 偵測到 WSL 環境（通過 /proc/version）
[SERVER] WSL 環境不被視為遠端環境
[SERVER] WSL 環境偵測到，預設使用 Web UI
[SERVER] GUI 可用: False
[SERVER] 建議介面: Web UI
```
## 影響範圍
- ✅ WSL 環境將預設使用 Web UI
- ✅ 不影響其他環境的邏輯
- ✅ 保持向後兼容性
- ✅ 用戶仍可通過 `FORCE_WEB` 環境變數控制介面選擇
## 測試建議
1. 在 WSL 環境中測試 MCP 服務器啟動
2. 驗證日誌顯示正確的環境偵測結果
3. 確認使用 Web UI 而非 GUI
4. 測試 `FORCE_WEB` 環境變數仍然有效
## 完成時間
2025-06-08 01:45:00