Samotpravil

CI npm License: MIT

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/

---

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

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

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-api-mcp.git
cd samotpravil-api-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-api-mcp/setup.sh .

---

Лицензия

MIT