mcp-multi-gmail

MCP server, který dá asistentovi přístup k několika gmailovým schránkám naráz a umožní hledat napříč nimi.

English version: README.en.md

Vestavěný gmailový konektor v Claude umí jednu schránku. Kdo má pracovní, firemní, fakturační a osobní adresu, musí každou z nich hlídat zvlášť - a většinu z nich jen proto, aby mu nic neuteklo. Přístup k několika samostatným schránkám naráz je důvod, proč tenhle server vznikl.

Pracovat se schránkami jde samostatně i dohromady. Většina nástrojů bere jednu schránku; mg_search_threads navíc umí account: "all" a projde všechny naráz. Které z toho dává smysl, záleží na tom, jak se ty schránky k sobě mají: tam, kde se projekty nepotkávají, je hledání napříč spíš pro výjimku, a tam, kde se prolínají, je to ta hlavní věc. Server to nerozhoduje - rozhoduje to, co mu zadáte.

Je to doplněk Miládky, AI asistentky, která běží v Claude Code nad tvým vaultem, a běží jen v ní: vydaný server se spustí jen ze složky doplňků Miládky. Návod pro asistenta - jak s tebou server nastavit a jak pak pracovat s poštou - je v docs/pro-asistenta.md. Server ho asistentovi nabídne sám při připojení.

Instalace

Řekni Miládce: „Nainstaluj si doplněk pro víc gmailových schránek." Postupuje podle návodu pro asistenta: stáhne server do své složky, domluví se s tebou na schránkách a provede tě tím, co musíš udělat ty. To je u každé schránky heslo aplikace v účtu Google (vyžaduje dvoufázové ověření) a zapnutý IMAP v Gmailu. Heslo vkládáš do souboru sám, Miládka ho nevidí.

Related MCP server: Gmail MCP Server

Stav

Server běží v reálném provozu na několika schránkách naráz - osobní, sdílené týmové i schránce, kam chodí jen automatické notifikace. Proti skutečnému Gmailu je vyzkoušené čtení, průchod novou poštou, štítkování, koncepty i odesílání.

Od verze 1.0.0 drží nástroje a klíče konfigurace zpětnou kompatibilitu; nekompatibilní změna zvedne první číslo verze. Co se mění, je v CHANGELOG.md.

Hlídač pošty: --wait --since jmeno=kotva spustí server jako hlídače na pozadí. Každých 5 minut se zeptá Gmailu na totéž co průchod a skončí, až přijde nová pošta, a tím asistenta probudí. Dokud nic nepřijde, nestojí žádné tokeny, na rozdíl od pravidelného průchodu přes cron. Podrobně v návodu pro asistenta, oddíl „Hlídač pošty".

Prefix mg_ v názvech je schválně: server běží vedle vestavěného gmailového konektoru, který má nástroje stejných jmen.

Rozsah

Jen Gmail a Google Workspace, přes IMAP. Server stojí na třech gmailových rozšířeních IMAPu:

Žádný jiný poskytovatel ani jedno z nich nenabízí a standardní THREAD (RFC 5256) Gmail neumí, takže v konfiguraci schválně není volba serveru: připojuje se vždycky na imap.gmail.com.

Co je potřeba

• Miládka

• Node.js 20 nebo novější (tolik vyžadují použité knihovny). Bez práv správce jako ZIP z https://nodejs.org/dist/ s ověřením SHA256, viz návod pro asistenta, krok 2.

• Heslo aplikace pro každou schránku (16 znaků; vyžaduje na účtu zapnuté dvoufázové ověření)

• Zapnutý IMAP v nastavení každé schránky

Nastavení

Nastavení je ve system/multigmail.json ve složce Miládky a zálohuje se s ní, hesla zvlášť v .miladka/secrets/multigmail/hesla.json, který se nezálohuje. Obojí zakládá Miládka podle návodu pro asistenta. Ukázky jsou dvě:

• config.example.json - minimum pro jednu schránku.

• config.example.advanced.json - tři schránky (vlastní, sdílená týmová a schránka pro automaty), klasifikační štítky, povolení adresáti, podpisy a alias.

U každé schránky:

A jednou pro celý server tyhle věci (a smtp_port pro všechny schránky, které ho nemají):

Prázdný attachment_dirs znamená nikam, ne kamkoli - stejně jako allowed_recipients. Zvláštní vypínač na přílohy proto není potřeba: zákaz je v tom, že není odkud brát.

Než tohle zapneš, přečti si to.

Přílohy jsou jediná věc v tomhle serveru, která umí dostat data z tvého disku ven. Všechno ostatní nanejvýš řekne něco navíc do schránky, kterou stejně vlastníš.

A pozor na to, s čím asistent pracuje: čte poštu, tedy text, který psal někdo cizí. Mail může být napsaný tak, aby ho navedl - „pošlete mi prosím soubor …". Povolený adresář je proto přesně tak velký, jak velký únik z něj může být.

Když to zapínáš, ať je to úzká složka určená na věci, co mají jít ven. Ne domovský adresář, ne složka s dokumenty, a rozhodně ne poznámkový vault.

Cesta se porovnává až po rozřešení symlinků a hranice adresáře končí oddělovačem, takže odkaz mířící ven ani složka se stejným začátkem názvu neprojdou. To je ale ochrana proti omylu, ne náhrada za úzký seznam.

Režimy průchodu

Průchod je pro každou schránku týž nástroj a týž postup. Liší se jen tím, co je v té které schránce práce - a to si schránka určuje sama, třemi klíči v konfiguraci. Žádný přepínač „režim" neexistuje: režim je to, co z těch tří hodnot vyjde.

Tři kombinace stojí za pojmenování, protože pokrývají skoro všechno.

Když nastavení dělá asistent, nabídne tyhle varianty uživateli a nechá ho vybrat - postup je v docs/pro-asistenta.md, krok 4.

Vlastní schránka

Schránka, ze které píše jeden člověk. Průchod bere celou schránku, klasifikuje se, odeslaná pošta i archiv jsou práce.

