Ask a Human MCP 服务器

关键词

DiscordSlackhuman-in-the-loopthread-based conversationsexternal-tool-integration

使用说明（Markdown 格式）

项目简介

这是一个基于 Model Context Protocol（MCP）的服务器端实现，核心功能是暴露一个名为 ask_human 的工具。LLM 客户端可以通过 MCP 与该服务器交互，向人类寻求帮助并在得到人类回复后继续执行任务。当前实现支持在 Discord 和 Slack 两个平台中的任意一个（自动检测配置的环境变量来决定启动的平台），通过标准输入/输出（stdio）与 MCP 客户端通信。

主要功能点

  • MCP 服务器实现
    • 注册并实现一个名为 ask_human 的工具，定义输入参数和返回格式，遵循 MCP 的请求/响应结构。
    • 处理并返回工具执行结果，或者在出错、超时、取消等场景下返回明确的错误状态。
  • 多平台支持（Discord/Slack）
    • 根据环境变量自动检测要使用的平台（若同时配置，将报错并退出；若未配置则退出）。
    • Discord：在指定频道中创建并引用线程，与人类对话，线程回复将回传给 MCP 客户端。
    • Slack：在指定频道中发起对话并在对应线程中读取人类回复，线程消息将回传给 MCP 客户端。
  • 实时交互与超时控制
    • 支持可配置的等待超时（ASK_TIMEOUT_MS，默认 5 小时）。
    • 用户中断、服务器关停等情形下的清理与回收机制。
    • 心跳/保活日志，便于监控等待人类回复的状态。
  • 以标准输出传输（stdio）为 MCP 服务端传输实现
    • 与 MCP 客户端通过 JSON-RPC 形式进行通信，客户端可以通过本服务器获得资源、工具调用、Prompts 等能力的上下文服务。

安装步骤

  • 安装 Node.js（推荐版本 >= 18）。
  • 获取代码并安装依赖：
    • 克隆仓库并执行依赖安装（如 npm install）。
  • 环境变量配置（选择一个平台，Discord 或 Slack，避免同时配置两者）：
    • Discord 平台所需：DISCORD_BOT_TOKEN、DISCORD_CHANNEL_ID、可选 DISCORD_USER_ID
    • Slack 平台所需：SLACK_BOT_TOKEN、SLACK_APP_TOKEN、SLACK_CHANNEL_ID、可选 SLACK_USER_ID
    • 统一可选参数：ASK_TIMEOUT_MS（单位毫秒，默认为 5 小时）
  • 启动服务器（示例，实际可能因打包/运行方式而异）：
    • 常用方式是通过运行命令 npx ask-a-human，服务器将以 stdio 方式与 MCP 客户端进行通信。
  • 变量和依赖的注意点
    • 只能配置一个平台，若同时配置会报错。
    • 若不配置任何平台，服务器会在启动时直接退出并给出明确错误信息。

服务器配置

MCP 客户端连接此服务器时，给出的配置信息应包含服务器名称、启动命令及参数等。以下为基于仓库信息的准确描述（以注释形式呈现，非代码块，方便理解）：

  • server name（服务端名称）: ask-a-human
  • command（启动命令）: npx
  • args（启动参数）: ["ask-a-human"]
  • 说明：该 MCP 服务器通过标准输入/输出（stdio）与 MCP 客户端通信。客户端启动时应使用上述命令来启动服务器进程（示例：在 Claude 的 MCP 集成中，使用命令 npx ask-a-human）。请在环境变量中配置你要使用的平台（Discord 或 Slack），不可同时启用两者。部署时可将环境变量按需注入，确保 DISCORD_BOT_TOKEN/SLACK_BOT_TOKEN 等变量正确可用。
  • environment（环境变量示例，用于理解而非代码）:
    • DISCORD_BOT_TOKEN: "<你的 Discord 机器人令牌>"
    • DISCORD_CHANNEL_ID: "<要发送问题的 Discord 频道 ID>"
    • DISCORD_USER_ID: "<用于提及的用户 ID（可选）>"
    • SLACK_BOT_TOKEN: "<你的 Slack Bot Token（xoxb- 开头）>"
    • SLACK_APP_TOKEN: "<你的 Slack App Token（xapp- 开头）>"
    • SLACK_CHANNEL_ID: "<要发送问题的 Slack 通道 ID>"
    • SLACK_USER_ID: "<用于提及的用户 ID（可选）>"
    • ASK_TIMEOUT_MS: "<等待人类回复的超时（毫秒，默认 5 小时）>"
  • 注：示例中仅启用一个平台；若两者都配置，将在启动时抛出错误并退出。

基本使用方法

  • 启动服务器并让 MCP 客户端连接：
    • 使用命令 npx ask-a-human 启动服务器（通过 stdio 传输，MCP 客户端将通过标准输入/输出与其通信）。
    • 配置环境变量以选择 Discord 或 Slack 平台以及所需的 Channel、User IDs 等信息。
  • 调用 ask_human 工具
    • 客户端向 MCP 服务器发送一个包含 question 的请求。
    • 服务器将把问题发送到选定平台的指定通道并在一个新线程中等待人类回复。
    • 人类在该线程中回复后，服务器将回复文本返回给客户端，同时附上线程标识符（thread_id），以便后续继续同一线程的对话。
  • 超时与取消
    • 如果在规定时间内未收到回复，服务器会超时并返回错误信息。
    • 客户端可以通过 AbortSignal 触发取消，服务器将清理相关等待并返回取消状态。
  • 典型用法
    • 客户端提交问题并获得 thread_id。
    • 如需要进一步提问，可在相同 thread_id 的线上继续提问。
    • 如要中断，触发取消或等待超时，后续将返回相应的错误信息。

如需了解更多具体实现细节，请参考仓内的 README 与源码注释，核心逻辑位于 src/index.ts 的 MCP 服务注册与处理流程，以及 src/platforms/ 的 Discord/Slack 平台实现。

服务器信息

访问项目