remnawave-mcp

Сервер MCP для API панели Remnawave.

Опубликовано под scope @folexz: имя remnawave-mcp без scope в npm принадлежит несвязанному проекту, рассчитанному на Remnawave 2.7.4, и не работает с 2.8.0+.

npx -y @folexz/remnawave-mcp   # configured via REMNAWAVE_BASE_URL + REMNAWAVE_API_TOKEN_READ/_WRITE

Он охватывает все 205 операций из 28 контроллеров Remnawave API v3.3.2 — пользователи, узлы, хосты, профили конфигурации, группы, подписки, плагины узлов, инфра-биллинг, системная статистика — и генерируется из собственного OpenAPI-документа панели, а не написан вручную. Укажете более новую спецификацию для npm run build-spec — и набор инструментов подстроится.

Основные возможности

• Управляемый спецификацией и самообновляющийся. npm run update-spec загружает свежий OpenAPI-документ из опубликованной копии Remnawave и пересобирает каталог; входная схема каждого инструмента берётся напрямую из параметров операции и тела запроса. Об API не написано вручную, а при пересборке выводится diff, перечисляющий каждую добавленную, удалённую или переименованную операцию, так что изменение версии не может молча скрьтие навыду тот.

• Ограниченная стоимость контекста. 205 типизированных инструментов обходились быпример~39k токенов tools/list на каждый запрос. Профиль по умолчанию предоставляет 5 инструментов (~1.4k токенов) и при этом достиается до любой операции — см. Почему не 205 инструментов.

• Аутентификация с двумя ботаками и наименьшими привилегиями. Токен для чтения и опциональный токен для записи. GET использует токен для чтения; POST/PATCH/PUT/DELETE — токен для записи. Без токена для записи инструменты, изменяющие данные, вообще nie регистрируются — сервер физически режим толко для чтения.

• Guard rails для живой панели. Мутации сериализуются с минимальным интервалом и повторяются с экспоненциальной приостановкой, потому что каждая запись конфигурации отправляет конфиг на все узлы и перезапускает Xray. Массовые и деструктивные операции вдобавок требуют confirm: true.

• Встроенные полвые предупреждения. Проблемные места ниже прикреплены к затронутым операциям, поэтому они появляются в описании инструмента и в выводе remnanwafe_describe_operation.

• Нет заведомо неуспешных запросов. 16 эндпоинтов (auth, passkeys,управление API-токенами) обслуживаются только залогиненным админским JWT и откакентя API-токенам. Они высекаются из спецификации и локально отклоняются с объяснением, вместо того чтобы отправляться на сервер.

• Запасные лáзыМи. remnawave_request_read / remnawave_request_write добираются до любого пути, включая недокументированные маршруты и такой синтаксис запросов, который OpenAPI не может выразить.

Требования

• Node.js ≥ 18

• Панель Remnawave (3.x), доступная по HTTPS

• API-токен панели: Настройки → API-токены. Remnawave 3.x поддерживает scoped-токены — заведите один с правами чтения, а если нужны изменения, второй — с правами записи.

Установка

Быстрый путь — npx; см. Регистрация с Claude Code. Для запуска из исходников:

git clone https://github.com/folexz/remnawave-mcp.git
cd remnawave-mcp
npm install
npm run build

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

Вся конфигурация — это переменные окружения, которые передаёт ваш MCP-хост. Никакие файлы не читаются.

Регистрация с Claude Code

Режим только чтения (рекомендуемый вариант по умолчанию):

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  -- npx -y @folexz/remnawave-mcp@latest

С включёнными изменениями и типизированными инструментами для повседневных контроллеров:

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  --env REMNAWAVE_API_TOKEN_WRITE=your_write_token \
  --env REMNAWAVE_TOOL_PROFILE=core \
  -- npx -y @folexz/remnawave-mcp@latest

@latest заставляет npx при каждом запуске выбирать последнюю опубликованную версию. Чтобы запустить локальную сборку, замените команду на node /absolute/path/to/remnawave-mcp/dist/index.js.

Регистрация с Claude Desktop / другими MCP-клиентами

{
  "mcpServers": {
    "remnawave": {
      "command": "npx",
      "args": ["-y", "@folexz/remnawave-mcp@latest"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://panel.example.com",
        "REMNAWAVE_API_TOKEN_READ": "your_read_token"
      }
    }
  }
}

Почему не 205 инструментов

tools/list отправляется модели заново при каждом запросе, поэтому его сериализованный размер — spostoyаný налога на контекст. Замерено на этой спецификации (npx tsx scripts/tool-stats.ts):

DTO Remnawave — то, почему full так дорог: один развёрнутый объект типа host — это ~30 KB JSON Schema сам по себе, потому что он включает в себя все варианты inbound и безопасности.