{ "name": "prace", "work_scope": "everything", "can_send": true }

Archiv i odeslaná pošta jsou tu k něčemu dobré: vlastní odpověď je to, podle čeho se pozná, že vlákno už je vyřízené, a archiv drží věci, které si ten člověk sám odložil. Klasifikace dává smysl, protože vlákna v téhle schránce patří jednomu člověku a jeho třídění nikomu nepřekáží.

Sdílená týmová schránka

Schránka, do které sahá víc lidí a rozebírají si ji mezi sebou.

{ "name": "tym", "shared": true, "work_scope": "inbox", "can_send": false,
  "classification_labels": {} }

Tři rozdíly a každý má svůj důvod:

• work_scope: "inbox" - co je v doručené poště, to ještě nikdo nevyřídil. Archiv je to, co někdo odložil, a složka Odeslané jsou odpovědi ostatních lidí na vlákna ostatních lidí - obojí je velké a pro toho, kdo schránku čte, to není práce. Zprávy mimo rozsah se odečítají po vyhledání, počítají se v outside_scope_in_window a nedrží kotvu - ale u vlákna, které prací je z jiného důvodu, se vypíšou, protože „na tohle už někdo odpověděl" je to nejcennější, co jde zjistit bez otevření vlákna.

  Hledá se pořád v celé schránce, ne ve složce INBOX. Vlákno má zprávy roztroušené, takže hledání v jedné složce by udělalo z jeho délky i štítků popis útržku.

• Prázdné classification_labels - klasifikace je tvrzení o tom, co má kdo udělat. V cizí schránce je to tvrzení o cizí práci a ostatní ho uvidí. Prázdná sada z toho dělá hranici, na kterou server narazí, místo pravidla, které se dá přehlédnout. Štítek o zpracování (processed_label) se dává dál - bez něj by se pošta četla pořád dokola.

• can_send: false - odepsat za tým z jeho adresy je něco jiného než odepsat za sebe.

Jak se v takové schránce pozná, co je moje. Tým obvykle značí vlákna podle toho, kdo je řeší. Když se ty štítky vyjmenují, průchod u každého vlákna rovnou řekne, čí je:

"assignment_labels": ["Anna", "Beda", "Cyril", "Dana"],
"my_label": "Anna"

Vlákno, které patří někomu jinému, se tak dá označit a nechat být, aniž se otevře a přečte - a to je na sdílené schránce ta drahá část.

Vyjmenování je schválně: schránka nese štítky několika druhů naráz a vlákno se štítkem Archiv není cizí práce, ale nezabraná věc, kterou někdo odložil. Kdyby se vážily všechny uživatelské štítky, znamenalo by „má štítek, který neznám" totéž co „není moje" - a vlákna ztracená tímhle způsobem se ztrácejí potichu. Štítek mimo seznam proto nechává vlákno none.

Bez těch dvou klíčů zůstávají jen user_labels, tedy holý výčet štítků, a co znamenají, musí rozhodnout ten, kdo server používá.

Schránka pro automaty

Adresa, kam chodí notifikace ze systémů: fakturační, monitorovací, portálové.

{ "name": "automaty", "work_scope": "inbox", "unread_only": true,
  "can_send": false, "classification_labels": {} }

Chová se jako sdílená, jen z jiného důvodu: nikdo tam nepíše, takže třídit není co. Drtivou většinu obsahu zpracuje něco jiného - účetní systém, skript, kolega - a za pozornost stojí jen to, k čemu se nikdo nedostal.

Schránka, kterou si člověk odbývá čtením, nemusí být štítkovaná vůbec. Pak se processed_label nastaví na null a průchod se ptá jen na časovou hranici:

{ "name": "automaty", "work_scope": "inbox", "unread_only": true,
  "processed_label": null, "can_send": false, "classification_labels": {} }

Má to jeden důsledek, se kterým se musí počítat: kotva se nemá jak pohnout. Zpráva zůstane v okně, dokud ji někdo nepřečte, takže window_clear bude false a průchod ji bude vracet pořád dokola. Taková schránka patří do průchodu jednou denně, ne každou půlhodinu. Výměnou za to v cizí schránce nepřibude štítek, který by tam nikomu nic neříkal.

unread_only je na to ten správný nástroj, ale je slabší než work_scope. Archiv a odeslané jsou stavy, které někdo zvolil; přečteno je stav, který způsobí i náhledové okno. Zpráva, kterou si někdo otevře na mobilu, z průchodu vypadne a nevrátí se - je mimo rozsah, takže nikdy nedostane štítek. Stojí to za to jedině tam, kde je druhá možnost číst úplně všechno.

Server sám ten příznak nikdy nenastavuje: každá čtecí cesta otevírá složku jen pro čtení, takže pohled do schránky nezmění, co o sobě říká.

Co režim nemění

Ať je schránka jakákoli, průchod má pořád jen dvě podmínky: nenese štítek o zpracování a přišlo po zadané hranici. Nic z toho, co je výš, se do dotazu nepřidává - všechno se odečítá až po vyhledání. Důvod je v mg_next_pass: Gmail váží podmínky po zprávě, takže podmínka navíc zahodí celé vlákno a odpověď se vrátí jako čistá nula.

Stejně tak platí ve všech režimech, že kotva se posouvá jedině na window_clear: true a že každá viděná zpráva dostane štítek o zpracování, včetně té, která se jen odbyla pohledem na odesílatele.

Podpisy a aliasy

Jedna schránka málokdy píše jedním hlasem. Ta samá adresa posílá nabídky, faktury i osobní odpovědi, a každá z nich končí jinak. Proto tu podpis patří k aliasu, ne ke schránce - pod jakou adresou zpráva odejde a jak se podepíše je jedno rozhodnutí, a rozdělit ho znamená vybrat správnou adresu a podepsat ji špatně.

