Enhanced MCP server for interactive user feedback and command execution in AI-assisted development, featuring dual interface support (Web UI and Desktop Application) with intelligent environment detection and cross-platform compatibility.

These details have not been verified by PyPI

Project description

MCP Keep Feedback（交互反馈 MCP）

📋 项目来源： 本项目基于 Minidoracat/mcp-feedback-enhanced 改造而来，特此致谢！

🎯 核心概念

这是一个 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

🔄 工作流程

AI 调用 → mcp-keep-feedback 工具
界面启动 → 自动打开桌面应用程序或浏览器界面（根据配置）
智能交互 → 提示词选择、文字输入、图片上传、自动提交
即时反馈 → WebSocket 连接即时传递信息给 AI
会话追踪 → 自动记录会话历史与统计
流程继续 → AI 根据反馈调整行为或结束任务

🌟 主要功能

🖥️ 双重界面支持

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

📝 智能工作流程

提示词管理：常用提示词的 CRUD 操作、使用统计、智能排序
永不超时交互：重构后的会话模型，支持无限期等待用户反馈
独立命令行触发（v2.8.0）：支持完全脱离 MCP，在终端直接交互。详见独立命令行触发方案
自动执行命令（v2.6.0）：新建会话和提交后可自动执行预设命令，提升开发效率

🛠️ 独立模式 (Standalone Mode)

即使不使用 MCP 协议，您也可以在任何终端环境中使用此工具：

触发反馈 (自动管理后台服务):

# 推荐 AI 使用 stdin 传递超长汇报
echo "任务汇报内容" | uv run python -m mcp_keep_feedback feedback

手动管理服务 (可选):
- 启动: uv run python -m mcp_keep_feedback web
- 停止: uv run python -m mcp_keep_feedback stop

AI 会在终端阻塞等待您的反馈。

🚀 快速开始

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. 安装与测试

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

2. 配置 MCP

在 Cursor 配置文件中添加：

