Mcp Feedback Enhanced

Name: Mcp Feedback Enhanced
Author: Minidoracat

本地服务

github.com/Minidoracat开发工具3.8k2 天前更新

代码仓库

关于 Mcp Feedback Enhanced

Mcp Feedback Enhanced 是一款 MCP 服务，为 AI 辅助开发任务加入人工反馈检查点。它提供 Web 界面和仅维护中的桌面外壳，并支持会话跟踪与可配置的反馈流程。

主要功能

01Web 界面与桌面界面
02提示词管理与定时提交
03会话历史和统计
04文本与图像反馈
05连接监控与通知

适用场景

01在长时间开发任务中收集澄清意见
02审阅 AI 工作摘要并反馈修正
03提交截图或其他图像作为反馈

MCP 相关

它向 MCP 客户端提供 `interactive_feedback` 工具，并打开浏览器界面或配置的桌面应用以收集用户输入。反馈通过 WebSocket 返回；命令执行功能已在 v2.6.1 移除。

#mcp-feedback #feedback-oriented-development #ai-assistant

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令uvx mcp-feedback-enhanced@latest

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypimcp-feedback-enhanced@lateststdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
project_directory	string	否	项目目录路径
summary	string	否	AI 工作完成情况摘要
timeout	integer	否	等待用户反馈的超时时间（秒）

详细介绍

MCP Feedback Enhanced

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

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

📢 维护状态（2026-08）

本项目已恢复维护。请升级到 v2.6.1 — 此版本修复了一项命令执行漏洞：
uvx mcp-feedback-enhanced@latest
v2.6.1 的变更：

🔒 已移除命令执行功能 — 修复 #219（未经身份验证的 WebSocket 可执行任意程序）。旧版黑名单只能拦截 Shell 元字符，但由于执行时使用了 shell=False，元字符从来不是风险所在——cat、curl、wget、python 都能直接通过，而且自动命令默认已启用。此功能将永久移除。详见 SECURITY.md。

🔒 已修复跨站 WebSocket 劫持（私下报告，编号为 GHSA-cmr5-gpm3-79vf、GHSA-2wx7-r4rh-f663）：浏览器打开 WebSocket 时不受同源策略限制，因此恶意页面可能诱使浏览器连接到本地 /ws。现在会在 accept() 前验证 Origin，并以 403 拒绝跨源请求。

🐛 已修复导致 Web UI 返回 500 的 Starlette 重大变更（#213、#217、#221、#228）。

🐛 已改用标准的 mcp.types.ImageContent 修复图像序列化问题（#154 及相关问题）。

当前维护范围： 安全问题，以及导致安装无法使用的兼容性问题（依赖更新、上游重大变更）。除此之外的问题将根据社区反馈决定——请参阅置顶讨论。

有一点值得明确说明： 该项目最初的卖点是“将多次往返请求合并为 Cursor 的单次请求，以节省配额”。Cursor 于 2025 年 6 月改为按 Token 用量计费，因此这一前提已不再成立 （参见 #115、#200）。现在的定位是“在长时间运行的任务中加入人工检查点”，而不是节省配额的工具。

另请注意，MCP 及其客户端现在已原生支持 Elicitation（由服务端发起的用户输入请求）和 MCP Apps（可返回交互式 UI 的工具）。如果原生功能能满足你的需求，请直接使用；如果有原生功能无法实现的需求，请在讨论中说明。这将决定接下来修复哪些问题。

🎯 核心概念

这是一个 MCP 服务，用于建立以反馈为导向的开发工作流，提供 Web UI 和桌面应用双界面选项，完美适配本地环境、SSH 远程环境和 WSL（Windows Subsystem for Linux）环境。通过引导 AI 向用户确认，而不是进行推测性操作，它能在长时间运行的任务中加入人工检查点，减少偏离和返工。

🌐 双界面架构优势：

🌐 Web UI：无需 GUI 依赖，适用于本地、远程和 WSL 环境（主要维护的界面）
🖥️ 桌面应用：基于 Tauri 的外壳，可加载相同的 Web UI，支持 Windows、macOS、Linux（自 v2.8.0 起仅维护，不再添加新功能，并计划在 v3 中移除——请参阅下文“桌面应用维护状态”）
📦 功能统一：两个界面提供完全相同的功能体验

支持的平台： Cursor | Cline | Windsurf | Augment | Trae

🔄 工作流

AI 调用 → mcp-feedback-enhanced 工具
界面启动 → 自动打开桌面应用或浏览器界面（取决于配置）
智能交互 → 选择提示词、输入文本、上传图片、自动提交
实时反馈 → WebSocket 连接立即将信息传递给 AI
会话跟踪 → 自动记录会话历史和统计数据
继续处理 → AI 根据反馈调整行为或结束任务