{
  "name": "firma",
  "address": "jan.novak@example.com",
  "can_send": true,
  "signatures": {
    "plny": { "html_file": "podpisy/plny.html", "text_file": "podpisy/plny.txt" },
    "kratky": { "text": "Jan" },
    "obchod": { "text": "Jan Novák\nobchodní oddělení" }
  },
  "default_signature": "plny",
  "aliases": [
    {
      "address": "obchod@example.com",
      "name": "Firma - obchod",
      "purpose": "poptávky, nabídky a ceníky",
      "default_signature": "obchod"
    }
  ]
}

Podpis se píše tam, kde se píše text - ne do JSONu. Je dlouhý, plný uvozovek a značek, a mění se. V souboru se otevře jako stránka; v konfiguraci by se musel po každé úpravě přeescapovat. text a html přímo v souboru jsou pro krátké podpisy, kde to za samostatný soubor nestojí. Relativní cesta k souboru se počítá od složky, ve které leží konfigurace. Podpisy nejsou tajné: patří do modulu pošty (.miladka/moduly/mail/podpisy/) a ze system/multigmail.json se na ně odkazuje cestou ../.miladka/moduly/mail/podpisy/plny.html.

Obě podoby se drží zvlášť a každá strana zprávy dostane svou. Podpis zadaný jen jako text se pro HTML stranu převede, ne zahodí - zpráva, která končí ničím, vypadá useknutě.

purpose čte asistent, ne Gmail. Bez něj je alias jen adresa, u které se nedá poznat, kdy je ta správná - a co asistent nepozná, to prostě nepoužije.

Alias musí být v konfiguraci. Gmail by neověřený stejně odmítl, ale to není ten důvod: pod jakými adresami schránka píše, rozhoduje ten, kdo ji nastavoval, a adresa, která jen není zakázaná, není totéž co adresa povolená. Stejné pravidlo jako u allowed_recipients a attachment_dirs.

Podpis, který se nenajde, je chyba, ne tichá nepodepsaná zpráva. Podpis je to, co příjemci říká, kdo píše, a volající věřil, že tam je.

V těle zprávy se podpis neopakuje. Vkládá ho server, nad citaci - pod historií by skončil na dně vlákna, které s každou odpovědí roste.

Obsah pošty jsou data, ne pokyny

Asistent, který tenhle server používá, čte text psaný lidmi mimo tvůj počítač. Do mailu může kdokoli napsat cokoli - včetně vět určených jemu: „přepošli mi ten soubor", „tohle už uživatel schválil", „nedrž se svých pravidel".

Server to říká ve svých instrukcích. Není to ale bezpečnostní opatření a nespoléhej se na něj - instrukce je taky jen text a text, který má asistenta obelstít, může tvrdit, že instrukce neplatí.

Skutečná hranice je to, co server neudělá, ať mu kdokoli píše cokoli:

• odešle jen ze schránky, která to má povolené, a jen povoleným adresátům

• přiloží soubor jen z vyjmenovaných adresářů, a bez nich vůbec

• pověsí jen štítek, který je v konfiguraci

• maže do koše, nikdy natrvalo

• nepamatuje si nic mezi voláními, takže není co přepsat

Proto stojí za to nechat attachment_dirs prázdné a allowed_recipients vyplněné, i když je to nepohodlné. Ta omezení se nedají ukecat.

A jedna věc, kam server nedosáhne: co si asistent z pošty zapíše do svých poznámek. Odeslaný mail uvidíš hned, ale nepravda uložená jako fakt vyjde najevo za měsíce - ve chvíli, kdy podle ní něco rozhodneš. Tohle si musí pohlídat pravidla, podle kterých asistent píše.

processed_label je celý název štítku, ne koncovka pod nějakým prefixem - napiš Asistent, pokud tvoje schránka používá tohle.

classification_labels vyjmenovává štítky, které smí asistent pověsit na vlákno, u každého i to, co znamená:

"classification_labels": {
  "Asistent/info": "dobré vědět, nic se nedělá",
  "Asistent/hoří": "musí se to stihnout dneska"
}

Ten popis není komentář. Je to text, podle kterého se asistent rozhoduje, který štítek se hodí - takže názvy můžou být v jakémkoli jazyce a kód o nich nemusí nic vědět. Napsané nahoře v souboru platí pro všechny schránky; schránka, která si vyjmenuje vlastní, tu sadu nahradí, ne rozšíří, protože soubor, který říká, jaké štítky schránka používá, to má myslet vážně.

Tyhle dvě volby jsou zároveň celý seznam štítků, na které nástroje sáhnou. Štítek, který v nich není, se odmítne v obou směrech: nedeklarovaný se nikdy nezaloží a štítek, který na vlákno pověsil uživatel sám, se nikdy neodebere. To první nechává po sobě nepořádek, který pak musíš najít a smazat; to druhé potichu odnese něco, co jsi tam chtěl mít - a chybějící štítek se neprojeví vůbec nikde. mg_list_labels pořád vypíše všechno, co ve schránce je, jen se to odsud nedá měnit.

Pozor na to, že zanoření zapsané lomítkem je v Gmailu jen zobrazení, ne dědičnost: Asistent/hoří a Asistent jsou dva nezávislé štítky a zpráva, která nese první z nich, nenese druhý. Tomu rozdělení, na kterém server stojí, to vyhovuje - štítek „viděl jsem to" jde na zprávu, klasifikace na vlákno - ale znamená to, že se musí pověsit obojí.

Heslo má každá schránka právě jedno: password, password_env, nebo řádek v souboru z passwords_file. password a password_env naráz se odmítne, protože by nebylo jasné, které se používá, a zapomenutá hodnota v tom druhém je heslo, o kterém nikdo neví, že tam je.

can_send je u každé schránky výchozím stavem false. Konfigurace, která by odesílání povolila tím, že se nic nenapíše, by vypadala zamčeně, aniž by zamčená byla.

