sweb-mcp — MCP-сервер для управления хостингом SpaceWeb через языковую модель

· 5 мин чтения
mcp mcp-server hosting python ai-agents
📂 Исходный код на GitHub

MCP-сервер (stdio, Python) для API SpaceWeb: 276 методов хостинга как tools для LLM, с трёхуровневой защитой и поддержкой нескольких аккаунтов.

sweb-mcp — MCP-сервер для управления хостингом SpaceWeb через языковую модель

sweb-mcp — это MCP-сервер на Python, который открывает клиентский API хостинг-провайдера SpaceWeb (sweb.ru) языковой модели. API построен на JSON-RPC 2.0 и охватывает 29 объектов и 276 уникальных методов: сайты, домены, DNS, VPS, почта, тарифы, платежи. Сервер превращает все эти методы в MCP-инструменты, поэтому вместо сценария «прочитай документацию и напиши curl» модель просто видит готовые tools и вызывает их.

Сервер работает по stdio и запускается любым MCP-клиентом по требованию: Claude Code, OpenCode, Cursor. Проект неофициальный и не связан со SpaceWeb; лицензия — MIT.

Что умеет

Типовой запрос к хостингу превращается в пару вызовов инструментов:

> сколько сейчас сайтов на аккаунте и которые из них без SSL?
  sites_index                   → 7 сайтов
  sites_getSiteInfo(siteId=...) → ...

Несколько примеров read-вызовов:

Запрос Вызов
Список сайтов sites_index
Баланс и платежи pay_index, pay_getBalance
DNS-записи домена domains_dns_info(domain="example.ru")
VPS-серверы vps_index
Почтовые ящики vh_mail_getMailboxesList(domain="example.ru")
Текущий тариф tariff_index

Ответы API отдаются как есть, в формате JSON, без преобразований и кеширования.

Как устроены инструменты

Каждый метод API становится tool с именем вида <объект>_<метод>: sites_index, vps_index, domains_dns_editTxt, vh_mail_createMbox. Поверх них работают пять мета-инструментов:

  • sweb_list_methods — обзор и поиск методов по группе или подстроке;
  • sweb_describe — описание конкретного метода: путь, параметры, семантика;
  • sweb_call — прямой вызов любого метода, даже без отдельного tool;
  • sweb_accounts — список аккаунтов и текущий аккаунт;
  • sweb_use_account — переключение аккаунта по умолчанию до перезапуска.

Типовой поток для модели: сначала sweb_list_methods, затем sweb_describe, затем вызов нужного tool с параметрами.

Установка

Нужен Python 3.11–3.13. Пакет в PyPI не публикуется, ставится из git, из клона или из Docker-образа на GHCR:

uvx --from git+https://github.com/avert/sweb-mcp sweb-mcp
docker run -i --rm --env-file .env ghcr.io/avert/sweb-mcp:latest

Подключение к Claude Code:

claude mcp add sweb -- uv run --directory "$PWD" --env-file .env sweb-mcp

Пример конфигурации для Cursor (.cursor/mcp.json), установка без клонирования:

{
  "mcpServers": {
    "sweb": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/avert/sweb-mcp", "sweb-mcp"],
      "env": { "SWEB_ACCOUNTS_FILE": "/path/to/accounts.json", "SWEB_ACCOUNT": "main" }
    }
  }
}

Для OpenCode настройка аналогична — блок mcp в opencode.json с командой uv run.

Безопасность: три уровня доступа

Каждый метод классифицируется как read, write, destructive или paid. Доступ включается ступенями:

  • read — выполняется свободно;
  • write — нужен SWEB_READONLY=0 и явный confirm=true в аргументах tool;
  • destructive и paid — дополнительно SWEB_ALLOW_DESTRUCTIVE=1.

В спеках API нет флагов read/write, поэтому класс выводится по эвристике: из имени метода, таблицы платных операций и ручных правок через SWEB_OVERRIDES. Метки [WRITE], [DESTRUCTIVE], [PAID] видны в описании tool — их стоит проверять перед включением записей.

Отдельная деталь защиты: авто-повторы после ошибок 502/503/504 и сбоев сети выполняются только для read-методов. Исход записи после такого сбоя неизвестен, а повтор мог бы задвоить заказ или удаление. Для ошибки 429 (превышен лимит запросов) повторы включены всегда — с экспоненциальной паузой и учётом заголовка Retry-After.

Аккаунты и учётные данные

Единственный источник учётных данных — JSON-файл из переменной SWEB_ACCOUNTS_FILE. Внутри — карта аккаунтов вида {"имя": {"login": "...", "password": "..."}} или {"имя": "login:password"}. Файлу нужны права chmod 600, и он не должен попадать в git — .gitignore уже исключает accounts*.json и .env.

Аккаунт по умолчанию задаёт SWEB_ACCOUNT. Токен кешируется на каждый аккаунт, а при истечении сессии (ошибка -32603) клиент перелогинивается автоматически.

Полезные переменные окружения:

Переменная Назначение По умолчанию
SWEB_READONLY только read-методы 1
SWEB_ALLOW_DESTRUCTIVE разрешить destructive и paid 0
SWEB_GROUPS фильтр групп, например vps,domains,vh/mail все
SWEB_OVERRIDES JSON с ручной правкой классов, например {"/vps:reboot":"write"} —
SWEB_MAX_CONCURRENCY, SWEB_MIN_INTERVAL защита от rate limit: одновременные запросы и пауза 4, 0.2 с
SWEB_MAX_RETRIES, SWEB_BACKOFF_BASE число повторов и база паузы 3, 0.5 с

Ограничения и типовые проблемы

О чём стоит знать до внедрения:

  • Спеки — это снапшот. Файлы specs/*.json сняты с apidoc.sweb.ru на момент синхронизации; официальной машиночитаемой спеки у SpaceWeb нет. Спеки в формате OpenRPC извлечены из JS-бандла документации, логика портирована из sanchpet/sweb-go-sdk. Обновление — скрипт scripts/sync_specs.py.
  • Классификация эвристическая. Ошибка возможна, поэтому перед разрешением записей проверяйте метки в описании tool.
  • Лимиты API не документированы. Настройки одновременных запросов и пауз подобраны с запасом; при 429 увеличивайте SWEB_MIN_INTERVAL.
  • Сервер «молчит» в клиенте. Это норма для stdio: логи идут в stderr. При ручном запуске печатается строка [sweb-mcp] readonly=… creds=set/MISSING.
  • Прокси не поддерживается через переменные окружения. Клиент ходит напрямую и игнорирует HTTP(S)_PROXY; прокси настраивается на сетевом уровне (VPN или обёртка).

Лицензия

Проект распространяется по лицензии MIT. Это неофициальный клиент: автор не связан со SpaceWeb, гарантий не даёт и не отвечает за последствия вызовов, выполненных с вашими учётными данными. Используя сервер, вы соблюдаете условия обслуживания SpaceWeb и лимиты API. Подробности для контрибьюторов — в CONTRIBUTING.md, история изменений — в GitHub Releases.

Источник: https://github.com/AVert/sweb-mcp