Human In The Loop MCP Server

人在环MCP服务器

  ](https://badge.fury.io/py/hitl-mcp-server)

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

demo

🚀 特性

💬 交互式对话工具

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

🎨 现代跨平台图形用户界面

• 视窗：现代Windows 11风格的界面，具有美观的造型、悬停效果和增强的视觉设计
• macOS：使用SF Pro Display字体和适当的窗口管理的原生macOS体验
• Linux：具有现代风格和系统字体的Ubuntu兼容GUI

⚡ 高级功能

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

📦 安装和设置

使用uvx快速安装（推荐）

使用此MCP服务器的最简单方法是 uvx:

# Install and run directly
uvx hitl-mcp-server

# Or use the underscore version
uvx hitl_mcp_server

手动安装

1. 从PyPI安装:

   pip install hitl-mcp-server

1. 运行服务器:

   hitl-mcp-server
   # or
   hitl_mcp_server

开发安装

1. 克隆存储库:

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

1. 在开发模式下安装:

   pip install -e .

🔧 Claude桌面配置

要将此服务器与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": []
    }
  }
}

配置文件位置

• 视窗: %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="Project Setup",
    prompt="Enter your project name:",
    default_value="my-project",
    input_type="text"
)

2. get_user_choice

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

参数：

• title （str）：对话框窗口标题
• prompt （str）：问题/提示文本
• choices （列表\[str\]）：可用选项
• allow_multiple （bool）：允许多选（默认值：false）

示例用法：

result = await get_user_choice(
    title="Framework Selection",
    prompt="Choose your preferred framework:",
    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="Code Review",
    prompt="Please provide your detailed feedback:",
    default_value=""
)

4. show_confirmation_dialog

在继续之前，请确认是/否。

参数：

• title （str）：对话框窗口标题
• message （str）：确认消息

示例用法：

result = await show_confirmation_dialog(
    title="Delete Confirmation",
    message="Are you sure you want to delete these 5 files? This action cannot be undone."
)

5. show_info_message

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

参数：

• title （str）：对话框窗口标题
• message （str）：信息消息

示例用法：

result = await show_info_message(
    title="Process Complete",
    message="Successfully processed 1,247 records in 2.3 seconds!"
)

6. health_check

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

示例用法：

status = await health_check()
# Returns detailed platform and functionality information

📋 响应格式

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

{
    "success": true,
    "user_input": "User's response text",
    "cancelled": false,
    "platform": "windows",
    "input_type": "text"
}

常见响应字段：

• success （bool）：操作是否成功完成
• cancelled （bool）：用户是否取消了对话
• platform （str）：操作系统平台
• error （str）：如果操作失败，则显示错误消息

工具特定字段：

• get_user_input: user_input, input_type
• 用户选择: selected_choice, selected_choices, allow_multiple
• get_multiline_input: user_input, character_count, line_count
• show_确认_对话框: confirmed, response
• show_info_message: acknowledged

🧠 人工智能集成的最佳实践

何时使用人机交互工具

1. 模糊要求 -当用户说明不清楚时
2. 决策点 -当您需要用户在有效选项之间进行偏好选择时
3. 创意输入 -用于主观选择，如设计或内容风格
4. 敏感操作 -在执行潜在的破坏性行动之前
5. 缺少信息 -当您需要未提供的具体细节时
6. 质量反馈 -对中间结果进行用户验证

集成模式示例

文件操作

# Get target directory
location = await get_user_input(
    title="Backup Location",
    prompt="Enter backup directory path:",
    default_value="~/backups"
)

# Choose backup type
backup_type = await get_user_choice(
    title="Backup Options",
    prompt="Select backup type:",
    choices=["Full Backup", "Incremental", "Differential"]
)

# Confirm before proceeding
confirmed = await show_confirmation_dialog(
    title="Confirm Backup",
    message=f"Create {backup_type['selected_choice']} backup to {location['user_input']}?"
)

if confirmed['confirmed']:
    # Perform backup
    await show_info_message("Success", "Backup completed successfully!")

内容创建

# Get content requirements
requirements = await get_multiline_input(
    title="Content Requirements",
    prompt="Describe your content requirements in detail:"
)

# Choose tone and style
tone = await get_user_choice(
    title="Content Style",
    prompt="Select desired tone:",
    choices=["Professional", "Casual", "Friendly", "Technical"]
)

# Generate and show results
# ... content generation logic ...
await show_info_message("Content Ready", "Your content has been generated successfully!")

🔍 故障排除

常见问题

GUI未出现

• 验证您是在桌面环境中运行的（不是无头服务器）
• 检查是否安装了tkinter： python -c "import tkinter"
• 运行健康检查： health_check() 诊断问题的工具

权限错误（macOS）

• 在“系统首选项”>“安全与隐私”>“辅助功能”中授予辅助功能权限
• 允许Python控制您的计算机
• 授予权限后重新启动终端

导入错误

• 确保软件包已安装： pip install hitl-mcp-server
• 检查Python版本兼容性（要求>=3.8）
• 验证虚拟环境激活（如果使用）

Claude桌面集成问题

• 检查配置文件语法和位置
• 配置更改后重新启动Claude Desktop
• 验证是否安装了uvx： pip install uvx
• 手动测试服务器： uvx hitl-mcp-server

对话框超时

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

调试模式

通过运行具有环境变量的服务器启用详细日志记录：

HITL_DEBUG=1 uvx hitl-mcp-server

🏗️ 发展

项目结构

Human-In-the-Loop-MCP-Server/
├── human_loop_server.py       # Main server implementation
├── pyproject.toml            # Package configuration
├── README.md                 # Documentation
├── LICENSE                   # MIT License
├── .gitignore               # Git ignore rules
└── demo.gif                 # Demo animation

贡献

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

代码质量

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

🌍 平台支持

视窗

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

macOS

• 原生macOS体验
• SF Pro显示系统字体
• 适当的窗口管理和重点
• 无障碍权限处理

Linux

• Ubuntu/Debian兼容
• 系统字体的现代风格
• 跨分发GUI支持
• 最低依赖性要求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🤝 致谢

• 内置于 FastMCP 框架
• 用途 派丹蒂克 用于数据验证
• 由tkinter提供支持的跨平台GUI
• 受到人类与人工智能协作需求的启发

🔗 链接

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

📊 使用统计

• 交叉平台的：Windows、macOS、Linux
• Python支持: 3.8, 3.9, 3.10, 3.11, 3.12+
• GUI框架：tkinter（内置于Python中）
• 线程安全：全面的并发操作支持
• 响应时间：\<100ms对话框初始化
• 内存使用：\<50MB典型操作

______________________________________________________________________

由以下材料制成❤️ 面向人工智能社区-通过直观的交互将人类和人工智能联系起来