beget-mcp 0.2.0__tar.gz

beget_mcp-0.2.0/.env.example

@@ -0,0 +1,2 @@
+BEGET_API_LOGIN=your_login
+BEGET_API_PASSWORD=your_password

beget_mcp-0.2.0/.github/workflows/deploy.yml

@@ -0,0 +1,35 @@
+name: Deploy beget-mcp
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # Нативный ssh вместо appleboy/ssh-action: тому пришлось бы отдать
+      # приватный ключ прод-хоста, то есть доверить root чужому коду,
+      # обновляющемуся вне нашего контроля.
+      - name: Prepare ssh key
+        run: |
+          install -m 700 -d ~/.ssh
+          printf '%s\n' "${{ secrets.VPS_SSH_KEY }}" > ~/.ssh/id_deploy
+          chmod 600 ~/.ssh/id_deploy
+          ssh-keyscan -H "${{ secrets.VPS_HOST }}" >> ~/.ssh/known_hosts 2>/dev/null
+
+      # Ключ на хосте заперт в forced command (/usr/local/sbin/ci-deploy-beget-mcp,
+      # ставится playbook'ом install-ci-deploy.yml в репо infra-docker). Отсюда уходит
+      # только глагол; шаги деплоя (git pull, compose up --build, restart mcpproxy-go)
+      # живут в обёртке на хосте. Прислать shell-строку бессмысленно: sshd её не
+      # исполнит, обёртка запишет REJECT в journalctl -t ci-deploy.
+      - name: Deploy to VPS
+        run: |
+          ssh -i ~/.ssh/id_deploy -o IdentitiesOnly=yes \
+            "${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}" deploy
+
+      - name: Verify container is running
+        run: |
+          ssh -i ~/.ssh/id_deploy -o IdentitiesOnly=yes \
+            "${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}" verify

beget_mcp-0.2.0/.github/workflows/publish-mcp.yml

@@ -0,0 +1,98 @@
+name: Publish to PyPI, GHCR and MCP Registry
+
+# Релиз идёт по тегу vX.Y.Z. Ни одного секрета: PyPI берётся trusted publishing
+# (OIDC), GHCR — встроенным GITHUB_TOKEN, реестр MCP — тем же OIDC. Токен,
+# который не заведён, невозможно утечь и не надо ротировать.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.tag.outputs.version }}
+    steps:
+      - uses: actions/checkout@v5
+
+      # Версия живёт в трёх местах, и расхождение всплыло бы уже после
+      # публикации пакета: PyPI не даёт перезалить версию.
+      - name: Tag matches pyproject and server.json
+        id: tag
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          [ "$GITHUB_REF" = "${GITHUB_REF#refs/tags/}" ] && VERSION="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          PY=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          SRV=$(jq -r .version server.json)
+          OCI=$(jq -r '.packages[] | select(.registryType=="oci") | .identifier' server.json)
+          PYPKG=$(jq -r '.packages[] | select(.registryType=="pypi") | .version' server.json)
+          echo "tag=$VERSION pyproject=$PY server.json=$SRV pypi=$PYPKG oci=$OCI"
+          test "$PY" = "$VERSION" || { echo "::error::pyproject version $PY != tag $VERSION"; exit 1; }
+          test "$SRV" = "$VERSION" || { echo "::error::server.json version $SRV != tag $VERSION"; exit 1; }
+          test "$PYPKG" = "$VERSION" || { echo "::error::pypi package version $PYPKG != tag $VERSION"; exit 1; }
+          test "$OCI" = "ghcr.io/badigit/beget-mcp:$VERSION" || { echo "::error::oci identifier $OCI != tag $VERSION"; exit 1; }
+
+  test:
+    needs: version-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra test
+      - run: uv run pytest -q
+
+  pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing, вместо PYPI_API_TOKEN
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  ghcr:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/badigit/beget-mcp:${{ needs.version-check.outputs.version }}
+            ghcr.io/badigit/beget-mcp:latest
+          # Реестр MCP проверяет владение образом по этой аннотации; она же
+          # стоит LABEL'ом в Dockerfile — дублируется намеренно, так как
+          # аннотация манифеста и label конфига это разные места.
+          annotations: |
+            io.modelcontextprotocol.server.name=io.github.badigit/beget-mcp
+
+  registry:
+    needs: [version-check, pypi, ghcr]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC-аутентификация в реестре MCP
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Authenticate
+        run: ./mcp-publisher login github-oidc
+      - name: Publish
+        run: ./mcp-publisher publish

