Samotpravil MCP

Samotpravil MCP

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

Версия: 1.8.0 · npm: samotpravil-mcp · MCP Registry: io.github.dkanster/samotpravil-api-mcp · Smithery: smithery.yaml · Cursor Directory: .mcp.json

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

Бесплатного тестового ключа нет: регистрация в ЛК → верификация домена отправителя → ключ в env. Пакетную боевую отправку по умолчанию не открываем (SAMOTPRAVIL_ALLOW_SEND=0).

Экосистема (рядом с MCP)

Для SaaS сразу два API-ключа (разные стоп-листы и webhook URL) — см. пример выше.

Сценарии и конфиги для Claude / VS Code: [docs/EXAMPLES.md](./docs/EXAMPLES.md)

Cursor Directory

Каталог сообщества cursor.directory автодетектит MCP из корневого .mcp.json (дубль: mcp.json, манифест plugin.json). Первая отправка: cursor.directory/plugins/new → URL этого репозитория (вход GitHub/Google). В листинг не входят swagger-mcp и Postman maintainer.

Дальше править код и карточку — docs/PUBLISH.md § «Cursor Directory»: релиз npm по tag v*; карточку Directory не слать второй раз (дубли). Add to Cursor у уже поставивших сам не обновляется.

---

Что внутри

Итого: ~59 tools ( +4 postman при POSTMAN_API_KEY).

---

Инструменты

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

Typed API (нужен SAMOTPRAVIL_API_KEY)

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](./docs/EXAMPLES.md#python-sdk-parity) · prompt python_sdk_parity

Postman maintainer (нужен POSTMAN_API_KEY)

Подробнее: [docs/EXAMPLES.md#postman-tools](./docs/EXAMPLES.md#postman-tools)

Auto tools

api_{method}_{path} — для HTTP-методов, не покрытых typed tools (legacy v1, tickets, email check/clean и т.д.).

MCP Prompts

MCP Resources

---

Безопасность

Секреты (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/samotpravil-smtp-api@1.0.0 · 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

---

Конфигурация

Шаблон: .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](./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](./SECURITY.md)
• Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)
• Changelog: [CHANGELOG.md](./CHANGELOG.md)
• Publish: [docs/PUBLISH.md](./docs/PUBLISH.md)
• Roadmap: [docs/ROADMAP_v1.6.md](./docs/ROADMAP_v1.6.md) · Release: [docs/RELEASE_v1.7.0.md](./docs/RELEASE_v1.7.0.md)
• Org migration: [docs/ORG_MIGRATION_RUNBOOK.md](./docs/ORG_MIGRATION_RUNBOOK.md) · npm run plan-org-migration
• API v1→v2: [docs/MIGRATION_V1_TO_V2.md](./docs/MIGRATION_V1_TO_V2.md)
• API wishlist (предложения для HTTP API продукта): [docs/API_WISHLIST.md](./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