mcp-keep-feedback 0.2.1

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

MCP Keep Feedback（交互反馈 MCP）

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

针对 Cursor：变相提高使用额度

本项目主要面向 Cursor 用户，用于变相提高可用额度：

• 在 Cursor 中，每发起一次提问或每次使用子代理都会消耗一次额度。
• 使用本工具后，AI 通过 MCP 工具 把多步结果汇总成一次汇报，在 Web 界面 上与你确认；你只需在浏览器里点选/输入并提交，AI 再根据反馈继续，无需在对话里多次发问。
• 这样可以把「多次对话轮次」收敛为「一次提问 + 多次 MCP 反馈」，从而减少提问次数、节省额度，同时保持「先确认再执行」的节奏，减少误操作。
• 节约效果：在需要多轮确认的场景下，至少可节约 3～4 倍 额度（例如从 500 次等效扩容到约 2000 次）。

下面用流程图对比「不用本工具」与「使用本工具」时额度的消耗方式：

flowchart TB
  subgraph 不用本工具["不用本工具：每轮确认都算一次提问"]
    direction TB
    A1["用户提问 ①"] -->|消耗 1 次| B1[AI 执行]
    B1 --> A2["用户再提问 ②"]
    A2 -->|消耗 1 次| B2[AI 继续]
    B2 --> A3["用户再提问 ③"]
    A3 -->|消耗 1 次| B3[AI 继续]
    B3 --> A4["用户再提问 ④"]
    A4 -->|消耗 1 次| B4[完成]
    style A1 fill:#f96,color:#000
    style A2 fill:#f96,color:#000
    style A3 fill:#f96,color:#000
    style A4 fill:#f96,color:#000
  end

  subgraph 用本工具["使用本工具：一次提问后循环确认，永不结束"]
    direction TB
    U1["用户提问 ①"] -->|消耗 1 次| V1[AI 执行多步]
    V1 --> W1[MCP 汇报]
    W1 --> X1[用户在 Web 点选/确认]
    X1 -->|不消耗额度| V1
    style U1 fill:#9f9,color:#000
  end

• 左图：用户只在对话里发 1 次提问，后续确认在 Web 里循环进行，不产生新对话消息、不额外消耗额度；理论上可永不结束，直到你或 Cursor 端停止。
• 右图：每轮「用户发一条消息」都计为一次额度，4 轮确认 ≈ 消耗 4 次。

因此同样完成多轮确认，使用本工具可把额度消耗降到约 1/4，相当于 500 次额度当 2000 次用。

使用限制：有时会遇到 Cursor 页面卡住、网络波动断连或 “Take too long” 等提示。此时需要手动停止当前会话，并重新在对话里发送 call feedback（或让 AI 再次调用本工具）以重新拉起反馈流程。这是目前的主要限制；否则理论上一次请求可以持续多轮确认而不额外消耗额度。

支持平台： Cursor（推荐） | Cline | Windsurf | Augment | Trae

模型建议：为获得更稳定的反馈与额度节约效果，建议在 Cursor 中使用 Claude Opus 或 Claude Sonnet 模型。

---

核心概念

这是一个 MCP 服务器，建立反馈导向的开发工作流程，提供 Web UI，适配本地、SSH 远程与 WSL。通过引导 AI 先与用户确认再继续，可将多轮工具调用合并为「单次汇报 → 用户反馈 → AI 继续」的循环，节省平台成本并提升可控性。

工作流程

1. AI 调用 → mcp-keep-feedback 工具（传入汇报内容）
2. 界面启动 → 自动打开浏览器 Web UI
3. 智能交互 → 提示词选择、文字输入、图片上传、自动提交
4. 即时反馈 → WebSocket 将你的反馈即时传回 AI
5. 会话追踪 → 自动记录会话历史与统计
6. 流程继续 → AI 根据反馈调整行为或结束任务

主要功能

• Web UI：轻量级浏览器界面，无需本地 GUI，适合远程和 WSL；环境自动检测（SSH Remote、WSL 等）
• 提示词管理：常用提示词的 CRUD、使用统计、智能排序
• 永不超时：会话支持无限期等待用户反馈后再提交
• 独立命令行触发：可脱离 MCP，在终端直接交互，详见 独立命令行触发方案
• 自动执行命令：新建会话和提交后可自动执行预设命令
• OpenAI 兼容 API 代理：提供标准 OpenAI API 端点，允许外部工具通过 OpenAI SDK 调用 Cursor，详见 OpenAI 代理设计文档

---

独立模式（Standalone Mode）

即使不接 MCP，也可在终端使用：

1. 触发反馈（自动管理后台服务）：

   echo "任务汇报内容" | uv run python -m mcp_keep_feedback feedback
   

2. 手动管理服务（可选）：
   • 启动：uv run python -m mcp_keep_feedback web
   • 停止：uv run python -m mcp_keep_feedback stop

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

---

快速开始

Web UI 示意

📱 点击查看完整界面截图

1. 安装与测试

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

2. 配置 MCP（Cursor）

在 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "mcp-keep-feedback": {
      "command": "uvx",
      "args": [
        "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"
      ]
    }
  }
}

