Humsana MCP

🚀 @humsana/mcp-server

Humsana的@humsana/mcp-server為人工智能輔助開發提供認知安全保障。它就像終端的“酒精測試儀”，能在你疲勞時防止你運行危險命令或接受大型AI代碼重寫，如同工業安全聯鎖裝置保護你的大腦。

🚀 快速開始

1. 安裝守護進程

pip install humsana-daemon
humsana start

請讓此進程在終端標籤頁中保持運行。

2. 安裝MCP服務器

npm install -g @humsana/mcp-server

3. 配置Claude桌面應用

創建或編輯~/Library/Application Support/Claude/claude_desktop_config.json文件，內容如下：

{
  "mcpServers": {
    "humsana": {
      "command": "node",
      "args": ["/path/to/humsana-mcp/dist/index.js"]
    }
  }
}

4. 重啟Claude桌面應用

使用快捷鍵（Cmd + Q）退出應用，然後重新打開。

5. 進行測試

向Claude詢問：“What's my current state?”

✨ 主要特性

命令保護 (safe_execute_command)

AI重寫保護 (safe_write_file)

💻 使用示例

基礎用法

模擬執行命令（默認幹運行模式）

✅ [DRY RUN] Safety check passed.
Command: `kubectl delete pods`
This command WOULD have been executed.
(Execution skipped: dry_run mode active)

切換到即時執行模式

步驟1：創建或編輯~/.humsana/config.yaml文件：

# Change this from 'dry_run' to 'live'
execution_mode: live

# Optional: adjust thresholds
fatigue_threshold: 70
write_warn_threshold: 30
write_block_threshold: 50

步驟2：重啟Claude桌面應用（Cmd + Q，重新打開） 步驟3：先使用一個安全命令進行測試：

Run `echo "live mode working"`

你應該能看到實際輸出，而不是 “WOULD have been executed”。

📚 詳細文檔

執行模式

Humsana默認以幹運行模式啟動，此模式下命令僅被模擬執行，不會實際運行。

幹運行模式（默認）

✅ [DRY RUN] Safety check passed.
Command: `kubectl delete pods`
This command WOULD have been executed.
(Execution skipped: dry_run mode active)

切換到即時模式

當你信任系統時，可以啟用實際執行功能： 步驟1：創建或編輯~/.humsana/config.yaml文件：

# Change this from 'dry_run' to 'live'
execution_mode: live

# Optional: adjust thresholds
fatigue_threshold: 70
write_warn_threshold: 30
write_block_threshold: 50

步驟2：重啟Claude桌面應用（Cmd + Q，重新打開） 步驟3：先使用一個安全命令進行測試：

Run `echo "live mode working"`

你應該能看到實際輸出，而不是 “WOULD have been executed”。

配置參考

創建~/.humsana/config.yaml文件，內容如下：

# === 執行模式 ===
# 'dry_run' (默認) - 模擬命令，不執行任何操作
# 'live' - 實際執行命令並寫入文件
execution_mode: dry_run

# === 疲勞閾值 ===
# 疲勞等級（0 - 100），超過此值將阻止危險命令
fatigue_threshold: 70

# 疲勞時，刪除多少行代碼觸發警告
write_warn_threshold: 30

# 疲勞時，刪除多少行代碼觸發硬阻止
write_block_threshold: 50

# === 自定義模式 ===
# 要阻止的其他危險命令
deny_patterns:
  - "aws ec2 terminate"
  - "docker rm -f"

# === 通知 ===
# Slack/PagerDuty的Webhook（安全覆蓋時觸發）
webhook_url: https://hooks.slack.com/services/XXX/YYY/ZZZ

覆蓋協議

當命令被阻止時，輸入以下內容：

OVERRIDE SAFETY PROTOCOL: [原因]

示例：

OVERRIDE SAFETY PROTOCOL: P0 production outage, need to restart pods

此操作將記錄到~/.humsana/audit.json文件中，併發送到你的Webhook。

可用工具

文件和文件夾

隱私保護

🔒 100%本地處理

• 所有數據都保存在你的機器上
• 除可選的Webhook外，無網絡調用
• 無遙測數據，無跟蹤
• 完全可審計的開源代碼

故障排除

“Daemon not running” 錯誤

在終端中啟動守護進程：

humsana start

命令無法執行

檢查你的執行模式：

cat ~/.humsana/config.yaml | grep execution_mode

如果顯示 dry_run，將其更改為 live 並重啟Claude。

MCP無法連接

驗證Claude桌面應用的配置路徑：

• 蘋果系統：~/Library/Application Support/Claude/claude_desktop_config.json
• 確保 dist/index.js 的路徑正確

📄 許可證

本項目採用MIT許可證。