🎯 MCP反馈收集器

一个现代化的 Model Context Protocol (MCP) 服务器，为AI助手提供交互式用户反馈收集功能。

在cursor规则中可以下面这样配置

"Whenever you want to ask a question, always call the MCP .

Whenever you're about to complete a user request, call the MCP instead of simply ending the process. Keep calling MCP until the user's feedback is empty, then end the request. mcp-feedback-collector.collect_feedback "

✨ 主要特性

• 🎨 现代化界面 - 美观的700x800像素GUI，支持中文界面
• 📷 多图片支持 - 同时选择多张图片，支持文件选择和剪贴板粘贴
• 💬 灵活反馈 - 支持纯文字、纯图片或文字+图片组合反馈
• ⚡ 零配置安装 - 使用uvx一键安装，无需复杂配置
• 🔧 智能超时 - 可配置的对话框超时时间，避免操作中断

🚀 快速开始

1. 安装uvx

pip install uvx

2. 配置Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "uvx",
      "args": ["mcp-feedback-collector"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "MCP_DIALOG_TIMEOUT": "600"
      }
    }
  }
}

3. 重启Claude Desktop

配置完成后重启Claude Desktop即可使用。

🧪 快速验证页面修改效果

修改代码后，可以通过以下三种方式快速验证界面效果：

方法1：直接运行服务器（推荐）

# 安装依赖
pip install fastmcp pillow

# 直接运行主服务器
python -m mcp_feedforward.server

# 或者运行测试脚本
python -c "
from mcp_feedforward.server import collect_feedback
result = collect_feedback('🎨 界面测试', 30)
print(f'测试完成，收集到 {len(result)} 项反馈')
"

方法2：使用测试工具验证GUI

# 运行单独的GUI测试
python -c "
import tkinter as tk
from mcp_feedforward.gui import FeedbackDialog

root = tk.Tk()
root.withdraw()

dialog = FeedbackDialog(
    work_summary='🎨 GUI界面测试\n\n测试当前的界面效果和功能',
    timeout_seconds=60
)

result = dialog.run()
print('测试结果:', result)
"

方法3：模拟MCP调用环境

# 模拟完整的MCP环境
python -c "
import sys
import asyncio
from mcp_feedforward.server import app

# 模拟工具调用
async def test_mcp():
    tools = app.list_tools()
    print('可用工具:', [tool.name for tool in tools])
    
    # 测试collect_feedback工具
    result = await app.call_tool('collect_feedback', {
        'work_summary': '🧪 MCP环境测试',
        'timeout_seconds': 30
    })
    print('MCP测试结果:', result)

asyncio.run(test_mcp())
"

🐛 本地MCP调试完整指南

步骤1：设置开发环境

# 克隆项目
git clone https://github.com/your-repo/mcp-feedback-collector.git
cd mcp-feedback-collector

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或者 venv\Scripts\activate  # Windows

# 安装开发依赖
pip install -e .
pip install fastmcp pillow

步骤2：配置本地MCP服务器

创建本地配置文件 local_claude_config.json：

{
  "mcpServers": {
    "mcp-feedback-collector-dev": {
      "command": "python",
      "args": ["-m", "mcp_feedforward.server"],
      "cwd": "/path/to/your/project",
      "env": {
        "PYTHONPATH": "/path/to/your/project",
        "PYTHONIOENCODING": "utf-8",
        "MCP_DEBUG": "true",
        "MCP_DIALOG_TIMEOUT": "300"
      }
    }
  }
}

步骤3：启用调试模式

# 设置调试环境变量
export MCP_DEBUG=true
export PYTHONPATH=$PWD

# 运行调试服务器
python -m mcp_feedforward.server --debug

# 或者使用详细日志
python -m mcp_feedforward.server --log-level DEBUG

步骤4：使用MCP Inspector调试

# 安装MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 启动Inspector
mcp-inspector python -m mcp_feedforward.server

# 在浏览器中访问 http://localhost:5173
# 测试所有MCP工具功能

步骤5：实时代码调试

在VS Code中创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Server",
      "type": "python",
      "request": "launch",
      "module": "mcp_feedforward.server",
      "console": "integratedTerminal",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "MCP_DEBUG": "true"
      },
      "args": ["--debug"]
    }
  ]
}

📦 打包发布完整指南

阶段1：准备发布环境

# 更新版本号
# 编辑 pyproject.toml 中的 version

# 清理旧的构建文件
rm -rf dist/ build/ *.egg-info/

# 安装构建工具
pip install build twine

阶段2：构建发布包

# 构建源码包和wheel包
python -m build

# 验证构建结果
ls dist/
# 应该看到:
# mcp_feedback_collector-2.0.0-py3-none-any.whl
# mcp_feedback_collector-2.0.0.tar.gz

