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

How It Compares

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.

check_assumption response statuses

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

Time-based decision decay

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

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:

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.