mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-07-27 10:42:25 +08:00

Minidoracat 33a049af4a 📖 更新 README.md 和 README.zh-TW.md，新增原始專案連結及支持方式，強調關注原作者和為專案按星星的方式。

2025-05-31 07:50:50 +08:00

13 KiB

Raw Blame History

Interactive Feedback MCP

🌐 Language / 語言切換: English | 繁體中文

Original Author: Fábio Ferreira | Original Project ⭐
Enhanced Fork: Minidoracat
UI Design Reference: sanshao85/mcp-feedback-collector - Thanks for modern interface design inspiration
Related Resources: dotcursorrules.com for more AI development workflow tools

A simple MCP server for implementing human-in-the-loop workflows in AI-assisted development tools (like Cursor). This server allows you to execute commands, view output, and provide text feedback and images directly to the AI. Also supports Cline and Windsurf.

✨ New Features

🌐 Full SSH Remote Support

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
Real-time Communication: WebSocket-based real-time command output and feedback
Dark Theme: Provides modern dark theme interface

🖼️ Image Upload Support

Multi-format Support: PNG, JPG, JPEG, GIF, BMP, WebP
Drag & Drop Upload: Support for dragging files to interface
Clipboard Support: Direct paste from clipboard
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

🌏 Multi-language Support

Full Internationalization: Complete multi-language support with structured JSON translation files
Supported Languages: Traditional Chinese, English, Simplified Chinese
Smart Detection: Automatic language detection based on system locale
Easy Extension: Simple JSON-based translation system for adding new languages
Legacy Compatibility: Fully backward compatible with existing code

🖥️ Interface Preview

Qt GUI Interface (Local Environment)

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
📱 Responsive design (Web UI)
🌐 Multi-language support (Traditional Chinese, English, Simplified Chinese)

🎯 Why Use This Tool?

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

For best results, add the following custom prompts to your AI assistant (e.g., in Cursor's rules or prompts):

Basic Prompt

Whenever you want to ask a question, be sure to call MCP mcp-feedback-enhanced.
Whenever you're about to complete a user request, call MCP mcp-feedback-enhanced instead of ending the process directly.
Continue calling MCP until the user's feedback is empty, then end the request.

Complete Rules Example

# 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.

This ensures your AI assistant uses this MCP server to request user feedback before marking tasks as complete.

🚀 Installation

Method 1: uvx Installation (Recommended)

This is the simplest method, no need to manually manage dependencies or virtual environments:

Install uv (if not already installed)

# Windows
pip install uv

# Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

Test Installation

# View version info (recommend using @latest for latest version)
uvx mcp-feedback-enhanced@latest version

# Run tests
uvx mcp-feedback-enhanced@latest test

# Persistent test mode (can actually test in browser)
uvx mcp-feedback-enhanced@latest test --persistent

Method 2: Install from Source (Developers)

Suitable for users who need to modify code or contribute to development:

Get the Code

git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git
cd mcp-feedback-enhanced

Install Dependencies
```
uv sync
```

Test Installation

# Basic functionality 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

Run MCP Server
```
uv run python -m mcp_feedback_enhanced
```

⚙️ AI Assistant Configuration

Recommended Configuration (using uvx)

Configure custom MCP server in Cursor settings, or manually edit mcp.json:

{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": [
        "mcp-feedback-enhanced@latest"
      ],
      "timeout": 600,
      "autoApprove": [
        "interactive_feedback"
      ]
    }
  }
}

Alternative Configuration (running from source)

If you need to use source version or want to customize environment variables:

{
  "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"
      ]
    }
  }
}

Remember to modify the path to your actual project directory!

🧪 Testing and Development

Testing with uvx

# Complete functionality test (recommended)
uvx mcp-feedback-enhanced@latest test

# Qt GUI specific test
uvx mcp-feedback-enhanced@latest test --gui

# Web UI specific test
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

# View version
uvx mcp-feedback-enhanced@latest version

# Enable debug mode testing
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test

🆕 Version History

