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"`

「WOULD have been executed」ではなく、実際の出力が表示されます。

---

設定リファレンス

~/.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	インターロック付きでシェルコマンドを実行します
safe_write_file	AI による書き換えの保護機能を使ってファイルを書き込みます

---

ファイルとフォルダー

パス	用途
~/.humsana/signals.db	デーモンからの行動データ
~/.humsana/config.yaml	設定
~/.humsana/activity.json	アクティビティのハートビート（疲労度の測定用）
~/.humsana/audit.json	安全イベントのログ
~/.humsana/pending_reviews/	ブロックされた AI による書き込みの保存先

---

プライバシー

🔒 すべてローカルで処理されます。

• すべてのデータはお使いのマシン上に保存されます
• ネットワーク通信は行いません（任意の Webhook を除く）
• テレメトリーやトラッキングはありません
• 完全に監査可能なオープンソースコードです

---

トラブルシューティング

「Daemon not running」エラー

ターミナルでデーモンを起動します。

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