2025-06-03 21:05:17 +08:00
# MCP Feedback Enhanced
2025-05-30 23:24:09 +08:00
2025-06-02 21:30:29 +08:00
**🌐 Language / 語言切換:** **English** | [繁體中文 ](README.zh-TW.md ) | [简体中文 ](README.zh-CN.md )
2025-05-30 23:24:09 +08:00
2025-06-05 10:33:28 +08:00
**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 )
2025-06-02 21:41:38 +08:00
**UI Design Reference:** [sanshao85/mcp-feedback-collector ](https://github.com/sanshao85/mcp-feedback-collector )
2025-05-31 06:53:35 +08:00
2025-06-02 21:41:38 +08:00
## 🎯 Core Concept
2025-06-02 21:30:29 +08:00
2025-06-15 18:04:06 +08:00
This is an [MCP server ](https://modelcontextprotocol.io/ ) that establishes **feedback-oriented development workflows** , providing **Web UI and Desktop Application** dual interface options, 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.
2025-06-13 18:51:17 +08:00
2025-06-15 18:04:06 +08:00
**🌐 Dual Interface Architecture Advantages:**
- 🖥️ **Desktop Application** : Native cross-platform desktop experience, supporting Windows, macOS, Linux
- 🌐 **Web UI Interface** : No GUI dependencies required, suitable for remote and WSL environments
- 🔧 **Flexible Deployment** : Choose the most suitable interface mode based on environment requirements
- 📦 **Unified Functionality** : Both interfaces provide exactly the same functional experience
2025-06-02 21:30:29 +08:00
2025-06-15 18:04:06 +08:00
**🖥️ Desktop Application:** v2.5.0 introduces cross-platform desktop application support based on Tauri framework, supporting Windows, macOS, and Linux platforms with native desktop experience.
2025-06-14 19:07:15 +08:00
2025-06-05 07:45:08 +08:00
**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 )
2025-06-02 21:30:29 +08:00
2025-06-02 21:41:38 +08:00
### 🔄 Workflow
2025-06-13 18:51:17 +08:00
1. **AI Call** → `mcp-feedback-enhanced` tool
2025-06-15 18:04:06 +08:00
2. **Interface Launch** → Auto-open desktop application or browser interface (based on configuration)
2025-06-13 18:51:17 +08:00
3. **Smart Interaction** → Prompt selection, text input, image upload, auto-submit
4. **Real-time Feedback** → WebSocket connection delivers information to AI instantly
5. **Session Tracking** → Auto-record session history and statistics
6. **Process Continuation** → AI adjusts behavior or ends task based on feedback
2025-06-02 21:30:29 +08:00
2025-06-02 21:41:38 +08:00
## 🌟 Key Features
2025-05-30 23:24:09 +08:00
2025-06-15 18:04:06 +08:00
### 🖥️ Dual Interface Support
- **Desktop Application**: Cross-platform native application based on Tauri, supporting Windows, macOS, Linux
- **Web UI Interface**: Lightweight browser interface suitable for remote and WSL environments
- **Automatic Environment Detection**: Intelligently recognizes SSH Remote, WSL and other special environments
- **Unified Feature Experience**: Both interfaces provide exactly the same functionality
### 📝 Smart Workflow
- **Prompt Management**: CRUD operations for common prompts, usage statistics, intelligent sorting
- **Auto-Timed Submit**: 1-86400 second flexible timer, supports pause, resume, cancel
- **Session Management & Tracking**: Local file storage, privacy controls, history export, real-time statistics
- **Connection Monitoring**: WebSocket status monitoring, auto-reconnection, quality indicators
- **AI Work Summary Markdown Display**: Support for rich Markdown syntax rendering including headers, bold text, code blocks, lists, links and other formats for enhanced content readability
### 🎨 Modern Experience
- **Responsive Design**: Adapts to different screen sizes, modular JavaScript architecture
- **Audio Notifications**: Built-in multiple sound effects, custom audio upload support, volume control
- **Smart Memory**: Input box height memory, one-click copy, persistent settings
- **Multi-language Support**: Traditional Chinese, English, Simplified Chinese, instant switching
### 🖼️ Images & Media
- **Full Format Support**: PNG, JPG, JPEG, GIF, BMP, WebP
- **Convenient Upload**: Drag & drop files, clipboard paste (Ctrl+V)
- **Unlimited Processing**: Support for any size images, automatic intelligent processing
2025-06-13 18:51:17 +08:00
2025-06-10 05:43:49 +08:00
## 🌐 Interface Preview
2025-05-30 23:24:09 +08:00
2025-06-15 18:04:06 +08:00
### Web UI Interface (v2.5.0 - Desktop Application Support)
2025-06-13 18:51:17 +08:00
< div align = "center" >
2025-06-15 18:04:06 +08:00
< img src = "docs/en/images/web1.jpeg" width = "400" alt = "Web UI Main Interface - Prompt Management & Auto Submit" / >
2025-06-13 18:51:17 +08:00
< / div >
< details >
< summary > 📱 Click to view complete interface screenshots< / summary >
2025-06-03 07:56:19 +08:00
< div align = "center" >
2025-06-13 18:51:17 +08:00
< img src = "docs/en/images/web2.jpeg" width = "800" alt = "Web UI Complete Interface - Session Management & Settings" / >
2025-06-03 07:56:19 +08:00
< / div >
2025-06-13 18:51:17 +08:00
< / details >
2025-06-15 18:04:06 +08:00
*Web UI Interface - Supports desktop application and Web interface, providing prompt management, auto-submit, session tracking and other smart features*
2025-05-30 23:24:09 +08:00
2025-06-15 18:04:06 +08:00
### Desktop Application Interface (v2.5.0 New Feature)
< div align = "center" >
< img src = "docs/en/images/desktop1.png" width = "600" alt = "Desktop Application - Native Cross-platform Desktop Experience" / >
< / div >
*Desktop Application - Native cross-platform desktop application based on Tauri framework, supporting Windows, macOS, Linux with exactly the same functionality as Web UI*
**Shortcut Support**
- `Ctrl+Enter` ( Windows/Linux) / `Cmd+Enter` ( macOS) : Submit feedback (both main keyboard and numeric keypad supported)
- `Ctrl+V` ( Windows/Linux) / `Cmd+V` ( macOS) : Direct paste clipboard images
- `Ctrl+I` ( Windows/Linux) / `Cmd+I` ( macOS) : Quick focus input box (Thanks @penn201500 )
2025-05-30 23:24:09 +08:00
2025-06-02 21:41:38 +08:00
## 🚀 Quick Start
2025-05-30 23:24:09 +08:00
2025-06-02 21:41:38 +08:00
### 1. Installation & Testing
```bash
# Install uv (if not already installed)
pip install uv
2025-05-30 23:24:09 +08:00
2025-06-02 21:41:38 +08:00
# Quick test
uvx mcp-feedback-enhanced@latest test
```
2025-05-30 23:24:09 +08:00
2025-06-15 18:04:06 +08:00
### 2. Configure MCP
2025-06-02 21:41:38 +08:00
**Basic Configuration** (suitable for most users):
2025-05-30 23:24:09 +08:00
```json
{
"mcpServers": {
2025-05-31 03:42:31 +08:00
"mcp-feedback-enhanced": {
"command": "uvx",
2025-06-02 21:41:38 +08:00
"args": ["mcp-feedback-enhanced@latest "],
2025-05-31 03:42:31 +08:00
"timeout": 600,
2025-06-02 21:41:38 +08:00
"autoApprove": ["interactive_feedback"]
2025-05-31 03:42:31 +08:00
}
}
}
```
2025-06-15 18:04:06 +08:00
**Advanced Configuration** (requires custom environment):
2025-05-31 03:42:31 +08:00
```json
{
"mcpServers": {
"mcp-feedback-enhanced": {
2025-06-02 21:41:38 +08:00
"command": "uvx",
"args": ["mcp-feedback-enhanced@latest "],
2025-05-30 23:24:09 +08:00
"timeout": 600,
2025-05-31 02:03:00 +08:00
"env": {
2025-06-10 05:43:49 +08:00
"MCP_DEBUG": "false",
2025-06-18 13:54:25 +00:00
"MCP_WEB_HOST": "127.0.0.1",
2025-06-10 05:43:49 +08:00
"MCP_WEB_PORT": "8765"
2025-05-31 02:03:00 +08:00
},
2025-06-02 21:41:38 +08:00
"autoApprove": ["interactive_feedback"]
2025-05-30 23:24:09 +08:00
}
}
}
```
2025-06-15 18:04:06 +08:00
**Desktop Application Configuration** (v2.5.0 new feature - using native desktop application):
```json
{
"mcpServers": {
"mcp-feedback-enhanced": {
"command": "uvx",
"args": ["mcp-feedback-enhanced@latest "],
"timeout": 600,
"env": {
"MCP_DESKTOP_MODE": "true",
2025-06-18 13:54:25 +00:00
"MCP_WEB_HOST": "127.0.0.1",
2025-06-15 18:04:06 +08:00
"MCP_WEB_PORT": "8765",
"MCP_DEBUG": "false"
},
"autoApprove": ["interactive_feedback"]
}
}
}
```
**Configuration File Examples**:
- Desktop Mode: [examples/mcp-config-desktop.json ](examples/mcp-config-desktop.json )
- Web Mode: [examples/mcp-config-web.json ](examples/mcp-config-web.json )
2025-06-02 21:41:38 +08:00
### 3. Prompt Engineering Setup
2025-06-15 18:04:06 +08:00
For optimal results, add the following rules to your AI assistant:
2025-06-02 21:30:29 +08:00
```
2025-06-02 21:41:38 +08:00
# MCP Interactive Feedback Rules
2025-06-02 21:30:29 +08:00
2025-06-15 18:04:06 +08:00
1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, you must call MCP mcp-feedback-enhanced.
2. Whenever user feedback is received, if the feedback content is not empty, you must call MCP mcp-feedback-enhanced again and adjust behavior based on the feedback content.
3. Only when the user explicitly indicates "end" or "no more interaction needed" can you stop calling MCP mcp-feedback-enhanced, and the process is considered complete.
4. Unless receiving termination instructions, all steps must repeatedly call MCP mcp-feedback-enhanced.
5. Before completing tasks, you must use the MCP mcp-feedback-enhanced tool to ask users for feedback.
2025-06-02 21:30:29 +08:00
```
2025-06-02 21:41:38 +08:00
## ⚙️ Advanced Settings
2025-06-02 21:30:29 +08:00
2025-06-02 21:41:38 +08:00
### Environment Variables
| Variable | Purpose | Values | Default |
|----------|---------|--------|---------|
| `MCP_DEBUG` | Debug mode | `true` /`false` | `false` |
2025-06-18 13:54:25 +00:00
| `MCP_WEB_HOST` | Web UI host | IP address or hostname | `127.0.0.1` |
2025-06-08 02:43:28 +08:00
| `MCP_WEB_PORT` | Web UI port | `1024-65535` | `8765` |
2025-06-15 18:04:06 +08:00
| `MCP_DESKTOP_MODE` | Desktop application mode | `true` /`false` | `false` |
2025-06-02 21:30:29 +08:00
2025-06-02 21:41:38 +08:00
### Testing Options
2025-06-02 21:30:29 +08:00
```bash
2025-06-02 22:56:03 +08:00
# Version check
uvx mcp-feedback-enhanced@latest version # Check version
2025-06-10 05:43:49 +08:00
# Interface testing
2025-06-03 07:56:19 +08:00
uvx mcp-feedback-enhanced@latest test --web # Test Web UI (auto continuous running)
2025-06-15 18:04:06 +08:00
uvx mcp-feedback-enhanced@latest test --desktop # Test desktop application (v2.5.0 new feature)
2025-06-02 21:41:38 +08:00
# Debug mode
2025-06-02 21:30:29 +08:00
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test
```
2025-06-02 21:41:38 +08:00
### Developer Installation
```bash
git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
cd mcp-feedback-enhanced
uv sync
2025-06-03 00:27:25 +08:00
```
**Local Testing Methods**
```bash
2025-06-15 18:04:06 +08:00
# Functional testing
make test-func # Standard functional testing
make test-web # Web UI testing (continuous running)
make test-desktop-func # Desktop application functional testing
# Or use direct commands
2025-06-13 18:51:17 +08:00
uv run python -m mcp_feedback_enhanced test # Standard functional testing
2025-06-15 18:04:06 +08:00
uvx --no-cache --with-editable . mcp-feedback-enhanced test --web # Web UI testing (continuous running)
uvx --no-cache --with-editable . mcp-feedback-enhanced test --desktop # Desktop application testing
2025-06-13 18:51:17 +08:00
2025-06-15 18:04:06 +08:00
# Desktop application build (v2.5.0 new feature)
make build-desktop # Build desktop application (debug mode)
make build-desktop-release # Build desktop application (release mode)
make test-desktop # Test desktop application
make clean-desktop # Clean desktop build artifacts
# Unit testing
2025-06-13 18:51:17 +08:00
make test # Run all unit tests
make test-fast # Fast testing (skip slow tests)
2025-06-15 18:04:06 +08:00
make test-cov # Test and generate coverage report
2025-06-13 18:51:17 +08:00
2025-06-15 18:04:06 +08:00
# Code quality checks
make check # Complete code quality check
make quick-check # Quick check and auto-fix
2025-06-02 21:30:29 +08:00
```
2025-06-03 00:27:25 +08:00
**Testing Descriptions**
2025-06-13 18:51:17 +08:00
- **Functional Testing**: Test complete MCP tool functionality workflow
- **Unit Testing**: Test individual module functionality
- **Coverage Testing**: Generate HTML coverage report to `htmlcov/` directory
- **Quality Checks**: Include linting, formatting, type checking
2025-06-03 00:27:25 +08:00
2025-06-03 22:34:29 +08:00
## 🆕 Version History
2025-06-15 18:04:06 +08:00
📋 **Complete Version History:** [RELEASE_NOTES/CHANGELOG.md ](RELEASE_NOTES/CHANGELOG.md )
2025-06-03 22:34:29 +08:00
2025-06-15 18:04:06 +08:00
### Latest Version Highlights (v2.5.0)
- 🖥️ **Desktop Application** : Brand new cross-platform desktop application supporting Windows, macOS, Linux
- 📋 **AI Work Summary Markdown Display** : Support for Markdown syntax rendering including headers, bold text, code blocks, lists, links and other formats
- ⚡ **Significant Performance Enhancement** : Introduced debounce/throttle mechanisms to reduce unnecessary rendering and network requests
- 📊 **Session History Storage Improvement** : Migrated from localStorage to server-side local file storage
- 🌐 **Network Connection Stability** : Improved WebSocket reconnection mechanism with network status detection
- 🎨 **UI Rendering Optimization** : Optimized rendering performance for session management, statistics, and status indicators
- 🛠️ **Build Process Optimization** : Added Makefile desktop application build commands and development tools
- 📚 **Documentation Enhancement** : Added desktop application build guide and workflow documentation
2025-06-02 21:30:29 +08:00
2025-06-02 21:41:38 +08:00
## 🐛 Common Issues
2025-05-31 05:20:53 +08:00
2025-06-08 02:43:28 +08:00
### 🌐 SSH Remote Environment Issues
**Q: Browser cannot launch in SSH Remote environment**
2025-06-15 18:04:06 +08:00
A: This is normal. SSH Remote environments have no graphical interface, requiring manual opening in local browser. For detailed solutions, refer to: [SSH Remote Environment Usage Guide ](docs/en/ssh-remote/browser-launch-issues.md )
2025-06-08 02:43:28 +08:00
**Q: Why am I not receiving new MCP feedback?**
2025-06-15 18:04:06 +08:00
A: Likely a WebSocket connection issue. **Solution** : Directly refresh the browser page.
2025-06-08 02:43:28 +08:00
**Q: Why isn't MCP being called?**
2025-06-15 18:04:06 +08:00
A: Please confirm MCP tool status shows green light. **Solution** : Repeatedly toggle MCP tool on/off, wait a few seconds for system reconnection.
2025-06-08 02:43:28 +08:00
**Q: Augment cannot start MCP**
2025-06-15 18:04:06 +08:00
A: **Solution** : Completely close and restart VS Code or Cursor, reopen the project.
2025-06-08 02:43:28 +08:00
### 🔧 General Issues
2025-06-15 18:04:06 +08:00
**Q: How to use desktop application?**
A: v2.5.0 introduces cross-platform desktop application support. Set `"MCP_DESKTOP_MODE": "true"` in MCP configuration to enable:
```json
2025-06-13 18:51:17 +08:00
{
"mcpServers": {
"mcp-feedback-enhanced": {
"command": "uvx",
2025-06-15 18:04:06 +08:00
"args": ["mcp-feedback-enhanced@latest "],
2025-06-13 18:51:17 +08:00
"timeout": 600,
2025-06-15 18:04:06 +08:00
"env": {
"MCP_DESKTOP_MODE": "true",
"MCP_WEB_PORT": "8765"
},
2025-06-13 18:51:17 +08:00
"autoApprove": ["interactive_feedback"]
}
}
}
```
2025-06-15 18:04:06 +08:00
**Configuration File Example**: [examples/mcp-config-desktop.json ](examples/mcp-config-desktop.json )
**Q: How to use legacy PyQt6 GUI interface?**
A: v2.4.0 completely removed PyQt6 GUI dependencies. To use legacy GUI, specify v2.3.0 or earlier: `uvx mcp-feedback-enhanced@2.3.0`
**Note**: Legacy versions don't include new features (prompt management, auto-submit, session management, desktop application, etc.).
2025-06-13 18:51:17 +08:00
2025-06-15 18:04:06 +08:00
**Q: "Unexpected token 'D'" error appears**
2025-06-02 21:41:38 +08:00
A: Debug output interference. Set `MCP_DEBUG=false` or remove the environment variable.
2025-05-31 05:20:53 +08:00
2025-06-05 10:33:28 +08:00
**Q: Chinese character garbled text**
2025-06-02 21:41:38 +08:00
A: Fixed in v2.0.3. Update to latest version: `uvx mcp-feedback-enhanced@latest`
2025-05-30 23:24:09 +08:00
2025-06-15 18:04:06 +08:00
**Q: Window disappears or positioning errors in multi-screen environment**
A: Fixed in v2.1.1. Go to "⚙️ Settings" tab, check "Always show window at primary screen center" to resolve. Especially suitable for T-shaped screen arrangements and other complex multi-screen configurations.
2025-06-08 02:43:28 +08:00
2025-06-15 18:04:06 +08:00
**Q: Image upload failure**
A: Check file format (PNG/JPG/JPEG/GIF/BMP/WebP). System supports any size image files.
2025-05-31 03:42:31 +08:00
2025-06-15 18:04:06 +08:00
**Q: Web UI cannot start**
A: Check firewall settings or try using different ports.
2025-06-02 21:30:29 +08:00
2025-06-15 18:04:06 +08:00
**Q: UV Cache occupies too much disk space**
A: Due to frequent use of `uvx` commands, cache may accumulate to tens of GB. Regular cleanup recommended:
2025-06-04 19:38:18 +08:00
```bash
2025-06-15 18:04:06 +08:00
# View cache size and detailed information
2025-06-04 19:38:18 +08:00
python scripts/cleanup_cache.py --size
2025-06-15 18:04:06 +08:00
# Preview cleanup content (no actual cleanup)
2025-06-04 19:38:18 +08:00
python scripts/cleanup_cache.py --dry-run
# Execute standard cleanup
python scripts/cleanup_cache.py --clean
2025-06-15 18:04:06 +08:00
# Force cleanup (attempts to close related programs, solving Windows file occupation issues)
2025-06-04 19:38:18 +08:00
python scripts/cleanup_cache.py --force
2025-06-15 18:04:06 +08:00
# Or directly use uv command
2025-06-04 19:38:18 +08:00
uv cache clean
```
2025-06-15 18:04:06 +08:00
For detailed instructions, refer to: [Cache Management Guide ](docs/en/cache-management.md )
2025-06-04 19:38:18 +08:00
2025-06-08 02:43:28 +08:00
**Q: AI models cannot parse images**
2025-06-15 18:04:06 +08:00
A: Various AI models (including Gemini Pro 2.5, Claude, etc.) may have instability in image parsing, sometimes correctly recognizing and sometimes unable to parse uploaded image content. This is a known limitation of AI visual understanding technology. Recommendations:
2025-06-08 02:43:28 +08:00
1. Ensure good image quality (high contrast, clear text)
2. Try uploading multiple times, retries usually succeed
3. If parsing continues to fail, try adjusting image size or format
2025-06-05 09:47:59 +08:00
2025-06-02 21:41:38 +08:00
## 🙏 Acknowledgments
2025-05-30 23:24:09 +08:00
2025-06-02 21:41:38 +08:00
### 🌟 Support Original Author
2025-06-05 10:33:28 +08:00
**Fábio Ferreira** - [X @fabiomlferreira ](https://x.com/fabiomlferreira )
2025-06-02 21:41:38 +08:00
**Original Project:** [noopstudios/interactive-feedback-mcp ](https://github.com/noopstudios/interactive-feedback-mcp )
2025-05-31 07:50:50 +08:00
2025-06-15 18:04:06 +08:00
If you find it useful, please:
2025-06-02 21:41:38 +08:00
- ⭐ [Star the original project ](https://github.com/noopstudios/interactive-feedback-mcp )
- 📱 [Follow the original author ](https://x.com/fabiomlferreira )
2025-05-30 23:24:09 +08:00
2025-06-02 21:41:38 +08:00
### Design Inspiration
2025-06-08 02:43:28 +08:00
**sanshao85** - [mcp-feedback-collector ](https://github.com/sanshao85/mcp-feedback-collector )
2025-06-08 03:51:29 +08:00
### Contributors
**penn201500** - [GitHub @penn201500 ](https://github.com/penn201500 )
- 🎯 Auto-focus input box feature ([PR #39 ](https://github.com/Minidoracat/mcp-feedback-enhanced/pull/39 ))
2025-06-08 02:43:28 +08:00
### Community Support
- **Discord:** [https://discord.gg/Gur2V67 ](https://discord.gg/Gur2V67 )
- **Issues:** [GitHub Issues ](https://github.com/Minidoracat/mcp-feedback-enhanced/issues )
## 📄 License
2025-06-15 18:04:06 +08:00
MIT License - See [LICENSE ](LICENSE ) file for details
2025-06-08 02:43:28 +08:00
2025-06-15 20:42:51 +08:00
## 📈 Star History
[](https://star-history.com/#Minidoracat/mcp -feedback-enhanced& Date)
2025-06-08 02:43:28 +08:00
---
2025-06-13 18:51:17 +08:00
**🌟 Welcome to Star and share with more developers!**