allowed_recipients je nepovinný a když tam je, vynucuje se přesně. Seznam, který existuje a je prázdný, nedovolí nikam - právě kvůli tomu se píše. Vynechaný klíč znamená bez omezení adresátů, takže zbývá jediná pojistka can_send. Položka je buď celá adresa, nebo doména zapsaná jako @example.com, a pravidlo pro doménu platí jen pro ni: @partner.example dovolí a@partner.example, ale ani a@zly-partner.example, ani a@sub.partner.example.

Jak ten soubor udržet mimo repozitář

Soubor s hesly patří do .miladka/secrets/multigmail/ (celá .miladka/secrets/ v .gitignore vaultu). Nastavení bez hesel (s passwords_file) smí do zálohy: leží ve system/multigmail.json. Pravidlo config.json* v .gitignore serveru je jen záchranná síť pro případ, že se soubor nebo jeho záloha do složky serveru dostane. Zálohy dělej do téže složky jako originál.

Když soubor s hesly leží v repozitáři, zkontroluj, že je ignorovaný (git check-ignore -v cesta/k/souboru musí vypsat pravidlo). Při startu se server podívá, kde soubory s hesly leží: když je uvnitř gitového repozitáře a není ignorovaný, řekne to na stderr dřív, než začne odpovídat. Je to varování, ne odmítnutí - ale neignoruj ho, protože tajemství, které se dostane do historie, se z ní nedá odstranit.

Spuštění

Miládka server zapisuje do .mcp.json v kořeni své složky, s cestami relativními k ní:

{
  "mcpServers": {
    "multi-gmail": {
      "command": "node",
      "args": [".doplnky/mcp-multi-gmail/mcp-multi-gmail.mjs", "--config", "system/multigmail.json"]
    }
  }
}

Mimo složku doplňků Miládky (.doplnky/mcp-multi-gmail/, v anglické Miládce .addons/) nebo ve složce bez .miladka/VERSION server nenaběhne a odkáže na miladka.cz.

Co server řekne asistentovi

Při připojení podá server klientovi krátkou sadu instrukcí, a klient, který je modelu ukáže, je před něj položí ještě dřív, než se zavolá první nástroj. Nesou to málo, co platí o celém serveru a nedá se pověsit na jeden nástroj: které schránky jsou k dispozici a že se dají prohledat i naráz, co znamenají ty dva druhy štítků, a že nastavená sada štítků je zároveň celá sada.

Nejsou napsané natvrdo, ale poskládané z konfigurace, a v tom je ta užitečná část. Štítky každé schránky se vypíšou i s významem, takže asistent nikdy nemusí hádat název. A když žádné klasifikační štítky nastavené nejsou, instrukce to řeknou a požádají asistenta, aby je s uživatelem před prvním průchodem probral - věta, která se objeví jen dokud je pravdivá. Instrukce se totiž posílají při každém připojení, takže napevno napsaná verze té žádosti by se opakovala na začátku každé konverzace navždycky, a tak se z instrukce stane text, který model přestane vnímat.

Jak nástroje zapadají do sebe

Jeden průchod poštou vypadá takhle:

1. mg_next_pass pro každou schránku zvlášť a s její kotvou - datem, do kterého je pošta v té schránce prokazatelně celá zpracovaná. Každá schránka má vlastní kotvu: account: "all" vrací jeden window_clear a jeden searched_at za všechny dohromady, takže jedna schránka s nezpracovanou zprávou by držela okno i ostatním. Dotaz skládá server sám ze štítku a z kotvy; není kam přidat podmínku navíc, a to je smysl toho, že je to vlastní nástroj a ne parametr hledání.

2. mg_get_thread na vlákna, kde message_count je vyšší než počet vrácených nezpracovaných zpráv. Vidíš totiž část konverzace a zbytek může změnit význam toho, co čteš.

3. mg_get_message na těla, která opravdu stojí za přečtení.

4. mg_label_message se štítkem processed_label na každou zprávu, na kterou ses podíval, včetně šumu - jedním voláním se seznamem, ne po jedné. A mg_label_thread s klasifikací té konverzace.

5. Kotvu posuň na searched_at, ale jedině když je window_clear true. Dokud je false, v okně něco neoznačeného zůstalo a příště se projde znovu.

Proč se kotva posouvá takhle opatrně: kdyby se posunula po každém běhu, zpráva, které se štítek z jakéhokoli důvodu nezapsal, se ocitne pod kotvou - není pak v žádném dalším okně a žádný průchod ji už nikdy nenajde. Neoznačený šum naopak kotvu drží na místě, takže označit se musí opravdu všechno, na co ses podíval.

Nástroje

mg_list_accounts

Vypíše nastavené schránky: krátké jméno, adresu, jestli je schránka sdílená, jestli je povolené odesílání, štítek značící viděnou zprávu, klasifikační štítky i s významem každého z nich, podpisy a aliasy.

Je tu i work_scope, tedy kolik ze schránky průchod bere jako práci - viz Režimy průchodu. Stojí za to si to přečíst dřív, než z chybějící pošty vyjde závěr, že něco nechodí: „nepřišlo" a „je mimo rozsah" vypadá odsud stejně.

S verify: true se navíc do každé schránky přihlásí a ověří heslo aplikace. U schránek, které smí odesílat, ověří i odesílání (přihlásí se na SMTP a nic nepošle) a v smtp vrátí port, přes který jde. Schránky se kontrolují souběžně a schránka, která selže, se ohlásí vedle výsledků, ne místo nich. Selhání s check: "smtp" znamená, že čtení funguje, ale odeslat by nešlo.

mg_next_pass

Vrátí vlákna, ve kterých je zpráva, co ještě neprošla průchodem. Tohle je nástroj na procházení nové pošty; mg_search_threads je na hledání konkrétní věci.

Nemá parametr s dotazem, a to je jeho smysl. Průchod se ptá přesně na dvě věci - nemá štítek zpracováno, a byl doručen po zadané kotvě - a nic dalšího se do toho dotazu nedá přidat, protože tudy nevede cesta. Gmail totiž váží podmínky po zprávě, ne po vláknu: jediné from: navíc zahodí vlákno, jehož nezpracovaná zpráva je shodou okolností od někoho jiného, a odpověď se vrátí jako čistý prázdný výsledek.

