AI: "I'll use PostgreSQL for this project"   ← assumption
         ↓
check_assumption("Use PostgreSQL", risk="medium", category="architecture")
         ↓
Kontrol Freek: query past decisions → detect contradictions → score risk
         ↓
├─ Low risk + past approval match  → ✅ Auto-approve, continue
├─ Medium risk / new decision      → 🔍 Notify human (Telegram / Slack / elicit)
└─ Contradiction or critical risk  → ⛔ Block + require explicit approval

pip install kontrol-freek-mcp

git clone https://github.com/berkbayri/kontrol-freek-mcp.git
cd kontrol-freek-mcp
python install.py

pip install -e ".[full]"   # Full: Telegram + Web + sentence-transformers embeddings
pip install -e ".[lite]"   # Lite: Telegram + Web (no embeddings)
pip install -e .           # Minimal: stdio only

{
  "mcpServers": {
    "kontrol-freek": {
      "command": "kontrol-freek",
      "env": {
        "KF_HMAC_SECRET": "your-secret",
        "KF_TELEGRAM_TOKEN": "your-bot-token",
        "KF_TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

{
  "mcpServers": {
    "kontrol-freek": {
      "command": "python",
      "args": ["-m", "kontrol_freek_mcp"],
      "env": {
        "KF_HMAC_SECRET": "your-secret"
      }
    }
  }
}

{
  "project_name": "my-app",
  "telegram_token": "bot-token-override",
  "telegram_chat_id": "chat-id-override",
  "slack_webhook": ""
}

kontrol-freek --transport streamable-http --port 8765

{
  "mcpServers": {
    "kontrol-freek": {
      "transport": "streamable-http",
      "url": "http://localhost:8765/mcp"
    }
  }
}

/kf approve <id>              Approve a pending assumption
/kf reject <id> [reason]      Reject with an optional reason
/kf answer <id> <answer>      Answer a direct question

AI calls check_assumption(assumption, risk_level, category, project_root)
    │
    ├── Query SQLite for similar past decisions
    ├── Compute semantic similarity score (TF-IDF or sentence-transformers)
    ├── Run contradiction analysis
    ├── Policy engine → auto_approve / review / block
    │
    ├── auto_approve    → log, return status: "auto_approved"
    ├── pending_review  → log, return status: "pending_review" (non-blocking)
    │                     optionally notify Telegram/Slack in background
    └── block           → log, return status: "blocked"
                          if Telegram/Slack configured → notify + wait (3 min max)
                          │
                          ├── Telegram bot    (/kf approve/reject <id>)
                          └── Slack webhook   (text instructions)

{
  "action": "human_approve",
  "text": "Use PostgreSQL",
  "detail": "Approved via Telegram",
  "decision_id": 42,
  "ts": "2025-01-15T14:30:00Z",
  "prev": "a1b2c3...",
  "hash": "d4e5f6..."
}

from kontrol_freek_mcp.audit import AuditTrail
trail = AuditTrail("~/.kontrol-freek/projects/my-app/audit.jsonl", "your-secret")
valid, count = trail.verify_chain()
print(f"Chain valid: {valid} — {count} entries")

python install.py --status     # Health check
python install.py --uninstall  # Clean removal

kontrol-freek-mcp/
├── src/kontrol_freek_mcp/
│   ├── server.py        # MCP server — 7 tools, 2 resources, 1 prompt
│   ├── db.py            # SQLite decision database
│   ├── policy.py        # Adaptive policy engine (risk scoring, decay)
│   ├── similarity.py    # Semantic similarity (TF-IDF + sentence-transformers)
│   ├── notifier.py      # Multi-channel routing + Telegram polling loop
│   ├── audit.py         # HMAC-SHA256 hash-chain audit trail
│   └── web.py           # FastAPI approval dashboard
├── tests/
├── install.py           # One-command installer
├── pyproject.toml
├── .env.example
└── README.md