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 集成。
• 所有提供反饋的貢獻者和用戶。