beget_mcp-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.env
+dist/
+*.egg-info/
+.venv/
+.ruff_cache/
+
+# Локальная обвязка агентов и beads: репо публичное,
+# а .beads/metadata.json содержит внутренний Dolt-хост
+.beads/
+.claude/
+.codex/
+.agents/
+CLAUDE.md
+AGENTS.md

beget_mcp-0.2.0/Dockerfile

@@ -0,0 +1,24 @@
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+
+WORKDIR /app
+# uv.lock коммитится и ставится через --frozen: без него `uv sync` резолвил
+# зависимости заново на каждой сборке и образ зависел от даты сборки, а не от
+# содержимого репо. Так mcp 2.0.0 (28.07.2026) и сломал соседний сервер.
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev
+
+COPY src/ src/
+RUN uv sync --frozen --no-dev
+
+# Реестр MCP проверяет владение образом по этому имени: оно обязано совпадать
+# с полем name в server.json, иначе публикация отклоняется.
+LABEL io.modelcontextprotocol.server.name="io.github.badigit/beget-mcp"
+
+ENV MCP_TRANSPORT=sse
+ENV MCP_HOST=0.0.0.0
+ENV MCP_PORT=8322
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8322
+
+ENTRYPOINT ["/app/.venv/bin/beget-mcp"]

