Ask Human MCP

🚀 ask-human mcp 🧑‍💻🤝🤖

stop your ai from hallucinating. gives it an escape route when confused instead of false confidence.本项目旨在防止AI产生幻觉，当AI陷入困惑时，为其提供一种解决方案，避免其盲目自信地给出错误答案。

🚀 快速开始

pip install ask-human-mcp
ask-human-mcp

.cursor/mcp.json 配置如下：

{
  "mcpServers": {
    "ask-human": { "command": "ask-human-mcp" }
  }
}

重启 Cursor 即可使用。

✨ 主要特性

• 安装便捷：通过 pip install ask-human-mcp 即可完成安装。
• 零配置、跨平台：无需复杂配置，支持多种操作系统。
• 实时反馈：实时监控文件，可即时获得反馈。
• 多代理支持：轻松应对多个AI代理。
• 安全保障：具备锁机制和资源限制，避免系统崩溃。
• 完整记录：以 Markdown 格式保存完整的问答历史，方便调试。

📦 安装指南

从 PyPI 安装

pip install ask-human-mcp

从源代码安装

git clone https://github.com/masonyarbrough/ask-human-mcp.git
cd ask-human-mcp
pip install -e ".[dev]"
ask-human-mcp

💻 使用示例

基础用法

answer = await ask_human(
    "what database should i use for this project?",
    "building a chat app with 1000+ concurrent users"
)

高级用法

列出待回答的问题

pending_questions = list_pending_questions()

获取问答会话统计信息

qa_stats = get_qa_stats()

📚 详细文档

工作原理

1. AI 遇阻：AI 遇到难题时，调用 ask_human(question, context) 方法。
2. 问题记录：问题会以唯一 ID 记录在 ask_human.md 文件中。
3. 人工回答：将文件中的 "PENDING" 替换为实际答案。
4. AI 继续：AI 获取答案后继续进行编码。

配置选项

命令行配置

ask-human-mcp --help
ask-human-mcp --port 3000 --host 0.0.0.0  # http 模式
ask-human-mcp --timeout 1800               # 30 分钟超时
ask-human-mcp --file custom_qa.md          # 自定义问答文件
ask-human-mcp --max-pending 50             # 最大并发问题数
ask-human-mcp --max-question-length 5000   # 最大问题长度
ask-human-mcp --rotation-size 10485760     # 文件达到 10MB 时进行轮转

不同客户端配置

Cursor（本地）

{
  "mcpServers": {
    "ask-human": {
      "command": "ask-human-mcp",
      "args": ["--timeout", "900"]
    }
  }
}

Cursor（HTTP）

{
  "mcpServers": {
    "ask-human": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "ask-human": {
      "command": "ask-human-mcp"
    }
  }
}

限制说明

平台支持

• Windows：全面支持，具备原生文件锁机制。
• macOS：全面支持，使用 fsevents 进行文件监控。
• Linux：全面支持，使用 inotify 进行文件监控。

🔧 技术细节

功能特性

• 零配置：开箱即用，无需复杂设置。
• 文件监控：保存答案时可即时响应。
• 超时处理：避免问题长时间挂起。
• 并发处理：支持多个 AI 代理同时提问。
• 持久日志：以 Markdown 格式保存完整的问答历史。
• 跨平台：支持 Windows、macOS 和 Linux 系统。
• MCP 标准：可与任何 MCP 客户端配合使用。
• 输入验证：对输入进行大小限制和清理。
• 文件轮转：自动归档大文件。
• 资源限制：防止拒绝服务攻击和内存泄漏。
• 健壮解析：能够优雅处理格式错误的 Markdown 文件。

安全机制

• 输入清理：移除控制字符并验证大小。
• 文件锁：防止并发访问导致文件损坏。
• 安全权限：创建具有受限访问权限的文件。
• 资源限制：防止内存耗尽和拒绝服务攻击。
• 路径验证：确保文件写入安全位置。

📄 许可证

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

贡献说明

欢迎任何形式的贡献！

问题反馈

使用 GitHub 问题跟踪器报告 bug 或提出功能请求，也可以直接发邮件至：mason@kallro.com。

反馈时请提供以下信息：

• Python 版本
• 操作系统
• MCP 客户端（如 Cursor、Claude Desktop 等）
• 错误信息或日志
• 复现步骤

版本历史

请参阅 CHANGELOG.md 了解版本历史。

致谢

• model context protocol 提供了优秀的标准。
• anthropic 提供了 Claude 和 MCP 支持。
• cursor 实现了 MCP 集成。
• 所有提供反馈的贡献者和用户。