Поэтому сервер не выбирает между «один инструмент на операцию» и «один грубый диспетчер» — он предоставляет и то и другое, а профиль решает, сколько объявлять:

1. Каталожные инструменты (always on, 3 инструмента). remnawave_list_operations просматривает и ищет в каталоге, возвращая одну компактную строкура на операцию; remnawave_describe_operation выдаёт полную JSON-схему и сопровождает полевые предупреждения для одной операции; remnawave_call выполняет любую из 205 операций по имени. Обычный цикл — list → describe → call — стоит тех же 1.4k токенов по независится от размера API. Это та же идея «ленивой загрузки», которую агентный фреймворк использует, когда откладывает схемы инструментов.

2. Типизированные (выбираются профилем). Для каждого контроллера, с которым вы действительно работаете, — по сгенерированному инструменту на операцию: core покрывает пользователей, узлы, хосты, профили конфигурации, внутренние группы, систему и два контроллера массовых операций; full — все операции; minimal — ни одну. Схемы больше REMNAWAVE_MAX_SCHEMA_BYTES сохраняют поля верхнего уровня и отбрасывают вложения, со ссылкой на remnawave_describe_operation для полной версии.

3. Запасные люки (2 инструмента). Обычный GET и обычная запись для всего, что спецификация не покрывает.

Каждый маршрут проходит через один и тот же исполнитель, поэтому входная дверь допуска, дверь деструктивного подтверждения, шаблонизация путей и обработка параметров поведения одинаково, каким бы инструментом вы ни воспользовались.

Подбирайте профиль по вкусу: minimal if у вас много MCP-серверов, core — если хочется получать обычные операции одним вызовом, full — если место в конексте не волнует.

Полевые заметки — поведение, которое спецификация не документирует

Все они проверены на живой панели 3.3.2 и прикреплены к затронуым операциям в описаниях инструментов.

• PATCH /api/config-profiles — это замена, а не патч. Тело — {uuid, config}, и config должен быть полным, валидным Xray-конфигом. Фрагмент приводит к ошибke A061: Config doesn't have inbounds. Правильная последовательность: GET /api/config-profiles/{uuid} → измените возвращённый объект config на месте → PATCH отправляет его обратно.

• Панель не отвечает на 127.0.0.1:3000, даже с самого vice docker-proxy слушает по этому адресу (curl вернёт заголовок ошибок 52, конецanswer. Всегда используйте публичный HTTPS-ориджин с Bearer token.

• Любый ответ оберрнут в {"response": ...}. Этот сервер снимает обёртку, поэтому выод инструмента — это сам payload.

• Хост привязываex к профилю через вложенное inbound.configProfileUuid (кроме inbound.configProfileInboundUuid), не top-level configProfileUuid. Проверено на live: вложенный config есть, top-level отсутствует.

• Пробег серии PATCH может уложить паn.agrave;. Each config write pushes to all nodes and повышает Xray; несколько подряд — и TLS-listener панели передстанot отвечать. Клиент сериализует mutation (REMNAWAVE_WRITE_MIN_INTERVAL_MS, default 1500 ms) and повтряет транспортные сбои с exponential backoff и jitter. Не омагайте его, запyma потивные массовые обновления патralleлью.

• POST /api/subscription-templates создаёт только pустой шаблablo.

• Congent загружается отдельным PATCH /api/subscription-templates. JSON and YAML bodies . Нельзя обновить за одну call.

• serverDescription на хосте орогор ограничен 30 симмволами (confirmed by maxLength in spec). Крme того, that's what a Hysteria2 host pasmit proper в 팬 app instead raw JSON.

• 16 энпоинтов only for admin JWT — весь controllers auth and passkeys плюс управение API-токенами (GET/POST /api/tokens, DELETE /api/tokens/{uuid}, GET /api/tokens/scopes). Панель на API-токен отвечает там 401/403. Этот сервер детзаццирует их через спецификацию и сам отклонят; REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1 вpyчает обход, если ваш token действительно admin JWT.

• GET /api/users/stream отдает json-строки через newline, нужно не единый документ; разбор происходит в проample из отдельных пользователей, а не как текстовый blob.

• PATCH /api/hosts — настоящий частичный патч — {uuid, serverDescription} работает и сам по себе. Именно только профили конфигурации имеют семантику полной замены. Verified live.

• Ошибки возвращаются как {message, errorCode}; errorCode (например A061) включается в текст ошибorna этого сервера.

Охват инструментов

Каждый контроллер достижим через remnawave_call и засайfree. Стол то typed column in таблице показывает, какие получают отдельные инструменты приunce REMNAWAVE_TOOL_PROFILE=core.

Запустите remnawave_list_operations против работающего сервера, чтобы получить точный, актуальный список.

Примеры

Просмотр и вызов без типизированных инструментов:

// 1. What is there?
{ "tool": "remnawave_list_operations", "arguments": { "controller": "nodes" } }

// 2. What does it take?
{ "tool": "remnawave_describe_operation",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart" } }

// 3. Do it.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart",
                 "params": { "uuid": "…" } } }

