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/

---

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

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

---

Что внутри

Итого: ~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 · prompt python_sdk_parity

Postman maintainer (нужен POSTMAN_API_KEY)

Подробнее: 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

---

Разработка

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