Skip to main content
Glama
@humsana/mcp-server

@humsana/mcp-server

@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)

Situation

Result

You're fresh, running ls

✅ Runs normally

You're fresh, running rm -rf

⚠️ Warning, allowed

You're tired, running rm -rf

⛔ BLOCKED — requires override

AI Rewrite Protection (safe_write_file)

Situation

Result

AI writes new file

✅ Allowed

AI rewrites 10 lines

✅ Allowed

You're tired + AI deletes 30+ lines

⚠️ Warning

You're tired + AI deletes 50+ lines

⛔ BLOCKED — saved for review


Related MCP server: FlowCheck MCP Server

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

Tool

Purpose

get_user_state

Get current stress, focus, fatigue levels

check_dangerous_command

Check if a command would be blocked

safe_execute_command

Execute shell commands with interlock

safe_write_file

Write files with AI rewrite protection


Files & Folders

Path

Purpose

~/.humsana/signals.db

Behavioral data from daemon

~/.humsana/config.yaml

Your configuration

~/.humsana/activity.json

Activity heartbeats (for fatigue)

~/.humsana/audit.json

Safety event log

~/.humsana/pending_reviews/

Blocked AI writes saved here


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

Available Tools

4 tools
humsana_check_dangerous_commandA

Check if a command is dangerous and whether the user is too fatigued to safely run it. Use this before helping with potentially destructive operations like rm -rf, DROP TABLE, git push --force, kubectl delete, terraform destroy, etc.

Inputs: command (required).

humsana_get_user_stateA

Get the user's current behavioral state including stress level, focus level, fatigue, and response style recommendations. Use this at the start of conversations to adapt your communication style.

Inputs: no named parameters.

humsana_safe_execute_commandA

Execute a shell command with Humsana Cognitive Interlock protection. This is THE tool for running commands - it blocks dangerous commands when the user is fatigued, requires override confirmation for high-risk operations, and logs all safety events. Use this instead of any other shell/bash tool.

Inputs: command (required), override_reason.

humsana_safe_write_fileA

Write content to a file with Humsana Cognitive Interlock protection. This tool prevents AI from making large destructive rewrites when the user is fatigued. If AI tries to delete/rewrite >30 lines while user is tired, it blocks the write and saves to a review folder. Use this for ALL file write operations.

Inputs: content (required), filepath (required), override_reason.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: retrieving user state, checking command risk, executing commands with protection, and writing files with protection. No overlap or ambiguity between them.

    Naming Consistency5/5

    All tools follow a consistent 'humsana_' prefix with a verb_noun pattern: get_user_state, check_dangerous_command, safe_execute_command, safe_write_file. Naming is uniform and predictable.

    Tool Count5/5

    The server has 4 tools, a well-scoped set for its stated purpose of providing safety-aware operations. Each tool is essential and there is no bloat or missing trivial add-ons.

    Completeness4/5

    The surface covers the core lifecycle: state check, pre-flight risk check, command execution, and file writes. Minor gaps exist such as no dedicated safe delete/read tools, but these can be worked around via safe_execute_command.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides real-time security risk assessment for AI coding prompts, analyzing potential dangers, blast radius, and complexity before code execution in Cursor.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A runtime gate for coding agents. Blocks the tool calls that wreck a repo (force-push main, rm -rf, secret exfiltration, CI wipe) and lets normal build and commit work through. Machine-checked git-branch core (z3); the rest is high-precision heuristics. Tested on 3,790 real CI commands, 0 false blocks.
      1
      MIT