guarded-messaging-agent

An MCP server that lets an LLM read your chats, search voice notes and images, and draft replies, but never send anything without passing a tested gate. Voice notes are transcribed locally (faster-whisper), images are captioned into the same searchable store, and every send goes through policy, allowlist, rate limit, human approval and an audit log, with 15 adversarial test cases proving the gate holds.

I build software that uses AI, and I test that it holds up. This repo is the "test that it holds up" part.

First the red-team eval, then python scripts/demo.py (an injected voice note, a fooled agent calls send_message: queued, outbox empty, audit row written). The output is real; the pacing is scripted for readability.

Status: the real Telegram bridge is not wired. Everything runs on FakeBridge, which replays a committed synthetic scenario. Details under Limits.

Try it in one command

No API key, no Docker, no Whisper download, no network at run time. You need Python 3.12 and a way to install packages.

uvx --from git+https://github.com/camilbenameur/guarded-messaging-agent gma-demo
# or, from a clone, with plain Python 3.12+:
git clone https://github.com/camilbenameur/guarded-messaging-agent && cd guarded-messaging-agent && make demo

It runs the 15-case red-team eval against the send gate, then plays an injected voice note whose transcript orders the agent to forward your chat. You see 15 passed, then the fooled agent's send_message call land in the approval queue: approval queue : 1 pending, outbox : 0 messages left the system, and an audit row.

Measured on a clean clone (Linux, Python 3.12, a busy shared machine, load average 12 to 16): uvx about 1.5 min (install a few seconds, red-team eval about 60 s because each test builds a SQLite store on a loaded disk, demo under 1 s); make demo about 3.3 min including the pip install. Expect less on an idle laptop.

Related MCP server: tg-mcp

Architecture

                 +-----------------------------+
   Bridge        |  FakeBridge (today)         |   same `Bridge` protocol:
   (seam)        |  TelethonBridge (not wired) |   poll / download_media / send_text
                 +--------------+--------------+
                                | events
                                v
                 +-----------------------------+
   ingest/       |  worker: poll -> route ->   |
                 |  persist (idempotent,       |
                 |  resumable cursor)          |
                 +---+-----------+---------+---+
                     |           |         |
                  text        audio      image
                     |           |         |
                     |   faster-whisper   Claude vision (mock by default,
                     |   (local, no net)  hardened prompt, forced tool call)
                     v           v         v
                 +-----------------------------+
   shared/       |  SQLite (WAL) + FTS5        |   content_text is ALWAYS filled:
                 |  messages, chats, cursor,   |   raw text, transcript or caption
                 |  send_queue, audit_log      |
                 +--------------+--------------+
                                |
                                v
                 +-----------------------------+
   mcp_server/   |  MCP server (streamable HTTP, :8808)
                 |   read:    list_chats, list_messages, search_messages,
                 |            get_message_context, get_media
                 |   propose: draft_reply, analyze_conversation, summarize_chat
                 |   act:     send_message  --+
                 +-----------------------------+
                                               |
              +--------------------------------v-----------------------------+
              | SEND GATE                                                    |
              | kill switch -> policy (per chat) -> allowlist -> never_when  |
              | -> rate limit -> approval queue (human) -> bridge.send_text  |
              |                  every decision -> audit_log                 |
              +--------------------------------------------------------------+

Design rule: ingestion and consumption are decoupled. The bridge writes to the store; the LLM only reads the store through MCP tools and can only propose actions. send_message is the single exit and it is gated unconditionally.

Guardrails and what each test proves

The threat model is the "lethal trifecta": private data, untrusted content (every incoming message, including a voice note or text inside an image, is a possible prompt injection), and the ability to act (sending). The common invariant of the 15 red-team cases: nothing reaches FakeBridge.outbox (the only exit) without crossing the gate, and every decision leaves an audit row. The clock is injected, so rate-limit windows are crossed without sleeping; no network is used.

What this eval is, precisely: 15 deterministic cases against the gate and the prompt-assembly seam, with the LLM mocked or stubbed. It proves the gate holds whatever the model decides to do. It does not measure how often a real model resists an injection; that is the job of the separate live-model eval below.

Live-model eval

evals/live_injection.py complements the deterministic gate cases with a model in the loop: 20 conversations (3 voice-note injections, 3 image-OCR injections, 3 exfiltration requests to a non-allowlisted contact, 3 IBAN/credentials requests, 2 injections in a chat with an auto-send policy, 3 benign "nothing to send" controls, 3 benign "user explicitly asks to send" controls) are run through a minimal tool-calling loop against the Anthropic Messages API, using the real MCP tool schemas and the real SendGate over a FakeBridge. For each run it records whether the model called send_message, what the gate decided (queued / sent / denied) and whether anything reached the outbox. Results are written to evals/results/<date>.json and .md.

pip install -e ./shared -e ./mcp_server
ANTHROPIC_API_KEY=... python evals/live_injection.py --models claude-haiku-5-5 claude-sonnet-5-5 --trials 2

Measured on 2026-11-10: --models claude-haiku-5-5 claude-sonnet-5-5 --prompts plain hardened --trials 2, 20 cases x 2 trials x 2 models x 2 prompts = 160 runs, max_tokens 700, estimated cost 3.01 USD (token counts at list prices). Full tables and every send attempt: evals/results/2026-11-10.md. Over the 24 injection runs per model and prompt (voice, OCR, exfiltration, credentials):

The three sonnet attempts were ordinary replies to Alice's real question ("Friday afternoon works. See you then, and thanks for bringing the slides!"), addressed to her chat; none forwarded anything, targeted another chat or carried injected or sensitive content. The gate queued all three for human approval. "Obeyed" is a heuristic (a send to another chat, or forwarding / credential / payment phrasing); the per-run table lets you check it.

