stalwart-mail-mcp 2.2.0

package/docs/mala-infrastruktura.md

@@ -0,0 +1,149 @@
+# Zapojení do malé vlastní infrastruktury
+
+*[English](small-infrastructure.md)*
+
+Popisuje sestavu, pro kterou server vznikl: jeden domácí nebo kancelářský stroj, na kterém běží
+Stalwart pro rodinu nebo pár lidí, před ním reverzní proxy a na notebooku každého Claude
+Desktop. Názvy hostitelů jsou příklady.
+
+## Jak to vypadá
+
+```text
+ notebook                                 tvůj server
+┌───────────────────────────┐            ┌──────────────────────────────────────────────┐
+│ Claude Desktop            │            │ reverzní proxy (Traefik / Caddy / nginx), TLS│
+│  └─ Stalwart Mail MCP ────┼── HTTPS ──▶│   /.well-known/jmap, /jmap/*  ──▶ Stalwart   │
+│      (místní proces)      │   JMAP     │   (správcovské API zůstává uvnitř)           │
+│  └─ další tvoje MCP       │            │ Stalwart: SMTP · IMAP · JMAP · CardDAV       │
+└───────────┬───────────────┘            │ webmail (volitelně) na stejném názvu         │
+            │ volitelně, jen skeny       └──────────────────────────────────────────────┘
+            ▼
+      OCR: lokální model (Ollama, LM Studio) nebo API (Mistral, Anthropic, kompatibilní s OpenAI)
+```
+
+MCP server je místní proces na notebooku. Drží heslo schránky (z klíčenky), mluví s tvým
+serverem přes JMAP a dává Claudovi deset nástrojů. Na straně serveru není potřeba žádný
+doplněk, účet navíc ani API klíč — jen JMAP dostupný přes HTTPS.
+
+## Co musí server nabízet
+
+1. **JMAP přes HTTPS** na veřejném názvu (nebo dostupném přes VPN) s platným certifikátem.
+2. **Dvě cesty přes reverzní proxy**: `/.well-known/jmap` a všechno pod `/jmap` (session,
+   API, nahrávání i stahování žijí tam). Nic dalšího potřeba není — správcovské API a správu
+   Stalwartu na veřejný router nedávej.
+3. **Adresy v session musí ukazovat na veřejný název.** Klient si z objektu session přečte
+   `apiUrl`, `uploadUrl` a `downloadUrl` a volá je tak, jak jsou. Ověření:
+
+   ```bash
+   curl -s -u jana@example.com https://mail.example.com/.well-known/jmap -L | head -c 600
+   ```
+
+   Když adresy ukazují na vnitřní název nebo `http://`, oprav nejdřív veřejnou adresu
+   Stalwartu / hlavičky proxy — jinak by hledání fungovalo, ale přílohy a odesílání ne.
+4. **Ke Stalwartu musí dojít skutečná IP klienta.** Stalwart banuje adresy, které hádají
+   hesla. Když vidí jen adresu proxy, jedno špatně opsané heslo v nastavení něčího rozšíření
+   zabanuje proxy, tedy všechny. Předej IP klienta dál (PROXY protocol nebo důvěryhodné
+   hlavičky) a bany zůstanou na jednom člověku.
+
+Router Traefiku pro JMAP vypadá takto (file provider):
+
+```yaml
+http:
+  routers:
+    stalwart-jmap:
+      rule: "Host(`mail.example.com`) && (PathPrefix(`/jmap`) || Path(`/.well-known/jmap`))"
+      entryPoints: [websecure]
+      service: stalwart-web
+      tls: {}
+  services:
+    stalwart-web:
+      loadBalancer:
+        servers:
+          - url: "http://stalwart:8080"
+```
+
+Pokud ti proti Stalwartu už běží webmail přes JMAP, cesty jsou hotové a není co měnit.
+
+## Účty a přihlášení
+
+- Každý se přihlašuje **svou schránkou** — stejnou adresou a heslem jako v telefonu. Pokud
+  tvůj Stalwart nabízí hesla aplikací, použij pro rozšíření jedno z nich, ať jde zrušit
+  samostatně.
+- `STALWART_TOKEN` přijme místo hesla přístupový token OAuth (posílá se jako Bearer), pokud
+  si tokeny vydáváš sám; rozšíření žádné interaktivní přihlášení OAuth nemá.
+- **Sdílené schránky a skupiny** se na klientu nenastavují: každý účet, ke kterému má
+  přihlášený uživatel přístup, je v JMAP session a nástroje ho berou parametrem `account`
+  (`account: "rodina"`). Vypíše je `mail_list_mailboxes`. Sdílený účet má vlastní složky,
+  odesílací identitu i adresář.
+- **Kontakty** jsou adresáře serveru (JMAP for Contacts). Tytéž adresáře se do telefonů
+  synchronizují přes CardDAV, takže kontakt, který Claude přidá do sdíleného adresáře, se
+  objeví všem v telefonu.
+
+## Co Claude může a co ne
+
+- Čte, hledá, zakládá koncepty a odesílá **jako ten člověk** — nic víc, než dovolí heslo
+  schránky, a nic v cizích soukromých schránkách.
+- Odeslání je okamžité. Popisy nástrojů modelu ukládají posílat jen na výslovný pokyn
+  a jinak uložit koncept; koncepty jsou vidět ve webmailu i v telefonu ke kontrole. Kdo chce
+  tvrdou pojistku místo pokynu, vypne v nastavení rozšíření **Povolit odesílání** — nástroje
+  pro odeslání pak pro model neexistují — nebo si je v klientu nechá schvalovat ručně.
+- Přijatou ani odeslanou poštu smazat neumí; `mail_delete_draft` odmítne cokoli, co není
+  koncept.
+- Přílohy se ukládají na notebook (výchozí `~/Downloads/Mail-Attachments`).
+
+## Co odchází z počítače
+
+| Data | Kam jdou |
+|---|---|
+| heslo schránky, veškerý poštovní provoz | jen na tvůj Stalwart |
+| obsah zpráv a příloh, které model čte | k AI klientu, který používáš (jako výstup každého nástroje) |
+| naskenované strany PDF a fotky, když je zapnuté OCR | ke zvolenému poskytovateli OCR — nebo s lokálním modelem nikam |
+
+OCR je vypnuté, dokud není nastavený poskytovatel, a `ocr: false` ho přeskočí u jedné přílohy.
+Když dokumenty nesmí opustit dům, pusť model s viděním v Ollamě na notebooku nebo na serveru
+a rozšíření na něj nasměruj (`ollama`, nebo `custom` s adresou serveru).
+
+## Jedno rozšíření pro celou domácnost
+
+Psát adresu serveru je pro většinu lidí o jedno pole víc, než je zdrávo. Vyrob **předvolbu**:
+kopii manifestu s předvyplněným serverem, vlastním názvem a ikonou a — pokud chceš, aby se
+nástroje v rozhovoru četly přirozeně — s vlastní předponou a výchozím jazykem.
+
+```text
+moje-predvolba/
+  manifest.json     name, display_name, výchozí server_url, env: MAIL_TOOL_PREFIX, MAIL_BRAND, MAIL_LANG
+  icon.png
+```
+
+```bash
+./pack.sh --preset ~/infra/moje-predvolba      # → ~/infra/moje-predvolba/<name>.mcpb
+```
+
+Soubor `.mcpb` rozdej lidem (není tajný, žádné přihlašovací údaje v něm nejsou); otevřou ho,
+zadají e-mail a heslo a je hotovo. Předvolbu drž vedle ostatní konfigurace infrastruktury
+a přestav ji, kdykoli se tento repozitář posune. Její `name` neměň, aby klient nabídl
+aktualizaci, a ne druhé rozšíření.
+
+## Kombinace s dalšími nástroji
+
+Smysl pošty za MCP je v tom, že se v jednom rozhovoru potká s ostatními daty:
+
+- oborový nástroj (CRM, databáze nemovitostí, fakturace jako vlastní MCP server) a pošta:
+  „podívej se, jestli už makléř odpověděl, přečti přiložený průkaz energetické náročnosti
+  a doplň zjištění k záznamu“;
+- ranní naplánovaná úloha: nepřečtená pošta od včerejška podle odesílatelů, s přílohami
+  shrnutými;
+- odpovědi z poznámek — Claude napíše koncept, ty ho odešleš z telefonu.
+
+Každou oblast drž ve vlastním MCP serveru; tenhle zná jen poštu a kontakty.
+
+## Provozní poznámky
+
+- **Bany**: po změně hesla uprav nastavení rozšíření dřív, než zavoláš další nástroj. Ban se
+  projeví jako odmítnuté spojení nebo 401 po nějakou dobu; zmizí sám, nebo ho zrušíš ve
+  správě Stalwartu.
+- **Aktualizace**: `git pull && ./pack.sh` (nebo `--preset …`) a otevřít nový `.mcpb`.
+- **Záloh** se netýká — server nedrží žádný stav, všechno je ve Stalwartu.
+- **Monitoring**: sonda na `https://mail.example.com/.well-known/jmap` řekne, že cesta, na
+  které rozšíření stojí, žije — bez přihlášení Stalwart odpoví 307 na `/jmap/session`, která
+  vrátí anonymní session (200, schopnosti serveru, ale žádné účty).

