stalwart-mail-mcp 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petr Šrámek
+
+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.

package/README.cs.md

@@ -0,0 +1,226 @@
+# Stalwart Mail MCP
+
+*[English](README.md)*
+
+MCP server, díky kterému Claude Desktop (a jakýkoli MCP klient přes stdio) pracuje se schránkou
+na vlastním poštovním serveru [Stalwart](https://stalw.art): hledá a čte poštu včetně příloh
+a skenů, odpovídá ve vlákně, odesílá, zakládá koncepty a hledá nebo přidává kontakty.
+
+Se serverem mluví protokolem JMAP a přihlašuje se účtem schránky. Na server se nic neinstaluje.
+
+```text
+Claude Desktop ──stdio──▶ dist/index.cjs (Node, tento MCP server)
+                              │  HTTPS · JMAP (RFC 8620 / 8621 / 9610)
+                              ▼
+                 https://mail.example.com/jmap   (reverzní proxy → Stalwart)
+```
+
+Jak ho zapojit do malé vlastní infrastruktury — reverzní proxy, co pustit ven, sdílené
+schránky, vlastní balíček pro rodinu nebo tým — popisuje
+[docs/mala-infrastruktura.md](docs/mala-infrastruktura.md).
+
+## Nástroje
+
+Názvy mají předponu, výchozí je `mail_` (vlastní balíček si ji může změnit).
+
+| Nástroj | Co dělá |
+|---|---|
+| `mail_list_mailboxes` | účty (vlastní + sdílené), složky s počty, povolení odesílatelé, adresáře |
+| `mail_search_emails` | fulltext / od / komu / předmět / složka / datum / nepřečtené / s přílohou, nebo celé vlákno |
+| `mail_get_email` | celá zpráva podle id (HTML → text) s číslovaným seznamem příloh |
+| `mail_get_attachment` | obsah přílohy: text, PDF po stranách, OCR skenů a fotek dokumentů, obrázky; soubor uloží na disk |
+| `mail_send_email` | odeslat nový mail nebo odpověď (`in_reply_to_id`, `reply_all`), přílohy z disku |
+| `mail_create_draft` | totéž, ale jen uložit do Konceptů |
+| `mail_send_draft` / `mail_delete_draft` | odeslat / smazat koncept podle id |
+| `mail_search_contacts` | adresáře všech účtů a navíc odesílatelé a adresáti z historie pošty |
+| `mail_add_contact` | nový kontakt (vlastní nebo sdílený adresář) |
+
+Odeslání je okamžité a nejde vzít zpět, proto popisy nástrojů modelu říkají, že má posílat jen
+na výslovný pokyn uživatele a jinak založit koncept.
+
+## Instalace
+
+### Claude Desktop (rozšíření)
+
+Stáhni `stalwart-mail.mcpb` z
+[posledního vydání](https://github.com/cybersmurf/stalwart-mail-mcp/releases/latest) a otevři
+ho — Claude Desktop nabídne instalaci. Nebo si ho sestav:
+
+```bash
+npm install
+./pack.sh                  # → stalwart-mail.mcpb
+open stalwart-mail.mcpb    # Claude Desktop → Install
+```
+
+Vyplň adresu serveru, e-mail a heslo schránky. Volitelně jazyk a klíč Mistral API pro OCR.
+Heslo se ukládá do klíčenky systému.
+
+### Jakýkoli MCP klient (stdio)
+
+```bash
+npm install && npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "stalwart-mail": {
+      "command": "node",
+      "args": ["/cesta/k/stalwart-mail-mcp/dist/index.cjs"],
+      "env": {
+        "STALWART_URL": "https://mail.example.com",
+        "STALWART_USER": "jana@example.com",
+        "STALWART_PASSWORD": "…"
+      }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add stalwart-mail --env STALWART_URL=https://mail.example.com --env STALWART_USER=jana@example.com --env STALWART_PASSWORD=… -- node /cesta/k/stalwart-mail-mcp/dist/index.cjs`
+
+## Nastavení
+
+| Proměnná | Význam |
+|---|---|
+| `STALWART_URL` | veřejná adresa serveru, např. `https://mail.example.com` (povinné) |
+| `STALWART_USER` | schránka, kterou se přihlašuješ (povinné) |
+| `STALWART_PASSWORD` | heslo schránky nebo heslo aplikace — posílá se jako Basic auth |
+| `STALWART_TOKEN` | přístupový token OAuth místo hesla — posílá se jako Bearer |
+| `MAIL_LANG` | `auto` (výchozí: jazyk počítače, angličtina, když ho neumíme) nebo kód jazyka |
+| `MAIL_TOOL_PREFIX` | předpona názvů nástrojů, výchozí `mail` |
+| `MAIL_BRAND` | zobrazovaný název serveru, výchozí `Stalwart Mail` |
+| `MAIL_DOWNLOAD_DIR` | kam se ukládají přílohy, výchozí `~/Downloads/Mail-Attachments` |
+| `MAIL_TIMEZONE` | časové pásmo (IANA) pro data ve výstupu, výchozí pásmo počítače |
+| `MAIL_OCR_PROVIDER`, `MAIL_OCR_API_KEY`, `MAIL_OCR_MODEL`, `MAIL_OCR_BASE_URL` | kdo čte skeny — viz [Poskytovatelé OCR](#poskytovatelé-ocr) |
+| `MISTRAL_API_KEY` | zkratka: když je nastavený jen tenhle, skeny jdou do Mistral OCR |
+| `MAIL_ALLOW_SEND` | `false` odebere `send_email` a `send_draft` |
+| `MAIL_ALLOW_DRAFTS` | `false` odebere `create_draft` a `delete_draft` |
+| `MAIL_ALLOW_CONTACT_EDIT` | `false` odebere `add_contact` |
+| `MAIL_ALLOW_ATTACHMENTS` | `false` odebere `get_attachment` |
+| `MAIL_SAVE_ATTACHMENTS` | `false` = otevřené přílohy se jen přečtou, na disk se nic nezapíše |
+
+## Co smí dělat
+
+Každá schopnost je přepínač v nastavení rozšíření (nebo proměnná výše), ve výchozím stavu je
+vše zapnuté. Vypnutá schopnost se **jako nástroj vůbec nenabídne**, takže platí bez ohledu na
+to, co si pamatují schvalovací dotazy klienta:
+
+- vypnuté odesílání → schránka, kterou Claude čte a píše do ní koncepty, ale nikdy z ní neodešle;
+- vypnuté odesílání, koncepty i úpravy kontaktů → schránka jen pro čtení;
+- vypnuté ukládání příloh → `get_attachment` čte soubor z dočasné kopie a je označený jako
+  nástroj jen pro čtení; se zapnutým ukládáním zapisuje do složky stahování a je označený jako
+  zapisující, s čímž klienti mohou při schvalování zacházet jinak.
+
+Samotné schvalování („povolit jednou / povolit vždy“) patří klientovi, ne tomuto serveru.
+V Claude Desktop se nastavuje po nástrojích v nastavení rozšíření; po aktualizaci, která změní
+definici nástroje, se klient může zeptat znovu.
+
+## Přílohy a OCR
+
+`mail_get_attachment` stáhne soubor a vrátí to, co model přečte:
+
+- textové soubory jako text, HTML převedené na text;
+- PDF jako text po stranách (u dlouhých `page_from` / `page_to`);
+- strany PDF bez textové vrstvy (skeny) a fotky jdou ke zvolenému **poskytovateli OCR** —
+  výsledkem je markdown včetně tabulek a takové strany jsou označené `(OCR)`. U smíšeného PDF
+  se posílají jen naskenované strany;
+- obrázky se vrací jako obrázky; cokoli nad ~600 kB nebo v HEIC se na macOS zmenší (`sips`);
+- ostatní typy (docx, xlsx, zip…) se jen uloží a vrátí se cesta.
+
+Bez poskytovatele nebo s `ocr: false` se sken vrátí jako obrázek 1. strany (macOS)
+s poznámkou. OCR je jediná věc, která z tohoto serveru posílá obsah jinam než na tvůj poštovní
+server — ke zvolenému poskytovateli, nebo s lokálním modelem vůbec nikam.
+
+### Poskytovatelé OCR
+
+| `MAIL_OCR_PROVIDER` | Co to je | Potřebuje | Čte PDF |
+|---|---|---|---|
+| `auto` (výchozí) | Mistral, když je nastavený `MISTRAL_API_KEY`; vlastní server, když je zadaná adresa a model; jinak vypnuto | — | — |
+| `mistral` | Mistral OCR (`mistral-ocr-latest`) | klíč | přímo |
+| `anthropic` | Claude přes oficiální SDK (výchozí model `claude-opus-5-5`) | klíč | přímo |
+| `openai`, `openrouter`, `gemini` | hostovaná API kompatibilní s OpenAI (chat s obrázky) | klíč + model | obrázky stran |
+| `ollama`, `lmstudio` | lokální modely na `localhost` | model | obrázky stran |
+| `custom` | jakýkoli jiný server kompatibilní s OpenAI | `MAIL_OCR_BASE_URL` + model | obrázky stran |
+| `off` | bez OCR | — | — |
+
+Volbu doplňují `MAIL_OCR_API_KEY`, `MAIL_OCR_MODEL` a `MAIL_OCR_BASE_URL`. Příklady:
+
+```bash
+MAIL_OCR_PROVIDER=ollama      MAIL_OCR_MODEL=llama3.2-vision                         # čistě lokálně
+MAIL_OCR_PROVIDER=openrouter  MAIL_OCR_API_KEY=…  MAIL_OCR_MODEL=<model s viděním>
+MAIL_OCR_PROVIDER=anthropic   MAIL_OCR_API_KEY=…
+MAIL_OCR_PROVIDER=custom      MAIL_OCR_BASE_URL=http://nas.lan:8000/v1  MAIL_OCR_MODEL=…
+```
+
+Poskytovatelé, kteří berou jen obrázky, dostanou každou naskenovanou stranu jako PNG vytažené
+z PDF (samotný sken, zmenšený na 2000 px). Stranu, která není jeden velký obrázek, jim předat
+nejde a nahlásí se jako nepřečtená; Mistral a Anthropic čtou jakékoli PDF. Strany se posílají
+po třech.
+
+S čím počítat: lokální model může na hustou stranu potřebovat minutu i víc, což může
+přesáhnout časový limit nástroje v klientu — dlouhé skeny čti po rozsazích stran. Obecné
+modely s viděním přepisují dobře, ale jako každé OCR umí v tabulkách s grafikou posunout
+buňky; `preview: true` přidá obrázek strany, aby si to model mohl zkontrolovat. U `anthropic`
+se odmítnutý požadavek na aktuálních modelech Claude zopakuje na serveru na záložním modelu
+(`fallbacks: "default"`).
+
+`node test/live-ocr.mjs` pustí poskytovatele nastaveného v prostředí proti naskenovanému
+testovacímu souboru (nebo tvému vlastnímu) a vypíše výsledek.
+
+## Jazyky
+
+Názvy a popisy nástrojů, výstupy i chybové hlášky jsou lokalizované. Angličtina je zdroj,
+čeština je psaná ručně a němčina, španělština, francouzština, italština, nizozemština,
+polština, portugalština a slovenština jsou **strojové překlady**, které zatím žádný rodilý
+mluvčí nekontroloval — opravy jsou vítané.
+
+Jazyk se přidává nebo opravuje v `src/locales/<kód>.ts` (zkopíruj `en.ts`, zachovej
+`{zástupné značky}` a zalomení řádků) a registruje se v `src/locales/index.ts`. Překlad může
+být neúplný, chybějící texty se vezmou z angličtiny. `npm run test:offline` každý jazyk
+porovná s anglickými klíči.
+
+## Vlastní balíčky (předvolby)
+
+Pro rodinu nebo tým jde vyrobit rozšíření, kde je adresa serveru předvyplněná a lidé zadají
+jen e-mail a heslo. Předvolba je složka s vlastním `manifest.json` (a volitelně `icon.png`),
+viz [presets/example](presets/example).
+
+```bash
+./pack.sh --preset /cesta/k/predvolbe     # → /cesta/k/predvolbe/<name>.mcpb
+```
+
+Manifest předvolby nastaví přes `env` `MAIL_TOOL_PREFIX`, `MAIL_BRAND`, `MAIL_LANG` nebo
+`MAIL_DOWNLOAD_DIR` a položce `server_url` dá výchozí hodnotu. `name` předvolby neměň, aby
+Claude Desktop bral nové sestavení jako aktualizaci.
+
+## Testy
+
+```bash
+npm run test:offline       # bez schránky: falešný JMAP + falešné OCR, skutečný server přes stdio
+MISTRAL_API_KEY=… node test/offline.mjs --live-ocr    # navíc pošle testovací soubory do skutečného OCR
+STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs          # skutečná schránka
+STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs --send   # navíc pošle mail sám sobě
+```
+
+Offline test pokrývá přílohy, OCR, předponu nástrojů, výběr jazyka a úplnost překladů.
+Kouřový test založí koncept a zase ho smaže; s `--send` po sobě nechá ve schránce jednu
+testovací zprávu.
+
+## Dobré vědět
+
+- **Chybné heslo = ban IP** ve Stalwartu po několika pokusech. Server se přihlašuje až při
+  prvním volání nástroje, ne při startu, takže restarty klienta ban nevyrobí; opakované volání
+  se špatným heslem ano.
+- Vzniklo pro Stalwart 0.16 a s ním se používá. Poštovní část je čisté RFC 8620/8621 a může
+  fungovat i s jinými JMAP servery, ale to není vyzkoušené; kontakty potřebují JMAP for
+  Contacts (RFC 9610).
+- `Email/query` s `"inMailbox": null` Stalwart odmítne — filtr musí buď chybět, nebo mít id.
+- Balíček je jeden soubor CommonJS (~3,8 MB, většinu dělá pdf.js z `unpdf`); přípona `.cjs`
+  je nutná, protože `package.json` má `"type": "module"`.
+- Výsledek nástroje má v Claude Desktop strop kolem 1 MB, proto limit 600 kB pro vložené
+  obrázky.
+
+## Licence
+
+MIT

package/README.md

@@ -0,0 +1,224 @@
+# Stalwart Mail MCP
+
+*[Česky](README.cs.md)*
+
+An MCP server that lets Claude Desktop (or any MCP client that speaks stdio) work with a mailbox
+on your own [Stalwart](https://stalw.art) mail server: search and read mail including
+attachments and scans, reply in a thread, send, keep drafts, and look up or add contacts.
+
+It talks JMAP with the mailbox's own credentials. Nothing is installed on the server.
+
+```text
+Claude Desktop ──stdio──▶ dist/index.cjs (Node, this MCP server)
+                              │  HTTPS · JMAP (RFC 8620 / 8621 / 9610)
+                              ▼
+                 https://mail.example.com/jmap   (reverse proxy → Stalwart)
+```
+
+How it fits into a small self-hosted setup — reverse proxy, what to expose, shared mailboxes,
+branded builds for a family or a team — is described in
+[docs/small-infrastructure.md](docs/small-infrastructure.md).
+
+## Tools
+
+Names carry a prefix, `mail_` by default (a branded build can change it).
+
+| Tool | What it does |
+|---|---|
+| `mail_list_mailboxes` | accounts (own + shared), folders with counts, allowed senders, address books |
+| `mail_search_emails` | full text / from / to / subject / folder / date / unread / has attachment, or a whole thread |
+| `mail_get_email` | a whole message by id (HTML → text) with a numbered list of attachments |
+| `mail_get_attachment` | an attachment's content: text, PDF page by page, OCR of scans and photographed documents, images; saves the file to disk |
+| `mail_send_email` | send a new mail or a reply (`in_reply_to_id`, `reply_all`), attachments from disk |
+| `mail_create_draft` | the same, but only saved to Drafts |
+| `mail_send_draft` / `mail_delete_draft` | send / delete a draft by id |
+| `mail_search_contacts` | address books of every account plus senders and recipients from the mail history |
+| `mail_add_contact` | new contact (own or shared address book) |
+
+Sending is immediate and cannot be undone, so the tool descriptions tell the model to send only
+on the user's explicit instruction and to create a draft otherwise.
+
+## Install
+
+### Claude Desktop (extension)
+
+Download `stalwart-mail.mcpb` from the
+[latest release](https://github.com/cybersmurf/stalwart-mail-mcp/releases/latest) and open it —
+Claude Desktop offers to install it. Or build it yourself:
+
+```bash
+npm install
+./pack.sh                  # → stalwart-mail.mcpb
+open stalwart-mail.mcpb    # Claude Desktop → Install
+```
+
+Fill in the server address, the mailbox e-mail and password. Optional: the language and a
+Mistral API key for OCR. The password is kept in the operating system's keychain.
+
+### Any MCP client (stdio)
+
+```bash
+npm install && npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "stalwart-mail": {
+      "command": "node",
+      "args": ["/path/to/stalwart-mail-mcp/dist/index.cjs"],
+      "env": {
+        "STALWART_URL": "https://mail.example.com",
+        "STALWART_USER": "jane@example.com",
+        "STALWART_PASSWORD": "…"
+      }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add stalwart-mail --env STALWART_URL=https://mail.example.com --env STALWART_USER=jane@example.com --env STALWART_PASSWORD=… -- node /path/to/stalwart-mail-mcp/dist/index.cjs`
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `STALWART_URL` | public address of the server, e.g. `https://mail.example.com` (required) |
+| `STALWART_USER` | the mailbox you sign in as (required) |
+| `STALWART_PASSWORD` | mailbox or app password — sent as Basic auth |
+| `STALWART_TOKEN` | an OAuth access token instead of the password — sent as Bearer |
+| `MAIL_LANG` | `auto` (default: the machine's language, English when unsupported) or a locale code |
+| `MAIL_TOOL_PREFIX` | prefix of the tool names, default `mail` |
+| `MAIL_BRAND` | display name of the server, default `Stalwart Mail` |
+| `MAIL_DOWNLOAD_DIR` | where attachments are saved, default `~/Downloads/Mail-Attachments` |
+| `MAIL_TIMEZONE` | IANA zone for dates in the output, default the machine's zone |
+| `MAIL_OCR_PROVIDER`, `MAIL_OCR_API_KEY`, `MAIL_OCR_MODEL`, `MAIL_OCR_BASE_URL` | who reads scans — see [OCR providers](#ocr-providers) |
+| `MISTRAL_API_KEY` | shortcut: with only this set, scans go to Mistral OCR |
+| `MAIL_ALLOW_SEND` | `false` removes `send_email` and `send_draft` |
+| `MAIL_ALLOW_DRAFTS` | `false` removes `create_draft` and `delete_draft` |
+| `MAIL_ALLOW_CONTACT_EDIT` | `false` removes `add_contact` |
+| `MAIL_ALLOW_ATTACHMENTS` | `false` removes `get_attachment` |
+| `MAIL_SAVE_ATTACHMENTS` | `false` = opened attachments are only read, nothing is written to disk |
+
+## What it is allowed to do
+
+Every capability is a switch in the extension settings (or an env variable above), all on by
+default. A capability that is off is **not offered as a tool at all**, so it holds regardless
+of what the client's approval prompts remember:
+
+- sending off → a mailbox Claude can read and draft in, but never send from;
+- sending, drafts and contact edits off → a read-only mailbox;
+- saving attachments off → `get_attachment` reads the file from a temporary copy and is
+  annotated read-only; with saving on it writes to the download folder and is annotated as a
+  writing tool, which clients may treat differently when asking for approval.
+
+Approvals themselves ("allow once / always allow") belong to the client, not to this server.
+In Claude Desktop they are set per tool in the extension's settings; a client may ask again
+after an update that changes a tool's definition.
+
+## Attachments and OCR
+
+`mail_get_attachment` downloads the file and returns what the model can read:
+
+- text files as text, HTML converted to text;
+- PDFs as text page by page (`page_from` / `page_to` for long ones);
+- PDF pages without a text layer (scans) and photos go to the **OCR provider** you choose —
+  the result is markdown including tables, and those pages are marked `(OCR)`. A mixed PDF
+  sends only its scanned pages;
+- images are returned as images; anything above ~600 kB or in HEIC is downscaled on macOS
+  (`sips`);
+- other types (docx, xlsx, zip…) are only saved, and the path is returned.
+
+Without a provider, or with `ocr: false`, a scan comes back as an image of page 1 (macOS) with
+a note. OCR is the only thing in this server that sends content anywhere besides your mail
+server — to the provider you picked, or nowhere at all with a local model.
+
+### OCR providers
+
+| `MAIL_OCR_PROVIDER` | What it is | Needs | Reads PDFs |
+|---|---|---|---|
+| `auto` (default) | Mistral when `MISTRAL_API_KEY` is set, a custom server when address and model are set, otherwise off | — | — |
+| `mistral` | Mistral OCR (`mistral-ocr-latest`) | key | directly |
+| `anthropic` | Claude through the official SDK (default model `claude-opus-5-5`) | key | directly |
+| `openai`, `openrouter`, `gemini` | hosted OpenAI-compatible vision chat APIs | key + model | page images |
+| `ollama`, `lmstudio` | local models on `localhost` | model | page images |
+| `custom` | any other OpenAI-compatible server | `MAIL_OCR_BASE_URL` + model | page images |
+| `off` | no OCR | — | — |
+
+`MAIL_OCR_API_KEY`, `MAIL_OCR_MODEL` and `MAIL_OCR_BASE_URL` complete the choice. Examples:
+
+```bash
+MAIL_OCR_PROVIDER=ollama      MAIL_OCR_MODEL=llama3.2-vision                         # fully local
+MAIL_OCR_PROVIDER=openrouter  MAIL_OCR_API_KEY=…  MAIL_OCR_MODEL=<a vision model>
+MAIL_OCR_PROVIDER=anthropic   MAIL_OCR_API_KEY=…
+MAIL_OCR_PROVIDER=custom      MAIL_OCR_BASE_URL=http://nas.lan:8000/v1  MAIL_OCR_MODEL=…
+```
+
+Providers that take images only get each scanned page as a PNG taken out of the PDF (the
+scan itself, scaled to 2000 px). A page that is not one big picture cannot be handed to them
+and is reported as unread; Mistral and Anthropic read any PDF. Pages are sent three at a time.
+
+Things to expect: a local model can need a minute or more per dense page, which may exceed
+your client's tool timeout — read long scans in page ranges. General vision models transcribe
+well but, like every OCR, can misplace cells in tables with graphics; `preview: true` adds the
+page image so the model can check. With `anthropic`, a declined request is retried
+server-side on a fallback model (`fallbacks: "default"`) on the current Claude models.
+
+`node test/live-ocr.mjs` runs the provider configured in the environment against a scanned
+fixture (or your own file) and prints the result.
+
+## Languages
+
+Tool titles, descriptions, output and error messages are localized. English is the source,
+Czech is written by hand, and German, Spanish, French, Italian, Dutch, Polish, Portuguese and
+Slovak are **machine translations** that no native speaker has reviewed yet — corrections are
+welcome.
+
+To add or fix a language edit `src/locales/<code>.ts` (copy `en.ts`, keep the `{placeholders}`
+and line breaks) and register it in `src/locales/index.ts`. A locale may be partial; missing
+keys fall back to English. `npm run test:offline` checks every locale against the English keys.
+
+## Branded builds (presets)
+
+For a family or a team you can ship an extension where the server address is pre-filled and
+people only type their e-mail and password. A preset is a folder with its own `manifest.json`
+(and optionally `icon.png`); see [presets/example](presets/example).
+
+```bash
+./pack.sh --preset /path/to/preset     # → /path/to/preset/<name>.mcpb
+```
+
+The preset's manifest sets `MAIL_TOOL_PREFIX`, `MAIL_BRAND`, `MAIL_LANG` or
+`MAIL_DOWNLOAD_DIR` through `env`, and gives `server_url` a default. Keep the preset's `name`
+stable so Claude Desktop treats new builds as updates.
+
+## Tests
+
+```bash
+npm run test:offline       # no mailbox needed: fake JMAP + fake OCR, the real server over stdio
+MISTRAL_API_KEY=… node test/offline.mjs --live-ocr    # also sends the fixtures to the real OCR
+STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs          # real mailbox
+STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs --send   # also sends a mail to yourself
+```
+
+The offline test covers attachments, OCR, the tool prefix, language selection and locale
+consistency. The smoke test creates a draft and deletes it; with `--send` it leaves one test
+message in the mailbox.
+
+## Good to know
+
+- **A wrong password gets the IP banned** by Stalwart after a few attempts. The server signs in
+  on the first tool call, not at start, so restarting the client does not cause bans; calling
+  tools repeatedly with a wrong password does.
+- Built for and used with Stalwart 0.16. The mail part is plain RFC 8620/8621 and may work with
+  other JMAP servers, but that is untested; contacts need JMAP for Contacts (RFC 9610).
+- `Email/query` with `"inMailbox": null` is rejected by Stalwart — the filter must be absent or
+  carry an id.
+- The extension bundle is one CommonJS file (~3.8 MB, most of it pdf.js from `unpdf`); the
+  `.cjs` extension matters because `package.json` says `"type": "module"`.
+- A tool result in Claude Desktop is capped at about 1 MB, hence the 600 kB limit for inline
+  images.
+
+## License
+
+MIT

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+The distributed bundle (`dist/index.cjs`, the `.mcpb` extension and the npm package) contains
+the following open-source software. Each is used unmodified.
+
+| Component | License | Source |
+|---|---|---|
+| @modelcontextprotocol/sdk | MIT | https://github.com/modelcontextprotocol/typescript-sdk |
+| @anthropic-ai/sdk | MIT | https://github.com/anthropics/anthropic-sdk-typescript |
+| zod | MIT | https://github.com/colinhacks/zod |
+| unpdf | MIT | https://github.com/unjs/unpdf |
+| PDF.js (bundled inside unpdf) | Apache-2.0 | https://github.com/mozilla/pdf.js |
+
+PDF.js is Copyright Mozilla Foundation and licensed under the Apache License, Version 2.0;
+a copy of that license is available at https://www.apache.org/licenses/LICENSE-2.0.
+The MIT-licensed components are Copyright their respective authors; their license texts ship
+in the corresponding packages on npm.