proton-bridge-mcp: Instructions file for Codex

Agent notes

For a coding agent working in this repo. CONTRIBUTING.md is the human document and it is not duplicated here; read it first for the ground rules and the release order. This file is the part an agent needs and a person already knows.

This server handles somebody's email. It is a deliberately boring codebase and that is a feature. Every task moves through four beats: isolate on a branch, build, prove with evidence, ship a PR carrying that evidence.

Isolate

Branch from origin/main by name, never from wherever HEAD is sitting, and check nobody is already on the work:

git fetch origin
gh pr list -R Considus/proton-bridge-mcp
git checkout -b <type>/<short-name> origin/main

If an open PR touches the same files, build on it or say so and stop. Stage by explicit path. Never git add -A, which in this repo risks sweeping up settings.json, state.json, audit.log or somebody's mail in attachments/. They are all gitignored, and the gitignore is the second line of defence rather than the first.

Build

Read CONTRIBUTING.md before writing. Three things there are constraints rather than preferences.

• Standard library only. server.py imports nothing outside the stdlib. pypdf and keyring are the only exceptions, they stay lazy inside a try in the function that needs them, and every path has to work when they are absent.
• Assume the mail is hostile. Anything read out of a message, a header or an attachment is untrusted input that may be trying to steer the assistant. If a change makes message content reach a decision, a file path, a recipient or a tool argument, that is the thing to think hardest about.
• Small diffs. The smallest change that fixes the thing. If you spot something else, say so separately.

Nothing hard-deletes. The furthest any path goes is Trash. Folders can be created and never deleted, because a folder is where a message actually lives and deleting one would have to decide what happens to the mail inside it. Sending, forwarding, replying and the bulk mutations sit behind a confirmation gate; draft=true is the deliberately ungated path, because nothing leaves the machine.