Human-In-the-Loop MCP Server

一个强大的模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够通过直观的GUI对话与人类互动。该服务器通过提供实时用户输入工具、选择、确认和反馈机制，弥合了自动化AI流程与人类决策之间的差距。

🚀 特性

💬 交互式对话工具

• 文本输入：从用户获取文本、数字或其他数据，并进行验证
• 多选：提供单选或多选选项
• 多行输入：收集较长的文本内容、代码或详细描述
• 确认对话框：在执行操作之前询问是/否决定
• 信息消息：显示通知、状态更新和结果
• 健康检查：监控服务器状态和GUI可用性

🎨 现代跨平台GUI

• Windows：具有漂亮样式、悬停效果和增强视觉设计的现代Windows 11风格界面
• macOS：使用SF Pro Display字体和正确窗口管理的本地macOS体验
• Linux：兼容Ubuntu的GUI，具有现代样式和系统字体

⚡ 高级特性

• 非阻塞操作：所有对话都在单独线程中运行，以防止阻塞
• 超时保护：可配置的5分钟超时防止挂起操作
• 平台检测：针对每个操作系统自动优化
• 现代UI设计：具有平滑动画和悬停效果的美观界面
• 错误处理：全面的错误报告和优雅恢复
• 键盘导航：完整的键盘快捷键支持（Enter/Escape）

📦 安装与设置

使用uvx快速安装（推荐）

使用此MCP服务器最简单的方法是通过uvx：

# 直接安装并运行
uvx hitl-mcp-server

# 或使用下划线版本
uvx hitl_mcp_server

手动安装

1. 从PyPI安装：

   pip install hitl-mcp-server
   

2. 运行服务器：

   hitl-mcp-server
   # 或
   hitl_mcp_server
   

开发安装

1. 克隆仓库：

   git clone https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server.git
   cd Human-In-the-Loop-MCP-Server
   

2. 开发模式安装：

   pip install -e .
   

🔧 Claude Desktop配置

要将此服务器与Claude Desktop一起使用，请在您的claude_desktop_config.json中添加以下配置：

使用uvx（推荐）

{
  "mcpServers": {
    "human-in-the-loop": {
      "command": "uvx",
      "args": ["hitl-mcp-server"]
    }
  }
}

使用pip安装

{
  "mcpServers": {
    "human-in-the-loop": {
      "command": "hitl-mcp-server",
      "args": []
    }
  }
}

配置文件位置

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

macOS用户的重要注意事项

注意：您可能需要在系统偏好设置 > 安全与隐私 > 辅助功能中允许Python控制您的计算机，以便GUI对话框正常工作。

更新配置后，请重启Claude Desktop以使更改生效。

🛠️ 可用工具

1. get_user_input

从用户获取单行文本、数字或其他数据。

参数：

• title (str)：对话窗口标题
• prompt (str)：问题/提示文本
• default_value (str)：预填值（可选）
• input_type (str)："text"、"integer"或"float"（默认："text"）

示例用法：

result = await get_user_input(
    title="项目设置",
    prompt="请输入项目名称：",
    default_value="my-project",
    input_type="text"
)

2. get_user_choice

向用户提供多个选项供选择。

参数：

• title (str)：对话窗口标题
• prompt (str)：问题/提示文本
• choices (List[str])：可用选项
• allow_multiple (bool)：是否允许多选（默认：false）

示例用法：

result = await get_user_choice(
    title="框架选择",
    prompt="请选择您偏好的框架：",
    choices=["React", "Vue", "Angular", "Svelte"],
    allow_multiple=False
)

3. get_multiline_input

收集较长的文本内容、代码或详细描述。

参数：

• title (str)：对话窗口标题
• prompt (str)：问题/提示文本
• default_value (str)：预填文本（可选）

示例用法：

result = await get_multiline_input(
    title="代码审查",
    prompt="请提供您的详细反馈：",
    default_value=""
)

4. show_confirmation_dialog

在继续之前询问是/否确认。

参数：

• title (str)：对话窗口标题
• message (str)：确认消息

示例用法：

result = await show_confirmation_dialog(
    title="删除确认",
    message="您确定要删除这5个文件吗？此操作无法撤销。"
)

5. show_info_message

显示信息、通知或状态更新。

参数：

• title (str)：对话窗口标题
• message (str)：信息消息

示例用法：

result = await show_info_message(
    title="过程完成",
    message="成功处理了1,247条记录，耗时2.3秒！"
)

6. health_check

检查服务器状态和GUI可用性。

示例用法：

status = await health_check()
# 返回详细的平台和功能信息

📋 响应格式

所有工具返回结构化的JSON响应：

{
    "success": true,
    "user_input": "用户的响应文本",
    "cancelled": false,
    "platform": "windows",
    "input_type": "text"
}

常见响应字段：

• success (bool)：操作是否成功完成
• cancelled (bool)：用户是否取消了对话
• platform (str)：操作系统平台
• error (str)：如果操作失败，返回错误消息

