使用说明

项目简介

这是一个基于Model Context Protocol (MCP) 构建的服务器，专为AI助手设计，使其能够在需要人类帮助解决歧义、获取偏好或弥补知识盲点时，通过本地操作系统原生的GUI对话框直接向用户提问。它使得AI能够暂停复杂任务，获取必要的上下文信息后继续执行，实现更高效、更智能的人机协作工作流。

主要功能点

• AI向人类提问： 允许AI通过调用标准工具向人类用户提出具体问题，并提供相关的背景信息。
• 原生GUI对话框： 在用户操作系统上显示原生的、用户友好的对话框，提供清晰的问题和输入区域。
• 跨平台支持： 支持macOS (osascript), Linux (zenity), 和 Windows (tkinter)，并提供自动回退机制。
• 获取人类反馈： 接收用户在对话框中的文本输入，并将反馈结果返回给AI。
• 超时及取消处理： 支持设置响应超时时间，并能处理用户取消对话框的情况。
• 标准MCP协议： 通过JSON-RPC over Stdio或SSE协议与MCP客户端（如Cursor）通信。

安装步骤

最推荐（尤其是Cursor用户）的方式是使用'uvx'，无需手动安装：

1. 确保您的MCP客户端（如Cursor）支持'uvx'自动安装。
2. 直接在客户端的MCP配置中添加该服务器配置即可，客户端会自动下载并运行（见下文配置说明）。

如果您需要手动安装，可以使用 pip：

1. 创建并激活一个Python虚拟环境（推荐）。
2. 运行命令 'pip install ask-human-for-context-mcp' 安装包。

服务器配置

此MCP服务器不是独立运行的，而是被一个MCP客户端（如Cursor）启动和管理的。您需要在您的MCP客户端的配置文件（例如Cursor的 '~/.cursor/mcp.json'）中添加如下配置条目。

该配置描述了客户端如何启动并连接到此服务器：

• 服务器名称 (server name): 您给这个MCP服务器实例起的名字，例如 '"ask-human-for-context"'。AI在调用工具时会用到这个名字。
• 启动命令 (command): 客户端用来启动服务器进程的可执行文件路径。
  • 如果使用 uvx 自动安装，命令通常是 '"uvx"'。
  • 如果手动使用 pip 安装到虚拟环境，命令是虚拟环境的 'bin' 或 'Scripts' 目录下的可执行文件路径，例如 '"/path/to/venv/bin/ask-human-for-context-mcp"'。
  • 如果手动使用 pip 安装到全局环境，命令可能是 '"ask-human-for-context-mcp"' (取决于PATH设置)。
• 启动参数 (args): 传递给启动命令的参数列表。
  • 如果使用 uvx，通常是 '["ask-human-for-context-mcp", "--transport", "stdio"]'。第一个参数是 uvx 要运行的包或脚本名，后续参数是传递给服务器本身的。
  • 如果直接运行可执行文件或模块，参数通常是 '["--transport", "stdio"]'。
  • '"--transport stdio"' 参数告诉服务器使用标准输入输出来与客户端通信，这是许多桌面客户端（如Cursor）的默认方式。

基本使用方法

作为用户，您主要通过AI助手间接使用此服务器。当AI助手需要您的输入时，它会调用服务器提供的工具。您会看到一个系统原生的弹窗，显示AI提出的问题和背景信息。您只需在输入框中键入您的回答，然后点击确认即可。您的回答会自动发送回AI，使其能够继续执行任务。

作为AI或集成开发者，您可以通过调用名称为 'ask-human-for-context' 服务器上的 'asking_user_missing_context' 工具来使用此功能。这个工具接受两个参数：

• 'question' (必需): AI向用户提出的具体问题（字符串）。
• 'context' (可选): 提供给用户的背景信息，解释为何需要此信息（字符串）。

工具执行后会返回一个字符串，表示用户响应的状态（成功响应、取消、超时或错误）以及用户的具体输入（如果成功）。