Mailganer API MCP

MCP-сервер для REST API Mailganer: локальный кэш документации и 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-сервер

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

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

Reload MCP в Cursor: Settings → MCP → Reload.

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

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

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

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 scripts/sync-all-docs.sh

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

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.

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

pip install -e ".[dev]"
pytest

Workflow .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 scripts/download-docs-cache.sh        # latest release
bash scripts/download-docs-cache.sh v0.5.1 # конкретный tag

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

Changelog: CHANGELOG.md. Contributing: CONTRIBUTING.md.

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

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

Workflow .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:

# 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.

Ручные связи (`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 запросов/мин

Mailganer API MCP