convez.ai
MCP ServerIntegração & APIsAvançado
ebongard

Renfield MCP Email Ingest

ebongard/renfield-mcp-email-ingest

Ingestão de anexos por IMAP IDLE com isolamento de credenciais e REST push

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que monitora caixas de email via IMAP IDLE (event-driven) e envia automaticamente anexos para o backend Renfield via REST. Implementa isolamento de credenciais, deduplicação e roteamento por esfera, permitindo ingestão de documentos sem polling ou bundles na imagem backend.

Instalação

$npx convez-ai ebongard/renfield-mcp-email-ingest

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de ingestão de documentos em sistemas Renfield a partir de emails
  • Monitoramento event-driven de caixas de email sem polling
  • Isolamento seguro de credenciais IMAP em daemon dedicado

Veredito

Solução robusta e bem-arquitetada para ingestão de anexos via email, com tratamento sofisticado de falhas (transientes vs. fatais), deduplicação e agregação inteligente de resultados. Exige familiaridade com IMAP, async Python e infraestrutura containerizada, mas resolve um problema real em pipelines de documento.

README

A tradução para o português deste README ainda está na fila.

renfield-mcp-email-ingest

Event-driven email-attachment auto-ingest for Renfield — the email analog of renfield-mcp-filesystem. A dedicated watcher holds the IMAP credentials the backend must not, watches one or more mailboxes via IMAP IDLE (event-driven, never polling), extracts the attachments from each new message, and pushes them into Renfield over REST. The backend reuses its existing folder-ingest pipeline (dedup, KB filing, Paperless leg) and owns the sphere routing (which mailbox files at which owner/tier/KB).

 new mail ──IDLE──▶ extract attachments ──▶ POST /api/email-ingest/document (Bearer)
   (IMAP)            (gate: ext + size)        │
                                               ├─ 200 {status} ──▶ move the EMAIL by the
                                               │                   aggregated per-attachment
                                               │                   status (Verarbeitet / Fehler / leave)
                                               ├─ 401/403 ──▶ fatal: stop the mailbox, notify
                                               └─ 503/err ──▶ leave UNSEEN, bounded retry

Why a dedicated service (not a backend-bundled MCP)

  • Credential isolation. IMAP usernames/passwords live in this pod's Secret, never in the backend image. The backend only ever sees pushed bytes + a routing mailbox_id.
  • Event-driven lifecycle. IMAP IDLE needs a long-lived async loop per mailbox — that is a daemon, not a per-request stdio MCP subprocess.
  • Server-authoritative sphere. This watcher sends ONLY a mailbox_id. The backend resolves mailbox_id → owner/tier/knowledge-base. A leaked push token therefore cannot escalate a mailbox's filing tier.

The 4-state push contract

Identical to folder-ingest (the backend reuses the same ingest_document + IngestStatus). The backend returns, per attachment, one of ingested | duplicate | retry | failed (all HTTP 200), plus 401/403 (fatal token error) and 503 (disabled / worker down → retry). See contract.py (EMAIL_INGEST_CONTRACT_VERSION is mirrored on both sides — bump together).

Because one email fans out into N attachment pushes, the watcher aggregates the per-attachment results into a single decision for the email (engine.py::aggregate):

email outcomewhenaction
processed≥1 attachment ingested/duplicate (no transient, no fatal)move → processed_folder
failedreal docs all terminally rejected, OR every attachment gate-rejectedmove → failed_folder + notify
leaveany attachment transient (retry / 503 / network)leave UNSEEN, bounded backoff retry
skipthe email has no ingestable attachmentsmark \Seen, leave in place
(fatal)any 401/403stop the mailbox, notify — never move

Gate-rejected attachments (wrong extension, oversize, empty) are treated as noise (logos, signatures) and never fail an email on their own — only a backend push failed, or an email whose attachments are all rejected, sends the email to failed_folder. Re-pushing a whole email is idempotent: the backend dedups on (content-hash, kb), so an already-ingested attachment returns duplicate.