Okno jede podle času doručení, ne podle hlavičky Date. Je to IMAP SINCE, ne Gmailí after: - ty dva se rozcházejí u přeposlané pošty a hranice podle hlavičky by zprávu přeposlanou dnes, ale psanou minulý měsíc, neukázala už nikdy. SINCE porovnává celé dny, takže den kotvy se pokaždé projde znovu; to nic nestojí, protože hotové zprávy odfiltruje štítek.

Vrací se jen vlákna se skutečnou prací. U každého jeho nezpracované zprávy s odesílatelem, adresáty a kopiemi odděleně - být jen v kopii většinou znamená, že věc patří někomu jinému - a jestli je zpráva v inboxu, nebo archivovaná. message_count je velikost celého vlákna: když je vyšší než počet vrácených zpráv, vidíš část konverzace a zbytek si dotáhni přes mg_get_thread. Je null, když schránka délku vlákna neřekla - schválně se tam nedosazuje počet zpráv, které zrovna známe, protože to by se četlo jako „tohle je celé vlákno" a zbytek konverzace by nikdo nepřečetl.

classification u vlákna říká, jakou kategorii teď nese - abys věděl, z čeho měníš, když ji chceš přepsat.

pending_outgoing vypíše u vlákna tvoje koncepty a naplánované zprávy, ať nenapíšeš druhou odpověď na něco, co už čeká na časovači.

Koncepty a naplánované zprávy se nepočítají jako práce. Je to tvoje vlastní psaní, leží to ve schránce bez štítku a naplánovaná zpráva vyhoví dotazu až do svého odeslání. Štítkovat je nemá smysl - úprava konceptu zprávu nahradí novou, takže štítek to nepřežije. Nevstupují proto do otázky, jestli je okno čisté, a kotvu nedrží; odečtou se až po vyhledání, nikdy jako třetí podmínka, která by uměla vlákno schovat. Vlákno, kde je jediná neoznačená zpráva koncept, se nevrací vůbec.

Naplánovaná zpráva se pozná podle času doručení v budoucnosti a podle toho, že je od tebe. Gmail na ni totiž nedává žádný štítek, takže jinak by vypadala jako běžná došlá pošta z budoucnosti - hlásila by se jako práce a držela kotvu, dokud by neodešla.

stale_threads počítá vlákna, která hledání vrátilo, ale štítek už dávno mají - vyhledávací index se po zápisu aktualizuje se zpožděním. Nevrací se, protože číst je znovu je práce pro nic.

Kotvu posuň na searched_at, a jedině když je window_clear true. Dokud je false, je oldest_unprocessed_at čas doručení nejstarší čekající zprávy - a když se to číslo mezi průchody přestane hýbat, něco v okně se nedaří označit a okno poroste, dokud se na to někdo nepodívá.

mg_search_threads

Hledá v jedné schránce, nebo s account: "all" ve všech. Dotaz je plná syntaxe gmailového hledání a předává se Gmailu nezměněný přes X-GM-RAW, takže se nic nepřekládá a žádná podmínka nemůže cestou vypadnout.

Prohledává se celá schránka, ne doručená pošta: u účtu s filtry většina provozu do INBOX vůbec nevstoupí, takže kdo se dívá jen tam, nevidí, co se ve schránce děje. Jestli je zpráva archivovaná, se hlásí u každé zprávy jako in_inbox, a bere se to ze štítku, ne ze složky.

matched_messages počítá zprávy vlákna, které dotazu odpovídaly, ne velikost vlákna - vlákno o devíti zprávách s jedním zásahem hlásí 1.

unprocessed_matches počítá, kolika z nich štítek opravdu chybí, a čte se to ze samotných zpráv, ne z vyhledávacího indexu. Gmail ten index aktualizuje nějakou dobu po zápisu štítku, takže dotaz na neoznačenou poštu dál vrací vlákna, která byla označená před chvílí. Jestli je ve vlákně něco nového, rozhoduj podle tohohle čísla, nikdy podle toho, že vlákno mezi výsledky je: matched_messages: 3, unprocessed_matches: 0 je zastaralý zásah a přeskočit ho nic nestojí. To zpoždění může vlákno leda ukázat navíc - schovat nezpracované neumí - takže tahle cesta chybuje vždycky na bezpečnou stranu.

U každého vlákna se vrací souhrn nejnovější odpovídající zprávy, ne celá zpráva: odesílatel, čas doručení, stav, in_inbox a Message-ID. Je to schválně úzké - odpověď na čtyřicet vláken s celým objektem zprávy u každého se přestane vejít do kontextu a musí se číst ze souboru, čímž nástroj přestane umět to, kvůli čemu vznikl. Nic se tím neztrácí, protože hledání je první ze dvou stupňů: celé vlákno dá mg_get_thread a tělo mg_get_message, takže se dotahuje jen to, co za to stojí. Z téhož důvodu tu není přepínač podrobnosti - dvoustupňové čtení funguje bez něj a format u čtení nevznikl přesně kvůli tomu.

U account: "all" selhání jedné schránky neznamená ztrátu ostatních. Schránky, které odpověděly, jsou v searched, ty, které ne, jsou vyjmenované v failures i s důvodem, a výsledky zbytku platí. Prázdná odpověď se seznamem selhání znamená „na tyhle schránky se nešlo dostat", ne „nic tam není".

mg_get_thread

Vrací všechny zprávy jednoho vlákna, od nejstarší. message_count je vždycky počet vrácených zpráv; tenhle nástroj nikdy nevrátí část vlákna.

unprocessed_messages odpovídá na otázku „je tu něco nového?", aniž by se musel procházet seznam, a u každé zprávy se to opakuje jako processed.

