AI导哈

HITL MCP服务器

HITL MCP服务器是一个用于Claude Desktop的模型上下文协议服务器，用于管理和处理人工介入（HITL）的升级请求，支持创建、批准、修改和拒绝操作。

  • by AgentMP
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 AgentMP/hitl-mcp-server

使用说明

如何设置Claude Desktop以使用HITL MCP？

  1. 注册AgentMap.ai并获得API密钥：

https://agentmp.ai/createapikey

（您必须使用您的gmail/linkdIn登录）

  1. 获取本地安装Docker镜像并运行它：（Prereq-Docker桌面已安装并正在运行）

docker pull-agentmp/hitl-mcp服务器：最新版本

docker run-d
--名称hitl mcp服务器
--env AGENTMP_API_KEY=“"
--除非停止，否则重新启动
-我
agentmp/hitl mcp服务器

  1. 配置claude_desktop.json

{ “mcpServers”：{ “hitl”：{ “command”：“docker”， “args”：[“exec”、“-i”、“hitl-mcp服务器”、“节点”、“app.js”]， “env”：{ “AGENTMP_API_KEY”（议程_项目_密钥）： “你的钥匙在这里” } } } }

  1. 在Claude上使用Cogito HITL

如。

列出我的所有HITL升级

使用以下详细信息创建HITL升级：

  • 会话ID:“测试会话-123”
  • 代理ID:“克劳德测试代理”
  • 用户提示：“用户想购买高级订阅”
  • 拟议行动：以29.99美元购买“保费计划”
  • 升级到：“karthik6461@gmail.com"
  • 优先级：平急

获取HITL升级“esc-[ID-FROM-TEST-2]”的详细信息

批准HITL升级“esc-[ID-FROM-TEST-2]”，并注明“批准用于测试目的”

为购买50美元的软件许可证创建HITL升级，然后将其修改为75美元的企业许可证

接收推送通知

  1. 要在Slack/Teams/WhatsApp/Telegram上接收Cogito推送通知，请访问https://agentmp.ai/linkchannels，选择您的首选频道并配置频道标识符。

对于Teams和Slack，请联系您的渠道管理员以启用AgentMP bot。

我们正在积极引入其他渠道。如果您需要在防火墙内完全运行此MCP服务器，请联系ops@manifoldsystems.io

  1. 为了在poster上测试Cogito HITL API，您可以在这个repo中使用poster集合-HITL.postmn_collection.json。

请参考此演示视频：

https://github.com/AgentMP/hitl-mcp-server/blob/main/HITLDemoVideo.mp4

HITL MCP服务器

这是怎么一回事？

HITL MCP服务器简化了用户与半自主AI代理的交互。代理可以使用此MCP工具执行任务，并向人类寻求批准、状态更新、反馈、课程更正。用户交互被捕获并存储，以备将来增强。用户交互由最终用户在选择的渠道中进行管理（slack/garts/whatsapp/telegraph/web浏览器）。

为什么？

  1. 标准化交互，不假设用户坐在代理面前等待反馈/批准
  2. 易于使用，无需安装任何新应用程序
  3. 存储和跟踪以供将来参考的结构化交互
  4. 领域无关的实现

为什么是现在？

HITL似乎没有单一的标准。

一个模型上下文协议（MCP）服务器，将Claude Desktop与HITL（Human In The Loop）升级服务连接起来。这允许Claude直接从Claude Desktop创建、批准、修改、拒绝和管理HITL升级。

https://hub.docker.com/r/agentmp/hitl-mcp-server

特性

  • 创建HITL升级：创建带有拟议行动的新升级请求
  • 批准升级：使用可选注释批准待处理的升级
  • 修改升级：使用新操作修改现有升级
  • 拒绝升级：使用可选注释拒绝升级
  • 获取升级详细信息：检索特定升级的详细信息
  • 列表升级：列出已验证用户的所有升级

如果你想自己在本地构建和运行。..

先决条件

  • Node.js 18+
  • Docker（可选，用于容器化部署）
  • AGENTMP API平台密钥
  • Claude桌面应用程序

在Claude桌面上配置Cogito HITL的步骤

（有关步骤，请参阅SetupClaudeDesktop.md）