Configuration

Global settings come from env; the watched mailboxes come from a mounted mailboxes.yaml (a ConfigMap), reloaded at runtime when it changes.

envdefaultmeaning
RENFIELD_URL— (required)Renfield backend base URL
RENFIELD_INGEST_TOKEN— (required)the email-ingest Bearer token (POST /api/email-ingest/token)
EMAIL_MAILBOXES_YAML—path to the mounted mailboxes.yaml
EMAIL_ALLOWED_EXTENSIONSpdf,docx,…comma list of allowed attachment extensions
EMAIL_MAX_FILE_SIZE_MB50per-attachment size ceiling
EMAIL_PUSH_TIMEOUT_SECONDS120push HTTP timeout
EMAIL_IDLE_RENEW_SECONDS1500re-issue IDLE within this (RFC 2177 < ~30 min)
EMAIL_NOTIFY_WEBHOOK_URL—optional: POST failure/disconnect notifications
EMAIL_MCP_HOST / EMAIL_MCP_PORT0.0.0.0 / 8080streamable-http MCP bind

mailboxes.yaml (see config/mailboxes.example.yaml) holds, per mailbox, ONLY the IMAP connection + a routing id + the move-folder names. No owner/tier/KB — those are server-authoritative. IMAP credentials are referenced by env-var name (kept in a Secret), never inlined.

Run

pip install .
RENFIELD_URL=http://localhost:8000 \
RENFIELD_INGEST_TOKEN=... \
EMAIL_MAILBOXES_YAML=./config/mailboxes.yaml \
BUCHHALTUNG_IMAP_USER=... BUCHHALTUNG_IMAP_PASS=... \
renfield-mcp-email-ingest

Validate config + credentials + the gate WITHOUT side effects (no push/move):

renfield-mcp-email-ingest-scan            # all mailboxes
renfield-mcp-email-ingest-scan buchhaltung

MCP tools (read-only ops visibility)

  • list_mailboxes — configured mailboxes + connection state.
  • list_unseen(mailbox) — UIDs of unprocessed messages in a mailbox's inbox.

The auto-push watcher is the primary job and needs no MCP call to function.

Deploy (k8s)

k8s/ has the Deployment (single replica, Recreate — two replicas would double-IDLE + double-push), ConfigMap (mailboxes.yaml), Service, and a Secret template. Image: registry.treehouse.x-idra.de/renfield/email-ingest-mcp.

Tests

pip install -e ".[dev]"
python -m pytest -o asyncio_mode=auto -q              # unit (no IMAP server needed)
# live IMAP loop (fetch/move/IDLE), opt-in — run on a host with reachable IMAP:
EMAIL_LIVE_IMAP_HOST=... EMAIL_LIVE_IMAP_USER=... EMAIL_LIVE_IMAP_PASS=... \
  python -m pytest tests/test_live_imap.py -o asyncio_mode=auto -v

The content/aggregation/transport logic is fully unit-tested with a fake provider + a mock HTTP transport; the live IMAP IDLE/fetch/move loop is validated by the opt-in live test (mirrors the filesystem repo's live inotify test).

Known limitations (validate during live bring-up)

  • UIDVALIDITY. Messages are keyed by IMAP UID. If a server bumps the inbox's UIDVALIDITY (mailbox recreated / index rebuilt), in-flight UIDs would address different messages. Rare; the UID-based design is the standard one and a fresh reconnect re-SEARCHes, but a validity-change flush is not yet implemented — confirm behavior against the target server during bring-up.
  • Servers without RFC 6851 MOVE and without UIDPLUS UID EXPUNGE. The watcher COPYs to the target folder and flags the original \Deleted \Seen, but deliberately does NOT issue a bare EXPUNGE (that would purge all \Deleted mail in the inbox). On such a server the originals accumulate \Deleted in the inbox until the user's own client expunges. Modern servers (Dovecot, Gmail, Outlook, Cyrus) support MOVE, so this is the cold path.
Ver o original no GitHub

Bom para

Relacionados