🌟 主要功能

🖥️ 双界面支持

桌面应用：基于 Tauri 的跨平台原生应用，支持 Windows、macOS、Linux
Web UI 界面：适用于远程和 WSL 环境的轻量级浏览器界面
环境适配：在 WSL 中，界面会自动在 Windows 浏览器中打开；SSH 远程环境需要端口转发（请参阅 FAQ）
功能体验统一：两个界面提供完全相同的功能

📝 智能工作流

提示词管理：常用提示词的 CRUD 操作、使用统计、智能排序
定时自动提交：1-86400 秒的灵活计时器，支持暂停、恢复、取消，并通过新增的暂停／恢复按钮进行控制
会话管理与跟踪：本地文件存储、隐私控制、历史记录导出（支持 JSON、CSV、Markdown 格式）、实时统计、灵活的超时设置
连接监控：WebSocket 状态监控、自动重新连接、连接质量指示
AI 工作总结 Markdown 显示：支持渲染丰富的 Markdown 语法，包括标题、粗体、代码块、列表、链接等格式，提升内容可读性

🎨 现代化体验

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

🖼️ 图片与媒体

全面支持格式：PNG、JPG、JPEG、GIF、BMP、WebP
便捷上传：拖放文件、从剪贴板粘贴（Ctrl+V）
无限制处理：支持任意尺寸的图片，自动智能处理

🌐 界面预览

Web UI 界面（v2.5.0 - 桌面应用支持）

📱 点击查看完整界面截图

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

桌面应用界面（v2.5.0 新功能）

桌面应用 - 基于 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. 安装与测试

# Install uv (if not already installed)
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": 600,
      "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"]
    }
  }
}

⚠️ 桌面应用维护状态（自 v2.8.0 起）

桌面应用目前仅处于维护模式：不再添加新功能（置顶、常驻后台、提交后保留窗口），仅修复安全问题和“完全无法启动”的兼容性问题；计划在 v3 中移除，发布说明将注明最后一个仍包含桌面应用二进制文件的版本。原因：它只是 Web UI 外的一层轻量 Tauri 壳，却占用了约 80% 的软件包体积，还需要三个平台的 CI 和代码签名；而且大多数已报告的问题都是无法在 CI 中复现的平台兼容性问题（杀毒软件误报、glibc、Gatekeeper、高 DPI、多显示器）。

继续使用桌面模式：将 IDE 的 MCP 配置中的 args 从 mcp-feedback-enhanced@latest 改为固定版本（例如 [email protected]），并保留 MCP_DESKTOP_MODE=true。自 2.8.0 起，如果桌面壳无法启动（被杀毒软件隔离、glibc 版本过旧、被 Gatekeeper 阻止、启动后立即报错退出），该调用会自动打开浏览器，并将 URL 输出到 stderr，而不是静默等待直至超时；重启 MCP 服务会重新尝试启动桌面壳。请勿固定到 2.6.0 或更早版本（存在未经身份验证的命令执行问题，详见 SECURITY.md）。

切换到 Web 模式：移除 MCP_DESKTOP_MODE。功能完全相同，提交后标签页会保持打开，并在下次调用时刷新。如果需要独立窗口，可在 Chrome/Edge 中打开反馈页面并选择“安装为应用”——但这是浏览器功能，并不等同于桌面壳：后端仍由 MCP 调用启动；关闭应用窗口后，下次调用会打开普通浏览器标签页，而不是应用窗口；端口变化后必须重新安装应用，且需要重新授予通知权限；如需置顶，请使用操作系统级工具。

配置文件示例：

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

3. 提示词工程设置

为获得最佳效果，请向 AI 助手添加以下规则：

# MCP Interactive Feedback Rules

follow mcp-feedback-enhanced instructions

⚙️ 高级设置

环境变量

变量	用途	值	默认值
`MCP_DEBUG`	调试模式	`true`/`false`	`false`
`MCP_WEB_HOST`	Web UI 主机绑定	IP 地址或主机名	`127.0.0.1`
`MCP_WEB_PORT`	Web UI 端口（`0` 表示由操作系统选择空闲端口，每次启动时端口都可能变化）	`0`、`1024-65535`	`8765`
`MCP_DESKTOP_MODE`	桌面应用模式	`true`/`false`	`false`
`MCP_LANGUAGE`	强制设置 Web UI 语言（也用于返回给 AI 的错误消息）	`zh-TW`/`zh-CN`/`en`	未设置