processed je vlastní štítek asistenta, ne příznak přečtení. Pole seen vedle něj je IMAP příznak \Seen, který nastaví člověk tím, že si zprávu otevře v poštovním klientovi - a protože tenhle server otevírá schránky jen pro čtení, asistent ho svým čtením nikdy nenastaví. seen tedy neříká nic o tom, co asistent udělal, a u sdílené schránky neříká skoro nic vůbec: nepřečteno tam neznamená nevyřízeno, protože to mohl vyřídit kolega, aniž by to označil.

Každá zpráva nese dva identifikátory a dvě časové značky, protože se v obou dvojicích rozcházejí a vybrat jeden by ten rozpor zamlčelo:

state je jedno z received, sent, draft a scheduled. To poslední je důležité: Gmail drží naplánovanou zprávu s hlavičkou Date: nastavenou na čas plánovaného odeslání, takže bez vlastního stavu vypadá jako zpráva, která už odešla.

mg_get_message

Jedna zpráva s výřezem těla. Tělo se vrací po výřezech proto, že u dlouhého vlákna nese každá odpověď citovanou historii, takže text naroste do stovek kilobajtů; body_total_length je celá délka a body_truncated říká, jestli text pokračuje. Přednost dostane prostý text a HTML se vrací tak, jak je, když prostý text chybí - převod, který potichu něco zahodí, je horší než značky, které aspoň vidíš.

Těla se dekódují podle znakové sady, kterou zpráva uvádí, takže pošta, která pořád chodí ve windows-1250 nebo iso-8859-2, si zachová diakritiku.

Neber citovanou historii v odpovědi jako zdroj kontextu. Většinou tam je, ale zaručená není: mobilní klienti ji odstřihávají, přílohy se necitují nikdy, a nic v ní neřekne, co chybí. Strukturu konverzace dává mg_get_thread.

Přílohy se vypíšou s velikostí, ale nestahují se.

mg_get_attachment

Stáhne jednu přílohu, zapíše ji do download_dir a vrátí cestu. Obsah se nevrací přímo v odpovědi, protože příloha běžně měří megabajty. Název souboru ze zprávy se bere jako nedůvěryhodný vstup: nechá se z něj jen poslední část cesty a oddělovače i řídicí znaky se nahradí, na každé platformě stejně.

Štítkovací nástroje

mg_list_labels vypíše, co schránka má. mg_label_message, mg_unlabel_message, mg_label_thread a mg_unlabel_thread mění štítky a nastavený štítek, který ještě neexistuje, se nejdřív založí - Gmail nepřidá štítek, který nezná, a chybu přitom nehlásí.

Každá změna se před ohlášením přečte zpátky. STORE, který server přijme a neprovede, by tě jinak nechal věřit, že zpráva je označená, i když není - a celá mechanika stojí na tom, že to označení je pravdivé. Čte se FETCHem na ty konkrétní zprávy, nikdy hledáním - vyhledávací index se po zápisu štítku aktualizuje se zpožděním a odpověděl by podle stavu z minulé chvíle.

Štítkování zpráv bere seznam a vrací výsledek u každé zprávy zvlášť. Jedno volání místo čtyřiceti, protože každé volání otevírá vlastní spojení a přihlášení stojí zhruba tolik co ta práce sama. U každé zprávy pak stojí changed, already, not_found nebo failed - zpráva, kterou se označit nepovedlo, nezhatí celé volání ani se neschová v celkovém úspěchu. Podle těchto výsledků se rozhoduje, jestli se smí posunout časová hranice průchodu, takže shrnutí za dávku by na to nestačilo. Označit znovu už označenou zprávu není chyba, vrátí se already - přerušený průchod se dá bez obav zopakovat.

Štítek na zprávu a štítek na vlákno jsou dvě různé operace, a proto na ně jsou oddělené nástroje:

A to rozdělení vynucuje server, ne kázeň. mg_label_message bere jedině processed_label, mg_label_thread jedině klasifikace; opačné použití se odmítne i s vysvětlením. To nebezpečnější z toho dvojího je štítek o průchodu na vlákně - Gmail by ho dal i zítřejší odpovědi a ta by se už nikdy neobjevila jako nová.

Vlákno nese jednu klasifikaci a ty se vylučují, takže mg_label_thread ji nastavuje, ne přidává: zadaná jde na vlákno a všechny ostatní z nastavené sady v témž volání spadnou. Starou tedy neodebírej předem - dvě volání by nechala okamžik, kdy je vlákno ve dvou kategoriích nebo v žádné, a vlákno bez kategorie vypadá jako nevyřízené. classification_before a classification_after v odpovědi říkají, z čeho na co.

Gmail štítkem na vlákně označí i zprávy, které do vlákna přijdou později. Štítek o průchodu by tedy na vlákně označil zítřejší odpověď jako viděnou dřív, než by ji kdo přečetl - a právě téhle tiché ztrátě to rozdělení brání.

Štítek na zprávě je filtr příštího průchodu, ne rozsudek. Odpovídá na jedinou otázku - prošla tahle zpráva průchodem - a šum ho nese úplně stejně jako zpráva, která pořád čeká na odpověď: obojí bylo viděné a ani jedno nepotřebuje číst znovu. Co se ještě má stát, je klasifikace, a ta jde na vlákno.

Zní to jako detail a není. Neoznačená zpráva se vrátí v každém dalším průchodu, a nejčastěji zůstane neoznačená právě pošta, se kterou se nic dělat nemuselo. Stačí si ten štítek přečíst jako „vyřízeno" a hromada se potichu naplní přesně tím, na čem záleželo nejmíň.

Vlastní gmailové štítky (\Inbox, \Starred, \Trash a další) se odmítají. Zapisovat je neznamená štítkovat, ale archivovat, hvězdičkovat nebo mazat, každé s vlastními důsledky, a ani jedno z toho tyhle nástroje nedělají.

mg_set_flags

Nastaví IMAP příznaky jedné zprávy: seen, flagged (hvězdička v Gmailu) a answered. Každý předaný příznak se nastaví na danou hodnotu, ty vynechané se nechají být, a aspoň jeden předat musíš. Příznaky se po změně čtou zpátky, jako každý jiný zápis tady.

