# owa-mail-mcp

MCP-сервер к корпоративному Exchange: почта, календарь, справочник людей.

Наружу Exchange отдаёт только `/owa/` (EWS SOAP, MAPI, IMAP/SMTP закрыты), поэтому
сервер работает через OWA JSON API (`/owa/service.svc`) — тот же протокол, что и
веб-клиент OWA, — поверх NTLM.

## Подключение

Конфиг MCP-клиента:

```json
{
  "mcpServers": {
    "owa-mail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mainpart/owa-mail-mcp.git", "owa-mail-mcp"],
      "env": {
        "EXCHANGE_USERNAME": "DOMAIN\\user",
        "EXCHANGE_PASSWORD": "..."
      }
    }
  }
}
```

Локальный запуск из клона: `uv sync && uv run owa-mail-mcp`.

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

| Переменная | Обяз. | Дефолт | Назначение |
|---|---|---|---|
| `EXCHANGE_USERNAME` | да | — | учётка NTLM, `DOMAIN\user` |
| `EXCHANGE_PASSWORD` | да | — | пароль |
| `EXCHANGE_OWA_URL` | | `https://owa.example.com` | хост OWA |
| `EXCHANGE_COOKIE_FILE` | | `~/.config/owa-mail-mcp/cookies` | кэш сессии (0600), пишется сервером |
| `EXCHANGE_VERIFY_SSL` | | `false` | `true` — строгая проверка TLS |
| `EXCHANGE_ATTACHMENT_DIR` | | `/tmp/attachments` | куда сохраняются вложения |
| `EXCHANGE_TIME_ZONE` | | `Russian Standard Time` | Windows-зона для `TimeZoneContext` |
| `EXCHANGE_LOG_LEVEL` | | `INFO` | уровень логов (в stderr) |
| `MCP_ENABLED_TOOLS` | | 20 тулов | allowlist видимых тулов (см. «Конфиг») |
| `MCP_TRANSPORT` / `MCP_HOST` / `MCP_PORT` | | `stdio` | транспорт |

## Методы

Служебное:

| Метод | Что делает |
|---|---|
| `check_auth` | Жив ли сеанс OWA — делает лёгкий запрос к ящику, возвращает `{authenticated, user, owa_url}` или `not_authenticated` |

Почта:

| Метод | Что делает |
|---|---|
| `get_folders` | Папки с id, счётчиками и непрочитанными (`limit`/`offset`) |
| `find_emails` | Список папки или полнотекстовый поиск (`query`, `granularity=threads\|messages`); листается по позиции (`offset`) или по курсору (`after`) |
| `get_email` | Письмо целиком: тело, получатели, id вложений, ссылки (`include_links`) |
| `get_thread` | Вся переписка по письму или `conversation_id` |
| `send_email` | Отправить письмо или сохранить черновик (`draft`) |
| `reply_email` | Ответить / ответить всем (`reply_all`) |
| `forward_email` | Переслать письмо с вложениями |
| `delete_email` | Удалить (в «Удалённые» или `hard_delete`) |
| `mark_email_read` ⚙ | Пометить прочитанным / непрочитанным |
| `move_email` ⚙ | Переместить письмо в папку |

Календарь:

| Метод | Что делает |
|---|---|
| `get_calendar_events` | События за период (`start`/`end`), свои или чужие (`person`); окно читается целиком, сужается датами, `limit` — только предохранитель |
| `get_event` | Событие целиком: тело, участники, статусы ответов |
| `get_calendars` | Какие календари видны и какие из них реально читаются |
| `get_user_availability` | Занятость человека с темами встреч — даже без доступа к папке |
| `find_meeting_time` | Свободные для всех слоты в рабочих часах |
| `create_event` | Создать событие или серию, разослать приглашения |
| `update_event` | Изменить событие и уведомить участников (`apply_to` для серий) |
| `cancel_event` | Отменить своё событие (`apply_to` для серий) |
| `respond_to_event` | Принять / отклонить / под вопросом (`comment`, `notify_organizer`, `apply_to`) |

Люди, вложения, автоответчик:

| Метод | Что делает |
|---|---|
| `find_people` | Справочник: имя/логин/адрес → адрес; при одном совпадении — полная карточка (должность, отдел, телефоны); `details` раскрывает несколько, `limit`/`offset` листают |
| `get_attachment` | Скачать вложение на диск |
| `get_oof` ⚙ | Прочитать настройки автоответчика |
| `set_oof` ⚙ | Включить / выключить / по расписанию |

⚙ — выключены по умолчанию, включаются через `MCP_ENABLED_TOOLS`.

## Конфиг

`MCP_ENABLED_TOOLS` полностью заменяет дефолт — перечисляйте ровно то, что нужно;
пустая строка выключает все тулы.

Включить всё (24 тула):

```
check_auth,get_folders,find_emails,get_email,get_thread,send_email,reply_email,forward_email,delete_email,mark_email_read,move_email,get_calendar_events,get_event,get_calendars,get_user_availability,find_meeting_time,create_event,update_event,cancel_event,respond_to_event,get_attachment,find_people,get_oof,set_oof
```

Только чтение:

```
check_auth,get_folders,find_emails,get_email,get_thread,get_calendar_events,get_event,get_calendars,get_user_availability,find_people
```