mcp-whatsapp

MCP server, přes který asistent čte a posílá zprávy na WhatsAppu.

English version: README.en.md

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 s ním pracovat, je v docs/pro-asistenta.md. Stavba a rozhodnutí jsou v SPEC.md.

Než začneš: riziko pro číslo

Server se k WhatsAppu připojuje jako další propojené zařízení, stejně jako WhatsApp Web, ale přes neoficiální knihovnu whatsmeow. Podmínky WhatsAppu neoficiální klienty zakazují a WhatsApp za to může číslo zablokovat. Doporučujeme proto pro asistenta samostatné číslo, ne tvoje hlavní.

Dva způsoby použití

Server se propojí s tím WhatsApp účtem, kterým naskenuješ QR kód.

• Asistent má vlastní číslo (doporučujeme): druhá SIM, eSIM nebo starý telefon. Píšeš a diktuješ mu ze svého telefonu jako komukoli jinému a on ti odpovídá. Riziko zablokování nese jeho číslo.
• Asistent na tvém čísle, podobně jako u pošty: čte tvoje chaty, připravuje odpovědi a za tebe posílá jen to, co mu schválíš. Každá zpráva odejde pod tvým jménem a riziko nese tvoje hlavní číslo. Pokyny mu přes WhatsApp psát nejde, tvoje zprávy jsou pro server odeslané tebou.

Co umí

• Spárování z chatu: QR kód jako obrázek, nebo kód k opsání do telefonu. Terminál nepotřebuješ.
• Čtení a odesílání s pevnými hranicemi. V config.json určíš, které chaty smí číst a kam smí psát, zvlášť pro osobní chaty a skupiny. Asistent si nastavení sám nepřepíše.
• Nové zprávy od kurzoru, hledání v uložených zprávách, fotky, soubory a hlasovky ke stažení.
• Píšeš a diktuješ asistentovi z telefonu. Pokyny bere jen od tvého čísla, zprávy ostatních jsou pro něj jen informace. Nové zprávy hlídá server sám (--wait) a asistenta probudí, až mu napíšeš. Čekání nestojí žádné tokeny.
• Přepis hlasovek na text přímo v počítači. Nic neodchází ven. Model se stáhne jednou (asi 510 MB), až k tomu dáš souhlas.
• Změna nastavení bez nové konverzace: asistent po úpravě config.json zavolá wa_reload_config a server ho načte hned.
• Čitelný stav: zastaralý klient, odhlášení z telefonu, výpadek sítě nebo spojení v jiné konverzaci jsou vidět jako různé stavy.
• Samo se udržuje: knihovna whatsmeow se jednou týdně aktualizuje a vyjde nová verze, když testy projdou.

Instalace

Řekni Miládce: „Nainstaluj si doplněk WhatsApp." Postupuje podle návodu pro asistenta: stáhne program pro tvůj systém (binárky pro Windows, macOS a Linux jsou v releasech se SHA256SUMS) do své složky .doplnky/mcp-whatsapp/, domluví se s tebou na nastavení a nechá tě naskenovat QR kód. Program si data dává vedle sebe do data/, takže se s Miládkou stěhuje jednou složkou.

Mimo složku doplňků Miládky, nebo ve složce bez .miladka/VERSION, server nenaběhne a odkáže na miladka.cz.

Nastavení

{
  "read": { "chats": "all", "groups": false },
  "send": { "chats": ["+420777123456"], "groups": false, "files": [] },
  "history_sync": false,
  "device_name": "Miládka"
}

Klíč	Význam
read.chats	osobní chaty, které smí číst: "all", false, nebo seznam čísel (+420…)
read.groups	skupiny: "all", false, nebo seznam JID skupin (…@g.us, zjistí wa_list_chats)
send.chats, send.groups	kam smí psát, stejný tvar; jen v rámci toho, co smí číst
send.files	celé cesty ke složkám, ze kterých smí posílat soubory; prázdné = soubory ne
history_sync	po spárování uložit historii povolených chatů (výchozí ne)
history_days	s history_sync: jen posledních N dní historie (1 = posledních 24 hodin); bez něj všechno, co telefon nabídne
device_name	jméno zařízení v telefonu v Propojených zařízeních
transcription.enabled	přepis hlasovek; výchozí true, platí až po instalaci (wa_transcription_setup)
transcription.threads, transcription.batch	vlákna a počet úseků najednou; výchozí 2 a 2 (asi 1,3 GB paměti). Na slabém stroji batch: 1
owner	tvoje číslo nebo seznam čísel (+420…): jen jejich zprávy jsou pro asistenta pokyny; musí být v read.chats
wake	které nové zprávy asistenta probudí (režim --wait): "owner" (výchozí), seznam dalších čísel a skupin (budí spolu s tebou), nebo "all"
media_dir	kam se ukládají fotky, hlasovky a dokumenty; výchozí data/media vedle programu, Miládka nastavuje vstupy/whatsapp
media_keep_days	po kolika dnech se stažená média smažou (text a přepis zůstanou); výchozí 30, 0 = nikdy
data_dir	kde leží data serveru; výchozí data/ vedle binárky
transcription.dir

Čísla vždycky s předvolbou země (+420777123456), číslo bez ní server odmítne. Prázdný seznam i chybějící klíč znamená nikam, ne kamkoli. Relativní cesty se berou od kořene složky Miládky.

V datové složce je session.db s klíči spárovaného zařízení. Kdo má ten soubor, má přístup k tvému WhatsAppu. Nepatří do gitu ani do zálohy.

Licence

PolyForm Shield 1.0.0, viz LICENSE. Kód je veřejný, abyste si mohli ověřit, co doplněk dělá. Smíte ho používat, upravovat i sdílet, jen z něj nesmíte udělat produkt, který konkuruje Miládce. Starší verze vyšly pod Apache 2.0 a pod ní zůstávají. Server vychází z částí wadb (MIT, upozornění v NOTICE). Knihovna whatsmeow je závislost pod MPL-2.0, její zdrojový kód je na GitHubu autora. Přepis hlasovek stahuje na požádání sherpa-onnx (Apache-2.0) a model NVIDIA Parakeet TDT 0.6B v3 (CC BY 4.0); podrobnosti v NOTICE.