{
  "mcpServers": {
    "mcp-keep-feedback": {
    "command": "uv",
    "args": [
      "--directory",
        "D:/project/mcp-keep-feedback",
        "run",
        "python",
        "-m",
        "mcp_keep_feedback"
      ],
      "timeout": 604800,
      "env": {
        "MCP_DEBUG": "false",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",

        "MCP_DESKTOP_MODE": "false",
        "MCP_LANGUAGE": "zh-CN"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

桌面应用程序配置（使用本地目录启动桌面模式）：

{
  "mcpServers": {
    "mcp-keep-feedback": {
      "command": "uv",
      "args": [
        "--directory",
        "/xxx/mcp-keep-feedback",
        "run",
        "python",
        "-m",
        "mcp_keep_feedback"
      ],
      "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_DEBUG`	调试模式	`true`/`false`	`false`
`MCP_WEB_HOST`	Web UI 主机绑定	IP 地址或主机名	`127.0.0.1`
`MCP_WEB_PORT`	Web UI 端口	`1024-65535`	`8765`

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-keep-feedback@latest version       # 检查版本

# 界面测试
uvx mcp-keep-feedback@latest test --web    # 测试 Web UI (自动持续运行)
uvx mcp-keep-feedback@latest test --desktop # 测试桌面应用程序 (v2.5.0 新功能)

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

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

开发者安装

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

本地测试方式

# 功能测试
make test-func                                           # 标准功能测试
make test-web                                            # Web UI 测试 (持续运行)
make test-desktop-func                                   # 桌面应用功能测试

# 或直接使用指令
uv run python -m mcp_keep_feedback test              # 标准功能测试
uvx --no-cache --with-editable . mcp-keep-feedback test --web   # Web UI 测试 (持续运行)
uvx --no-cache --with-editable . mcp-keep-feedback test --desktop # 桌面应用测试

# 桌面应用构建 (v2.5.0 新功能)
make build-desktop                                       # 构建桌面应用 (debug 模式)
make build-desktop-release                               # 构建桌面应用 (release 模式)
make test-desktop                                        # 测试桌面应用
make clean-desktop                                       # 清理桌面构建产物

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

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

测试说明

功能测试：测试 MCP 工具的完整功能流程
单元测试：测试各个模块的独立功能
覆盖率测试：生成 HTML 覆盖率报告到 htmlcov/ 目录
质量检查：包含 linting、格式化、类型检查

🆕 版本更新记录

📋 完整版本更新记录： RELEASE_NOTES/CHANGELOG.zh-CN.md

版本亮点（v2.6.0）

🚀 自动执行命令: 新建会话和提交后可自动执行预设命令，提升工作效率
📊 会话导出功能: 支持将会话记录导出为多种格式，方便分享和存档
🌏 多语系强化: 重构多语系架构，通知系统也完整支持多语言

🐛 常见问题

🌐 SSH Remote 环境问题

Q: SSH Remote 环境下浏览器无法启动或无法访问 A: 提供两种解决方案：

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

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

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

方案二：SSH 端口转发（传统方法）

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

详细解决方案请参考：SSH Remote 环境使用指南

Q: 为什么没有接收到 MCP 新的反馈？ A: 可能是 WebSocket 连接问题。解决方法：直接重新刷新浏览器页面。由于本版本移除了超时机制，您可以长时间保持页面开启。

Q: 为什么没有调用出 MCP？ A: 请确认 MCP 工具状态为绿灯。解决方法：反复开关 MCP 工具，等待几秒让系统重新连接。

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

🔧 一般问题

Q: 如何使用桌面应用程序？ A: 在 MCP 配置中设定 "MCP_DESKTOP_MODE": "true" 即可启用。推荐配合本地目录配置使用：

{
  "command": "uv",
  "args": ["--directory", "/xxx/mcp-keep-feedback", "run", "python", "-m", "mcp_keep_feedback"],
  "env": { "MCP_DESKTOP_MODE": "true" }
}

Q: 如何使用旧版 PyQt6 GUI 界面？ A: v2.4.0 版本已完全移除 PyQt6 GUI 依赖。如需使用旧版 GUI，请指定 v2.3.0 或更早版本：uvx mcp-keep-feedback@2.3.0 注意：旧版本不包含新功能。

Q: 出现 "Unexpected token 'D'" 错误 A: 调试输出干扰。设置 MCP_DEBUG=false 或移除该环境变量。

Q: 中文字符乱码 A: 已在 v2.0.3 修复。更新到最新版本。

Q: 多屏幕环境下窗口消失或定位错误 A: 已在 v2.1.1 修复。进入「⚙️ 设置」标签页，勾选「总是在主屏幕中心显示窗口」即可解决。

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

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

Q: 如何处理 AI 客户端（如 Cursor）自身的超时？ A: 虽然本工具永不超时，但 AI 客户端通常有内置超时（如 5-10 分钟）。如果客户端报错，请尝试缩短反馈时间或调整客户端设置。

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

# 查看 cache 大小和详细信息
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

# 或直接使用 uv 命令
uv cache clean

详细说明请参考：Cache 管理指南

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

确保图片质量良好（高对比度、清晰文字）
多尝试几次上传，通常重试可以成功
如持续无法解析，可尝试调整图片大小或格式

🙏 致谢

🌟 支持原作者

Fábio Ferreira - X @fabiomlferreira 原始项目： noopstudios/interactive-feedback-mcp

如果您觉得有用，请：

⭐ 为原项目按星星
📱 关注原作者

设计灵感

sanshao85 - mcp-feedback-collector

贡献者

penn201500 - GitHub @penn201500

🎯 自动聚焦输入框功能 (PR #39)

leo108 - GitHub @leo108

🌐 SSH 远程开发支持 (MCP_WEB_HOST 环境变量) (PR #113)

Alsan - GitHub @Alsan

🍎 macOS PyO3 编译配置支持 (PR #93)

fireinice - GitHub @fireinice

📝 工具文档优化 (LLM 指令移至 docstring) (PR #105)

社群支援

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

📄 授权

MIT 授权条款 - 详见 LICENSE 档案

📈 Star History

🌟 欢迎 Star 并分享给更多开发者！

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.2.2

Apr 8, 2026

0.2.1

Apr 4, 2026

0.2.0

Apr 3, 2026

0.1.10

Mar 25, 2026

0.1.9

Mar 24, 2026

0.1.8

Mar 24, 2026

0.1.7

Mar 23, 2026

0.1.6

Mar 11, 2026

0.1.5

Mar 11, 2026

0.1.4

Mar 10, 2026

This version

0.1.3

Mar 9, 2026

0.1.2

Mar 9, 2026

0.1.1

Mar 9, 2026

0.1.0

Mar 9, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_keep_feedback-0.1.3.tar.gz (1.1 MB view details)

Uploaded Mar 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mcp_keep_feedback-0.1.3-py3-none-any.whl (312.8 kB view details)

Uploaded Mar 9, 2026 Python 3

File details

Details for the file mcp_keep_feedback-0.1.3.tar.gz.

File metadata

Download URL: mcp_keep_feedback-0.1.3.tar.gz
Upload date: Mar 9, 2026
Size: 1.1 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.13

File hashes

Hashes for mcp_keep_feedback-0.1.3.tar.gz
Algorithm	Hash digest
SHA256	`ac4b95708ed7708a1f3ab46956b724b805ec817519aff4660c2daf3dfd0b4382`
MD5	`92a04748f4105a5c8a1f16b6b3b427f4`
BLAKE2b-256	`ca299e6632e8fda1a6476f4cf85f4ddc6d154f909893f797c991ba8cd9948ef7`

See more details on using hashes here.

File details

Details for the file mcp_keep_feedback-0.1.3-py3-none-any.whl.

File metadata

Download URL: mcp_keep_feedback-0.1.3-py3-none-any.whl
Upload date: Mar 9, 2026
Size: 312.8 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.13

File hashes

Hashes for mcp_keep_feedback-0.1.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`4109800e9a9428e653d8deb2c8d3f0ce41ef5efec5684921f9296c47075497ef`
MD5	`1b03e7a6af47f070bf047a0da2ddc316`
BLAKE2b-256	`b60b0c76a103dc23687e9b6ae6357df1703355173cac233fb54ed764f82b5ba5`

See more details on using hashes here.

mcp-keep-feedback 0.1.3

Navigation

Verified details

Maintainers

Unverified details

Meta

Classifiers

Project description

MCP Keep Feedback（交互反馈 MCP）

🎯 核心概念

🔄 工作流程

🌟 主要功能

🖥️ 双重界面支持

📝 智能工作流程

🛠️ 独立模式 (Standalone Mode)

🚀 快速开始

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

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

🚀 快速开始

1. 安装与测试

2. 配置 MCP

3. 设置提示工程

⚙️ 高级设置

环境变量

测试选项

开发者安装

🆕 版本更新记录

最新版本亮点（v2.7.0）

版本亮点（v2.6.0）

🐛 常见问题

🌐 SSH Remote 环境问题

🔧 一般问题

🙏 致谢

🌟 支持原作者

设计灵感

贡献者

社群支援

📄 授权

📈 Star History

Project details

Verified details

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes