proton-workflow-connector 1.2.1__tar.gz

proton_workflow_connector-1.2.1/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "proton-workflow-connector",
+  "owner": {
+    "name": "NtrpyDev",
+    "url": "https://github.com/NtrpyDev"
+  },
+  "plugins": [
+    {
+      "name": "proton-workflow-connector",
+      "source": "./plugins/proton-workflow-connector",
+      "description": "Self-hosted Proton Mail Bridge and SimpleLogin tools over MCP. Requires a locally running Proton Mail Bridge and the proton-workflow-connector package on PATH.",
+      "category": "productivity"
+    }
+  ]
+}

proton_workflow_connector-1.2.1/.env.example

@@ -0,0 +1,93 @@
+# Copy to .env for local testing. Do not commit .env.
+
+# Proton Mail Bridge settings. Confirm the host, ports, TLS mode, username,
+# and Bridge-generated password in the Proton Mail Bridge app.
+PROTON_BRIDGE_IMAP_HOST=127.0.0.1
+PROTON_BRIDGE_IMAP_PORT=1143
+PROTON_BRIDGE_IMAP_TLS=starttls
+PROTON_BRIDGE_SMTP_HOST=127.0.0.1
+PROTON_BRIDGE_SMTP_PORT=1025
+PROTON_BRIDGE_SMTP_TLS=starttls
+PROTON_BRIDGE_ALLOW_INSECURE_TLS=true
+PROTON_BRIDGE_USERNAME=user@example.com
+PROTON_BRIDGE_PASSWORD=replace-with-bridge-password
+PROTON_BRIDGE_EMAIL=user@example.com
+# Comma-separated addresses this Bridge account may send from.
+PROTON_BRIDGE_SENDER_ADDRESSES=user@example.com
+
+# Folder names vary by account and Bridge version. Use list_folders to verify.
+PROTON_ARCHIVE_FOLDER=Archive
+PROTON_TRASH_FOLDER=Trash
+# Mailbox prefix Bridge uses for Proton labels (apply_label/remove_label/list_labels).
+PROTON_LABELS_FOLDER=Labels
+PROTON_DRAFTS_FOLDER=Drafts
+PROTON_SENT_FOLDER=Sent
+PROTON_SPAM_FOLDER=Spam
+
+# SimpleLogin is optional. Leave unset if you do not use SimpleLogin tools.
+SIMPLELOGIN_API_KEY=
+SIMPLELOGIN_BASE_URL=https://app.simplelogin.io
+
+# Safety bounds.
+PROTON_MCP_BULK_LIMIT=50
+PROTON_MCP_BODY_PREVIEW_CHARS=500
+PROTON_MCP_MAX_BODY_CHARS=20000
+PROTON_MCP_MAX_ATTACHMENT_DOWNLOAD_BYTES=50000000
+PROTON_MCP_MAX_OUTGOING_ATTACHMENT_BYTES=25000000
+PROTON_MCP_MAX_ATTACHMENTS=100
+PROTON_MCP_SEARCH_ALL_LIMIT=100
+PROTON_MCP_REQUEST_TIMEOUT=30
+
+# Hosted Streamable HTTP security. Leave unset for stdio or localhost-only HTTP.
+PROTON_MCP_OAUTH_ISSUER_URL=
+PROTON_MCP_OAUTH_AUDIENCE=
+PROTON_MCP_OAUTH_RESOURCE_SERVER_URL=
+PROTON_MCP_OAUTH_JWKS_URL=
+PROTON_MCP_OAUTH_BASE_SCOPE=proton-workflow-connector
+PROTON_MCP_HTTP_ALLOWED_HOSTS=
+PROTON_MCP_HTTP_ALLOWED_ORIGINS=
+PROTON_MCP_ALLOW_UNAUTHENTICATED_HTTP=false
+
+# Optional privacy-safe JSONL audit log and per-client limits per minute.
+PROTON_MCP_AUDIT_LOG=
+PROTON_MCP_RATE_LIMIT_READ=120
+PROTON_MCP_RATE_LIMIT_WRITE=30
+PROTON_MCP_RATE_LIMIT_DESTRUCTIVE=5
+
+# Safety modes. read-only blocks all writes/destructive ops; allow-send=false blocks send/reply/
+# forward/send_draft only; allowed-actions is an optional comma list of permitted categories
+# (read,write,destructive) — when set, anything outside it is refused. Dry-run previews are exempt.
+PROTON_MCP_READ_ONLY=false
+PROTON_MCP_ALLOW_SEND=true
+PROTON_MCP_ALLOWED_ACTIONS=
+
+# Mailbox triggers (proton-workflow-watch and the poll_mailbox tool).
+# Set a webhook URL to push new-message events to n8n, Zapier, Make, or your own service.
+PROTON_MCP_WATCH_WEBHOOK_URL=
+# Optional shared secret. When set, each POST carries an X-Proton-Signature: sha256=<hmac> header.
+PROTON_MCP_WATCH_WEBHOOK_SECRET=
+# Comma-separated folders to watch. Defaults to INBOX.
+PROTON_MCP_WATCH_FOLDERS=INBOX
+PROTON_MCP_WATCH_INTERVAL=60
+PROTON_MCP_WATCH_LIMIT=50
+PROTON_MCP_WATCH_UNREAD_ONLY=false
+# Delivery retries. On failure the cursor is held so events retry on the next poll (at-least-once).
+PROTON_MCP_WATCH_MAX_RETRIES=3
+PROTON_MCP_WATCH_RETRY_BACKOFF=2
+# Cursor state file. Defaults to $XDG_STATE_HOME/proton-workflow-connector/watch-state.json.
+PROTON_MCP_WATCH_STATE=
+# Optional JSON rules file with multiple named triggers (per-rule source, filter, webhook_url).
+# When set, it overrides PROTON_MCP_WATCH_FOLDERS. See docs/WATCH.md.
+PROTON_MCP_WATCH_RULES=
+# Delivery target: webhook (default), file (append JSONL), or command (pipe event JSON to stdin).
+PROTON_MCP_WATCH_SINK=webhook
+# Path for the file sink (PROTON_MCP_WATCH_SINK=file).
+PROTON_MCP_WATCH_FILE=
+# Command for the command sink (PROTON_MCP_WATCH_SINK=command); each event is piped to its stdin.
+PROTON_MCP_WATCH_COMMAND=
+# Dead-letter file for events that keep failing. Defaults next to the cursor state file.
+PROTON_MCP_WATCH_DEAD_LETTER=
+# Failed delivery cycles on one event before it is dead-lettered and the cursor advances past it.
+PROTON_MCP_WATCH_DEAD_LETTER_MAX_ATTEMPTS=5
+# Use IMAP IDLE for near-instant mail triggers instead of interval polling (falls back if unsupported).
+PROTON_MCP_WATCH_IDLE=false

proton_workflow_connector-1.2.1/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format
+        run: ruff format --check .
+      - name: Test
+        run: pytest
+      - name: Compile
+        run: python -m compileall -q src
+      - name: Dependency audit
+        run: pip-audit

proton_workflow_connector-1.2.1/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

proton_workflow_connector-1.2.1/.github/workflows/secret-scan.yml

@@ -0,0 +1,18 @@
+name: Secret scan
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_CONFIG: .gitleaks.toml

proton_workflow_connector-1.2.1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.venv/
+venv/
+
+# Local secrets and private config
+.env
+.env.*
+!.env.example
+*.local
+local-config/
+private/
+private-notes/
+bridge-notes*
+proton-bridge*
+*.pem
+*.key
+*.crt
+*.p12
+
+# Logs, caches, and mailbox artifacts
+*.log
+logs/
+cache/
+tmp/
+*.mbox
+*.eml
+*.maildir/
+mail-export/
+screenshots/
+
+# Local deployment files
+docker-compose.override.yml
+deploy.local.*
+.codex/config.toml
+.claude/settings.local.json
+
+# Local work-order, not part of the project
+AGENT_BRIEF.md
+HANDOFF.md
+TEST_PLAN.md
+
+# Wrangler local state for the test fixture worker
+.wrangler/

proton_workflow_connector-1.2.1/.gitleaks.toml

@@ -0,0 +1,10 @@
+title = "Proton Mail MCP secret scan"
+
+[allowlist]
+description = "Allow documented fake placeholder values only."
+regexes = [
+  '''replace-with-[a-z-]+''',
+  '''user@example\.com''',
+  '''alice@example\.com''',
+  '''bob@example\.com''',
+]

proton_workflow_connector-1.2.1/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format-check
+        name: ruff format check
+        entry: ruff format --check
+        language: system
+        types_or: [python, pyi]
+      - id: gitleaks
+        name: gitleaks staged secret scan
+        entry: gitleaks protect --staged --redact --config .gitleaks.toml
+        language: system
+        pass_filenames: false

proton_workflow_connector-1.2.1/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project are recorded here. Versions follow [semantic versioning](https://semver.org/).
+
+## 1.2.1 - 2026-07-01
+
+### Fixed
+
+- Synchronous tools now run in worker threads instead of on the event loop, so one stalled
+  Bridge IMAP call can no longer freeze the whole server for every session.
+- JWKS and OIDC discovery fetches send an explicit `User-Agent`; CDNs and WAFs that block
+  urllib's default agent were silently rejecting every OAuth token with 401. Failed token
+  verifications are now logged with the reason instead of being swallowed.
+- Message fetches retry briefly when Bridge answers an OK FETCH without the message body
+  (a transient Bridge quirk under load), and report a clear "moved or deleted" error when
+  a stale UID is fetched after a message left the folder.
+
+All three were found by the new live acceptance harness (`scripts/live_acceptance.py`), which
+exercises all 67 tools against a real Bridge, SimpleLogin, watcher sinks, safety modes, and a
+hosted OAuth deployment.
+
+## 1.2.0 - 2026-07-01
+
+### Added
+
+- Proton label tools, header inspection, richer search filters, draft replies/forwards, and
+  List-Unsubscribe handling.
+- Rule actions for the watcher, including mark read/unread, star/unstar, label/remove label,
+  archive/trash/move, and forward.
+- IMAP IDLE support for lower-latency watcher polling when Bridge supports it.
+- Read-only mode, send disablement, allowed-action guardrails, and MCP tool annotations.
+- Dry-run previews for send/reply/forward, bulk operations, permanent delete, empty-folder operations,
+  and watcher rules.
+- Dependency-free outbound HTML sanitization with `html_sanitized` result markers and a
+  `trusted_html` opt-out for caller-controlled HTML.
+- `content_trust: "untrusted"` markers on read/search message payloads.
+- Post-operation verification for message flags and label application.
+
+### Changed
+
+- Reworked the README around clearer setup, capabilities, automations, and security boundaries.
+
+### Fixed
+
+- Watcher rules that combine a move action with `forward` are rejected at parse time because retries
+  cannot reliably forward a message after its UID changes.
+
+## 1.1.0 - 2026-07-01
+
+Turns the watcher into a real workflow layer: more event sources, flexible delivery, and reliable
+forward progress.
+
+### Added
+
+- **SimpleLogin alias events.** A second event source (`alias.created`) alongside `mail.received`,
+  with a cursor on the highest alias id. Add it as a watcher source or pull it with the new
+  `poll_aliases` MCP tool.
+- **Rules file.** Point `PROTON_MCP_WATCH_RULES` (or `--rules`) at a JSON file to run several named
+  triggers at once, each with its own source, filter, and optional `webhook_url`.
+- **Delivery targets.** Besides the default webhook, the watcher can append events to a JSONL file
+  (`--sink file`) or pipe them to a command's stdin (`--sink command`).
+- **Dead-letter and replay.** After a configurable number of failed cycles, a stuck event is written
+  to a dead-letter file and the cursor advances so one bad event can't stall a source. Re-deliver
+  parked events later with `--replay-dead-letter`.
+- **Trust model** documented in [docs/WATCH.md](docs/WATCH.md).
+
+### Fixed
+
+- Alias polling no longer stops early on SimpleLogin's out-of-order list (pinned and recently active
+  aliases float to the top), which previously let new aliases on later pages be missed.
+
+## 1.0.0
+
+Initial release: MCP tools for Proton Mail through Bridge and SimpleLogin, local stdio / private
+HTTP / hosted OAuth transports, and the first trigger layer (`poll_mailbox` plus a webhook watcher).

proton_workflow_connector-1.2.1/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Do not put account-specific or private data in this repository.
+
+Before opening a pull request, run:
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest
+python -m compileall -q src
+pip-audit
+gitleaks detect --redact --config .gitleaks.toml
+```
+
+Tests must use fake data. Use addresses under `example.com`, short synthetic message bodies, and made-up IDs.
+
+Do not add account-specific screenshots, mailbox exports, logs, private IPs, private hostnames, usernames, credentials, or local deployment notes.

proton_workflow_connector-1.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NtrpyDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proton_workflow_connector-1.2.1/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: proton-workflow-connector
+Version: 1.2.1
+Summary: Unofficial self-hosted MCP connector for Proton Mail Bridge and SimpleLogin.
+Project-URL: Homepage, https://github.com/NtrpyDev/proton-workflow-connector
+Project-URL: Repository, https://github.com/NtrpyDev/proton-workflow-connector
+Project-URL: Issues, https://github.com/NtrpyDev/proton-workflow-connector/issues
+Author: NtrpyDev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: imap,mcp,proton-mail,simplelogin,smtp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.28.1
+Requires-Dist: pyjwt[crypto]>=2.10
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pip-audit>=2.9; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Proton Workflow Connector
+
+[![CI](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/ci.yml)
+[![Secret scan](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/secret-scan.yml/badge.svg)](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/secret-scan.yml)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Proton Workflow Connector (PWC) is a self-hosted MCP connector for reading, sending, organizing, and automating Proton Mail through Proton Mail Bridge.
+It works with any MCP client or local agent runtime that can launch a stdio server or call a Streamable HTTP MCP endpoint.
+SimpleLogin support is optional.
+
+This is an unofficial project. It is not affiliated with, endorsed by, or sponsored by Proton AG.
+The connector uses Bridge-generated IMAP/SMTP credentials. It does not accept Proton account passwords or store Proton login sessions.
+
+[Quick start](#quick-start) · [Example workflows](#example-workflows) · [Capabilities](#capabilities) · [Automations](#automations) · [Security](#security-model) · [Documentation](#documentation) · [Buy Me a Coffee](https://buymeacoffee.com/ntrpydev)
+
+## Why use it?
+
+Use one local server for the mail work agents usually have to piece together:
+
+- Search, read, send, reply, forward, draft, label, archive, and download attachments through 53 Proton Mail tools.
+- Require confirmation for destructive tools, preview sends and destructive operations with `dry_run`, sanitize outbound HTML by default, bound bulk operations, and allow only configured sender addresses.
+- React to new mail or SimpleLogin aliases through MCP polling or a background watcher that can call a webhook, append JSONL, or run a command.
+- Add 13 SimpleLogin tools when you want alias, contact, and mailbox management.
+- Connect over stdio, localhost Streamable HTTP, or OAuth-protected hosted HTTP.
+
+The server exposes 67 tools in total. See the [complete tool reference](docs/TOOLS.md).
+
+## How it works
+
+PWC is an MCP server. Your client starts it over stdio or connects to it over Streamable HTTP.
+
+The connector talks to Proton Mail Bridge over local IMAP/SMTP. Bridge must be installed, signed in, and running on the same machine as the connector. One connector process serves one Bridge account.
+
+SimpleLogin is optional. If `SIMPLELOGIN_API_KEY` is set, PWC adds alias, contact, mailbox, and new-alias polling tools. If it is unset, the Proton Mail tools still work.
+
+For automation, run `proton-workflow-watch` or call the polling tools from your MCP client. Watcher output can go to a webhook, a JSONL file, or a command.
+
+## Quick start
+
+### Prerequisites
+
+- Python 3.11 or newer
+- [Proton Mail Bridge](https://proton.me/mail/bridge), signed in and running
+- The IMAP/SMTP host, ports, username, and generated password shown by Bridge
+- A SimpleLogin API key only if you want the optional SimpleLogin tools
+
+### 1. Install
+
+```bash
+git clone https://github.com/NtrpyDev/proton-workflow-connector.git
+cd proton-workflow-connector
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install .
+```
+
+On Windows PowerShell, activate the environment with `.venv\Scripts\Activate.ps1`.
+
+### 2. Configure Bridge credentials
+
+Keep the environment file outside the repository:
+
+```bash
+mkdir -p ~/.config/proton-workflow-connector
+cp .env.example ~/.config/proton-workflow-connector/env
+chmod 600 ~/.config/proton-workflow-connector/env
+```
+
+Edit the copied file with the connection details shown in Proton Mail Bridge. Set `PROTON_BRIDGE_EMAIL` to the default sender and list every permitted sender address in `PROTON_BRIDGE_SENDER_ADDRESSES`.
+
+### 3. Run the connector
+
+```bash
+proton-workflow-connector --transport stdio \
+  --env-file ~/.config/proton-workflow-connector/env
+```
+
+### 4. Connect an MCP client
+
+Any MCP client or local agent runtime can use PWC as long as it supports stdio or Streamable HTTP:
+
+- stdio: run `proton-workflow-connector --transport stdio --env-file ...`
+- HTTP: run the connector with `--transport streamable-http` and point the client at `/mcp`
+
+Claude Code stdio example:
+
+```bash
+claude mcp add --transport stdio --scope user proton-workflow \
+  -- "$PWD/.venv/bin/proton-workflow-connector" --transport stdio \
+  --env-file ~/.config/proton-workflow-connector/env
+```
+
+Codex stdio example:
+
+```toml
+[mcp_servers.proton_workflow]
+command = "/absolute/path/to/repo/.venv/bin/proton-workflow-connector"
+args = [
+  "--transport", "stdio",
+  "--env-file", "/absolute/path/to/private/proton-workflow-connector-env"
+]
+default_tools_approval_mode = "prompt"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+Run `server_status` after connecting. It checks IMAP, SMTP, SimpleLogin, OAuth configuration, and the server version without returning secrets.
+Then run `list_folders`; Bridge folder names vary by account and version.
+
+See [MCP client setup](docs/CLIENTS.md) for generic client configuration, localhost HTTP, hosted Streamable HTTP, Codex, Claude Code, and the plugin wrapper.
+
+## Example workflows
+
+Once connected, ask your MCP client to:
+
+- "List my mail folders and show the unread count for each."
+- "Find unread invoices from the last 30 days without marking them read."
+- "Draft a reply to the latest message in this thread, but do not send it."
+- "Download the PDF attachments from this message."
+- "Archive these message UIDs after showing me the exact list."
+- "Create a SimpleLogin alias for shopping and add a contact for this merchant."
+- "Poll for new mail from `billing@vendor.example` using the `invoices` cursor."
+
+The connector returns structured data to the MCP client. The client decides how to present it and when to request approval for actions.
+
+## Capabilities
+
+| Area | Included operations |
+| --- | --- |
+| Search and reading | Search one folder or all selectable folders, read messages and threads, inspect headers, and download attachments |
+| Sending and drafts | Send, reply, reply-all, forward, create and update drafts, use allowed alternate senders, and attach files |
+| Organization | Create and manage folders, apply Proton labels, change flags, archive, move, copy, restore, and manage Spam or Trash |
+| Bounded bulk actions | Preview, mark, star, move, copy, archive, trash, restore, or permanently delete explicit UID lists |
+| Automations | Poll persistent cursors or push new-message and new-alias events to a webhook, JSONL file, or command |
+| SimpleLogin | Inspect account data and manage aliases, contacts, and mailboxes with an optional API key |
+| Deployment | Local stdio, localhost Streamable HTTP, or OAuth/OIDC-protected hosted HTTP |
+
+Proton Contacts are not included because Proton Mail Bridge does not expose them.
+
+## Automations
+
+The background watcher polls for new mail or newly created SimpleLogin aliases and emits one event per new item:
+
+```bash
+proton-workflow-watch \
+  --env-file ~/.config/proton-workflow-connector/env \
+  --folder INBOX \
+  --webhook-url https://example.com/hooks/proton \
+  --interval 60
+```
+
+Key behavior:
+
+- The first run establishes a baseline and does not replay the existing mailbox.
+- Persistent cursors survive restarts and account for IMAP `UIDVALIDITY` changes.
+- Webhook delivery is at-least-once, with retries, exponential backoff, and dead-letter handling.
+- An optional HMAC-SHA256 signature lets webhook receivers verify each event.
+- Events contain message metadata only; bodies and attachments remain available on demand through MCP tools.
+- JSON rules can run several independently filtered triggers from one watcher.
+- `--dry-run` shows which events and rule actions would fire without delivering, acting, or advancing cursors.
+
+Read [Triggers and webhooks](docs/WATCH.md) for event schemas, filters, delivery guarantees, signature verification, rules, and systemd examples.
+
+## Security model
+
+This connector processes private mail. Its defaults and boundaries are intentionally explicit:
+
+- **Prefer local stdio.** Bridge and the connector should stay on the same trusted machine whenever possible.
+- **Keep credentials private.** Store Bridge-generated credentials and optional API keys outside Git with user-only permissions.
+- **Confirm destructive actions.** Permanent deletion, empty-folder operations, folder deletion, and alias deletion require `confirm=true` after explicit user intent.
+- **Preview before mutating.** Sends, forwards, replies, bulk actions, permanent delete, and empty-folder operations support `dry_run=true` previews.
+- **Treat mail as untrusted.** Read/search results mark email content as `content_trust: "untrusted"`, and outbound HTML is sanitized unless `trusted_html=true`.
+- **Bound bulk operations.** Bulk tools require explicit numeric UIDs and default to a maximum of 50 messages per call.
+- **Restrict senders.** Mail can only be sent from `PROTON_BRIDGE_EMAIL` or an address in `PROTON_BRIDGE_SENDER_ADDRESSES`.
+- **Protect remote access.** Non-local HTTP deployments require deliberate Host/Origin policy; internet deployments require HTTPS and an external OAuth/OIDC provider.
+- **Limit exposed data.** Optional audit records exclude addresses, message bodies, attachments, credentials, and tokens.
+- **Treat events as untrusted input.** Email subjects and alias names can be attacker-controlled; webhook receivers and commands must validate event fields.
+
+Read [SECURITY.md](SECURITY.md) before using real mail and [Hosted HTTP setup](docs/HOSTING.md) before exposing the connector beyond localhost.
+
+## Known boundaries
+
+- Proton Mail Bridge must remain running while the connector or watcher is active.
+- One server process connects to one Bridge account.
+- Proton Contacts, native scheduled sending, filters, account settings, and key management are not exposed by Bridge and are not emulated.
+- New-mail and new-alias triggers use polling because Proton and SimpleLogin do not provide a compatible push API.
+- Trigger events include metadata, not message bodies or attachments.
+- `All Mail` is a virtual read-only Bridge mailbox; start move and permanent-delete operations from a writable folder.
+
+## Documentation
+
+| Guide | Use it for |
+| --- | --- |
+| [Setup](docs/SETUP.md) | Bridge configuration, private environment files, folder names, and network modes |
+| [Tool reference](docs/TOOLS.md) | All 67 MCP tools, arguments, safety limits, and boundaries |
+| [Client setup](docs/CLIENTS.md) | Generic MCP clients, local agents, Codex, Claude Code, plugins, and Streamable HTTP |
+| [Triggers and webhooks](docs/WATCH.md) | Watcher rules, payloads, delivery behavior, and signature verification |
+| [Hosted HTTP](docs/HOSTING.md) | OAuth/OIDC, HTTPS, Host/Origin validation, scopes, audit logs, and systemd |
+| [Integration tests](docs/INTEGRATION_TESTS.md) | Live Bridge and SimpleLogin verification |
+
+Official upstream references:
+
+- [Proton Mail Bridge](https://proton.me/mail/bridge)
+- [Proton IMAP/SMTP setup](https://proton.me/support/imap-smtp-and-pop3-setup)
+- [SimpleLogin API](https://github.com/simple-login/app/blob/master/docs/api.md)
+
+## Development
+
+Install the development dependencies and run the local checks:
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest
+python -m compileall -q src
+pip-audit
+gitleaks detect --redact --config .gitleaks.toml
+```
+
+Tests use synthetic data and do not require access to a real mailbox. Live checks are documented separately in [Integration tests](docs/INTEGRATION_TESTS.md).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and privacy requirements. Report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+<!-- mcp-name: io.github.ntrpydev/proton-workflow-connector -->