package/docs/publishing.md

@@ -0,0 +1,86 @@
+# Publishing checklist
+
+The repository starts private. Nothing below happens automatically — each step is a decision.
+
+## 0. Before anything goes public
+
+- Read `git log` and the tree once more for anything private (hostnames, names, credentials).
+  The test fixtures are synthetic; presets with real server names belong in your own
+  infrastructure repository, not here.
+- `npm run test:offline` and, against a real mailbox, `node test/smoke.mjs`.
+- Bump `version` in `package.json` (and `server.json`); `pack.sh` copies it into the manifest.
+
+## 1. GitHub: make the repository public and cut a release
+
+```bash
+gh repo edit cybersmurf/stalwart-mail-mcp --visibility public --accept-visibility-change-consequences
+./pack.sh
+git tag v2.0.0 && git push origin v2.0.0
+gh release create v2.0.0 stalwart-mail.mcpb --title "Stalwart Mail MCP 2.0.0" --notes "First public release."
+```
+
+The `.mcpb` attached to the release is what Claude Desktop users download and open. This step
+alone is enough for people to use it.
+
+## 2. npm: `npx stalwart-mail-mcp` for every other MCP client
+
+```bash
+npm adduser                      # once
+npm publish --access public      # prepublishOnly builds and runs the offline test
+```
+
+After that any client can run it without cloning:
+
+```json
+{ "command": "npx", "args": ["-y", "stalwart-mail-mcp"], "env": { "STALWART_URL": "…", "STALWART_USER": "…", "STALWART_PASSWORD": "…" } }
+```
+
+## 3. Official MCP Registry (feeds the catalogs of MCP clients)
+
+The registry stores metadata only and verifies it against the npm package, so step 2 comes
+first. `package.json` already carries `mcpName` and `server.json` is in the repository root;
+both must name `io.github.cybersmurf/stalwart-mail-mcp` and the same version as on npm.
+
+```bash
+brew install mcp-publisher
+mcp-publisher login github       # device code in the browser
+mcp-publisher publish
+```
+
+Guide: <https://modelcontextprotocol.io/registry/quickstart>
+
+## 4. Claude directory (optional, reviewed by Anthropic)
+
+The directory no longer lists local servers packaged as desktop extensions (`.mcpb`). A local
+MCP server gets there inside a **plugin bundle**, and that has a consequence worth knowing
+before spending time on it: per Anthropic's platform table, a local server in a plugin runs in
+**Claude Code** and in **Cowork sessions on your own computer**, and is **ignored in chat**
+(claude.ai, desktop and mobile). Cowork also does not ask for settings, so a server that needs
+a password only really works in Claude Code. People who want mail in Claude Desktop chat keep
+using the `.mcpb` from the GitHub release.
+
+The bundle is in [`plugin/`](../plugin): `.claude-plugin/plugin.json` (settings as
+`userConfig`, secrets marked `sensitive`), `.mcp.json` (starts `npx -y stalwart-mail-mcp@<exact
+version>`), a README that says what it runs and where data goes, and the license.
+
+1. npm publish first (step 2) — the bundle starts the package from npm.
+2. Keep the version in `plugin/.mcp.json` and `plugin/.claude-plugin/plugin.json` equal to
+   the published one (`claude plugin validate ./plugin` checks the files are well-formed).
+3. From a paid Claude account open <https://claude.ai/directory/manage> → **Submit new** →
+   **Plugin bundle** → repository `cybersmurf/stalwart-mail-mcp`, folder `plugin` → **Validate**.
+4. Expect holds for a reviewer rather than an instant listing: a pinned `npx` package is
+   always reviewed by a person, and the name contains "Stalwart", a brand that is not ours —
+   say in the submission that this is an independent client for Stalwart servers.
+
+Checklist: <https://claude.com/docs/plugins/pre-submission-checklist>
+
+## 5. Tell people who run Stalwart
+
+A short post in Stalwart's GitHub Discussions (or their community chat) with the link to the
+release and to `docs/small-infrastructure.md` reaches exactly the audience this is for.
+
+## Releasing an update
+
+Bump the version in `package.json`, `server.json`, `plugin/.claude-plugin/plugin.json` and `plugin/.mcp.json` → `npm run test:offline` → commit and tag →
+`./pack.sh` and `gh release create` → `npm publish` → `mcp-publisher publish`. Branded presets
+are rebuilt with `./pack.sh --preset <dir>` from their own repositories.