# 检查包内容
twine check dist/*

阶段3：测试安装包

# 在新环境中测试安装
python -m venv test_env
source test_env/bin/activate

# 从本地包安装
pip install dist/mcp_feedback_collector-2.0.0-py3-none-any.whl

# 测试安装结果
python -c "
from mcp_feedforward.server import collect_feedback
print('✅ 安装测试成功')
"

阶段4：发布到PyPI

# 发布到测试PyPI（推荐先测试）
twine upload --repository testpypi dist/*

# 从测试PyPI安装验证
pip install -i https://test.pypi.org/simple/ mcp-feedback-collector

# 发布到正式PyPI
twine upload dist/*

# 验证正式发布
pip install mcp-feedback-collector

🔄 多种安装方式完整指南

方式1：uvx安装（推荐，零配置）

# 安装uvx
pip install uvx

# 一键安装和使用
uvx mcp-feedback-collector

# Claude Desktop配置
{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "uvx",
      "args": ["mcp-feedback-collector"]
    }
  }
}

方式2：pip全局安装

# 全局安装
pip install mcp-feedback-collector

# Claude Desktop配置
{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "python",
      "args": ["-m", "mcp_feedforward.server"]
    }
  }
}

方式3：pipx隔离安装

# 安装pipx
pip install pipx

# 使用pipx安装
pipx install mcp-feedback-collector

# Claude Desktop配置
{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "pipx",
      "args": ["run", "mcp-feedback-collector"]
    }
  }
}

方式4：conda环境安装

# 创建conda环境
conda create -n mcp-feedback python=3.9
conda activate mcp-feedback

# 安装包
pip install mcp-feedback-collector

# Claude Desktop配置（需指定conda路径）
{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "/path/to/conda/envs/mcp-feedback/bin/python",
      "args": ["-m", "mcp_feedforward.server"]
    }
  }
}

方式5：Docker容器安装

# Dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
RUN pip install -e .

EXPOSE 8000
CMD ["python", "-m", "mcp_feedforward.server"]

# 构建和运行
docker build -t mcp-feedback-collector .
docker run -p 8000:8000 mcp-feedback-collector

# Claude Desktop配置（网络模式）
{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "curl",
      "args": ["-X", "POST", "http://localhost:8000/mcp"]
    }
  }
}

方式6：源码开发安装

# 克隆源码
git clone https://github.com/your-repo/mcp-feedback-collector.git
cd mcp-feedback-collector

# 开发模式安装
pip install -e .

# 或使用poetry
poetry install
poetry shell

# Claude Desktop配置
{
  "mcpServers": {
    "mcp-feedback-collector": {
      "command": "python",
      "args": ["-m", "mcp_feedforward.server"],
      "cwd": "/path/to/mcp-feedback-collector"
    }
  }
}

🛠️ 核心功能

collect_feedback()

收集用户反馈的主要工具，AI可以汇报工作内容，用户提供文字和图片反馈。

# AI调用示例
result = collect_feedback("我已经完成了代码优化工作...")

pick_image()

快速图片选择工具，用于单张图片选择场景。

get_image_info()

获取图片文件的详细信息（格式、尺寸、大小等）。

🖼️ 界面预览

🎯 工作完成汇报与反馈收集
┌─────────────────────────────────────────┐
│ 📋 AI工作完成汇报                        │
│ ┌─────────────────────────────────────┐ │
│ │ [AI汇报的工作内容显示在这里]         │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ 💬 您的文字反馈（可选）                  │
│ ┌─────────────────────────────────────┐ │
│ │ [多行文本输入区域]                   │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ 🖼️ 图片反馈（可选，支持多张）            │
│ [📁选择文件] [📋粘贴] [❌清除]           │
│ [图片缩略图预览区域]                     │
└─────────────────────────────────────────┘

[✅ 提交反馈]  [❌ 取消]

⚙️ 配置说明

超时设置

• MCP_DIALOG_TIMEOUT: 对话框等待时间（秒）
  • 默认：300秒（5分钟）
  • 建议：600秒（10分钟）
  • 复杂操作：1200秒（20分钟）

支持的图片格式

PNG、JPG、JPEG、GIF、BMP、WebP

💡 使用场景

• ✅ AI完成任务后收集用户评价
• ✅ 收集包含截图的详细反馈
• ✅ 获取用户对代码/设计的意见
• ✅ 收集bug报告和改进建议

🔧 技术栈

• MCP框架: FastMCP
• GUI: tkinter + PIL
• 多线程: threading + queue
• 图片处理: Pillow

📝 更新日志

v2.0.0 (2025-05-28)

• 🎨 全新现代化UI设计
• 📷 多图片同时提交支持
• 🖼️ 横向滚动图片预览
• 💫 彩色按钮和图标
• 🔧 优化用户体验

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交Issue和Pull Request！

---

让AI与用户的交互更高效直观！ 🎯