beget_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beget_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: beget-mcp
+Version: 0.2.0
+Summary: Beget hosting MCP server — manage sites, domains, MySQL, FTP, DNS, cron, backups via AI agents
+Project-URL: Homepage, https://badigit.github.io/beget-mcp/
+Project-URL: Repository, https://github.com/badigit/beget-mcp
+Project-URL: Issues, https://github.com/badigit/beget-mcp/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: beget,claude,dns,hosting,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: dnspython>=2.6
+Requires-Dist: mcp[cli]<2.0.0,>=1.27
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Provides-Extra: test
+Requires-Dist: pytest-mock>=3.12; extra == 'test'
+Requires-Dist: pytest-timeout>=2.3; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: responses>=0.25; extra == 'test'
+Description-Content-Type: text/markdown
+
+# beget-mcp
+
+MCP-сервер для управления сервисами хостера [Beget](https://beget.com/p1211871) из AI-агентов.
+
+Построен на [FastMCP](https://github.com/modelcontextprotocol/python-sdk) и покрывает весь [Beget REST API](https://beget.com/p1211871/kb/api/) — 73 инструмента в 10 разделах.
+
+> [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — открытый стандарт для подключения AI-моделей к внешним сервисам.
+
+<!-- mcp-name: io.github.badigit/beget-mcp -->
+
+## Быстрый старт
+
+Из PyPI, без установки в систему:
+
+```bash
+claude mcp add beget -s user \
+  -e BEGET_API_LOGIN=your_login \
+  -e BEGET_API_PASSWORD=your_password \
+  -- uvx beget-mcp
+```
+
+Контейнером (образ по умолчанию поднимает SSE — локальному клиенту нужен stdio):
+
+```bash
+docker run -i --rm \
+  -e MCP_TRANSPORT=stdio \
+  -e BEGET_API_LOGIN=your_login \
+  -e BEGET_API_PASSWORD=your_password \
+  ghcr.io/badigit/beget-mcp:latest
+```
+
+Из исходников:
+
+```bash
+pip install -e .
+
+claude mcp add beget -s user \
+  -e BEGET_API_LOGIN=your_login \
+  -e BEGET_API_PASSWORD=your_password \
+  -- python -m mcp_beget
+```
+
+Сервер публикуется в [MCP Registry](https://registry.modelcontextprotocol.io) под именем
+`io.github.badigit/beget-mcp`. Страница проекта — <https://badigit.github.io/beget-mcp/>.
+
+## Что умеет
+
+| Раздел | Инструменты | Примеры операций |
+|--------|------------|-----------------|
+| Сайты | 8 | создание, удаление, привязка доменов, заморозка файлов |
+| Домены | 13 | управление, поддомены, PHP-версии, директивы, проверка доступности |
+| DNS | 8 | A, CNAME, MX, TXT — безопасный merge; частичное обновление через `dns_patch_record`; `dns_verify` сверяет факт у авторитативного NS |
+| MySQL | 6 | базы, доступы с хостов, пароли |
+| FTP | 4 | аккаунты, домашние каталоги |
+| Cron | 7 | задачи, расписание, активация, email-отчёты |
+| Бэкапы | 9 | просмотр содержимого, откат, выгрузка файлов и БД |
+| Почта | 12 | ящики, пароли, спам-фильтр, пересылка, catch-all, one-shot-настройка Яндекс 360 / Mail.ru |
+| Статистика | 4 | нагрузка по сайтам и БД — сводная и детальная |
+| Аккаунт | 2 | тариф, баланс, SSH-доступ |
+
+## Документация
+
+| Файл | О чём |
+|------|-------|
+| [docs/api-coverage.md](docs/api-coverage.md) | покрытие методов Beget API |
+| [docs/beget-api-gotchas.md](docs/beget-api-gotchas.md) | грабли API: ошибка в success-конверте и прочее |
+| [docs/dns-facts-vs-intent.md](docs/dns-facts-vs-intent.md) | DNS: несозданный поддомен, catch-all зоны, задержка распространения |
+| [docs/new-app-deploy-chain.md](docs/new-app-deploy-chain.md) | цепочка вызовов для нового приложения на shared-хостинге |
+
+## Переменные окружения
+
+| Переменная | Назначение |
+|-----------|-----------|
+| `BEGET_API_LOGIN` | Логин Beget |
+| `BEGET_API_PASSWORD` | Пароль Beget |
+
+## Архитектура
+
+```
+src/mcp_beget/
+├── app.py       — экземпляр FastMCP
+├── config.py    — конфигурация (dataclass + валидация)
+├── client.py    — HTTP-клиент с переиспользованием сессии
+├── errors.py    — типизированные исключения (Auth / API)
+├── server.py    — точка входа, инициализация, логирование
+└── tools/       — инструменты, сгруппированные по разделам API
+```
+
+## Требования
+
+- Python >= 3.11
+- mcp[cli]
+- requests
+- python-dotenv
+
+## Contributing
+
+Issues и pull requests приветствуются. Если нашли баг или хотите предложить улучшение — создайте issue.
+
+## Лицензия
+
+[MIT](LICENSE)
+
+---
+
+Нет аккаунта на Beget? [Зарегистрируйтесь по ссылке](https://beget.com/p1211871) — вы получите хостинг, а автор проекта небольшой бонус.

beget_mcp-0.2.0/README.md

@@ -0,0 +1,106 @@
+# beget-mcp
+
+MCP-сервер для управления сервисами хостера [Beget](https://beget.com/p1211871) из AI-агентов.
+
+Построен на [FastMCP](https://github.com/modelcontextprotocol/python-sdk) и покрывает весь [Beget REST API](https://beget.com/p1211871/kb/api/) — 73 инструмента в 10 разделах.
+
+> [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — открытый стандарт для подключения AI-моделей к внешним сервисам.
+
+<!-- mcp-name: io.github.badigit/beget-mcp -->
+
+## Быстрый старт
+
+Из PyPI, без установки в систему:
+
+```bash
+claude mcp add beget -s user \
+  -e BEGET_API_LOGIN=your_login \
+  -e BEGET_API_PASSWORD=your_password \
+  -- uvx beget-mcp
+```
+
+Контейнером (образ по умолчанию поднимает SSE — локальному клиенту нужен stdio):
+
+```bash
+docker run -i --rm \
+  -e MCP_TRANSPORT=stdio \
+  -e BEGET_API_LOGIN=your_login \
+  -e BEGET_API_PASSWORD=your_password \
+  ghcr.io/badigit/beget-mcp:latest
+```
+
+Из исходников:
+
+```bash
+pip install -e .
+
+claude mcp add beget -s user \
+  -e BEGET_API_LOGIN=your_login \
+  -e BEGET_API_PASSWORD=your_password \
+  -- python -m mcp_beget
+```
+
+Сервер публикуется в [MCP Registry](https://registry.modelcontextprotocol.io) под именем
+`io.github.badigit/beget-mcp`. Страница проекта — <https://badigit.github.io/beget-mcp/>.
+
+## Что умеет
+
+| Раздел | Инструменты | Примеры операций |
+|--------|------------|-----------------|
+| Сайты | 8 | создание, удаление, привязка доменов, заморозка файлов |
+| Домены | 13 | управление, поддомены, PHP-версии, директивы, проверка доступности |
+| DNS | 8 | A, CNAME, MX, TXT — безопасный merge; частичное обновление через `dns_patch_record`; `dns_verify` сверяет факт у авторитативного NS |
+| MySQL | 6 | базы, доступы с хостов, пароли |
+| FTP | 4 | аккаунты, домашние каталоги |
+| Cron | 7 | задачи, расписание, активация, email-отчёты |
+| Бэкапы | 9 | просмотр содержимого, откат, выгрузка файлов и БД |
+| Почта | 12 | ящики, пароли, спам-фильтр, пересылка, catch-all, one-shot-настройка Яндекс 360 / Mail.ru |
+| Статистика | 4 | нагрузка по сайтам и БД — сводная и детальная |
+| Аккаунт | 2 | тариф, баланс, SSH-доступ |
+
+## Документация
+
+| Файл | О чём |
+|------|-------|
+| [docs/api-coverage.md](docs/api-coverage.md) | покрытие методов Beget API |
+| [docs/beget-api-gotchas.md](docs/beget-api-gotchas.md) | грабли API: ошибка в success-конверте и прочее |
+| [docs/dns-facts-vs-intent.md](docs/dns-facts-vs-intent.md) | DNS: несозданный поддомен, catch-all зоны, задержка распространения |
+| [docs/new-app-deploy-chain.md](docs/new-app-deploy-chain.md) | цепочка вызовов для нового приложения на shared-хостинге |
+
+## Переменные окружения
+
+| Переменная | Назначение |
+|-----------|-----------|
+| `BEGET_API_LOGIN` | Логин Beget |
+| `BEGET_API_PASSWORD` | Пароль Beget |
+
+## Архитектура
+
+```
+src/mcp_beget/
+├── app.py       — экземпляр FastMCP
+├── config.py    — конфигурация (dataclass + валидация)
+├── client.py    — HTTP-клиент с переиспользованием сессии
+├── errors.py    — типизированные исключения (Auth / API)
+├── server.py    — точка входа, инициализация, логирование
+└── tools/       — инструменты, сгруппированные по разделам API
+```
+
+## Требования
+
+- Python >= 3.11
+- mcp[cli]
+- requests
+- python-dotenv
+
+## Contributing
+
+Issues и pull requests приветствуются. Если нашли баг или хотите предложить улучшение — создайте issue.
+
+## Лицензия
+
+[MIT](LICENSE)
+
+---
+
+Нет аккаунта на Beget? [Зарегистрируйтесь по ссылке](https://beget.com/p1211871) — вы получите хостинг, а автор проекта небольшой бонус.

beget_mcp-0.2.0/docs/_config.yml

@@ -0,0 +1,10 @@
+title: beget-mcp
+description: MCP-сервер для хостинга Beget — 73 инструмента, всё покрытие Beget REST API
+theme: jekyll-theme-cayman
+lang: ru
+show_downloads: false
+
+# Внутренние заметки не должны становиться отдельными страницами сайта: они
+# нужны как разделы, на которые ссылается index, а не как корневая навигация.
+exclude:
+  - _config.yml

beget_mcp-0.2.0/docs/api-coverage.md

@@ -0,0 +1,69 @@
+# Beget API — план полного покрытия
+
+Источник: https://beget.com/ru/kb/api/
+
+## Сводка
+
+| Раздел | В API | Реализовано | Не хватает |
+|--------|-------|-------------|------------|
+| **user** | 2 | 2 | 0 |
+| **backup** | 9 | 9 | 0 |
+| **cron** | 7 | 7 | 0 |
+| **dns** | 2 | 2 | 0 |
+| **ftp** | 4 | 4 | 0 |
+| **mysql** | 6 | 6 | 0 |
+| **site** | 8 | 8 | 0 |
+| **domain** | 13 | 13 | 0 |
+| **mail** | 10 | 10 | 0 |
+| **stat** | 4 | 4 | 0 |
+| **ИТОГО** | **65** | **65** | **0** |
+
+## Недостающие методы
+
+### user (1)
+- [x] `user/toggleSsh` — вкл/выкл SSH (params: status 0|1, ftplogin?)
+
+### backup (5)
+- [x] `backup/getFileList` — файлы внутри бэкапа (params: backup_id?, path?)
+- [x] `backup/getMysqlList` — БД внутри бэкапа (params: backup_id?)
+- [x] `backup/downloadFile` — скачать файлы из бэкапа в корень (params: backup_id?, paths[])
+- [x] `backup/downloadMysql` — скачать дамп БД в корень (params: backup_id?, bases[])
+- [x] `backup/getLog` — статусы заданий восстановления
+
+### cron (4)
+- [x] `cron/edit` — редактировать задачу (params: id, minutes?, hours?, days?, months?, weekdays?, command?)
+- [x] `cron/changeHiddenState` — вкл/выкл задачу (params: row_number, is_hidden 0|1)
+- [x] `cron/getEmail` — получить email уведомлений
+- [x] `cron/setEmail` — установить email (params: email)
+
+### mysql (2)
+- [x] `mysql/addAccess` — добавить доступ к БД (params: suffix, access, password)
+- [x] `mysql/dropAccess` — удалить доступ к БД (params: suffix, access)
+
+### site (3)
+- [x] `site/freeze` — заморозить сайт (params: id, excludedPaths?)
+- [x] `site/unfreeze` — разморозить (params: id)
+- [x] `site/isSiteFrozen` — проверить заморозку (params: site_id)
+
+### domain (6)
+- [x] `domain/addSubdomainVirtual` — добавить поддомен (params: subdomain, domain_id)
+- [x] `domain/deleteSubdomain` — удалить поддомен (params: id)
+- [x] `domain/checkDomainToRegister` — проверить доступность (params: hostname, zone_id, period)
+- [x] `domain/getDirectives` — PHP-директивы домена (params: full_fqdn)
+- [x] `domain/addDirectives` — добавить директивы (params: full_fqdn, directives_list[])
+- [x] `domain/removeDirectives` — удалить директивы (params: full_fqdn, directives_list[])
+
+### mail (8)
+- [x] `mail/changeMailboxPassword` — сменить пароль (params: domain, mailbox, mailbox_password)
+- [x] `mail/dropMailbox` — удалить ящик (params: domain, mailbox)
+- [x] `mail/changeMailboxSettings` — настройки ящика (params: domain, mailbox, spam_filter_status?, spam_filter?, forward_mail_status?)
+- [x] `mail/forwardListAddMailbox` — добавить пересылку (params: domain, mailbox, forward_mailbox)
+- [x] `mail/forwardListDeleteMailbox` — удалить пересылку (params: domain, mailbox, forward_mailbox)
+- [x] `mail/forwardListShow` — список пересылки (params: domain, mailbox)
+- [x] `mail/setDomainMail` — установить почту домена (params: domain, domain_mailbox)
+- [x] `mail/clearDomainMail` — сбросить почту домена (params: domain)
+
+### stat (3)
+- [x] `stat/getDbListLoad` — нагрузка по всем БД
+- [x] `stat/getSiteLoad` — детальная нагрузка сайта (params: site_id)
+- [x] `stat/getDbLoad` — детальная нагрузка БД (params: db_name)

beget_mcp-0.2.0/docs/beget-api-gotchas.md

@@ -0,0 +1,84 @@
+# Грабли Beget API
+
+Поведение, которое нельзя вывести из документации и которое уже стоило потерянных
+DNS-записей. Всё ниже проверено живыми вызовами на боевом аккаунте.
+
+## Ошибка метода приезжает в success-конверте
+
+`api.beget.com` отвечает HTTP 200 и `{"status": "success", "answer": {...}}`, а
+собственную ошибку метода кладёт **внутрь** `answer`:
+
+```json
+{"status": "success",
+ "answer": {"status": "error",
+            "errors": [{"error_code": "METHOD_FAILED", "error_text": "Failed to get DNS records"}]}}
+```
+
+Проверять только конверт недостаточно. Пока `BegetClient.call()` возвращал такой
+`answer` как значение, ломались сразу две вещи:
+
+- любой `except BegetAPIError` становился недостижим — в частности фолбэк
+  `dns_get` на родительскую зону никогда не срабатывал;
+- `_get_result()` отдавал `{}`, read-merge-write считал зону пустой и
+  `dns/changeRecords` стирал все записи, которых не было в запросе.
+
+Отсюда два инварианта, закрытых тестами:
+
+- `client.call()` райзит `BegetAPIError`, если `answer.status == "error"`
+  (`tests/test_client.py`);
+- `_get_result()` райзит `NO_ZONE_DATA`, если зона не прочиталась, и запись не
+  выполняется (`tests/test_dns.py`).
+
+Второй инвариант нужен отдельно от первого: фейковый клиент в тестах райзил
+корректно, поэтому тесты фолбэка проходили, пока живой клиент молчал. Дыра была
+ровно на границе клиента.
+
+## www-алиасы поддоменов не существуют для API
+
+Beget автоматически заводит `www.sub.site.ru` к поддомену `sub.site.ru`, и в
+панели такой алиас виден. Для API его нет:
+
+- `domain/getSubdomainList` его не возвращает (проверено: 20 реальных
+  поддоменов, ни одного `www.*`);
+- `dns/getData` по нему отвечает `METHOD_FAILED`.
+
+`dns_get` в этом случае уходит на родительскую зону и помечает ответ полями
+`note`, `queried_fqdn`, `parent_zone`. Тот же фолбэк закрывает DKIM-имена вида
+`mail._domainkey.site.ru`, которые тоже иногда живут на уровне родителя.
+
+Фолбэк срабатывает **только** на `METHOD_FAILED`. `INVALID_DATA`, лимиты и
+транзиентные сбои отдаются как есть: иначе они подменялись бы записями родителя
+и пометкой «поддомена не существует», и настоящая причина терялась бы.
+
+Setter-тулам зоны нет — они райзят `SUBDOMAIN_NOT_CREATED`, если родительская
+зона при этом читается (лечится `domain_add_subdomain`), и `NO_ZONE_DATA` в
+остальных случаях. Вслепую не пишут ни в том, ни в другом. Осознанно записать
+зону целиком, не читая её, можно через `dns_set_records` с `replace_all=True` —
+этот путь идёт мимо read-merge-write, и для несозданного поддомена он НЕ помогает:
+сущность так не появляется.
+
+Зачем это разделение, чем опасны автозаписи нового поддомена, почему отсутствие
+записи в зоне не означает «имя не резолвится» и почему `success` от `dns_set_*`
+не равен «отдаётся миру» — `docs/dns-facts-vs-intent.md`.
+
+## Имена параметров, которые легко угадать неверно
+
+Проверено живыми вызовами, ошибочные варианты возвращают `INVALID_DATA`:
+
+| Метод | Верно | Неверно |
+|---|---|---|
+| `cron/delete` | `row_number` (поле так и называется в `cron/getList`) | `id` |
+| `mysql/changeAccessPassword` | `suffix` + `access` + `password`; `access` обязателен | без `access` |
+| `stat/getSiteLoad` | `site_id` — принимает и число, и строку | — |
+
+## Пароль API: спецсимволы и query string
+
+Пароль аккаунта Beget API может содержать `#` и прочие символы, ломающие URL.
+`BegetClient` отправляет `login`/`passwd` **POST'ом в теле формы**, поэтому не
+задет: кодирование берёт на себя `requests`, и пароль не попадает в access-логи
+по пути. В query остаётся только `output_format`.
+
+Сторонние клиенты этим не защищены: `dns_beget.sh` из acme.sh кладёт креды прямо
+в query string без URL-кодирования (`dnsapi/dns_beget.sh`), и на `#` в пароле
+curl обрывает URL — наружу это выглядит как `error code: 3` /
+«Can't get domain list».