mcp-feedback-enhanced/README.md

Interactive Feedback MCP

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

Original Author: Fábio Ferreira
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

🖥️ 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)

🎯 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:

1. Install uv (if not already installed)

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

2. 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:

1. Get the Code

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

2. Install Dependencies

   uv sync
   

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

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

🛠️ 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
If you find Interactive Feedback MCP useful, the best way to support is by following the original author's X account.

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!

Related Resources

• 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!