# whatsapp-mcp

MCP-сервер к WhatsApp через шлюз [GREEN-API](https://green-api.com). Даёт агенту
чтение переписки (история чата, журналы входящих и исходящих, контакты, группы)
и отправку сообщений и файлов.

Работает с обычным личным номером: номер один раз привязывается к инстансу
GREEN-API по QR-коду в консоли шлюза, дальше никакого локального процесса
и никакого повторного сканирования не нужно.

## Зачем шлюз

Официальный WhatsApp Business Cloud API от Meta не даёт доступа к личной
переписке и истории — только к диалогам, начатым после подключения бизнес-номера.
Локальные мосты (whatsmeow, Baileys) требуют постоянно работающего процесса
на машине пользователя. GREEN-API закрывает обе проблемы ценой платного тарифа
и того, что под капотом у него неофициальный протокол.

> Репозиторий пока лежит в личном пространстве `eurogas-bbl`, а не в
> `brain-boost-academy`: прав на создание репозиториев в организации нет.
> После переноса GitHub оставит редирект, и ссылки ниже продолжат работать.

## Установка

Зависимостей, кроме `uv`, нет:

```bash
uvx --from git+https://github.com/eurogas-bbl/whatsapp-mcp whatsapp-mcp
```

Как запись в `.mcp.json`:

```json
{
  "mcpServers": {
    "whatsapp": {
      "command": "uvx",
      "args": [
        "--env-file", "/путь/к/whatsapp-mcp.env",
        "--from", "git+https://github.com/eurogas-bbl/whatsapp-mcp",
        "whatsapp-mcp"
      ]
    }
  }
}
```

## Переменные окружения

| Переменная | Обязательна | Описание |
| --- | --- | --- |
| `GREENAPI_ID_INSTANCE` | да | `idInstance` из консоли GREEN-API |
| `GREENAPI_API_TOKEN_INSTANCE` | да | `apiTokenInstance` оттуда же |
| `GREENAPI_API_URL` | нет | Личный хост инстанса, например `https://7105.api.greenapi.com`. По умолчанию `https://api.green-api.com` |
| `GREENAPI_MEDIA_URL` | нет | По умолчанию `https://media.green-api.com`; используется только при отправке локального файла |
| `WHATSAPP_READONLY` | нет | `true` — инструменты отправки не регистрируются вовсе |

Токен не попадает в текст ошибок: он лежит в URL, а URL — в сообщениях httpx,
поэтому перед выдачей модели он заменяется на `***`.

## Инструменты

Чтение — всегда:

`get_state`, `get_settings`, `list_chats`, `get_chat_history`,
`get_last_incoming_messages`, `get_last_outgoing_messages`, `get_contact_info`,
`get_group_data`, `check_whatsapp`, `get_file_link`, `receive_notification`,
`delete_notification`.

Запись — если не выставлен `WHATSAPP_READONLY`:

`send_message`, `send_file`, `send_file_by_url`, `mark_chat_read`, `set_settings`.

`delete_notification` доступен и в режиме чтения: он убирает обработанное
событие из очереди шлюза и ничего не меняет в самих чатах, а без него
`receive_notification` бесконечно возвращает одно и то же.

## Идентификаторы чатов

Личный чат — `79001234567@c.us`, группа — `120363043968066561@g.us`, скрытый
номер — `123456789012345@lid`. Голый номер телефона (`79001234567`,
`+7 (900) 123-45-67`) достраивается до `@c.us`; для групп и `@lid` идентификатор
нужно передавать целиком, потому что от номера они неотличимы.

## Ограничения

- История видна только за то время, пока номер привязан к инстансу: GREEN-API
  не выгружает переписку, накопленную до подключения.
- У `getChatHistory` нет постраничного обхода — только `count`.
- Журналы входящих и исходящих и отметка прочитанным работают лишь при
  включённых уведомлениях инстанса: `set_settings` с `incomingWebhook: yes`,
  `outgoingMessageWebhook: yes`, `outgoingAPIMessageWebhook: yes`.
- Ответы обрезаются на 256 КБ, чтобы длинная переписка не вытеснила контекст;
  обрезанный ответ помечен полем `truncated`.

## Разработка

```bash
uv sync
uv run pytest -q
uv run pyright
```

Тесты офлайн: HTTP замокан через `httpx.MockTransport`, инструменты вызываются
настоящим MCP-клиентом.