feedback-angel 2.6.8

Feedback Angel - Interactive MCP server for user feedback and command execution in AI-assisted development, featuring Web UI with intelligent environment detection and cross-platform compatibility.

Feedback Angel

Forked from MCP Feedback Enhanced

🌐 Language / 语言切换: English | 繁体中文 | 简体中文

Original Author: Fábio Ferreira | Original Project ⭐ Enhanced Fork: Minidoracat | hefy2027 UI Design Reference: sanshao85/mcp-feedback-collector

🎯 Core Concept

This is an MCP server that establishes feedback-oriented development workflows, providing a Web UI interface, perfectly adapting to local, SSH Remote 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 | Cline | Windsurf | Augment | Trae

🔄 Workflow

1. AI Call → feedback-angel tool
2. Interface Launch → Auto-open browser interface
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

🌟 Key Features

🌐 Web UI Interface

• Lightweight Browser Interface: Suitable for local, remote and WSL environments
• Automatic Environment Detection: Intelligently recognizes SSH Remote, WSL and other special environments

📝 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 with new pause/resume button controls
• Auto Command Execution (v2.6.0): Automatically execute preset commands after creating new sessions or commits for improved development efficiency
• Session Management & Tracking: Local file storage, privacy controls, history export (supports JSON, CSV, Markdown formats), real-time statistics, flexible timeout settings
• 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
• System Notifications (v2.6.0): System-level real-time alerts for important events (like auto-commit, session timeout)
• 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

🌐 Interface Preview

Web UI Interface

📱 Click to view complete interface screenshots

Web UI Interface - Providing prompt management, auto-submit, session tracking and other smart features

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)

🚀 Quick Start

1. Installation & Testing

# Install uv (if not already installed)
pip install uv

2. Configure MCP

Basic Configuration (suitable for most users):

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

Advanced Configuration (requires custom environment):

