MCP Feedback Enhanced

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

原作者: Fábio Ferreira | 原始项目 ⭐ 增强分支: Minidoracat UI设计参考: sanshao85/mcp-feedback-collector

🎯 核心概念

这是一个MCP服务器，它建立了一个以反馈为导向的开发工作流程，提供了Web UI和桌面应用程序两种界面选项，完美适应本地、SSH远程环境以及WSL（Windows Subsystem for Linux）环境。通过引导AI与用户确认而不是进行推测性操作，可以将多个工具调用整合成一个反馈导向请求，大大降低了平台成本并提高了开发效率。

🌐 双界面架构优势:

• 🖥️ 桌面应用程序: 原生跨平台桌面体验，支持Windows、macOS、Linux
• 🌐 Web UI: 不需要GUI依赖，适用于远程和WSL环境
• 🔧 灵活部署: 根据环境需求选择最合适的界面模式
• 📦 统一功能: 两个界面提供完全相同的功能体验

🖥️ 桌面应用程序: v2.5.0引入了基于Tauri框架的跨平台桌面应用支持，支持Windows、macOS和Linux平台，并具有原生桌面体验。

支持平台: Cursor | Cline | Windsurf | Augment | Trae

🔄 工作流

1. AI调用 → mcp-feedback-enhanced工具
2. 界面启动 → 自动打开桌面应用程序或浏览器界面（根据配置）
3. 智能交互 → 提示选择、文本输入、图片上传、自动提交
4. 实时反馈 → WebSocket连接即时向AI传递信息
5. 会话跟踪 → 自动记录会话历史和统计
6. 过程延续 → AI根据反馈调整行为或结束任务

🌟 关键特性

🖥️ 双界面支持

• 桌面应用程序: 基于Tauri的跨平台原生应用，支持Windows、macOS、Linux
• Web UI界面: 轻量级浏览器界面，适合远程和WSL环境
• 自动环境检测: 智能识别SSH远程、WSL等特殊环境
• 统一功能体验: 两个界面提供完全相同的功能

📝 智能工作流

• 提示管理: 常见提示的CRUD操作、使用统计、智能排序
• 自动定时提交: 1-86400秒灵活计时器，支持暂停、恢复、取消的新暂停/恢复按钮控制
• 自动命令执行 (v2.6.0): 创建新会话或提交后自动执行预设命令，提高开发效率
• 会话管理和跟踪: 本地文件存储、隐私控制、历史导出（支持JSON、CSV、Markdown格式）、实时统计、灵活超时设置
• 连接监控: WebSocket状态监控、自动重连、质量指标
• AI工作总结Markdown显示: 支持丰富的Markdown语法渲染，包括标题、加粗文本、代码块、列表、链接等格式，增强内容可读性

🎨 现代体验

• 响应式设计: 适应不同屏幕尺寸，模块化JavaScript架构
• 音频通知: 内置多种音效，支持自定义音频上传、音量控制
• 系统通知 (v2.6.0): 对重要事件（如自动提交、会话超时）提供系统级别的实时提醒
• 智能记忆: 输入框高度记忆、一键复制、持久设置
• 多语言支持: 繁体中文、英语、简体中文，即时切换

🖼️ 图像及媒体

• 全格式支持: PNG、JPG、JPEG、GIF、BMP、WebP
• 便捷上传: 拖放文件、剪贴板粘贴（Ctrl+V）
• 无限处理: 支持任意大小图像，自动智能处理

🌐 界面预览

Web UI界面 (v2.5.0 - 桌面应用程序支持)

<div align="center"> <img src="docs/en/images/web1.png" width="400" alt="Web UI主界面 - 提示管理和自动提交" /> </div> <details> <summary>📱 点击查看完整的界面截图</summary> <div align="center"> <img src="docs/en/images/web2.jpeg" width="800" alt="Web UI完整界面 - 会话管理和设置" /> </div> </details>

Web UI界面 - 支持桌面应用程序和Web界面，提供提示管理、自动提交、会话跟踪等智能功能

桌面应用程序界面 (v2.5.0 新特性)

<div align="center"> <img src="docs/en/images/desktop1.png" width="600" alt="桌面应用程序 - 基于Tauri框架的原生跨平台桌面体验" /> </div>