package/docs/small-infrastructure.md

@@ -0,0 +1,150 @@
+# Plugging it into a small self-hosted setup
+
+*[Česky](mala-infrastruktura.md)*
+
+This describes the kind of setup the server was built for: one home or small-office machine
+that runs Stalwart for a family or a handful of people, behind a reverse proxy, with Claude
+Desktop on everyone's laptop. Hostnames below are examples.
+
+## The picture
+
+```text
+ laptop                                   your server
+┌───────────────────────────┐            ┌──────────────────────────────────────────────┐
+│ Claude Desktop            │            │ reverse proxy (Traefik / Caddy / nginx), TLS │
+│  └─ Stalwart Mail MCP ────┼── HTTPS ──▶│   /.well-known/jmap, /jmap/*  ──▶ Stalwart   │
+│      (local process)      │   JMAP     │   (admin API stays internal)                 │
+│  └─ your other MCP servers│            │ Stalwart: SMTP · IMAP · JMAP · CardDAV       │
+└───────────┬───────────────┘            │ webmail (optional) on the same host name     │
+            │ optional, scans only       └──────────────────────────────────────────────┘
+            ▼
+      OCR: a local model (Ollama, LM Studio) or an API (Mistral, Anthropic, OpenAI-compatible)
+```
+
+The MCP server is a local process on the laptop. It holds the mailbox password (from the
+keychain), speaks JMAP to your server, and gives Claude ten tools. The server side needs no
+plugin, no extra account and no API key — only JMAP reachable over HTTPS.
+
+## What the server has to provide
+
+1. **JMAP over HTTPS** on a public (or VPN-reachable) host name with a valid certificate.
+2. **Two paths through the reverse proxy**: `/.well-known/jmap` and everything under `/jmap`
+   (session, API, upload and download all live there). Nothing else is required — keep
+   Stalwart's management API and admin UI off the public router.
+3. **Session URLs that point at the public name.** The client reads `apiUrl`, `uploadUrl` and
+   `downloadUrl` from the session object and calls them as they are. Check it:
+
+   ```bash
+   curl -s -u jane@example.com https://mail.example.com/.well-known/jmap -L | head -c 600
+   ```
+
+   If the URLs show an internal host or `http://`, fix Stalwart's public URL / proxy headers
+   first — attachments and sending would otherwise fail while searching still works.
+4. **The real client IP reaching Stalwart.** Stalwart bans addresses that guess passwords. If
+   it only ever sees the proxy's address, one mistyped password in someone's extension settings
+   bans the proxy, i.e. everybody. Pass the client IP through (PROXY protocol or trusted
+   forwarded headers) and bans stay per person.
+
+A Traefik router for the JMAP part looks like this (file provider):
+
+```yaml
+http:
+  routers:
+    stalwart-jmap:
+      rule: "Host(`mail.example.com`) && (PathPrefix(`/jmap`) || Path(`/.well-known/jmap`))"
+      entryPoints: [websecure]
+      service: stalwart-web
+      tls: {}
+  services:
+    stalwart-web:
+      loadBalancer:
+        servers:
+          - url: "http://stalwart:8080"
+```
+
+If a webmail client already works against your Stalwart over JMAP, the routes are already
+there and there is nothing to change.
+
+## Accounts and sign-in
+
+- Each person signs in with **their own mailbox** — the same address and password as on the
+  phone. If your Stalwart offers app passwords, use one for the extension so it can be revoked
+  on its own.
+- `STALWART_TOKEN` takes an OAuth access token instead (sent as Bearer) if you issue tokens
+  yourself; the extension has no interactive OAuth flow.
+- **Shared mailboxes and groups** need no setup on the client: every account the signed-in
+  user can access appears in the JMAP session, and tools take it through the `account`
+  parameter (`account: "family"`). `mail_list_mailboxes` lists them. A shared account has its
+  own folders, sending identity and address book.
+- **Contacts** are the server's address books (JMAP for Contacts). The same books sync to
+  phones over CardDAV, so a contact Claude adds to the shared book appears on everyone's phone.
+
+## What Claude can and cannot do
+
+- It reads, searches, drafts and sends **as that person** — nothing more than the mailbox
+  password allows, and nothing on other people's private mailboxes.
+- Sending is immediate. The tool descriptions instruct the model to send only when the user
+  explicitly asks and to save a draft otherwise; drafts show up in webmail and on the phone
+  for review. If you want a hard guarantee rather than an instruction, switch **Allow sending** off
+  in the extension settings — the send tools then do not exist for the model — or keep them
+  on manual approval in the client.
+- It cannot delete received or sent mail; `mail_delete_draft` refuses anything that is not a
+  draft.
+- Attachments are written to the laptop (`~/Downloads/Mail-Attachments` by default).
+
+## What leaves the machine
+
+| Data | Goes to |
+|---|---|
+| mailbox password, all mail traffic | your Stalwart server only |
+| message and attachment content the model reads | the AI client you use (as with any tool output) |
+| scanned PDF pages and photos, when OCR is on | the OCR provider you chose — or nowhere, with a local model |
+
+OCR is off until a provider is set up, and `ocr: false` skips it for a single attachment. If
+the documents must not leave the house, run a vision model in Ollama on the laptop or on the
+server and point the extension at it (`ollama`, or `custom` with the server's address).
+
+## One extension for the whole household
+
+Typing a server address is one field too many for most people. Build a **preset**: a copy of
+the manifest with your server pre-filled, your own name and icon, and — if you want the tools
+to read naturally in conversations — your own prefix and default language.
+
+```text
+my-preset/
+  manifest.json     name, display_name, default server_url, env: MAIL_TOOL_PREFIX, MAIL_BRAND, MAIL_LANG
+  icon.png
+```
+
+```bash
+./pack.sh --preset ~/infra/my-preset      # → ~/infra/my-preset/<name>.mcpb
+```
+
+Hand the `.mcpb` to people (it is not secret — it contains no credentials); they open it,
+type e-mail and password, done. Keep the preset next to the rest of your infrastructure
+config and rebuild it whenever this repository moves forward. Keep its `name` unchanged so
+the client offers an update instead of a second extension.
+
+## Combining it with other tools
+
+The point of putting mail behind MCP is that it meets your other data in one conversation:
+
+- a domain tool (a CRM, a property database, an invoicing system as its own MCP server) plus
+  mail: "check whether the agent already answered, read the attached energy certificate and
+  add the findings to the record";
+- a scheduled morning task: unread mail since yesterday, grouped by sender, with attachments
+  summarized;
+- drafting replies from notes — Claude writes the draft, you send it from the phone.
+
+Keep each concern in its own MCP server; this one only knows mail and contacts.
+
+## Operating notes
+
+- **Bans**: after a password change, update the extension settings before the next tool call.
+  A ban shows up as a refused connection or 401 for a while; it lifts by itself or from the
+  Stalwart admin UI.
+- **Updates**: `git pull && ./pack.sh` (or `--preset …`) and open the new `.mcpb`.
+- **Backups** are unaffected — the server keeps no state; everything lives in Stalwart.
+- **Monitoring**: a blackbox probe on `https://mail.example.com/.well-known/jmap` tells you
+  the route the extension depends on is alive — without credentials Stalwart answers 307 to
+  `/jmap/session`, which returns an anonymous session (200, capabilities but no accounts).

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "stalwart-mail-mcp",
+  "version": "2.2.0",
+  "description": "MCP server for Stalwart Mail over JMAP: search, read (attachments, OCR of scans), reply, send, drafts, contacts",
+  "mcpName": "io.github.cybersmurf/stalwart-mail-mcp",
+  "license": "MIT",
+  "author": "Petr Šrámek",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cybersmurf/stalwart-mail-mcp.git"
+  },
+  "homepage": "https://github.com/cybersmurf/stalwart-mail-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "stalwart",
+    "jmap",
+    "email",
+    "contacts",
+    "ocr",
+    "claude"
+  ],
+  "bin": {
+    "stalwart-mail-mcp": "dist/index.cjs"
+  },
+  "files": [
+    "dist/index.cjs",
+    "README.md",
+    "README.cs.md",
+    "docs",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "type": "module",
+  "main": "dist/index.cjs",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/index.cjs --log-level=warning",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node test/offline.mjs && node test/smoke.mjs",
+    "test:offline": "npm run build && node test/offline.mjs",
+    "pack": "bash pack.sh",
+    "prepublishOnly": "npm run build && node test/offline.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "unpdf": "^1.8.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "esbuild": "^0.27.0",
+    "typescript": "^5.9.3"
+  }
+}