3. 提示工程

为获得最佳效果，建议在 Cursor Settings 的 Rules 中配置提示工程规则，详见 提示工程设置指南。

---

高级设置

环境变量

变量	用途	值	默认
MCP_DEBUG	调试模式	true/false	false
MCP_WEB_HOST	Web UI 绑定地址	IP 或主机名	127.0.0.1
MCP_WEB_PORT	Web UI 端口	1024–65535	8765
MCP_LANGUAGE	界面语言	zh-TW/zh-CN/en	自动检测
MCP_AUTO_REPLY_TIMEOUT	自动回复超时（分钟）	整数	0（禁用）
MCP_OPENAI_ENABLED	启用 OpenAI 代理	true/false	false
MCP_OPENAI_MODEL_NAME	OpenAI 模型名称	字符串	cursor
MCP_OPENAI_TIMEOUT	OpenAI 请求超时（秒）	整数	300
MCP_OPENAI_API_KEY	OpenAI API Key（可选）	字符串	空（无需验证）

• MCP_WEB_HOST：127.0.0.1 仅本机；0.0.0.0 允许远程（如 SSH 开发）。
• MCP_LANGUAGE：强制界面语言，覆盖系统检测。
• MCP_OPENAI_ENABLED：启用后，可通过标准 OpenAI API 调用 Cursor（见下方说明）。
• MCP_OPENAI_API_KEY：设置后，请求需携带 Authorization: Bearer <key> 验证。

测试命令

uvx mcp-keep-feedback@latest version
uvx mcp-keep-feedback@latest test --web
MCP_LANGUAGE=zh-CN uvx mcp-keep-feedback@latest test --web

---

OpenAI 兼容 API 代理

启用 OpenAI 代理后，外部工具可通过标准 OpenAI API 调用 Cursor：

配置

在 MCP 配置中添加环境变量：

{
  "env": {
    "MCP_OPENAI_ENABLED": "true",
    "MCP_OPENAI_MODEL_NAME": "cursor",
    "MCP_OPENAI_TIMEOUT": "300",
    "MCP_OPENAI_API_KEY": "your-api-key"  // 可选
  }
}

使用示例

使用 OpenAI SDK 调用：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8765/v1",
    api_key="your-api-key"  # 如果设置了 MCP_OPENAI_API_KEY
)

response = client.chat.completions.create(
    model="cursor",
    messages=[
        {"role": "user", "content": "用 Python 实现二分查找"}
    ]
)

print(response.choices[0].message.content)

使用 curl 调用：

curl http://localhost:8765/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "cursor",
    "messages": [{"role": "user", "content": "解释快速排序"}]
  }'

端点

端点	方法	说明
/v1/chat/completions	POST	聊天补全（OpenAI 兼容）
/v1/models	GET	获取可用模型列表

工作原理

1. 外部工具通过 OpenAI API 发送请求到 mcp-keep-feedback
2. 请求被入队并等待 Cursor 通过 MCP 工具消费
3. Cursor 处理请求并通过 interactive_feedback 返回结果
4. 结果被格式化为 OpenAI 兼容响应返回给调用方

⚠️ 注意：OpenAI 代理模式仍遵守原有的 MCP 反馈闭环协议。Cursor 需要持续调用 interactive_feedback 工具来完成请求处理。详见 OpenAI 代理设计文档。

---

开发者安装

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

make test-func
make test
make check

本地开发配置

在 Cursor 的 MCP 配置中使用本地开发路径：

{
  "mcpServers": {
    "mcp-keep-feedback": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keep-feedback",
        "run",
        "python",
        "-m",
        "mcp_keep_feedback"
      ],
      "timeout": 604800,
      "env": {
        "MCP_DEBUG": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_LANGUAGE": "zh-CN",
        "MCP_OPENAI_ENABLED": "true"
      },
      "autoApprove": [
        "interactive_feedback"
      ]
    }
  }
}

配置说明：

• --directory：指定项目根目录路径（Windows 路径如 D:\\project\\mcp-keep-feedback，Linux/macOS 如 /home/user/mcp-keep-feedback）
• MCP_DEBUG：开发时建议设为 true 以查看详细日志
• 其他环境变量按需配置

常见问题

SSH Remote / 远程

Q: 浏览器打不开或无法访问 Web UI
A: 在 MCP 配置中设置 "MCP_WEB_HOST": "0.0.0.0"，然后在本地浏览器访问 http://[远程主机IP]:8765。或使用 SSH 端口转发 8765，访问 http://localhost:8765。详见 SSH Remote 使用指南。

Q: 收不到新反馈
A: 多为 WebSocket 问题，刷新浏览器页面即可。

Q: MCP 没被调用
A: 确认 MCP 工具为绿灯，可反复开关 MCP 等待重连。

一般

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

Q: 客户端（如 Cursor）自己超时
A: 本工具无超时，但客户端常有 5–10 分钟限制，可缩短单次反馈时间或调整客户端设置。

Q: UV Cache 占用大
A: 使用 uv cache clean 或项目内 python scripts/cleanup_cache.py，详见 Cache 管理。

授权

MIT - 详见 LICENSE