Безопасное редактирование конфигурационного профиля (ловушка A061):

// Read the whole profile first — PATCH replaces the config wholesale.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_get_config_profiles_uuid", "params": { "uuid": "…" } } }

// Send the full, edited config back.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_patch_config_profiles",
                 "params": { "body": { "uuid": "…", "config": { /* complete Xray config */ } } } } }

Синтаксис запросов, который спецификация выразить не может:

{ "tool": "remnawave_request_read",
  "arguments": { "path": "/api/users",
                 "query": { "size": 25, "start": 0,
                            "filters[0][id]": "status", "filters[0][value]": "ACTIVE" } } }

Тестирование

npm run build
npm test            # 50 unit tests + the offline smoke suite
npm run test:unit   # unit tests alone

Модульные тесты покрывают части, которые ломаются молча: разворачивание $ref через рекурсивные DTO Remnawave, присваивание имён инструментам (бюджет длины, детерминизм, поиск коллизий), сравнение каталога, оба шлюза записи, шлюз admin-JWT, схлопывание схемы и разбор NDJSON.

Проверки только для чтения против реальной панели

Когда панель доступна и в окружении есть read-токен, смоук-скрипт также выполняет реальные вызовы только для чтения (никогда — мутации):

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$REMNAWAVE_API_TOKEN" \
npm run smoke

Запускайте его там, где токен уже находится (например, на хосте панели), чтобы секрет никогда не пересылался. Скрипт печатает формы — типы, имена ключей, длину массивов, — но никогда не выводит значения, поэтому его результат безопасно вставлять в issue.

Проверки ограничений намеренно указывают на http://127.0.0.1:9, поэтому сбойно открытый шлюз не смог бы обратиться к реальной панели.

Проверка пути записи

Чтением нельзя доказать, что маршрутизация токенов, ограничитель частоты, шлюз подтверждения и семантика частичного PATCH действительно работают. scripts/write-check.mjs доказывает это на объектах, к которым никто не привязан, и возвращает тот единственный ранее существовавший объект, которого он коснулся:

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$T" REMNAWAVE_API_TOKEN_WRITE="$T" \
node scripts/write-check.mjs --i-understand-this-mutates [--host-uuid <uuid>]

Скрипт создаёт внутренний squad без входящих подключений и без участников, затем удаляет его, после чего переписывает serverDescription на одном хосте и восстанавливает исходное значение. Он не запускается без флага подтверждения и возвращает ненулевой код выхода, если что-то осталось.

Проверка против живой панели 3.3.2 подтвердила: шлюз подтверждения держит реальный DELETE; частичный PATCH /api/hosts работает; панель отклоняет serverDescription из 31 символа; исходное значение (включая null) успешно проходит полный цикл; последовательные мутации были разнесены на 1525 и 1524 мс при настроенном минимальном интервале 1500 мс.

Локальный просмотр

REMNAWAVE_BASE_URL=https://panel.example.com REMNAWAVE_API_TOKEN_READ=xxx npm run inspect

Обновление спецификации API

Всё, что относится к API, берётся из одного файла, поэтому следить за новым релизом Remnawave — одна команда:

npm run update-spec            # fetch the newest spec + rebuild the catalogue
npm run update-spec -- --strict  # additionally fail if any operation disappeared or was renamed
npm run build && npm test      # compile and verify

Откуда спецфикация

https://cdn.remna.st/docs/openapi.json — публикуется собственным workflow Remnawave Build&Push OpenAPI Specs на каждый астрамный тег, поэтому он всегда описывает новейший реливз. Перекрыть можно через --url <u> или REMNAWAVE_SPEC_URL.

Инстанс панели не является источником: документация по умолчанию раздражает, даже если включена, Swagger смонтирован по адресу /backend-tools/swagger, который обычный реверс-прокси не маршрутизирует. Зондирование живой панели 3.3.2 вернулю 404 для всех стандартных путей спецификации.

Скачивание пишется на диск только после того, как содержимое разобралось как документ OpenAPI с непустым paths, то есть страница с ошибкой или captive portal вслучаться рабочий спецификацию не может.

Что проверить потом

build-spec сравнивает новый каталог с предыдущим и печатает каждое изменение:

build-spec: Remnawave API v3.4.0 -> 211 operations, 28 controllers, 315 KB
  methods: DELETE=22 GET=90 PATCH=19 POST=78 PUT=2  admin-JWT-only: 16
  diff: API version 3.3.2 -> 3.4.0
  REMOVED — tools that will disappear (1):
    remnawave_get_old_thing  (GET /api/old-thing)
  added (7):
    ...

• REMOVED / RENAMED — ломающие изменения для всех, чьи промпты или скрипты называют эти инструменты. --пусм превращает их в ненулевой код выхода — такой флаг и должна использовать автоматизация.

• added — не опасны; новые операции сразу становятся доступны через remnawave_call и получают типизированные инструменты, если их контроллер включён в активном профиле.

• schema changed — стоит просмотреть для операций, которые вы реально используете.

Затем npm test перепроверяет, что catalogue на диске совпадает с свежей сборкой, что имена всех инструментов уникальны и укладываются в бюджет 64 символа, а head-ограждения всё ещё удерживают.

Автоматизация

npm run update-spec -- --strict   # exits non-zero on a breaking catalogue change
npm test
npm version minor --no-git-tag-version
git commit -am "chore: Remnawave API 3.4.0" && git push
git tag "v$(node -p "require('./package.json').version")" && git push --tags

Отправленный тег запускает release workflow, который перепубликует пакет в npm. Клиенты, зарегистрированные в @folexz/remnawave-mcp@latest, получают новую версию при следующем запуске.

Реlиз (мейнтайнеров)

Первая публикация — вручную

npm не может настроить доверенного издателя для несуществующего пакета: эта настройка находится на странице параметров самого пакета. Это известное (и до сих пор открытое) ограничение (npm/cli#8544), распространяется оно и на scoped-пакеты. Поэтому версию 0.1.0 нужно публиковать с машины, где выполнен вход:

npm whoami            # must print the account that owns the @folexz scope
npm publish --access public

--access public обязателен: scoped-пакеты по умолчанию ограничены.

Затем перейти на релизы без токенов

После того как пакет существует, на npmjs.com → @folexz/remnawave-mcp → Settings → Trusted Publisher добавьте издателя GitHub Actions с репозиторием folexz/remnawave-mcp и workflow release.yml. repository.url в package.json должен точно совпасть с GitHub-репозиторием — что он и делает.

После этого .github/workflows/release.yml публикует любой отправленный тег vX.Y.Z через OIDC — без токменов и секретов, с автоматической проверкой происхождения (provenance):

npm version patch --no-git-tag-version
git commit -am "chore: v0.1.1"
git push
git tag v0.1.1 && git push origin v0.1.1

Workflow переустанавливает зависимости из lock-файла, пересобирает, запускает модульные тесты и офлайн-смоук, и падает на ранней стадии, если тег не соответствует package.json.

Клиенты, зарегистрированные в @folexz/remnawave-mcp@latest, получат новую версию при следующем запуске.

Заметки о безопасности

• Токены читаются только из окружения и никогда не фиксируются в журналах. Логи прд отстуе в stderr; stdout — канал JSON-RPC MCP.

• Лучше настраиваивать только REMNAWAVE_API_TOKEN_READ. Без write-токенирования мутирующие инструменты не существуют — скомпрометированный или подменённый клиент не изменит панель.

• Subscription-передачи возвращают рабочие клиентские конфигурации. Считайте их содержимое секретом.

• Никогда не поддерживайте реальные токены в репозитории. .env исключён из git; .env.example описывает структуру.

Известные ограничения

• Проверка тела отправлена на панель. Этот сервер проверяет только наличие обязательных аргументов и обязательного body; он не проверяет внутреннюю форму тела на соответствие, потому что панель и так валидирует каждое поле и возвращает точный message + errorCode (например A061). Дублировать это локально ещё и Shipping JSON SchemaValidator — создавать опять же , вторую растущую копию правил. Цена такого тестирования — один лишний сетевой выясняющий цикл для некорректного тела.

• Escape-люки игнорируют шлюзы по операциям. REMNAWAVE_REQUEST_WRITE — это намеренно «сырой» подход: он каждый раз требует write-токен, проходит ограничение частоты и логику повторов, но не применяет разрушительный шлюз confirm и не проверяет admin-JWT, потому что у него нет операции, по которой их отыскать. Поэтому для обычных вызовов предпочитайте remnawave_call пара тех операций, которых нет в спецификации.

• Инструменты могут быть колдер, чем сама спецификация (v3.3.2). Панель другой минорной версии может открывать маршруты, которые спецификация не описывает; для этого и сущест fallback-люки. См. [Обновления специации API](#updating-the- apipec).