{
  "mcpServers": {
    "feedback-angel": {
      "command": "uvx",
      "args": ["feedback-angel@latest"],
      "timeout": 600,
      "env": {
        "MCP_DEBUG": "false",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_LANGUAGE": "en"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Configuration File Example: examples/mcp-config-web.json

3. Prompt Engineering Setup

For optimal results, add the following rules to your AI assistant:

# MCP Interactive Feedback Rules

follow feedback-angel instructions

⚙️ Advanced Settings

Environment Variables

Variable	Purpose	Values	Default
MCP_DEBUG	Debug mode	true/false	false
MCP_WEB_HOST	Web UI host binding	IP address or hostname	127.0.0.1
MCP_WEB_PORT	Web UI port	1024-65535	8765
MCP_LANGUAGE	Force UI language	zh-TW/zh-CN/en	Auto-detect
MCP_IMAGE_DIR	Image file storage directory (enables file mode)	File path	Not set (base64 mode)
MCP_IMAGE_MODE	How AI receives image references (file mode only)	filepath/url	filepath

MCP_WEB_HOST Explanation:

• 127.0.0.1 (default): Local access only, higher security
• 0.0.0.0: Allow remote access, suitable for SSH remote development environments

MCP_LANGUAGE Explanation:

• Used to force the interface language, overriding automatic system detection
• Supported language codes:
  • zh-TW: Traditional Chinese
  • zh-CN: Simplified Chinese
  • en: English
• Language detection priority:
  1. User-saved language settings in the interface (highest priority)
  2. MCP_LANGUAGE environment variable
  3. System environment variables (LANG, LC_ALL, etc.)
  4. System default language
  5. Fallback to default language (Traditional Chinese)

MCP_IMAGE_DIR Explanation:

• When not set (default): Images are processed using base64 encoding (original behavior)
• When set to a directory path: Enables file storage mode - images are saved to disk instead of base64
• If the path is invalid, falls back to system temp directory
• Old session images are automatically cleaned up when a new session is created

MCP_IMAGE_MODE Explanation (only effective when MCP_IMAGE_DIR is set):

• filepath (default): AI receives local file paths (use Read tool to view images)
• url: AI receives HTTP URLs (use WebFetch tool to view images)

Testing Options

# Version check
uvx feedback-angel@latest version       # Check version

# Interface testing
uvx feedback-angel@latest test --web    # Test Web UI (auto continuous running)

# Debug mode
MCP_DEBUG=true uvx feedback-angel@latest test

# Specify language for testing
MCP_LANGUAGE=en uvx feedback-angel@latest test --web    # Force English interface
MCP_LANGUAGE=zh-TW uvx feedback-angel@latest test --web  # Force Traditional Chinese
MCP_LANGUAGE=zh-CN uvx feedback-angel@latest test --web  # Force Simplified Chinese

Developer Installation

git clone https://github.com/hefy2027/feedback-angel.git
cd mcp-feedback-enhanced
uv sync

Local Testing Methods

# Functional testing
make test-func                                           # Standard functional testing
make test-web                                            # Web UI testing (continuous running)

# Or use direct commands
uv run python -m mcp_feedback_enhanced test              # Standard functional testing
uvx --no-cache --with-editable . feedback-angel test --web   # Web UI testing (continuous running)

# Unit testing
make test                                                # Run all unit tests
make test-fast                                          # Fast testing (skip slow tests)
make test-cov                                           # Test and generate coverage report

# Code quality checks
make check                                              # Complete code quality check
make quick-check                                        # Quick check and auto-fix

Testing Descriptions

• 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

🆕 Version History

📋 Complete Version History: RELEASE_NOTES/CHANGELOG.en.md

Latest Version Highlights (v2.6.0)

• 🚀 Auto Command Execution: Automatically execute preset commands after creating new sessions or commits, improving workflow efficiency
• 📊 Session Export Feature: Support exporting session records to multiple formats for easy sharing and archiving
• ⏸️ Auto-commit Control: Added pause and resume buttons for better control over auto-commit timing
• 🔔 System Notifications: System-level notifications for important events with real-time alerts
• ⏱️ Session Timeout Optimization: Redesigned session management with more flexible configuration options
• 🌏 I18n Enhancement: Refactored internationalization architecture with full multilingual support for notifications
• 🎨 UI Simplification: Significantly simplified user interface for improved user experience

🐛 Common Issues

🌐 SSH Remote Environment Issues

Q: Browser cannot launch or access in SSH Remote environment A: Two solutions available:

Solution 1: Environment Variable Setting (v2.5.5 Recommended) Set "MCP_WEB_HOST": "0.0.0.0" in MCP configuration to allow remote access:

{
  "mcpServers": {
    "feedback-angel": {
      "command": "uvx",
      "args": ["feedback-angel@latest"],
      "timeout": 600,
      "env": {
        "MCP_WEB_HOST": "0.0.0.0",
        "MCP_WEB_PORT": "8765"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Then open in local browser: http://[remote-host-IP]:8765

Solution 2: SSH Port Forwarding (Traditional Method)

1. Use default configuration (MCP_WEB_HOST: 127.0.0.1)
2. Set up SSH port forwarding:
   • VS Code Remote SSH: Press Ctrl+Shift+P → "Forward a Port" → Enter 8765
   • Cursor SSH Remote: Manually add port forwarding rule (port 8765)
3. Open in local browser: http://localhost:8765

For detailed solutions, refer to: SSH Remote Environment Usage Guide

Q: Why am I not receiving new MCP feedback? A: Likely a WebSocket connection issue. Solution: Directly refresh the browser page.

Q: Why isn't MCP being called? A: Please confirm MCP tool status shows green light. Solution: Repeatedly toggle MCP tool on/off, wait a few seconds for system reconnection.

Q: Augment cannot start MCP A: Solution: Completely close and restart VS Code or Cursor, reopen the project.

🔧 General Issues

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 feedback-angel@2.3.0 Note: Legacy versions don't include new features (prompt management, auto-submit, session management, etc.).

Q: "Unexpected token 'D'" error appears 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 feedback-angel@latest

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.

Q: Image upload failure A: Check file format (PNG/JPG/JPEG/GIF/BMP/WebP). System supports any size image files.

Q: Web UI cannot start A: Check firewall settings or try using different ports.

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:

# View cache size and detailed information
python scripts/cleanup_cache.py --size

# Preview cleanup content (no actual cleanup)
python scripts/cleanup_cache.py --dry-run

# Execute standard cleanup
python scripts/cleanup_cache.py --clean

# Force cleanup (attempts to close related programs, solving Windows file occupation issues)
python scripts/cleanup_cache.py --force

# Or directly use uv command
uv cache clean

For detailed instructions, refer to: Cache Management Guide

Q: AI models cannot parse images 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:

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

🙏 Acknowledgments

🌟 Support Original Author

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

If you find it useful, please:

• ⭐ Star the original project
• 📱 Follow the original author

Design Inspiration

sanshao85 - mcp-feedback-collector

Contributors

penn201500 - GitHub @penn201500

• 🎯 Auto-focus input box feature (PR #39)

leo108 - GitHub @leo108

• 🌐 SSH Remote Development Support (MCP_WEB_HOST environment variable) (PR #113)

Alsan - GitHub @Alsan

• 🍎 macOS PyO3 Compilation Configuration Support (PR #93)

fireinice - GitHub @fireinice

• 📝 Tool Documentation Optimization (LLM instructions moved to docstring) (PR #105)

Community Support

• Discord: https://discord.gg/Gur2V67
• Issues: GitHub Issues

📄 License

MIT License - See LICENSE file for details

📈 Star History

---

🌟 Welcome to Star and share with more developers!