特定工具字段：

• get_user_input：user_input，input_type
• get_user_choice：selected_choice，selected_choices，allow_multiple
• get_multiline_input：user_input，character_count，line_count
• show_confirmation_dialog：confirmed，response
• show_info_message：acknowledged

🧠 AI集成的最佳实践

何时使用人机协作工具

1. 模糊需求 - 当用户指令不清楚时
2. 决策点 - 当需要用户在有效替代方案之间做出选择时
3. 创意输入 - 对于主观选择如设计或内容风格
4. 敏感操作 - 在执行潜在破坏性动作之前
5. 缺失信息 - 当需要未提供的具体细节时
6. 质量反馈 - 获取用户对中间结果的验证

示例集成模式

文件操作

# 获取目标目录
location = await get_user_input(
    title="备份位置",
    prompt="请输入备份目录路径：",
    default_value="~/backups"
)

# 选择备份类型
backup_type = await get_user_choice(
    title="备份选项",
    prompt="选择备份类型：",
    choices=["完全备份", "增量", "差异"]
)

# 确认后再继续
confirmed = await show_confirmation_dialog(
    title="确认备份",
    message=f"创建{backup_type['selected_choice']}备份到{location['user_input']}？"
)

if confirmed['confirmed']:
    # 执行备份
    await show_info_message("成功", "备份已完成！")

内容创作

# 获取内容要求
requirements = await get_multiline_input(
    title="内容要求",
    prompt="详细描述您的内容要求："
)

# 选择语气和风格
tone = await get_user_choice(
    title="内容风格",
    prompt="选择所需语气：",
    choices=["专业", "随意", "友好", "技术"]
)

# 生成并展示结果
# ... 内容生成逻辑 ...
await show_info_message("内容就绪", "您的内容已成功生成！")

🔍 故障排除

常见问题

GUI未出现

• 确保您正在桌面环境中运行（而非无头服务器）
• 检查tkinter是否已安装：python -c "import tkinter"
• 运行健康检查：health_check()工具以诊断问题

权限错误（macOS）

• 在系统偏好设置 > 安全与隐私 > 辅助功能中授予访问权限
• 允许Python控制您的计算机
• 授予权限后重启终端

导入错误

• 确保已安装包：pip install hitl-mcp-server
• 检查Python版本兼容性（>=3.8必需）
• 如果使用虚拟环境，请确保激活

Claude Desktop集成问题

• 检查配置文件语法和位置
• 配置更改后重启Claude Desktop
• 确保uvx已安装：pip install uvx
• 手动测试服务器：uvx hitl-m-服务器

对话超时

• 默认超时时间为5分钟（300秒）
• 如果用户没有响应，对话将返回cancelled=true
• 触发对话时确保用户在场

调试模式

通过运行服务器时设置环境变量启用详细日志：

HITL_DEBUG=1 uvx hitl-mcp-server

🏗️ 开发

项目结构

Human-In-the-Loop-MCP-Server/
├── human_loop_server.py       # 主服务器实现
├── pyproject.toml            # 包配置
├── README.md                 # 文档
├── LICENSE                   # MIT许可证
├── .gitignore               # Git忽略规则
└── demo.gif                 # 演示动画

贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行适当测试的更改
4. 遵循代码风格指南（Black，Ruff）
5. 添加类型提示和文档字符串
6. 提交带有详细描述的拉取请求

代码质量

• 格式化：Black（行长度：88）
• 代码检查：Ruff，具有全面规则集
• 类型检查：MyPy，严格配置
• 测试：Pytest用于单元和集成测试

🌍 平台支持

Windows

• Windows 10/11，具有现代UI样式
• 增强视觉设计，包括悬停效果
• 集成Segoe UI和Consolas字体
• 完整键盘导航支持

macOS

• 本地macOS体验
• 使用SF Pro Display系统字体
• 正确的窗口管理和焦点
• 处理辅助功能权限

Linux

• 兼容Ubuntu/Debian
• 使用系统字体的现代样式
• 跨发行版的GUI支持
• 最小依赖要求

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

🤝 致谢

• 使用FastMCP框架构建
• 使用Pydantic进行数据验证
• 跨平台GUI由tkinter驱动
• 受到人类与AI协作需求的启发

🔗 链接

• PyPI包：https://pypi.org/project/hitl-mcp-server/
• 仓库：https://github.com/GongRzhe/Human-In-the--Loop-MCP-Server
• 问题：报告错误或请求功能
• MCP协议：了解模型上下文协议

📊 使用统计

• 跨平台：Windows，macOS，Linux
• Python支持：3.8，3.9，3.10，3.11，3.12+
• GUI框架：tkinter（Python自带）
• 线程安全：完全并发操作支持
• 响应时间：<100毫秒对话初始化
• 内存使用：<50MB典型操作

---

为AI社区制作 - 通过直观交互连接人类和AI