Samotpravil MCP

MCP-сервер вокруг документации API СамОтправил и HTTP API api.samotpravil.ru.

Версия: 1.7.0 · npm: samotpravil-mcp · MCP Registry: io.github.dkanster/samotpravil-mcp · Smithery: smithery.yaml

Хостинг: репозиторий временно в dkanster/samotpravil-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-mcp/

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

npx -y samotpravil-mcp@latest

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "samotpravil": {
      "command": "npx",
      "args": ["-y", "samotpravil-mcp@latest"],
      "env": {
        "SAMOTPRAVIL_API_KEY": "your_api_key_here",
        "SAMOTPRAVIL_READ_ONLY": "1",
        "SAMOTPRAVIL_ALLOW_SEND": "0"
      }
    }
  }
}

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

npx samotpravil-mcp --http --port 3000
# POST http://127.0.0.1:3000/mcp

Env: SAMOTPRAVIL_HTTP_HOST, SAMOTPRAVIL_HTTP_PORT, SAMOTPRAVIL_HTTP_AUTH_TOKEN, SAMOTPRAVIL_HTTP_JSON_LOG=1 (structured logs).

docker build -t samotpravil-mcp .
docker run --rm -p 3000:3000 -e SAMOTPRAVIL_API_KEY=... -e SAMOTPRAVIL_HTTP_AUTH_TOKEN=... samotpravil-mcp

OpenAPI + Swagger-MCP

npm run export-openapi        # → data/openapi.yaml
npm run upload-swaggerhub     # SwaggerHub (нужен .env.swaggerhub)
npm run prepare-swagger-mcp   # Vizioz/Swagger-MCP

Спека: mailganer/[email protected] · docs/SWAGGERHUB.md

Docusaurus preview

npm run docusaurus:install && npm run docusaurus:start

Live: https://dkanster.github.io/samotpravil-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

SAMOTPRAVIL_API_KEY=your_key_here
# POSTMAN_API_KEY=...          # maintainer tools
# SAMOTPRAVIL_READ_ONLY=1

Ключ API: https://samotpravil.ru/get-access

Полный список env: docs/EXAMPLES.md

Разработка

git clone https://github.com/dkanster/samotpravil-mcp.git
cd samotpravil-mcp
npm install && npm test && npm run dev
npm run setup-hooks   # optional: pre-commit (lint + test)
npm run lint          # ESLint
npm run pre-publish-check   # перед npm tag
npm run release-prepare      # pre-flight перед npm tag
npm run generate-tool-catalog
npm run scaffold-typed-tool send_package

• 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 в свой проект

/path/to/samotpravil-mcp/setup.sh .

Лицензия

MIT