Kontrol Freek

Kontrol Freek — AI Assumption Firewall for MCP Agents

   

Kontrol Freek is an open-source Model Context Protocol (MCP) server that acts as an AI safety guardrail for autonomous agents. It intercepts AI assumptions before they cause irreversible mistakes, verifies every decision against a persistent project log, detects contradictions, scores risk, and routes human approval requests through Telegram, Slack, or native MCP elicitation — all without blocking your workflow.

Gate every AI assumption. Keep humans in the loop. Prevent agentic mistakes before they happen.

---

Why Kontrol Freek?

AI agents and coding assistants make implicit assumptions constantly — about architecture choices, file locations, API designs, and deployment targets. Without a structured checkpoint, these assumptions silently accumulate into hard-to-reverse technical debt or outright mistakes.

Kontrol Freek solves the human-in-the-loop problem for MCP agents: it sits between your AI agent and every risky decision, comparing new assumptions against your project's history, flagging contradictions, and routing approval requests to you — wherever you are.

Kontrol Freek adds a decision firewall between your AI agent and every risky action:

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

---

Key Features

| Feature | Description | |---------|-------------| | Assumption interception | Catches AI guesses before they execute | | SQLite decision log | Persists every decision per project | | Semantic similarity | Finds related past decisions using TF-IDF or sentence-transformers | | Contradiction detection | Blocks decisions that conflict with approved history | | Risk scoring | Adaptive policy engine — auto-approve low risk, gate high risk | | Time-based decay | Old decisions lose weight; prevents stale approvals | | Telegram polling | Background loop processes /kf approve/reject/answer commands | | Multi-channel routing | ctx.elicit() → Telegram → Slack → Web dashboard | | HMAC-SHA256 audit trail | Cryptographically signed, hash-chained decision log | | Per-project isolation | Each project gets its own DB, audit log, and config | | MCP native | Works with any MCP-compatible client |

---

How It Compares

| Feature | clarify-mcp | CONTINUITY | mcp-human-loop | VantaGate | Kontrol Freek | |---------|:-----------:|:----------:|:--------------:|:---------:|:-----------------:| | ctx.elicit() support | ✅ | ❌ | ❌ | ❌ | ✅ | | SQLite decision log | ❌ | ✅ | ❌ | ❌ | ✅ | | Risk scoring | ❌ | ❌ | ✅ | ❌ | ✅ | | Semantic similarity | ❌ | ❌ | ❌ | ❌ | ✅ | | Contradiction detection | ❌ | ❌ | ❌ | ❌ | ✅ | | Cryptographic audit trail | ❌ | ❌ | ❌ | ✅ | ✅ | | Time-based decision decay | ❌ | ❌ | ❌ | ❌ | ✅ | | Telegram interactive approval | ❌ | ❌ | ❌ | ❌ | ✅ | | Per-project isolation | ❌ | ❌ | ❌ | ❌ | ✅ | | Adaptive policy engine | ❌ | ❌ | Basic | Static | Adaptive |

---

Installation

pip (recommended)

pip install kontrol-freek-mcp

One-command setup (macOS / Linux / Windows)

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

The installer:

1. Installs the Python package
2. Generates a .env with a random HMAC secret
3. Registers a system service (auto-start on boot, crash recovery)
4. Registers the MCP server with compatible clients automatically

Manual install

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

---

Configuration

MCP client config

Add to your MCP client's server configuration (mcpServers block):

{
  "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"
      }
    }
  }
}

Or using python -m if installed without the entry point:

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

Per-project config (.kontrol-freek.json)

Place this file in your project root to override global credentials and set a project name:

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

Per-project config is detected automatically — no restart required when the file changes.

HTTP server mode (remote / multi-user)

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

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

---

Telegram Setup

1. Message @BotFather → /newbot → copy the token
2. Start a DM with your bot or add it to a group
3. Get your chat ID: https://api.telegram.org/bot<TOKEN>/getUpdates
4. Set credentials in .env or .kontrol-freek.json

Telegram commands

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

Kontrol Freek runs a background long-poll loop — no webhook setup needed. Commands are processed in real time while the MCP server is running.

---

MCP Tools Reference

Always pass project_root as your current working directory so decisions are isolated per project.

| Tool | When to use | |------|-------------| | check_assumption | At every decision point — architecture, file paths, API choices, etc. | | confirm_decision | To record a finalized decision; set is_irreversible=True for destructive actions | | ask_human | When genuinely uncertain — prompts human via Telegram/Slack/elicitation | | query_decisions | At the start of a task — load prior context before making new decisions | | revoke_decision | When a past decision is no longer valid — prevents it from influencing future auto-approvals | | get_firewall_stats | View approval rates, total decisions, and activity by category | | healthcheck | Verify DB, audit chain, and notification channel health | | setup_project | Initialize per-project config on first use |

check_assumption response statuses

| Status | Meaning | Agent should… | |--------|---------|---------------| | auto_approved | Low risk, matches prior approved decision | Proceed | | pending_review | Human review recommended (architecture / security / deployment) | Proceed with caution — call confirm_decision() when task is done | | blocked | Contradiction detected or critical risk | Stop — do not proceed without explicit human approval | | human_approved | Human approved via Telegram/Slack | Proceed | | human_rejected | Human rejected | Stop and reconsider |

---

How It Works

Decision flow

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)

Policy rules

| Condition | Verdict | |-----------|---------| | critical risk | ⛔ Block — always requires human approval | | Contradiction with approved decision | ⛔ Block | | Category: security, architecture, deployment | 🔍 Human review | | Low risk + ≥78% similarity + prior approval | ✅ Auto-approve | | high risk | 🔍 Human review | | Default | 🔍 Human review |

Time-based decision decay

Older decisions carry less weight in similarity matching, preventing stale approvals from auto-approving new assumptions:

| Age | Weight | |-----|--------| | 0 days | 1.00 | | 30 days | 0.72 | | 90 days | 0.37 | | 180 days | 0.14 |

Cryptographic audit trail

Every action is written to an HMAC-SHA256 signed, hash-chained JSONL file:

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

Verify audit chain integrity:

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

---

Auto-Start & Crash Recovery

python install.py configures an OS-native service:

| Platform | Mechanism | Details | |----------|-----------|---------| | macOS | LaunchAgent | ~/Library/LaunchAgents/com.kontrol-freek.mcp.plist — starts at login, KeepAlive restarts on crash | | Linux | systemd user service | ~/.config/systemd/user/kontrol-freek.service — Restart=on-failure, persists across logouts via loginctl enable-linger | | Windows | Task Scheduler | schtasks — triggers at logon |

The wrapper script includes exponential backoff (5s → 10s → 20s → ..., max 10 restarts).

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

---

Project Structure

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

---

License

MIT — free to use, modify, and distribute.