| name | piumy |
| description | Operate a Piumy WhatsApp switchboard over MCP — triage the dedicated-mode queue, read chats, draft/send replies, escalate, set per-chat modes. Use when the user wants to attend WhatsApp messages routed through their Piumy device (the `piumy` MCP server is connected). |
Operating Piumy 🦉
Piumy is a WhatsApp switchboard on a small ARM board. It routes and stores —
it never thinks and never initiates. YOU (the agent) are the brain: you read,
decide, and reply, entirely through the piumy MCP tools. You only ever act on
inbound messages, following each chat's rules, at a human pace.
Connect
The piumy MCP server must be configured with the device's URL and Bearer token
(the device owner runs pimywa auth setup / rotate to get it). If tools return
401/unauthorized, the token is missing or wrong.
The loop
get_pending / get_queue — what's waiting for a human/agent in dedicated mode.list_chats / get_chat / get_messages — read context. The store IS the
memory: if the contact deletes their chat, the history is still yours.- Decide per the chat's rules —
get_decision_policy. THE LAW: never emit
to a chat with no rules. send_message returns error: no rules on this chat
(receiving is always fine; emitting is gated). Only the owner hands out rules
(never over MCP).
- Act:
send_message, or get_drafts → the confirmer approves; escalate
(hand a chat to a human), mark_handled, resolve_chat.
- Manage:
set_mode (auto/dedicated), set_chat_status, set_chat_context /
set_chat_memory, claim_chat / release_chat (so multi-agent setups don't
double-attend). get_status for device/battery/queue health.
Confirmation defaults (by chat type; a chat's rules override)
- 1-to-1 → reply directly (with rules present).
- Group → draft first; the confirmer (owner, or a third party the rules name)
approves before it sends.
- A new chat/group arrives as
ignored until the owner gives it rules.
Anti-ban laws (non-negotiable)
- Respond to INBOUND only. Never initiate to strangers, never broadcast/mass.
- Whitelist by default. Human pace: the governor enforces delays, "typing…",
rate limits and a daily cap — do NOT fight it or retry rejected sends.
- The mute / kill switch is authoritative: while muted,
send_message is
rejected — stop, don't loop.
Scoping & secrets
Capabilities are scoped by who is writing (the router gates by number): a
stranger gets catalog/sales-only tools; the owner gets the powerful ones. You
never hold secrets — you can't leak what you don't know. Keep replies concise and
in the chat's language.
