{
  "markdown": "# @humsana/mcp-server\n\nCognitive Security for AI-assisted development.\n\n> 🛡️ \"The breathalyzer for your terminal.\"\n\nHumsana 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.\n\n## What It Does\n\n### Command Protection (`safe_execute_command`)\n\n| Situation | Result |\n|-----------|--------|\n| You're fresh, running `ls` | ✅ Runs normally |\n| You're fresh, running `rm -rf` | ⚠️ Warning, allowed |\n| You're tired, running `rm -rf` | ⛔ **BLOCKED** — requires override |\n\n### AI Rewrite Protection (`safe_write_file`)\n\n| Situation | Result |\n|-----------|--------|\n| AI writes new file | ✅ Allowed |\n| AI rewrites 10 lines | ✅ Allowed |\n| You're tired + AI deletes 30+ lines | ⚠️ Warning |\n| You're tired + AI deletes 50+ lines | ⛔ **BLOCKED** — saved for review |\n\n---\n\n## Quick Start\n\n### 1. Install the Daemon\n\n```bash\npip install humsana-daemon\nhumsana start\n```\n\nKeep this running in a terminal tab.\n\n### 2. Install the MCP Server\n\n```bash\nnpm install -g @humsana/mcp-server\n```\n\n### 3. Configure Claude Desktop\n\nCreate/edit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"humsana\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/humsana-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### 4. Restart Claude Desktop\n\nQuit (Cmd+Q) and reopen.\n\n### 5. Test It\n\nAsk Claude: \"What's my current state?\"\n\n---\n\n## Execution Modes\n\nHumsana starts in **dry-run mode** for safety. Commands are simulated, not executed.\n\n### Dry-Run Mode (Default)\n\n```\n✅ [DRY RUN] Safety check passed.\nCommand: `kubectl delete pods`\nThis command WOULD have been executed.\n(Execution skipped: dry_run mode active)\n```\n\n### Switching to Live Mode\n\nWhen you trust the system, enable real execution:\n\n**Step 1:** Create/edit `~/.humsana/config.yaml`:\n\n```yaml\n# Change this from 'dry_run' to 'live'\nexecution_mode: live\n\n# Optional: adjust thresholds\nfatigue_threshold: 70\nwrite_warn_threshold: 30\nwrite_block_threshold: 50\n```\n\n**Step 2:** Restart Claude Desktop (Cmd+Q, reopen)\n\n**Step 3:** Test with a safe command first:\n\n```\nRun `echo \"live mode working\"`\n```\n\nYou should see actual output instead of \"WOULD have been executed.\"\n\n---\n\n## Configuration Reference\n\nCreate `~/.humsana/config.yaml`:\n\n```yaml\n# === EXECUTION MODE ===\n# 'dry_run' (default) - Simulates commands, nothing executed\n# 'live' - Actually executes commands and writes files\nexecution_mode: dry_run\n\n# === FATIGUE THRESHOLDS ===\n# Fatigue level (0-100) above which dangerous commands are blocked\nfatigue_threshold: 70\n\n# Lines removed to trigger warning (when fatigued)\nwrite_warn_threshold: 30\n\n# Lines removed to trigger hard block (when fatigued)\nwrite_block_threshold: 50\n\n# === CUSTOM PATTERNS ===\n# Additional dangerous commands to block\ndeny_patterns:\n  - \"aws ec2 terminate\"\n  - \"docker rm -f\"\n\n# === NOTIFICATIONS ===\n# Webhook for Slack/PagerDuty (fires on safety overrides)\nwebhook_url: https://hooks.slack.com/services/XXX/YYY/ZZZ\n```\n\n---\n\n## Override Protocol\n\nWhen blocked, say:\n\n```\nOVERRIDE SAFETY PROTOCOL: [reason]\n```\n\nExample:\n```\nOVERRIDE SAFETY PROTOCOL: P0 production outage, need to restart pods\n```\n\nThis is logged to `~/.humsana/audit.json` and sent to your webhook.\n\n---\n\n## Tools Available\n\n| Tool | Purpose |\n|------|---------|\n| `get_user_state` | Get current stress, focus, fatigue levels |\n| `check_dangerous_command` | Check if a command would be blocked |\n| `safe_execute_command` | Execute shell commands with interlock |\n| `safe_write_file` | Write files with AI rewrite protection |\n\n---\n\n## Files & Folders\n\n| Path | Purpose |\n|------|---------|\n| `~/.humsana/signals.db` | Behavioral data from daemon |\n| `~/.humsana/config.yaml` | Your configuration |\n| `~/.humsana/activity.json` | Activity heartbeats (for fatigue) |\n| `~/.humsana/audit.json` | Safety event log |\n| `~/.humsana/pending_reviews/` | Blocked AI writes saved here |\n\n---\n\n## Privacy\n\n🔒 **100% Local.**\n\n- All data stays on your machine\n- No network calls (except optional webhook)\n- No telemetry, no tracking\n- Fully auditable open-source code\n\n---\n\n## Troubleshooting\n\n### \"Daemon not running\" error\n\nStart the daemon in a terminal:\n```bash\nhumsana start\n```\n\n### Commands not executing\n\nCheck your mode:\n```bash\ncat ~/.humsana/config.yaml | grep execution_mode\n```\n\nIf it says `dry_run`, change to `live` and restart Claude.\n\n### MCP not connecting\n\nVerify your Claude Desktop config path:\n- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Ensure the path to `dist/index.js` is correct\n\n---\n\n## License\n\nMIT",
  "bytes": 4652,
  "sha": "53a49859db691cb4cb5486ed5f2ab17a278294dbe2eb7929e5edca7e50c92234",
  "repo_slug": "sriramnatrajhen/humsana-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sriramnatrajhen_humsana_mcp_e8b1852c/readme"
}