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许可证。