humsana-mcp

@humsana/mcp-server

面向 AI 辅助开发的认知安全。

🛡️ “终端的酒精检测仪。”

当你疲劳时，Humsana 会阻止你运行危险命令，或接受大规模 AI 代码重写。可以把它想象成工业安全联锁装置，只不过保护的是你的大脑。

功能介绍

命令保护（safe_execute_command）

情况	结果
你状态良好，运行 ls	✅ 正常运行
你状态良好，运行 rm -rf	⚠️ 发出警告，允许运行
你很疲劳，运行 rm -rf	⛔ 已阻止 — 需要覆盖限制

AI 重写保护（safe_write_file）

情况	结果
AI 写入新文件	✅ 允许
AI 重写 10 行	✅ 允许
你很疲劳 + AI 删除 30 行以上	⚠️ 发出警告
你很疲劳 + AI 删除 50 行以上	⛔ 已阻止 — 已保存以供审核

---

快速开始

1. 安装守护进程

pip install humsana-daemon
humsana start

让它在终端标签页中持续运行。

2. 安装 MCP 服务

npm install -g @humsana/mcp-server

3. 配置 Claude Desktop

创建/编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

4. 重启 Claude Desktop

退出（Cmd+Q）并重新打开。

5. 测试

询问 Claude：“我当前的状态如何？”

---

执行模式

为确保安全，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 Desktop（Cmd+Q，然后重新打开）

步骤 3： 先使用安全命令进行测试：

Run `echo "live mode working"`

你应该会看到实际输出，而不是“本来会执行”。

---

配置参考

创建 ~/.humsana/config.yaml：

# === EXECUTION MODE ===
# 'dry_run' (default) - Simulates commands, nothing executed
# 'live' - Actually executes commands and writes files
execution_mode: dry_run

# === FATIGUE THRESHOLDS ===
# Fatigue level (0-100) above which dangerous commands are blocked
fatigue_threshold: 70

# Lines removed to trigger warning (when fatigued)
write_warn_threshold: 30

# Lines removed to trigger hard block (when fatigued)
write_block_threshold: 50

# === CUSTOM PATTERNS ===
# Additional dangerous commands to block
deny_patterns:
  - "aws ec2 terminate"
  - "docker rm -f"

# === NOTIFICATIONS ===
# Webhook for Slack/PagerDuty (fires on safety overrides)
webhook_url: https://hooks.slack.com/services/XXX/YYY/ZZZ

---

覆盖限制流程

命令被阻止时，请说：

OVERRIDE SAFETY PROTOCOL: [reason]

示例：

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

此操作会记录到 ~/.humsana/audit.json，并发送到你的 webhook。

---

可用工具

工具	用途
get_user_state	获取当前压力、专注度和疲劳程度
check_dangerous_command	检查命令是否会被阻止
safe_execute_command	在联锁保护下执行 Shell 命令
safe_write_file	写入文件并防护 AI 重写

---

文件和文件夹

路径	用途
~/.humsana/signals.db	守护进程收集的行为数据
~/.humsana/config.yaml	你的配置
~/.humsana/activity.json	活动心跳（用于判断疲劳程度）
~/.humsana/audit.json	安全事件日志
~/.humsana/pending_reviews/	被阻止的 AI 写入内容会保存在此处

---

隐私

🔒 100% 本地运行。

• 所有数据都保留在你的计算机上
• 不会进行网络调用（可选的 webhook 除外）
• 不收集遥测数据，不跟踪用户
• 完全可审计的开源代码

---

故障排除

“守护进程未运行”错误

在终端中启动守护进程：

humsana start

命令未执行

检查运行模式：

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

如果显示 dry_run，请将其改为 live 并重启 Claude。

MCP 无法连接

确认 Claude Desktop 的配置路径：

• Mac：~/Library/Application Support/Claude/claude_desktop_config.json
• 确保 dist/index.js 的路径正确

---

许可证

MIT