v2.0.9 - Multi-language Architecture Enhancement (Latest)

🌏 Complete Multi-language Architecture Restructuring: Migrated from embedded translations to structured JSON-based system
📁 Organized Language Files: Separated language files into src/mcp_feedback_enhanced/locales/ directory structure
🔧 Enhanced Internationalization: Dynamic loading with nested key structure and browser language detection
📚 Comprehensive Documentation: Added detailed README for translation contributors with examples and guidelines
🔄 Backward Compatibility: Maintained full compatibility with existing code while enabling modern features
🖼️ Interface Screenshots Update: Added comprehensive screenshots showcasing both English and Traditional Chinese interfaces
📝 Documentation Enhancement: Updated README files with multi-language screenshots and feature descriptions

v2.0.7 - Stability and Performance Improvements

🛡️ Enhanced Error Handling: Improved stability and error recovery mechanisms
🚀 Performance Optimizations: Faster startup times and improved resource management
🔧 Bug Fixes: Various minor fixes and improvements
📦 Package Optimization: Better dependency management and build process
🎨 Visual Improvements: Enhanced button visibility and color consistency
🖱️ Interaction Fixes: Improved drag-and-drop indicators and empty state hints
📱 Responsive Design: Better layout adaptation for different screen sizes
🌐 Language Switching: Fixed Qt GUI language switching with proper checkmarks
🛡️ Complete Chinese Character Encoding Fix: Perfect Chinese character display support
🔧 JSON Parsing Error Resolution: Fixed MCP client "Unexpected token" errors
🎛️ Controllable Debug Mode: Debug output control via MCP_DEBUG environment variable
🖼️ Enhanced Image Support: Improved image processing and Base64 encoding
🚀 Output Isolation: Strict separation of debug output from MCP communication
📦 Package Optimization: Improved uvx installation experience and dependency management

v2.0.0 - Web UI and Remote Support

✅ Web UI Interface: Added Web UI support for SSH remote development environments
✅ Automatic Environment Detection: Smart interface selection based on environment
✅ WebSocket Real-time Communication: Live command execution and feedback
✅ Modern Dark Theme: Beautiful dark theme with responsive design
✅ Persistent Testing Mode: Enhanced testing capabilities

v1.0.0 - Foundation (Original Author)

✅ Qt GUI Interface: Native desktop interface
✅ Command Execution: Real-time command execution and output
✅ MCP Protocol Support: Full Model Context Protocol implementation
✅ Cross-platform Support: Windows, macOS, and Linux compatibility

🛠️ Environment Variables

Core Environment Variables

Environment Variable	Purpose	Available Values	Default
`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

Common Issues

Q: Getting "Unexpected token 'D'" error
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.

Q: Chinese characters display as garbled text
A: Completely fixed in v2.0.3. If still having issues, please update to latest version: uvx mcp-feedback-enhanced@latest

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
A: Ensure firewall allows local port access, or try setting FORCE_WEB=true environment variable.

🙏 Acknowledgments & Contact

Original Author

Fábio Ferreira - X @fabiomlferreira
Original Project: noopstudios/interactive-feedback-mcp

If you find Interactive Feedback MCP useful, the best ways to show support are:

🌟 Star the original project: Click here to star the original repo ⭐
📱 Follow the original author: @fabiomlferreira on X

UI Design Inspiration

sanshao85 - mcp-feedback-collector
Thanks for providing modern interface design inspiration, making this project's UI more beautiful and user-friendly.

Fork Maintainer

For questions about Web UI functionality, image support, or other issues, please submit at GitHub Issues.

Community Support

Join our Discord community for real-time assistance and discussions: Discord Community: https://discord.gg/Gur2V67
Feel free to ask any questions in the community!

dotcursorrules.com - More AI-assisted development workflow resources
Model Context Protocol - Official MCP documentation

📄 License

This project is licensed under the MIT License. See LICENSE file for details.

🌟 Welcome to Star this project and share it with more developers!

13 KiB Raw Blame History