MCP_WEB_HOST 说明：

127.0.0.1（默认）：仅限本地访问——请保留此设置
0.0.0.0：绑定所有网络接口。⚠️ 不推荐：Web UI 和 /ws 端点没有身份验证，因此任何能访问该端口的人都可以读取会话内容（包括项目路径和 AI 摘要）并提交反馈。请改用 SSH 端口转发（参见常见问题）。

MCP_LANGUAGE 说明：

可接受的值仅限 zh-TW（繁体中文）、zh-CN（简体中文）和 en（英语）；首尾空格会被忽略。任何其他值（例如 ja、EN、zh_TW 或空字符串）都会被忽略，并视为未设置
Web UI 语言（反馈页面和等待页面）：
1. MCP_LANGUAGE：页面会以此语言打开。语言选择器仍可使用，但选择仅对当前页面生效——不会保存选择，刷新或重新打开页面后会恢复为 MCP_LANGUAGE 指定的语言。设置此变量时，不会使用或更改保存在 ui_settings.json 中的语言
2. 在 UI 中保存的语言（~/.config/mcp-feedback-enhanced/ui_settings.json 中的 language）
3. 浏览器语言
4. 繁体中文（zh-TW）
未设置 MCP_LANGUAGE 时，在 UI 中切换语言会将选择保存到 ui_settings.json。
返回给 AI 的错误消息语言：
1. MCP_LANGUAGE
2. 系统环境变量（LANG、LC_ALL、LC_MESSAGES、LANGUAGE）
3. 系统区域设置
4. 繁体中文（zh-TW）
在 Web UI 中选择的语言不会影响错误消息。

测试选项

# Version check
uvx mcp-feedback-enhanced@latest version       # Check version

# Interface testing
uvx mcp-feedback-enhanced@latest test --web    # Test Web UI (auto continuous running)
uvx mcp-feedback-enhanced@latest test --desktop # Test desktop application (v2.5.0 new feature)

# Debug mode (the test subcommand sets MCP_DEBUG=true itself; debug logs go to stderr)
uvx mcp-feedback-enhanced@latest test --web

# Specify language for testing (the language picker only applies to the current page and is not saved)
MCP_LANGUAGE=en uvx mcp-feedback-enhanced@latest test --web    # Force English interface
MCP_LANGUAGE=zh-TW uvx mcp-feedback-enhanced@latest test --web  # Force Traditional Chinese
MCP_LANGUAGE=zh-CN uvx mcp-feedback-enhanced@latest test --web  # Force Simplified Chinese

开发者安装

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

本地测试方法

# Functional testing
make test-web                                            # Web UI testing (continuous running)
make test-desktop-func                                   # Desktop application functional testing

# Or use direct commands
uv run python -m mcp_feedback_enhanced test --web       # Web UI testing with the project .venv (continuous running)
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

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

测试说明

功能测试：测试完整的 MCP 工具功能工作流
单元测试：测试各个模块的功能
覆盖率测试：在 htmlcov/ 目录中生成 HTML 覆盖率报告
质量检查：包括 lint、格式检查和类型检查

🆕 版本历史

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

🐛 常见问题

🌐 SSH 远程环境问题

Q：在 SSH 远程环境中无法启动或访问浏览器 A：使用 SSH 端口转发（安全，不会暴露服务）：

使用默认配置（MCP_WEB_HOST：127.0.0.1）
设置 SSH 端口转发：
- VS Code Remote SSH：按 Ctrl+Shift+P →“转发端口”→ 输入 8765
- Cursor SSH Remote：手动添加端口转发规则（端口 8765）
在本地浏览器中打开：http://localhost:8765

⚠️ 较早版本的 README 建议使用 MCP_WEB_HOST=0.0.0.0 直接暴露服务。现已不再推荐： Web UI 和 /ws 端点都没有身份验证，因此公开绑定后，网络上的任何人都能读取你的会话并提交反馈。

如需详细解决方案，请参阅：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 [email protected] 注意：旧版不包含新功能（提示词管理、自动提交、会话管理、桌面应用等）。

Q：出现“Unexpected token 'D'”错误 A：调试输出造成干扰。请设置 MCP_DEBUG=false 或移除该环境变量。

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

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

Q：Web UI 无法启动 A：请检查防火墙设置，或尝试使用其他端口。

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

# 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

如需详细说明，请参阅：缓存管理指南

Q：AI 模型无法解析图像 A：各种 AI 模型（包括 Gemini Pro 2.5、Claude 等）解析图像时可能不稳定，有时能正确识别，有时则无法解析上传的图像内容。这是 AI 视觉理解技术已知的局限性。建议：