设置

选项1:Docker部署（推荐）

  1. 克隆或创建项目文件:

    mkdir hitl-mcp-server
cd hitl-mcp-server

  2. 创建所有必需的文件 （app.js、package.json、package-lock.json、Dockerfile、docker compose.yml）

  3. 设置API密钥:

    export AGENTMP_API_KEY="your_api_key_here"

  4. 构建并运行容器:

    chmod +x run.sh
./run.sh

    或手动：

    docker-compose up --build -d

选项2：本地Node.js部署（建议用于故障排除）

  1. 安装依赖项:

    npm install

  2. 设置API密钥:

    export AGENTMP_API_KEY="your_api_key_here"

  3. 使用安装脚本:

    chmod +x setup-local.sh
./setup-local.sh

  4. 或手动运行:

    node app.js

测试您的设置

在配置Claude Desktop之前，请测试您的设置：

# Test the server directly
export AGENTMP_API_KEY="your_api_key"
node app.js

如果工作正常，您应该看到：

🚀 Starting HITL MCP Server...
✅ API Key loaded successfully  
🔧 Setting up request handlers...
✅ HITL MCP Server initialized successfully
🌟 HITL MCP Server running and connected via stdio
📡 Ready to handle HITL requests from Claude Desktop

Claude桌面配置

要将此MCP服务器与Claude Desktop一起使用，您需要在Claude Desktop设置中对其进行配置。

配置步骤

  1. 打开克劳德桌面
  2. 前往设置 → 开发者
  3. 编辑配置 （这将打开您的MCP配置文件）
  4. 添加以下配置:

对于Docker部署：

{
  "mcpServers": {
    "hitl": {
      "command": "docker",
      "args": ["exec", "-i", "hitl-mcp-server", "node", "app.js"],
      "env": {
        "AGENTMP_API_KEY": "your_api_key_here"
      }
    }
  }
}

对于本地Node.js部署：

{
  "mcpServers": {
    "hitl": {
      "command": "node",
      "args": ["/path/to/your/hitl-mcp-server/app.js"],
      "env": {
        "AGENTMP_API_KEY": "your_api_key_here"
      }
    }
  }
}
  1. 保存配置文件
  2. 重新启动克劳德桌面

用法示例

配置后，您可以在Claude Desktop中使用以下命令：

创建HITL升级

Create a HITL escalation for session "sess-123" with agent "my-agent" for a purchase of "Premium License" costing $99.99. Escalate to user "user@example.com" with normal priority.

批准升级

Approve HITL escalation "esc-123456789" with comment "Approved for purchase"

修改升级

Modify HITL escalation "esc-123456789" to change the item to "Enterprise License" and amount to $199.99 with comment "Upgraded to enterprise"

拒绝升级

Reject HITL escalation "esc-123456789" with comment "Budget exceeded"

获取升级详细信息

Get details for HITL escalation "esc-123456789"

列出所有升级

List all my HITL escalations

可用工具

MCP服务器提供以下工具：

  1. create_hitl：创建新的HITL上报请求
  2. 批准_标题：批准HITL升级
  3. 修改标题：使用新操作修改HITL升级
  4. 拒绝_标题：拒绝HITL升级
  5. 获取标题：获取特定HITL升级的详细信息
  6. list_hitls：列出已验证用户的所有HITL升级

环境变量

  • AGENTMP_API_KEY （必需）：AGENTMP平台的API密钥

使用的API端点

服务器使用以下端点与HITL服务通信：

  • POST /api/hitl/mcp -MCP JSON-RPC端点，用于创建、批准、修改
  • POST /api/hitl/{id}/reject -用于拒绝升级的REST端点
  • GET /api/hitl/{id} -用于获取升级详细信息的REST端点
  • GET /api/hitl -用于列表升级的REST端点

故障排除

