Samotpravil MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Samotpravil MCP listing page.
Samotpravil MCP
MCP-сервер вокруг документации API СамОтправил и HTTP API api.samotpravil.ru.
Версия: 1.7.0 · npm: samotpravil-mcp · MCP Registry: io.github.dkanster/samotpravil-api-mcp · Smithery: smithery.yaml
Хостинг: репозиторий временно в dkanster/samotpravil-api-mcp.
Планируется: переезд в org Samotpravil →@samotpravil/mcp— docs/ORG_MIGRATION.md.
Сервер подтягивает Postman-коллекцию с documenter (live + offline snapshot) и даёт агенту tools для поиска методов, вызова API и безопасных пресетов (READ_ONLY, dry_run). Имена typed tools совпадают с Python SDK samotpravil.
Экосистема: Postman → snapshot → MCP / OpenAPI / Docusaurus — docs/ECOSYSTEM.md · live preview: https://dkanster.github.io/samotpravil-api-mcp/
Быстрый старт
Cursor — .cursor/mcp.json:
SAMOTPRAVIL_API_KEY опционален для docs-only tools. После правок: Settings → MCP → Reload.
Сценарии и конфиги для Claude / VS Code: docs/EXAMPLES.md
Что внутри
| Компонент | Кол-во | Нужен ключ |
|---|---|---|
| Docs tools | 4 | нет |
| Core typed API | 9 + api_request | SAMOTPRAVIL_API_KEY |
| Python SDK parity | 28 | SAMOTPRAVIL_API_KEY |
Auto tools (api_*) | ~16 | SAMOTPRAVIL_API_KEY |
| Postman maintainer | 4 | POSTMAN_API_KEY |
| MCP Resources | 9 | нет |
| MCP Prompts | 5 | нет |
Итого: ~59 tools ( +4 postman при POSTMAN_API_KEY).
Инструменты
Документация (без API-ключа)
| Tool | Описание |
|---|---|
get_overview | Авторизация, SMTP, лимиты, категории |
list_endpoints | Список всех методов API |
search_docs | Поиск по документации |
get_endpoint | Подробности по методу |
Typed API (нужен SAMOTPRAVIL_API_KEY)
| Tool | Описание |
|---|---|
send_email | POST /api/v1/smtp_send |
send_mail_v2 | POST /api/v2/mail/send |
get_delivery_status | GET /api/v2/issue/status (message_id или x_track_id) |
get_package_status | GET /api/v2/package/status |
search_stop_list | Поиск email в стоп-листах |
add_stop_list_email / remove_stop_list_email | Стоп-лист (mail_from или domain) |
validate_email | POST /api/v2/emails/validate/ |
list_allowed_domains | GET /api/v2/blist/domains |
api_request | Generic escape hatch |
Python SDK parity (v1.3+)
Typed tools с именами как в PyPI-пакете samotpravil: send_package, get_statistics, get_ext_status, stop_list_export_create, domain_add, get_blist, create_authkey и др.
Полный список и маппинг: docs/EXAMPLES.md#python-sdk-parity · prompt python_sdk_parity
Postman maintainer (нужен POSTMAN_API_KEY)
| Tool | Описание |
|---|---|
postman_get_collection | Коллекция из Postman API |
postman_sync_snapshot | Postman API → data/collection.snapshot.json |
postman_diff_snapshot | Diff Postman vs локальный snapshot |
postman_search_requests | Поиск запросов в коллекции |
Подробнее: docs/EXAMPLES.md#postman-tools
Auto tools
api_{method}_{path} — для HTTP-методов, не покрытых typed tools (legacy v1, tickets, email check/clean и т.д.).
MCP Prompts
| Prompt | Описание |
|---|---|
integration_overview | Обзор SMTP + HTTP + лимиты |
send_transactional | Чеклист отправки письма |
stop_list_workflow | Работа со стоп-листами |
check_delivery | Статус по X-Track-ID / выпуску |
python_sdk_parity | Python SDK → MCP tools |
MCP Resources
| URI | Содержимое |
|---|---|
samotpravil://overview | Обзор API |
samotpravil://endpoints | Индекс методов |
samotpravil://endpoint/{slug} | Один метод |
samotpravil://errors | Популярные ошибки |
samotpravil://integration | SMTP, X-Track-ID, трекинг |
samotpravil://sdk-mapping | Python SDK → MCP tools |
samotpravil://changelog | Фрагмент CHANGELOG пакета |
samotpravil://rate-limits | Лимиты API и отправки |
samotpravil://api-wishlist | Предложения по HTTP API (фрагмент) |
Безопасность
| Env | Эффект |
|---|---|
SAMOTPRAVIL_READ_ONLY=1 | Только GET/HEAD |
SAMOTPRAVIL_ALLOW_SEND=0 | Блок send/package |
SAMOTPRAVIL_ALLOW_MUTATIONS=0 | Блок stop-list, доменов, authkey |
SAMOTPRAVIL_ALLOW_GENERIC_API=0 | Отключить api_request |
SAMOTPRAVIL_DOCS_MODE | auto | live | snapshot |
dry_run: true | Preview запроса без отправки |
Секреты (api_key, key= в query) маскируются в ответах MCP.
Транспорты и интеграции
HTTP transport
Env: SAMOTPRAVIL_HTTP_HOST, SAMOTPRAVIL_HTTP_PORT, SAMOTPRAVIL_HTTP_AUTH_TOKEN, SAMOTPRAVIL_HTTP_JSON_LOG=1 (structured logs).
OpenAPI + Swagger-MCP
Спека: mailganer/samotpravil-smtp-api@1.0.0 · docs/SWAGGERHUB.md
Docusaurus preview
Live: https://dkanster.github.io/samotpravil-api-mcp/ · docs/DOCS_SITE.md
Discovery
| Площадка | Ссылка |
|---|---|
| npm | https://www.npmjs.com/package/samotpravil-mcp |
| MCP Registry | https://registry.modelcontextprotocol.io |
| Smithery | smithery.yaml в корне — docs/PUBLISH.md |
| Официальный promo | docs/official/ |
Конфигурация
Шаблон: .env.samotpravil.example
Ключ API: https://samotpravil.ru/get-access
Полный список env: docs/EXAMPLES.md
Разработка
- Security: SECURITY.md
- Contributing: CONTRIBUTING.md
- Changelog: CHANGELOG.md
- Publish: docs/PUBLISH.md
- Roadmap: docs/ROADMAP_v1.6.md · Release: docs/RELEASE_v1.7.0.md
- Org migration: docs/ORG_MIGRATION_RUNBOOK.md ·
npm run plan-org-migration - API v1→v2: docs/MIGRATION_V1_TO_V2.md
- API wishlist (предложения для HTTP API продукта): docs/API_WISHLIST.md
Источник документации
- Live: https://documentation.samotpravil.ru/
- Offline:
data/collection.snapshot.json - Обновить:
npm run sync-docsилиpostman_sync_snapshot - API: https://api.samotpravil.ru · SMTP:
api.samotpravil.ru:1126/:1127
Из git clone в свой проект
Лицензия
MIT