# Mailganer API MCP

MCP-сервер для [REST API Mailganer](https://mailganer.com/documentation/api/): **локальный кэш документации** и **live-вызовы API** через единый интерфейс.

Кэширует страницы документации и Postman-коллекцию в `docs/`, даёт инструменты для поиска, синхронизации и проверки изменений. С `MAILGANER_API_KEY` — выполняет реальные HTTP-запросы к API.

## Структура

```
mailganer-api-mcp/
├── docs/
│   ├── overview.md          # авторизация, лимиты, пагинация
│   ├── api-index.json       # каталог всех страниц
│   ├── sitemap-pages.json   # страницы из sitemap.xml
│   ├── postman-index.json   # индекс Postman-запросов
│   ├── postman-collection.md  # changelog и инструкция по обновлению коллекции
│   ├── crosslinks.json      # связи docs ↔ Postman
│   ├── manual-crosslinks.json  # ручные связи и пояснения для «дырок»
│   ├── endpoints/           # JSON по каждой странице API
│   └── postman/             # Postman collection JSON
├── docs_kb.py               # фасад над пакетом kb/
├── kb/                      # модули knowledge base
│   ├── storage.py           # загрузка кэша
│   ├── matching.py          # сопоставление docs ↔ Postman paths
│   ├── crosslinks.py        # crosslinks и linked docs
│   ├── search.py            # поиск по docs/Postman
│   ├── prepare.py           # prepare_api_call
│   ├── sync_runner.py       # sync + live diff
│   └── sanitize.py          # маскирование секретов при sync
├── paths.py                 # нормализация API paths
├── http_retry.py            # retry/backoff для HTTP
├── sync_lib.py              # парсинг и sync документации с сайта
├── mailganer_client.py      # HTTP-клиент для live-вызовов API
├── mcp_resources.py         # MCP resources (docs, postman)
├── mcp_prompts.py           # MCP prompts (workflows)
├── scripts/
│   ├── sync-api-docs.py     # парсер документации (sitemap + menu)
│   ├── sync-postman.py      # синхронизация Postman-коллекции (скачивание)
│   ├── add-missing-postman-requests.py  # добавление методов в Postman (запись)
│   └── build-docusaurus-docs.py  # генерация markdown для Docusaurus
├── website/                 # Docusaurus-сайт (локальный preview docs)
└── server.py                # MCP-сервер
```

## Быстрый старт

```bash
cd mailganer-api-mcp
chmod +x setup.sh
./setup.sh .
```

Reload MCP в Cursor: **Settings → MCP → Reload**.

Или в чате: **«установи mailganer api docs»** / **«обнови документацию mailganer»**.

### Переменные окружения (`.env.api`)

```env
MAILGANER_API_KEY=your_api_key
MAILGANER_API_BASE_URL=https://mailganer.com/api
POSTMAN_API_KEY=PMAK-your_postman_api_key
```

- **MAILGANER_API_KEY** — раздел **Настройки аккаунта** в личном кабинете Mailganer (для live-вызовов API)
- **POSTMAN_API_KEY** — [Postman → Settings → API keys](https://go.postman.co/settings/me/api-keys)

### MCP-серверы

| Сервер | Назначение |
|---|---|
| `mailganer-api` | Локальный кэш документации Mailganer API |
| `postman` | Ваши workspace, коллекции и запросы в Postman |

Режим Postman MCP по умолчанию: `--code`. Чтобы сменить (`--minimal`, `--full`), отредактируйте `.cursor/postman-mcp.sh`.

## MCP-инструменты

### Документация (без API-ключа)

| Инструмент | Описание |
|---|---|
| `get_doc_status` | Статус кэша: дата sync, кол-во страниц, ошибки |
| `get_cache_health` | Готовность кэша (`ready` / `warnings`) — после pip install без clone |
| `sync_documentation` | Обновить docs с сайта (`all` / `api` / `postman`) |
| `list_api_docs` | Список страниц, фильтр по категории |
| `search_api_docs` | Полнотекстовый поиск по кэшу |
| `get_api_endpoint_doc` | Страница docs **+ связанные Postman-запросы** |
| `get_linked_postman_request` | Postman-запрос **+ связанные страницы docs** |
| `rebuild_doc_crosslinks` | Пересобрать `docs/crosslinks.json` |
| `list_crosslink_gaps` | Список «дырок» без связи + пояснения |
| `check_doc_page` | Сравнить кэш с live-сайтом, показать diff |
| `get_api_overview` | Обзор: auth, лимиты, пагинация |
| `search_postman` | Поиск по Postman-коллекции |
| `get_postman_request` | Запрос Postman по имени или path |

### Live API (нужен `MAILGANER_API_KEY`)

| Инструмент | Описание |
|---|---|
| `get_api_credentials_status` | Проверить, настроен ли API-ключ (без раскрытия) |
| `prepare_api_call` | Собрать method/path/auth/body из docs по slug |
| `call_mailganer_api` | Выполнить HTTP-запрос к Mailganer API |

## MCP Resources

| URI | Содержимое |
|---|---|
| `mailganer://docs/overview` | Обзор API (markdown) |
| `mailganer://docs/status` | Статус кэша (JSON) |
| `mailganer://docs/cache` | Готовность кэша: ready/warnings (JSON) |
| `mailganer://docs/index` | Каталог страниц (JSON) |
| `mailganer://docs/endpoint/{slug}` | Страница docs + Postman-связи |
| `mailganer://postman/request/{name}` | Postman-запрос + связанные docs |

## MCP Prompts

| Prompt | Назначение |
|---|---|
| `explore-endpoint` | Найти docs и Postman по slug/ключевому слову |
| `call-endpoint` | Подготовить и выполнить live-запрос по slug |
| `sync-docs-review` | Sync + обзор изменений |
| `find-crosslink-gaps` | Анализ дыр docs ↔ Postman |

## Обновить документацию вручную

```bash
bash scripts/sync-all-docs.sh
```

или по отдельности:

```bash
python3 scripts/sync-api-docs.py
python3 scripts/sync-postman.py
python3 scripts/build-crosslinks.py
```

## Docusaurus preview

Локальный сайт с документацией из кэша `docs/` — sidebar по категориям mailganer.com, на страницах методов есть связанные Postman-запросы.

**Требования:** Node.js ≥ 20.

```bash
python3 scripts/build-docusaurus-docs.py   # website/docs/ + website/sidebars.ts
cd website
npm install
npm start                                  # http://localhost:3000
```

После sync документации перегенерируйте страницы тем же скриптом `build-docusaurus-docs.py`.

Production-сборка: `cd website && npm run build` → статика в `website/build/`.

## Тесты и CI

```bash
pip install -e ".[dev]"
pytest
```

Workflow [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — pytest и ruff на Python 3.11–3.13 при push/PR.

### Кэш docs и pip install

Каталог `docs/` **не входит в wheel** — после `pip install` без clone кэш пустой.  
Проверка: MCP tool `get_cache_health` или `get_doc_status` → `cache.ready` и `cache.warnings`.  
Решение: clone репозитория, `./setup.sh .` или `bash scripts/sync-all-docs.sh`.

**Без sync** — скачать готовый кэш из GitHub Release:

```bash
bash scripts/download-docs-cache.sh        # latest release
bash scripts/download-docs-cache.sh v0.5.1 # конкретный tag
```

Release создаётся workflow [`.github/workflows/release-docs.yml`](.github/workflows/release-docs.yml) при push tag `v*`.

Changelog: [`CHANGELOG.md`](CHANGELOG.md). Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md).

Сгенерированные `website/docs/` и `website/sidebars.ts` в `.gitignore` — в репозитории только исходники сайта и скрипт генерации.

## CI: автоматический sync

Workflow [`.github/workflows/sync-docs.yml`](.github/workflows/sync-docs.yml):

| Триггер | Когда |
|---|---|
| `schedule` | Каждый понедельник, 06:00 UTC |
| `workflow_dispatch` | Вручную: GitHub → Actions → Sync API docs → Run workflow |

Если документация на сайте изменилась, workflow создаёт PR `automation/sync-docs` с обновлённым `docs/`.

После merge PR локально: `git pull` или `./setup.sh .` для обновления кэша.

**Настройка репозитория (один раз):** Settings → Actions → General → Workflow permissions → *Read and write* и включить **Allow GitHub Actions to create and approve pull requests**. Без этого workflow не сможет открыть PR.

## Источники

| Источник | URL | Скрипт |
|---|---|---|
| Sitemap | https://mailganer.com/sitemap.xml | `sync-api-docs.py` |
| Меню API | https://mailganer.com/documentation/api/ | `sync-api-docs.py` (fallback) |
| Postman | https://documenter.getpostman.com/view/23131434/VUxPvnhA | `sync-postman.py` |

## Postman-коллекция: добавление методов

`sync-postman.py` только **скачивает** публичную коллекцию в `docs/postman/`. Чтобы **добавить** запросы в workspace Mailganer Team:

```bash
# POSTMAN_API_KEY в .env.api
python3 scripts/add-missing-postman-requests.py
python3 scripts/sync-postman.py
python3 scripts/build-crosslinks.py
```

Подробности, список добавленных методов (2026-06-22) и как расширять скрипт: [`docs/postman-collection.md`](docs/postman-collection.md).

## Ручные связи (`manual-crosslinks.json`)

Автоматический матчинг не покрывает всё: разные пути (`/api/auth/` vs `/api/v2/auth/`), несколько способов вызова, методы без отдельной doc-страницы.

Файл `docs/manual-crosslinks.json`:
- `doc_to_postman` — явные связи slug → имена Postman-запросов
- `doc_notes` — пояснение, почему у страницы нет Postman (webhook, нет в коллекции)

После правок: `python3 scripts/build-crosslinks.py`  
Проверить «дыры»: MCP-инструмент `list_crosslink_gaps`.

## Авторизация API (справка)

- **v1** — `api_key` в теле запроса
- **v2** — заголовок `Authorization: CodeRequest {{api_key}}`
- Лимит: **500 запросов/мин**