Humsana MCP

@humsana/mcp-server

Cognitive Security for AI-assisted development.

🛡️ "The breathalyzer for your terminal."

Humsana prevents you from running dangerous commands or accepting large AI code rewrites when you're fatigued. Think of it as an industrial safety interlock, but for your brain.

What It Does

Command Protection (safe_execute_command)

AI Rewrite Protection (safe_write_file)

---

Quick Start

1. Install the Daemon

pip install humsana-daemon

humsana start

Keep this running in a terminal tab.

2. Install the MCP Server

npm install -g @humsana/mcp-server

3. Configure Claude Desktop

Create/edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{

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

4. Restart Claude Desktop

Quit (Cmd+Q) and reopen.

5. Test It

Ask Claude: "What's my current state?"

---

Execution Modes

Humsana starts in dry-run mode for safety. Commands are simulated, not executed.

Dry-Run Mode (Default)

✅ [DRY RUN] Safety check passed.

Command: kubectl delete pods This command WOULD have been executed. (Execution skipped: dry_run mode active)

Switching to Live Mode

When you trust the system, enable real execution:

Step 1: Create/edit ~/.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

Step 2: Restart Claude Desktop (Cmd+Q, reopen)

Step 3: Test with a safe command first:

Run `echo "live mode working"`

You should see actual output instead of "WOULD have been executed."

---

Configuration Reference

Create ~/.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 Protocol

When blocked, say:

OVERRIDE SAFETY PROTOCOL: [reason]

Example:

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

This is logged to ~/.humsana/audit.json and sent to your webhook.

---

Tools Available

---

Files & Folders

---

Privacy

🔒 100% Local.

• All data stays on your machine
• No network calls (except optional webhook)
• No telemetry, no tracking
• Fully auditable open-source code

---

Troubleshooting

"Daemon not running" error

Start the daemon in a terminal:

humsana start

Commands not executing

Check your mode:

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

If it says dry_run, change to live and restart Claude.

MCP not connecting

Verify your Claude Desktop config path:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Ensure the path to dist/index.js is correct

---

License

MIT