Tohle není místo, kam si asistent zapisuje vlastní práci. Příznak \Seen patří tomu, kdo si zprávu otevřel v poštovním klientovi - server otevírá schránky jen pro čtení, takže čtením zprávy odsud se \Seen nikdy nenastaví - a u sdílené schránky nepřečteno neznamená nevyřízeno. Co prošlo průchodem, patří do štítku, na zprávu.

Seznam zapisovatelných příznaků je schválně uzavřený. \Deleted v něm není: označit ho není změna příznaku, ale mazání, a co Gmail s expunge udělá, rozhoduje nastavení v účtu uživatele, ne tenhle server. \Draft v něm není taky, protože jeho zrušením by vznikla zpráva, která není ani koncept, ani odeslaná.

mg_save_draft

Uloží koncept do složky Koncepty pomocí IMAP APPEND. Nic se neodesílá a žádné SMTP spojení se neotevírá.

U odpovědi předej in_reply_to s hlavičkou Message-ID zprávy, na kterou se odpovídá. Vlákno, do kterého koncept spadl, se přečte zpátky a porovná s vláknem, do kterého měl patřit, a joined_thread: false znamená, že se koncept nepřipojil a odešel by jako samostatná zpráva. To je dobré vědět dřív, než se odešle, ne potom.

from_alias nastaví hlavičku From na jinou adresu. Musí to být alias už ověřený v Gmailu; tenhle server ověřit žádný neumí a je to jednorázová věc v nastavení Gmailu, ne něco, co by poštovní protokol zvládl.

Pod odpověď se vloží citace zprávy, na kterou odpovídá - quote_original je zapnuté a vypíná se jen tehdy, když má odpověď dorazit holá. Cituje se jen ta jedna zpráva: svou vlastní historii už v sobě nese, takže se vlákno nabaluje samo, přesně jako v poštovním klientovi. Prostá a HTML strana se staví každá ze své předlohy, takže citace neztratí formátování původní zprávy.

Vložené obrázky citaci nepřežijí. Jsou to přílohy, na které HTML odkazuje přes cid:, a přílohy se s citací nepřenášejí - odkaz tedy nikam nevede. Gmail má celou zprávu na svých serverech a udržet je umí, tenhle server ne.

Koncept se ukládá bez příznaku \Draft, což jde proti tomu, jak se IMAP obvykle čte. Gmail ho na svých konceptech nemá také - koncept napsaný ve webovém rozhraní leží ve složce jen s \Seen a konceptem ho dělá ta složka. Zpráva, která ten příznak nese, se Gmailu jeví jako cizí a schová celé její tělo pod tlačítko „zobrazit oříznutý obsah", jako by to byla citovaná historie. Koncept pak vypadá prázdný a uživatel musí kliknout, aby našel vlastní text.

Tělo piš jako HTML ve tvaru, který skládá Gmail sám - vnější <div dir="ltr">, každý odstavec jako <div>, prázdný řádek jako <div><br></div>. Se značkami <p> nastane totéž schování jako s příznakem \Draft, protože je Gmail nepovažuje za vlastní text.

Pozor na režim prostého textu. Když ho má uživatel v okně psaní zapnutý, Gmail HTML část zahodí a pracuje jen s prostým textem - ten pak při odeslání zalomí natvrdo uprostřed vět. Nepozná se to ničím jiným než nápisem „Prostý text" v záhlaví okna, a vypadá to jako chyba serveru. Není.

mg_list_drafts

Vypíše koncepty čekající ve schránce, od nejnovějšího.

U každého konceptu se zopakuje kontrola joined_thread, kterou dělá mg_save_draft, ale proti schránce v aktuálním stavu, ne že by se věřilo tomu, jak to dopadlo při ukládání. Koncept se od vlákna může odtrhnout dodatečně - stačí editace v jiném klientovi - a odtržený koncept vypadá ve výpisu úplně obyčejně až do chvíle, kdy odejde jako samostatná zpráva.

joined_thread: null znamená, že koncept není odpověď, nebo že zpráva, na kterou odpovídal, už ve schránce není a nebylo se s čím porovnávat. warning řekne, která z těch dvou možností to je.

mg_send_message

Odešle zprávu přes SMTP a ověří kopii v Odeslané poště. Tohle se nedá vzít zpátky, takže je to nejvíc pojištěný nástroj tady.

Port se vybírá předem, ne podle chyby. Hostingy, firemní sítě a hotelové wifi port 465 často blokují. Bez smtp_port server před prvním odesláním ze schránky jen zkusí přihlášení na 465, a když se tam nepřipojí, na 587 - nic přitom neposílá. Fungující port si pamatuje. Samotné odeslání pak jde jedním portem a po chybě se nikdy neopakuje jiným: spojení může spadnout ve chvíli, kdy Gmail zprávu už přijal, a druhý pokus by ji doručil dvakrát. Chyba, při které se nic neodeslalo, to říká výslovně; chyba uprostřed odesílání říká, že zpráva odejít mohla a že se má nejdřív zkontrolovat Odeslaná pošta. Výsledek hlásí smtp_port, přes který zpráva šla.

Dvě pojistky, obě výchozím stavem zavřené. Schránka odešle jedině tehdy, když to can_send dovolí, a výchozí stav je false; když je nastavený allowed_recipients, vynucuje se přesně a prázdný seznam nedovolí nikam.

Dva výsledky, hlášené zvlášť. accepted a rejected říkají, ke kterým adresátům zpráva dorazila a ke kterým ne; sent_copy říká, jestli je k nalezení v Odeslané poště. Chybějící kopie neznamená neúspěšné odeslání: když je sent_copy.saved rovno false, zpráva stejně odešla a nesmí se poslat znovu, jen po ní v Odeslané nezůstane stopa a příští průchod poštou o ní nebude vědět. Co stojí za pozornost, se zopakuje ve warning.

