{
  "markdown": "# Samotpravil MCP\n\n[![CI](https://github.com/dkanster/samotpravil-api-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dkanster/samotpravil-api-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/samotpravil-mcp.svg)](https://www.npmjs.com/package/samotpravil-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nMCP-сервер вокруг [документации API СамОтправил](https://documentation.samotpravil.ru/) и HTTP API `api.samotpravil.ru`.\n\n**Версия:** 1.7.0 · **npm:** [`samotpravil-mcp`](https://www.npmjs.com/package/samotpravil-mcp) · **MCP Registry:** `io.github.dkanster/samotpravil-api-mcp` · **Smithery:** [`smithery.yaml`](./smithery.yaml)\n\n> **Хостинг:** репозиторий временно в [dkanster/samotpravil-api-mcp](https://github.com/dkanster/samotpravil-api-mcp).  \n> **Планируется:** переезд в org **Samotpravil** → `@samotpravil/mcp` — [docs/ORG_MIGRATION.md](./docs/ORG_MIGRATION.md).\n\nСервер подтягивает Postman-коллекцию с documenter (live + offline snapshot) и даёт агенту tools для поиска методов, вызова API и безопасных пресетов (`READ_ONLY`, `dry_run`). Имена typed tools совпадают с [Python SDK `samotpravil`](https://pypi.org/project/samotpravil/).\n\n**Экосистема:** Postman → snapshot → MCP / OpenAPI / Docusaurus — [docs/ECOSYSTEM.md](./docs/ECOSYSTEM.md) · live preview: **https://dkanster.github.io/samotpravil-api-mcp/**\n\n---\n\n## Быстрый старт\n\n```bash\nnpx -y samotpravil-mcp@latest\n```\n\n**Cursor** — `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"samotpravil\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"samotpravil-mcp@latest\"],\n      \"env\": {\n        \"SAMOTPRAVIL_API_KEY\": \"your_api_key_here\",\n        \"SAMOTPRAVIL_READ_ONLY\": \"1\",\n        \"SAMOTPRAVIL_ALLOW_SEND\": \"0\"\n      }\n    }\n  }\n}\n```\n\n`SAMOTPRAVIL_API_KEY` опционален для docs-only tools. После правок: **Settings → MCP → Reload**.\n\nСценарии и конфиги для Claude / VS Code: **[docs/EXAMPLES.md](./docs/EXAMPLES.md)**\n\n---\n\n## Что внутри\n\n| Компонент | Кол-во | Нужен ключ |\n|-----------|--------|------------|\n| Docs tools | 4 | нет |\n| Core typed API | 9 + `api_request` | `SAMOTPRAVIL_API_KEY` |\n| Python SDK parity | 28 | `SAMOTPRAVIL_API_KEY` |\n| Auto tools (`api_*`) | ~16 | `SAMOTPRAVIL_API_KEY` |\n| Postman maintainer | 4 | `POSTMAN_API_KEY` |\n| MCP Resources | 9 | нет |\n| MCP Prompts | 5 | нет |\n\n**Итого:** ~59 tools ( +4 postman при `POSTMAN_API_KEY`).\n\n---\n\n## Инструменты\n\n### Документация (без API-ключа)\n\n| Tool | Описание |\n|------|----------|\n| `get_overview` | Авторизация, SMTP, лимиты, категории |\n| `list_endpoints` | Список всех методов API |\n| `search_docs` | Поиск по документации |\n| `get_endpoint` | Подробности по методу |\n\n### Typed API (нужен `SAMOTPRAVIL_API_KEY`)\n\n| Tool | Описание |\n|------|----------|\n| `send_email` | POST `/api/v1/smtp_send` |\n| `send_mail_v2` | POST `/api/v2/mail/send` |\n| `get_delivery_status` | GET `/api/v2/issue/status` (`message_id` или `x_track_id`) |\n| `get_package_status` | GET `/api/v2/package/status` |\n| `search_stop_list` | Поиск email в стоп-листах |\n| `add_stop_list_email` / `remove_stop_list_email` | Стоп-лист (`mail_from` или `domain`) |\n| `validate_email` | POST `/api/v2/emails/validate/` |\n| `list_allowed_domains` | GET `/api/v2/blist/domains` |\n| `api_request` | Generic escape hatch |\n\n### Python SDK parity (v1.3+)\n\nTyped tools с именами как в PyPI-пакете `samotpravil`: `send_package`, `get_statistics`, `get_ext_status`, `stop_list_export_create`, `domain_add`, `get_blist`, `create_authkey` и др.\n\nПолный список и маппинг: **[docs/EXAMPLES.md#python-sdk-parity](./docs/EXAMPLES.md#python-sdk-parity)** · prompt `python_sdk_parity`\n\n### Postman maintainer (нужен `POSTMAN_API_KEY`)\n\n| Tool | Описание |\n|------|----------|\n| `postman_get_collection` | Коллекция из Postman API |\n| `postman_sync_snapshot` | Postman API → `data/collection.snapshot.json` |\n| `postman_diff_snapshot` | Diff Postman vs локальный snapshot |\n| `postman_search_requests` | Поиск запросов в коллекции |\n\nПодробнее: **[docs/EXAMPLES.md#postman-tools](./docs/EXAMPLES.md#postman-tools)**\n\n### Auto tools\n\n`api_{method}_{path}` — для HTTP-методов, не покрытых typed tools (legacy v1, tickets, email check/clean и т.д.).\n\n### MCP Prompts\n\n| Prompt | Описание |\n|--------|----------|\n| `integration_overview` | Обзор SMTP + HTTP + лимиты |\n| `send_transactional` | Чеклист отправки письма |\n| `stop_list_workflow` | Работа со стоп-листами |\n| `check_delivery` | Статус по X-Track-ID / выпуску |\n| `python_sdk_parity` | Python SDK → MCP tools |\n\n### MCP Resources\n\n| URI | Содержимое |\n|-----|------------|\n| `samotpravil://overview` | Обзор API |\n| `samotpravil://endpoints` | Индекс методов |\n| `samotpravil://endpoint/{slug}` | Один метод |\n| `samotpravil://errors` | Популярные ошибки |\n| `samotpravil://integration` | SMTP, X-Track-ID, трекинг |\n| `samotpravil://sdk-mapping` | Python SDK → MCP tools |\n| `samotpravil://changelog` | Фрагмент CHANGELOG пакета |\n| `samotpravil://rate-limits` | Лимиты API и отправки |\n| `samotpravil://api-wishlist` | Предложения по HTTP API (фрагмент) |\n\n---\n\n## Безопасность\n\n| Env | Эффект |\n|-----|--------|\n| `SAMOTPRAVIL_READ_ONLY=1` | Только GET/HEAD |\n| `SAMOTPRAVIL_ALLOW_SEND=0` | Блок send/package |\n| `SAMOTPRAVIL_ALLOW_MUTATIONS=0` | Блок stop-list, доменов, authkey |\n| `SAMOTPRAVIL_ALLOW_GENERIC_API=0` | Отключить `api_request` |\n| `SAMOTPRAVIL_DOCS_MODE` | `auto` \\| `live` \\| `snapshot` |\n| `dry_run: true` | Preview запроса без отправки |\n\nСекреты (`api_key`, `key=` в query) маскируются в ответах MCP.\n\n---\n\n## Транспорты и интеграции\n\n### HTTP transport\n\n```bash\nnpx samotpravil-mcp --http --port 3000\n# POST http://127.0.0.1:3000/mcp\n```\n\nEnv: `SAMOTPRAVIL_HTTP_HOST`, `SAMOTPRAVIL_HTTP_PORT`, `SAMOTPRAVIL_HTTP_AUTH_TOKEN`, `SAMOTPRAVIL_HTTP_JSON_LOG=1` (structured logs).\n\n```bash\ndocker build -t samotpravil-mcp .\ndocker run --rm -p 3000:3000 -e SAMOTPRAVIL_API_KEY=... -e SAMOTPRAVIL_HTTP_AUTH_TOKEN=... samotpravil-mcp\n```\n\n### OpenAPI + Swagger-MCP\n\n```bash\nnpm run export-openapi        # → data/openapi.yaml\nnpm run upload-swaggerhub     # SwaggerHub (нужен .env.swaggerhub)\nnpm run prepare-swagger-mcp   # Vizioz/Swagger-MCP\n```\n\nСпека: [mailganer/samotpravil-smtp-api@1.0.0](https://app.swaggerhub.com/apis/mailganer/samotpravil-smtp-api/1.0.0) · [docs/SWAGGERHUB.md](./docs/SWAGGERHUB.md)\n\n### Docusaurus preview\n\n```bash\nnpm run docusaurus:install && npm run docusaurus:start\n```\n\nLive: **https://dkanster.github.io/samotpravil-api-mcp/** · [docs/DOCS_SITE.md](./docs/DOCS_SITE.md)\n\n### Discovery\n\n| Площадка | Ссылка |\n|----------|--------|\n| npm | https://www.npmjs.com/package/samotpravil-mcp |\n| MCP Registry | https://registry.modelcontextprotocol.io |\n| Smithery | `smithery.yaml` в корне — [docs/PUBLISH.md](./docs/PUBLISH.md) |\n| Официальный promo | [docs/official/](./docs/official/) |\n\n---\n\n## Конфигурация\n\nШаблон: [`.env.samotpravil.example`](./.env.samotpravil.example)\n\n```env\nSAMOTPRAVIL_API_KEY=your_key_here\n# POSTMAN_API_KEY=...          # maintainer tools\n# SAMOTPRAVIL_READ_ONLY=1\n```\n\nКлюч API: https://samotpravil.ru/get-access\n\nПолный список env: **[docs/EXAMPLES.md](./docs/EXAMPLES.md#переменные-окружения)**\n\n---\n\n## Разработка\n\n```bash\ngit clone https://github.com/dkanster/samotpravil-api-mcp.git\ncd samotpravil-api-mcp\nnpm install && npm test && npm run dev\nnpm run setup-hooks   # optional: pre-commit (lint + test)\nnpm run lint          # ESLint\nnpm run pre-publish-check   # перед npm tag\nnpm run release-prepare      # pre-flight перед npm tag\nnpm run generate-tool-catalog\nnpm run scaffold-typed-tool send_package\n```\n\n- Security: **[SECURITY.md](./SECURITY.md)**\n- Contributing: **[CONTRIBUTING.md](./CONTRIBUTING.md)**\n- Changelog: **[CHANGELOG.md](./CHANGELOG.md)**\n- Publish: **[docs/PUBLISH.md](./docs/PUBLISH.md)**\n- Roadmap: **[docs/ROADMAP_v1.6.md](./docs/ROADMAP_v1.6.md)** · Release: **[docs/RELEASE_v1.7.0.md](./docs/RELEASE_v1.7.0.md)**\n- Org migration: **[docs/ORG_MIGRATION_RUNBOOK.md](./docs/ORG_MIGRATION_RUNBOOK.md)** · `npm run plan-org-migration`\n- API v1→v2: **[docs/MIGRATION_V1_TO_V2.md](./docs/MIGRATION_V1_TO_V2.md)**\n- **API wishlist** (предложения для HTTP API продукта): **[docs/API_WISHLIST.md](./docs/API_WISHLIST.md)**\n\n### Источник документации\n\n- Live: https://documentation.samotpravil.ru/\n- Offline: `data/collection.snapshot.json`\n- Обновить: `npm run sync-docs` или `postman_sync_snapshot`\n- API: https://api.samotpravil.ru · SMTP: `api.samotpravil.ru:1126` / `:1127`\n\n### Из git clone в свой проект\n\n```bash\n/path/to/samotpravil-api-mcp/setup.sh .\n```\n\n---\n\n## Лицензия\n\nMIT\n",
  "bytes": 8620,
  "sha": "cf2b38460c7370e763594bdc8ed7af9718292206623cc0c975c112882f829557",
  "repo_slug": "dkanster/samotpravil-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dkanster_samotpravil_mcp_e2d5f656/readme"
}