桌面应用程序 - 基于Tauri框架的原生跨平台桌面应用程序，支持Windows、macOS、Linux，与Web UI具有完全相同的功能

快捷键支持

• Ctrl+Enter（Windows/Linux）/ Cmd+Enter（macOS）：提交反馈（支持主键盘和数字小键盘）
• Ctrl+V（Windows/Linux）/ Cmd+V（macOS）：直接粘贴剪贴板中的图片
• Ctrl+I（Windows/Linux）/ Cmd+I（macOS）：快速聚焦输入框（感谢 @penn201500）

🚀 快速开始

1. 安装与测试

# 安装uv（如果尚未安装）
pip install uv

2. 配置MCP

基本配置（适用于大多数用户）：

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

高级配置（需要自定义环境）：

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

桌面应用程序配置（v2.5.0新特性 - 使用原生桌面应用程序）：

{
  "mcpServers": {
    "mcp-feedback-enhanced": {
      "command": "uvx",
      "args": ["mcp-feedback-enhanced@latest"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

配置文件示例：

• 桌面模式: examples/mcp-config-desktop.json
• Web模式: examples/mcp-config-web.json

3. 提示工程设置

为了获得最佳效果，请在您的AI助手中添加以下规则：

# MCP互动反馈规则

遵循mcp-feedback-enhanced指令

⚙️ 高级设置

环境变量

变量	目的	值	默认值
MCP_DEBUG	调试模式	true/false	false
MCP_WEB_HOST	Web UI主机绑定	IP地址或主机名	127.0.0.1
MCP_WEB_PORT	Web UI端口	1024-65535	8765
MCP_DESKTOP_MODE	桌面应用程序模式	true/false	false
MCP_LANGUAGE	强制界面语言	zh-TW/zh-CN/en	自动检测

MCP_WEB_HOST说明:

• 127.0.0.1 (默认): 仅限本地访问，安全性更高
• 0.0.0.0: 允许远程访问，适用于SSH远程开发环境

MCP_LANGUAGE说明:

• 用于强制界面语言，覆盖自动系统检测
• 支持的语言代码:
  • zh-TW: 繁体中文
  • zh-CN: 简体中文
  • en: 英语
• 语言检测优先级:
  1. 用户在界面上保存的语言设置（最高优先级）
  2. MCP_LANGUAGE环境变量
  3. 系统环境变量（LANG、LC_ALL等）
  4. 系统默认语言
  5. 回退到默认语言（繁体中文）

测试选项

# 版本检查
uvx mcp-feedback-enhanced@latest version       # 检查版本

# 界面测试
uvx mcp-feedback-enhanced@latest test --web    # 测试Web UI（自动连续运行）
uvx mcp-feedback-enhanced@latest test --desktop # 测试桌面应用程序（v2.5.0新特性）

# 调试模式
MCP_DEBUG=true uvx mcp-feedback-enhanced@latest test

# 指定语言进行测试
MCP_LANGUAGE=en uvx mcp-feedback-enhanced@latest test --web    # 强制英文界面
MCP_LANGUAGE=zh-TW uvx mcp-feedback-enhanced@latest test --web  # 强制繁体中文
MCP_LANGUAGE=zh-CN uvx mcp-feedback-enhanced@latest test --web  # 强制简体中文

开发者安装

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

本地测试方法

# 功能测试
make test-func                                           # 标准功能测试
make test-web                                            # Web UI测试（连续运行）
make test-desktop-func                                   # 桌面应用程序功能测试

# 或使用直接命令
uv run python -m mcp_feedback_enhanced test              # 标准功能测试
uvx --no-cache --with-editable . mcp-feedback-enhanced test --web   # Web UI测试（连续运行）
uvx --no-cache --with-editable . mcp-feedback-enhanced test --desktop # 桌面应用程序测试

# 桌面应用程序构建（v2.5.0新特性）
make build-desktop                                       # 构建桌面应用程序（调试模式）
make build-desktop-release                               # 构建桌面应用程序（发布模式）
make test-desktop                                        # 测试桌面应用程序
make clean-desktop                                       # 清理桌面构建产物

# 单元测试
make test                                                # 运行所有单元测试
make test-fast                                          # 快速测试（跳过慢速测试）
make test-cov                                           # 测试并生成覆盖率报告

# 代码质量检查
make check                                              # 完整代码质量检查
make quick-check                                        # 快速检查并自动修复

测试描述

• 功能测试: 测试完整的MCP工具功能工作流
• 单元测试: 测试单个模块功能
• 覆盖率测试: 生成HTML覆盖率报告至htmlcov/目录
• 质量检查: 包括代码格式化、类型检查

🆕 版本历史

📋 完整版本历史: RELEASE_NOTES/CHANGELOG.en.md

最新版本亮点 (v2.6.0)

• 🚀 自动命令执行: 创建新会话或提交后自动执行预设命令，提高工作流效率
• 📊 会话导出功能: 支持将会话记录导出为多种格式，便于分享和归档
• ⏸️ 自动提交控制: 添加暂停和恢复按钮，更好地控制自动提交时间
• 🔔 系统通知: 对重要事件提供系统级别的实时提醒
• ⏱️ 会话超时优化: 重新设计会话管理，提供更多灵活配置选项
• 🌏 国际化增强: 重构国际化架构，全面支持多语言的通知
• 🎨 UI简化: 显著简化用户界面，提升用户体验

🐛 常见问题

🌐 SSH远程环境问题

Q: 浏览器无法启动或访问在SSH远程环境中 A: 有两种解决方案：

方案1: 环境变量设置 (推荐v2.5.5) 在MCP配置中设置 "MCP_WEB_HOST": "0.0.0.0" 允许远程访问：

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

然后在本地浏览器中打开: http://[远程主机IP]:8765

方案2: SSH端口转发 (传统方法)

1. 使用默认配置 (MCP_WEB_HOST: 127.0.0.1)
2. 设置SSH端口转发:
   • VS Code远程SSH: 按 Ctrl+Shift+P → "Forward a Port" → 输入 8765
   • Cursor SSH远程: 手动添加端口转发规则（端口8765）
3. 在本地浏览器中打开: http://localhost:8765

详细解决方案参见: SSH远程环境使用指南

Q: 为什么我没有收到新的MCP反馈？ A: 很可能是WebSocket连接问题。解决办法: 直接刷新浏览器页面。

Q: 为什么MCP没有被调用？ A: 请确认MCP工具状态显示绿灯。解决办法: 多次切换MCP工具开关，等待几秒钟让系统重新连接。

Q: Augment无法启动MCP A: 解决办法: 完全关闭并重启VS Code或Cursor，重新打开项目。

🔧 通用问题

Q: 如何使用桌面应用程序？ A: v2.5.0引入了跨平台桌面应用程序支持。在MCP配置中设置 "MCP_DESKTOP_MODE": "true" 启用：

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

配置文件示例: examples/mcp-config-desktop.json

Q: 如何使用旧版PyQt6 GUI界面？ A: v2.4.0完全移除了PyQt6 GUI依赖。要使用旧版GUI，请指定v2.3.0或更早版本: uvx mcp-feedback-enhanced@2.3.0 注意: 旧版本不包含新功能（提示管理、自动提交、会话管理、桌面应用程序等）。

Q: 出现“意外标记'D'”错误 A: 调试输出干扰。设置 MCP_DEBUG=false 或移除该环境变量。

Q: 中文字符乱码 A: 在v2.0.3中已修复。更新到最新版本: uvx mcp-feedback-enhanced@latest

Q: 窗口消失或在多屏环境下定位错误 A: 在v2.1.1中已修复。前往“⚙️ 设置”标签页，勾选“始终在主屏幕中心显示窗口”以解决。特别适用于T形屏幕布局和其他复杂多屏配置。

Q: 图片上传失败 A: 检查文件格式（PNG/JPG/JPEG/GIF/BMP/WebP）。系统支持任意大小的图片文件。

Q: Web UI无法启动 A: 检查防火墙设置或尝试使用不同的端口。

Q: UV缓存占用过多磁盘空间 A: 由于频繁使用uvx命令，缓存可能累积到数十GB。建议定期清理：

# 查看缓存大小和详细信息
python scripts/cleanup_cache.py --size

# 预览清理内容（无实际清理）
python scripts/cleanup_cache.py --dry-run

# 执行标准清理
python scripts/cleanup_cache.py --clean

# 强制清理（尝试关闭相关程序，解决Windows文件占用问题）
python scripts/cleanup_cache.py --force