常见问题

  1. “没有这样的容器：hitl-mcp服务器”

    • Docker容器未运行
    • 运行： docker-compose up -d 开始它
    • 检查： docker ps | grep hitl-mcp-server 验证它是否正在运行
    • 推荐：改用本地Node.js设置

  2. “找不到模块'@modelcontextprotocol/sdk/server/index.js'”

    • 未在本地安装依赖项
    • 运行： npm install 在项目目录中
    • 使用package.json确保你在正确的目录中

  3. 未设置API密钥

    • 确保 AGENTMP_API_KEY 环境变量设置正确
    • 检查API密钥是否有效并具有正确的权限

  4. 容器未启动

    • 检查Docker日志： docker logs hitl-mcp-server
    • 确保在环境中提供API密钥

  5. Claude Desktop无法识别服务器

    • 验证Claude Desktop中的MCP配置语法
    • 检查脚本的路径是否正确（使用绝对路径）
    • 配置更改后重新启动Claude Desktop
    • 对于本地设置，请使用提供的配置格式 setup-local.sh

  6. 连接问题

    • 确保您的网络允许连接到 backend.agentmp.io
    • 检查是否有防火墙规则阻止了连接

日志

对于Docker部署，使用以下命令查看日志：

docker logs hitl-mcp-server

对于本地部署，日志将显示在您运行的终端中 npm start.

安全考虑

  • 安全存储API密钥，切勿将其提交给版本控制
  • 为了安全起见，容器以非root用户身份运行
  • 考虑在生产部署中使用Docker secrets
  • 定期旋转API键

贡献

请随时提交问题和增强请求！

许可证

MIT许可证

设置API密钥

export AGENTMP_API_KEY=“99aeae0e6b4f4107a59d1b59010834cb3eb96ae0f667078f7cc2a296dad27785”

塑造形象

docker构建-t hitl mcp服务器。

运行容器

docker run-d
--名称hitl mcp服务器
--env AGENTMP_API_KEY=“99aeae0e6b4f4107a59d1b59010834cb3eb96ae0f667078f7cc2a296dad27785”
--除非停止，否则重新启动
-我
hitl mcp服务器

太好了！您的Docker容器正在成功运行（ID: 3c10bcf71a6d...).

🎯 Claude桌面配置

打开克劳德桌面→ 设置→ 开发者→ 编辑配置并添加以下内容：##📝 设置步骤

  1. 保存上面的配置 在克劳德桌面
  2. 重新启动克劳德桌面
  3. 使用以下示例进行测试

🧪 简单测试用例

以下是从基本到高级的测试用例：

测试1：列出现有HITL（基本）

List all my HITL escalations

预期：应显示您现有的HITL升级或空列表

测试2：创建HITL升级（核心功能）

Create a HITL escalation with these details:
- Session ID: "test-session-123"  
- Agent ID: "claude-test-agent"
- User prompt: "User wants to purchase premium subscription"
- Proposed action: Purchase of "Premium Plan" for $29.99
- Escalate to: "karthik6461@gmail.com"
- Priority: "normal"

预期：应返回升级ID，如“esc-xxxxx-xxxxx-xxxxx”

测试3：获取HITL详细信息（验证）

Get details for HITL escalation "esc-[ID-FROM-TEST-2]"

用测试2中的实际ID替换[ID-FROM-TEST-2]

测试4：批准HITL（行动）

Approve HITL escalation "esc-[ID-FROM-TEST-2]" with comment "Approved for testing purposes"

测试5：创建和修改（高级）

Create a HITL escalation for a $50 software license purchase, then modify it to $75 enterprise license

🔍 快速验证命令

在Claude中测试之前，请验证您的容器：

# Check container is running
docker ps | grep hitl-mcp-server

# Check container logs
docker logs hitl-mcp-server

# Test the container directly
docker exec -i hitl-mcp-server node -e 'console.log("✅ Container is working!")'

📊 预期的克劳德回应

如果工作正常，克劳德应该：

  • ✅ 自动识别HITL工具
  • ✅ 创建升级和返回ID，如 esc-xxxxx-xxxxx-xxxxx
  • ✅ 显示带有升级详细信息的JSON响应
  • ✅ 处理批准/修改/拒绝操作

🚨 如果出了什么问题

  1. 检查Docker日志: docker logs hitl-mcp-server
  2. 重新启动克劳德桌面 在任何配置更改之后
  3. 验证容器是否正在运行: docker ps | grep hitl-mcp-server

从开始 测试1 （列出HITL）-这是最安全的，并将确认连接是否正常工作！

相关 MCP