Kopii si Gmail ukládá sám. SMTP o schránkách neví nic, takže poštovní klient běžně odešle přes SMTP a pak si kopii přidá do Odeslané přes IMAP - jenže Gmail je výjimka: všechno, co projde přes smtp.gmail.com, se do Odeslané uloží automaticky a vypnout to nejde. Vlastní přidání navíc by zprávu nahrálo podruhé a Gmail může takový souběžný zápis odmítnout, což by se pak hlásilo jako chybějící kopie, která ve skutečnosti je.

Kopie se proto ověřuje, nezapisuje: po odeslání se v Odeslané hledá Message-ID, chvíli opakovaně, protože Gmail ji nemusí založit v tu vteřinu, kdy se odeslání vrátí. Teprve když tam není, přidá ji server sám. sent_copy.filed_by řekne, co z toho nastalo - gmail, nebo server. Přidají se přesně ty bajty, které odešly, protože se zpráva skládá jednou a týž buffer jde do SMTP i do APPEND.

Odeslat existující koncept přes SMTP nejde a tenhle server nepředstírá opak. Protokol takovou operaci nezná: poslat, co je v konceptu, znamená složit tutéž zprávu znovu a původní koncept pak uklidit.

Při tom skládání znovu dej quote_original: false a signature: false. Citace i podpis jsou v tom konceptu už vloženy - když se nechají zapnuté, odejde historie i patička dvakrát.

Ten úklid dělá asistent a dělá ho až po odeslání, nikdy před ním. To pořadí je jediné bezpečné. Když selže mazání, zůstane v Konceptech duplikát - je vidět, dá se smazat a nic se neztratilo. Při opačném pořadí by selhané odeslání nechalo zprávu nenapsanou a koncept už smazaný, tedy text pryč a není z čeho ho vzít zpátky. Uklidit tenhle koncept je správně: uživatel řekl „pošli", ne „nech tam kopii". Proto je to jediná výjimka z pravidla u mg_trash_message, že se poštou neuklízí bez vyžádání.

Koncept, který zůstane v Konceptech po odeslání, není normální stav. Znamená to, že mazání selhalo, a stojí za to si toho všimnout - právě proto se maže až jako druhé.

Přeposlání

Nástroj na přeposlání tu není a nebude. IMAP ani SMTP takovou operaci neznají: předat zprávu dál je z pohledu protokolu nová zpráva, ne úkon nad tou původní. Nechybí tu tedy funkce, jen se jmenuje jinak.

Předává se dál takhle:

1. Odpověz do vlákna přes mg_send_message (nebo mg_save_draft) s in_reply_to nastaveným na Message-ID původní zprávy a s jiným adresátem.

2. Citace jde s sebou sama. quote_original je ve výchozím stavu zapnuté a vloží pod odpověď tu zprávu, na kterou se odpovídá - s řádkou „Dne … napsal:" a odsazeným textem, tak jak to dělá poštovní klient. Do body a html_body piš jen nový text; když do nich citaci napíšeš taky, bude ve zprávě dvakrát.

3. Přílohy vezmi s sebou ručně. Samy nepřejdou: stáhni je přes mg_get_attachment a předej uložené soubory v attachments.

Když přílohy nepřidáš, řekni to - místo abys poslal mail, o kterém si adresát myslí, že v něm faktura je.

Přiložit jde jen ze složek, které vyjmenuje attachment_dirs, a když žádná nastavená není, přílohy nejdou vůbec. Gmail navíc odmítne zprávu nad 25 MB a kódování přílohy zvětší zhruba o třetinu, takže dlouhé vlákno s přílohami se do jedné zprávy vejít nemusí.

mg_trash_message

Přesune jednu zprávu do koše. Jednu zprávu, nikdy celé vlákno: štítkování má nástroj na vlákno proto, že klasifikace platí o konverzaci, kdežto vyhazování pošty ne.

Nic tady nemaže poštu natrvalo. Gmail drží zprávu v koši 30 dní a do té doby ji jde obnovit.

Je to pořád schránka uživatele, takže se sem sahá, když o to řekl, ne na uklízení. Že zpráva prošla průchodem, se zaznamenává štítkem přes mg_label_message a zpráva zůstane, kde je. Jediná výjimka je koncept, jehož text právě odešel přes mg_send_message - ten uklidí asistent sám, viz výš.

Zprávu přesouvá, místo aby ji označil \Deleted, a ten rozdíl není kosmetický. Co Gmail udělá se zprávou, kterou klient označí jako smazanou a provede expunge, rozhoduje nastavení v IMAP volbách uživatele - archivovat, dát do koše, nebo smazat navždy - takže totéž volání by na třech účtech udělalo tři různé věci a jedna z nich je nevratná. MOVE do složky, kterou server sám hlásí jako \Trash, dělá všude jednu věc. (Gmail rozšíření MOVE ohlašuje až po přihlášení, takže seznam schopností přečtený před ověřením ho neukáže.)

Zpráva se po přesunu v koši vyhledá, takže neprovedený přesun je chyba, ne veselé hlášení. Zopakovaný požadavek na zprávu, která už v koši je, chyba není: výsledek řekne moved: false a nic se nezmění.

Bezpečnost

• Heslo aplikace otevírá celou schránku a nedá se zúžit. Gmailový IMAP vyžaduje plný rozsah https://mail.google.com/, takže varianta jen pro čtení neexistuje. Jakékoli omezení musí být v tomhle serveru.

• Hesla se nikdy nezapisují do logu a nikdy je nevrátí žádný nástroj.

• Pro čtení se schránky otevírají jen pro čtení, takže se prohlédnutím zprávy nic ve tvojí schránce neoznačí jako přečtené.

• Diagnostika jde jenom na stderr; na stdout je MCP protokol.

• Odesílání je u každé schránky vypnuté, dokud ho konfigurace nezapne, a nastavený ale prázdný allowed_recipients nedovolí nikam, ne kamkoli.

Licence

Apache License 2.0 - viz LICENSE a NOTICE.