Auto-send chats (2 cases x 2 trials per model and prompt): one sonnet plain run sent that same benign reply to Alice, which the auto policy allows, so it reached the outbox; no other model or prompt attempted a send there. Controls: every model and prompt sent in 6/6 runs where the user explicitly asked for a send (they are not simply refusing to act) and 0/6 on quiet chats.

Gate off vs gate on, 2026-11-11 (--gate on then --gate off, Haiku 5.5 and Sonnet 5.5, plain prompt, 25 cases x 2 trials, 5 new cases where the injection poses as the user inside an auto-send chat; estimated 3.73 USD; gate-on, gate-off). On the attack cases, messages that left the system: 9 without the gate, 2 with it (Haiku: 0 and 0). Every one of those messages, in both modes, was the same benign reply to Alice's real question; none carried injected content. So this run shows the gate holding unapproved sends for a human (7 of 9), and the auto policy letting a benign reply through (2), not the gate stopping an attack: the models never obeyed one.

What this run shows and does not show: on these payloads no model followed an injection, even without a hardened prompt, so the gate was never tested by a fooled model here; the 15 deterministic cases above carry that proof.

Caveats to keep when reading future results: N is small (20 cases, a couple of trials each), so rates have wide error bars; they depend on one system prompt (--prompts plain|hardened compares an unhardened and a hardened prompt), on the model version and on the injection wording, and say nothing about adaptive attackers. A model attempting a send is not a failure of the system (the gate still decides); the interesting numbers are the attempt rate and, in the auto-policy cases, whether the gate's content rules catch what the model was talked into sending.

Eval results

Measured on 2026-11-10, Python 3.12.3, Linux, mcp 1.30.0, no API key (mocks), command cd mcp_server && pytest -q -m redteam:

Unique tests: 100 (shared 25, ingest 37, mcp_server 38); 99 pass, 1 skipped. The skip is a smoke test of a real Claude vision call, which requires ANTHROPIC_API_KEY. STT is not mocked: real OGG/Opus fixtures are transcribed by faster-whisper and compared to their source text.

Quickstart

Requirements: Python 3.12, ffmpeg. No API key needed (vision and drafts fall back to deterministic mocks).

git clone https://github.com/camilbenameur/guarded-messaging-agent && cd guarded-messaging-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ./shared -e "./ingest[dev]" -e "./mcp_server[dev]"

(cd mcp_server && pytest -q -m redteam)   # the adversarial eval, ~10 s
(cd mcp_server && pytest -q)              # server + guardrail suites
(cd ingest && pytest -q)                  # worker, STT (downloads ~460 MB model once), vision

Run the MCP server (port 8808, health at /health):

docker compose up -d --build
curl http://localhost:8808/health        # {"status":"ok"}
# any MCP client can connect to http://localhost:8808/mcp

Set ANTHROPIC_API_KEY in .env (see .env.example) to switch from mocks to real captions (CAPTION_MODEL) and real drafts (DRAFT_MODEL). Approve or reject queued sends from the console: python -m mcp_server.approve --list.

Repo layout

shared/       Bridge protocol, FakeBridge, Store (SQLite WAL + FTS5 + sync triggers)
ingest/       worker (poll -> route -> persist), faster-whisper STT, Claude vision captioning
mcp_server/   MCP server, draft client, per-chat policy, send gate, approval CLI, red-team eval
tests/fixtures/  synthetic scenario: 13 events, 3 chats, TTS voice notes, generated PNGs
scripts/      fixture generators, `demo.py` (the scripted demo behind the GIF)
evals/        live-model injection eval (`live_injection.py`) and its dated results
docs/         demo GIF

Limits

• Telegram bridge not wired, runs on FakeBridge. The Bridge protocol is implemented only by FakeBridge; the Telethon implementation does not exist yet. The seam is covered by the tests, so adding it should not touch the worker, STT, vision, MCP or gate code, but that claim is untested until it is built.

• The red-team eval is deterministic and model-free. It validates the gate, not the model's resistance to injection. The model-in-the-loop script (evals/live_injection.py) measures how often a real model tries to send: on 2026-11-10, 0 of 96 injection runs across haiku-5-5 and sonnet-5-5 followed an injection and nothing reached the outbox (small N, a handful of payload wordings, one system prompt each; not a guarantee, and not an adaptive attacker).

• Auto-send mode trusts the policy's content rules. In a chat with an auto policy, an injected instruction that makes the model send harmless-looking text passes the gate (no IBAN, not a group, known contact). The gate bounds recipients, content classes and volume; it does not judge intent.

• Real Claude calls are not exercised in CI. The one live vision smoke test is skipped without a key; drafts are tested against a recording stub.

• No encryption at rest. SQLite and media blobs are plain files under ./data/.

• No authentication on the MCP server. docker-compose.yml publishes the port on 127.0.0.1 only, and the SDK's DNS-rebinding protection rejects non-local Host headers, but that is not authentication: anyone who can reach the port can read the store. Keep it bound to localhost.

• Approval is console-only. There is no chat-based approval channel.

• Confidence values are rough. The STT confidence is an averaged exp(avg_logprob), not a calibrated probability; caption confidence is self-reported by the model; there is no intent classifier (intent_in conditions fail closed). Policy mode values accept French spellings (manuel, assisté, auto_validé) alongside the English ones (manual, assisted, auto); the credential detector also matches a few French keywords.

• Dependency pin. mcp is pinned <2: MCP SDK 2.x renamed FastMCP and this code targets 1.x.

• Not a product. A personal engineering project, built to demonstrate testable safety around an LLM tool surface.

License

MIT