From 4e14f40dbf86e95671b86885807cf813dfc72a63 Mon Sep 17 00:00:00 2001 From: huangzhenpc Date: Sat, 7 Jun 2025 15:33:27 +0800 Subject: [PATCH] first commit --- README.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2b7795e --- /dev/null +++ b/README.md @@ -0,0 +1,248 @@ +# MCP Feedback Enhanced + +**๐ŸŒ Language / ่ชž่จ€ๅˆ‡ๆ›:** **English** | [็น้ซ”ไธญๆ–‡](README.zh-TW.md) | [็ฎ€ไฝ“ไธญๆ–‡](README.zh-CN.md) + +**Original Author:** [Fรกbio Ferreira](https://x.com/fabiomlferreira) | [Original Project](https://github.com/noopstudios/interactive-feedback-mcp) โญ +**Enhanced Fork:** [Minidoracat](https://github.com/Minidoracat) +**UI Design Reference:** [sanshao85/mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector) + +## ๐ŸŽฏ 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. + +**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) + +### ๐Ÿ”„ Workflow +1. **AI Call** โ†’ `mcp-feedback-enhanced` +2. **Environment Detection** โ†’ Auto-select appropriate interface +3. **User Interaction** โ†’ Command execution, text feedback, image upload +4. **Feedback Delivery** โ†’ Information returns to AI +5. **Process Continuation** โ†’ Adjust or end based on feedback + +## ๐ŸŒŸ Key Features + +### ๐Ÿ–ฅ๏ธ Dual Interface System +- **Qt GUI**: Native experience for local environments, modular refactored design +- **Web UI**: Modern interface for remote SSH and WSL environments, brand new architecture +- **Smart Switching**: Auto-detect environment (local/remote/WSL) and choose optimal interface + +### ๐ŸŽจ Brand New Interface Design (v2.1.0) +- **Modular Architecture**: Both GUI and Web UI adopt modular design +- **Centralized Management**: Reorganized folder structure for easier maintenance +- **Modern Themes**: Improved visual design and user experience +- **Responsive Layout**: Adapts to different screen sizes and window dimensions + +### ๐Ÿ–ผ๏ธ Image Support +- **Format Support**: PNG, JPG, JPEG, GIF, BMP, WebP +- **Upload Methods**: Drag & drop files + clipboard paste (Ctrl+V) +- **Auto Processing**: Smart compression to ensure 1MB limit compliance + +### ๐ŸŒ Multi-language +- **Three Languages**: English, Traditional Chinese, Simplified Chinese +- **Smart Detection**: Auto-select based on system language +- **Live Switching**: Change language directly within interface + +### โœจ WSL Environment Support (v2.2.5 New Feature) +- **Auto Detection**: Intelligently identifies WSL (Windows Subsystem for Linux) environments +- **Browser Integration**: Automatically launches Windows browser in WSL environments +- **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 + +## ๐Ÿ–ฅ๏ธ Interface Preview + +### Qt GUI Interface (Refactored Version) +
+ Qt GUI Main Interface + Qt GUI Settings Interface +
+ +*Qt GUI Interface - Modular refactoring, supporting local environments* + +### Web UI Interface (Refactored Version) +
+ Web UI Main Interface + Web UI Settings Interface +
+ +*Web UI Interface - Brand new architecture, suitable for SSH Remote environments* + +**Keyboard Shortcuts** +- `Ctrl+Enter` (Windows/Linux) / `Cmd+Enter` (macOS): Submit feedback (supports both main keyboard and numpad) +- `Ctrl+V` (Windows/Linux) / `Cmd+V` (macOS): Directly paste clipboard images + +## ๐Ÿš€ Quick Start + +### 1. Installation & Testing +```bash +# Install uv (if not already installed) +pip install uv + +# Quick test +uvx mcp-feedback-enhanced@latest test +``` + +### 2. MCP Configuration +**Basic Configuration** (suitable for most users): +```json +{ + "mcpServers": { + "mcp-feedback-enhanced": { + "command": "uvx", + "args": ["mcp-feedback-enhanced@latest"], + "timeout": 600, + "autoApprove": ["interactive_feedback"] + } + } +} +``` + +**Advanced Configuration** (custom environment needed): +```json +{ + "mcpServers": { + "mcp-feedback-enhanced": { + "command": "uvx", + "args": ["mcp-feedback-enhanced@latest"], + "timeout": 600, + "env": { + "FORCE_WEB": "true", + "MCP_DEBUG": "false" + }, + "autoApprove": ["interactive_feedback"] + } + } +} +``` + +### 3. Prompt Engineering Setup +For best results, add these rules to your AI assistant: + +``` +# MCP Interactive Feedback Rules + +1. During any process, task, or conversation, whether asking, responding, or completing stage tasks, must call 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. 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. Unless receiving end command, all steps must repeatedly call MCP mcp-feedback-enhanced. +5. Before completing the task, use the MCP mcp-feedback-enhanced to ask the user for feedback. +``` + +## โš™๏ธ Advanced Settings + +### Environment Variables +| Variable | Purpose | Values | Default | +|----------|---------|--------|---------| +| `FORCE_WEB` | Force use Web UI | `true`/`false` | `false` | +| `MCP_DEBUG` | Debug mode | `true`/`false` | `false` | + +### Testing Options +```bash +# Version check +uvx mcp-feedback-enhanced@latest version # Check version + +# Interface-specific testing +uvx mcp-feedback-enhanced@latest test --gui # Quick test Qt GUI +uvx mcp-feedback-enhanced@latest test --web # Test Web UI (auto continuous running) + +# Debug mode +MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test +``` + +### Developer Installation +```bash +git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git +cd mcp-feedback-enhanced +uv sync +``` + +**Local Testing Methods** +```bash +# Method 1: Standard test (recommended) +uv run python -m mcp_feedback_enhanced test + +# Method 2: Complete test suite (macOS and Windows dev environment) +uvx --with-editable . mcp-feedback-enhanced test + +# Method 3: Interface-specific testing +uvx --with-editable . mcp-feedback-enhanced test --gui # Quick test Qt GUI +uvx --with-editable . mcp-feedback-enhanced test --web # Test Web UI (auto continuous running) +``` + +**Testing Descriptions** +- **Standard Test**: Complete functionality check, suitable for daily development verification +- **Complete Test**: Deep testing of all components, suitable for pre-release verification +- **Qt GUI Test**: Quick launch and test of local graphical interface +- **Web UI Test**: Start Web server and keep running for complete Web functionality testing + +## ๐Ÿ†• Version History + +๐Ÿ“‹ **Complete Version History:** [RELEASE_NOTES/CHANGELOG.en.md](RELEASE_NOTES/CHANGELOG.en.md) + +### Latest Version Highlights (v2.2.5) +- โœจ **WSL Environment Support**: Added comprehensive support for WSL (Windows Subsystem for Linux) environments +- ๐ŸŒ **Smart Browser Launching**: Automatically invokes Windows browser in WSL environments with multiple launch methods +- ๐ŸŽฏ **Environment Detection Optimization**: Improved remote environment detection logic, WSL no longer misidentified as remote environment +- ๐Ÿงช **Testing Experience Improvement**: Test mode automatically attempts browser launching for better testing experience + +## ๐Ÿ› Common Issues + +**Q: Getting "Unexpected token 'D'" error** +A: Debug output interference. Set `MCP_DEBUG=false` or remove the environment variable. + +**Q: Chinese character garbled text** +A: Fixed in v2.0.3. Update to latest version: `uvx mcp-feedback-enhanced@latest` + +**Q: Image upload fails** +A: Check file size (โ‰ค1MB) and format (PNG/JPG/GIF/BMP/WebP). + +**Q: Web UI won't start** +A: Set `FORCE_WEB=true` or check firewall settings. + +**Q: UV Cache taking up too much disk space** +A: Due to frequent use of `uvx` commands, cache may accumulate to tens of GB. Regular cleanup is recommended: +```bash +# Check cache size and detailed information +python scripts/cleanup_cache.py --size + +# Preview cleanup content (without actually cleaning) +python scripts/cleanup_cache.py --dry-run + +# Execute standard cleanup +python scripts/cleanup_cache.py --clean + +# Force cleanup (attempts to close related processes, solves Windows file lock issues) +python scripts/cleanup_cache.py --force + +# Or use uv command directly +uv cache clean +``` +For detailed instructions, see: [Cache Management Guide](docs/en/cache-management.md) + +**Q: Gemini Pro 2.5 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. + +**Q: Multi-screen window positioning issues** +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. + +**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 + +### ๐ŸŒŸ Support Original Author +**Fรกbio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira) +**Original Project:** [noopstudios/interactive-feedback-mcp](https://github.com/noopstudios/interactive-feedback-mcp) + +If you find this useful, please: +- โญ [Star the original project](https://github.com/noopstudios/interactive-feedback-mcp) +- ๐Ÿ“ฑ [Follow the original author](https://x.com/fabiomlferreira) + +### Design Inspiration +**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector) \ No newline at end of file