XfeaturesControlMCP

Автономный MCP-сервер для управления игровыми серверами через панель Calagopus. ИИ-клиент (Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI) видит ваши серверы, читает логи и файлы, правит конфиги, ищет и ставит плагины и моды с Modrinth и CurseForge. Права ограничены API-ключом пользователя и его правами на сервере: панель сама проверяет каждое действие.

Это не расширение панели: отдельная программа на TypeScript, которая ходит в Client API панели по Authorization: Bearer <ключ>. Набор инструментов, схемы и тексты совпадают со встроенным MCP-аддоном панели (addons.calagopus.mcpserver), поэтому промпты для ИИ работают с обоими.

Запуск

Нужен Node.js ≥ 20.

git clone https://github.com/biggikos/XfeaturesControlMCP.git
cd XfeaturesControlMCP
npm ci && npm run build

Два режима:

После публикации в npm станет доступен npx -y xfeatures-control-mcp.

Related MCP server: easypanel-mcp

Настройка

Переменные окружения (или JSON-файл, путь в XFEATURES_CONFIG; окружение главнее файла):

Опечатка в имени группы даёт ошибку запуска, а не молча оставляет группу включённой. Выключенная группа пропадает из tools/list и отклоняется при вызове.

Ключ. Создайте его в панели: Аккаунт → API-ключи. Ключ нигде не логируется и не попадает в ответы инструментов и ошибки.

HTTP-режим слушает 127.0.0.1. Чтобы открыть его наружу, задайте HTTP_HOST и ставьте перед ним TLS-прокси: ключ панели идёт в заголовке, по обычному HTTP его нельзя гонять через сеть.

BACKEND

• native: свой код ходит в Client API панели. Предсказуемо, ничего не пробует.

• addon: всё пересылается встроенному MCP-аддону панели (/api/client/extensions/addons.calagopus.mcpserver/mcp). Если аддон не установлен, будет ошибка.

• auto: если аддон есть и включён, пересылка ему (действует политика админа панели), иначе native. Наши TOOL_GROUPS_OFF и ALLOW_KILL работают поверх и могут только сужать.

Подключение к клиенту

Готовые конфигурации печатает сам сервер (ключ всегда заглушка <panel-api-key>):

PANEL_URL=https://panel.example.com node dist/index.js --snippet claude-code
node dist/index.js --snippet claude-desktop --transport http
node dist/index.js --prompt          # текст, который можно отдать ИИ-агенту: он подключится сам

Клиенты: claude-code, claude-desktop, cursor, vscode, codex, other. Флаги: --transport stdio|http, --name, --package (что запускает npx).

Например, Claude Code, stdio:

claude mcp add xfeatures -e PANEL_URL=https://panel.example.com -e PANEL_API_KEY=<panel-api-key> -- npx -y xfeatures-control-mcp

Claude Code, HTTP:

claude mcp add --transport http xfeatures http://127.0.0.1:3333/mcp --header "Authorization: Bearer <panel-api-key>"

Инструменты

servers, server_info, logs, power, command, files (list/read/grep), file_write (целиком или find/replace), content_search, content_info, content_installed, content_install, content_updates, content_remove, describe.

Каждый помечен readOnlyHint/destructiveHint. Собственных подтверждений нет: их запрашивает клиент по своему режиму.

Экономия токенов заложена в дизайн: 14 инструментов с короткими описаниями (подробности через describe), ответы компактным текстом (TSV) с потолком 24 КБ, сервер указывается по имени, загрузчик и версия Minecraft определяются сами, логи и файлы читаются окнами и через grep, поиск возвращает одну строку на результат с объединением Modrinth и CurseForge, content_install разрешает всё дерево зависимостей за один вызов, dry_run показывает план.

Зависимости и версии. Выбирается новейший релиз, совместимый с загрузчиком и версией (Paper берёт paper/spigot/bukkit, Purpur ещё и purpur, Quilt берёт fabric). Обязательные зависимости ставятся сами, несовместимые с установленным блокируют установку. content_updates{target_mc} показывает, что сломается при смене версии Minecraft. content_remove не удаляет jar, который требует другой установленный.

Безопасность

• Запретные пути (.env, .ssh, ключи, /proc, /sys, /dev, сокеты) отсекаются до запроса к панели.

• Файлы скачивает сама нода через files/pull; разрешены только https на CDN Modrinth и CurseForge (по разобранному имени хоста, без логина в URL).

• Лимиты: запись целиком до 512 КиБ, правка find/replace до 2 МиБ (файл не UTF-8 или обрезанный не правится), ответ до 24 КБ.

• Регулярки из grep проверяются на типовые шаблоны катастрофического отката (см. ограничения).

• Ошибки инструментов возвращаются как результат isError, а не как ошибка протокола: модель читает сообщение и может исправиться.

Отличия от аддона панели

Совпадают: 14 инструментов, их схемы, аннотации, INSTRUCTIONS, тексты describe, группы, правила совместимости загрузчиков. Это проверяет тест test/parity.test.ts, который разбирает исходники аддона (запуск ниже).

Не перенесено: Hytale (в образце вне ядра MCP), административные страницы и настройки панели (public_url, enabled, эндпоинты /config и /access), собственные проверки прав (панель сама проверяет каждый вызов).

Ограничения

• Скачивание асинхронное. «installed N/M» значит, что нода приняла задачи files/pull, а не что файлы уже скачаны. Результат видно через content_installed через несколько секунд.

• Замена не откатывается. Старый jar удаляется до скачивания нового; сбой сети после удаления оставит сервер без плагина.

• Опознаются только jar, известные Modrinth. Для остальных обновления недоступны; установленное с CurseForge определяется только по имени файла.

• Защита от тяжёлых регулярок эвристическая. Она отсекает типовые шаблоны ((a+)+), но не гарантирует защиту от любых; худший случай: зависание одного запроса.

• Логи ограничены 1000 строк окном lines панели, поэтому errors и grep ищут в последних 1000 строках.

Разработка

npm ci
npm run typecheck
npm test                 # юнит-тесты; сети нет: фикстуры Modrinth/CurseForge и поддельная панель

Сверка с исходниками аддона (нужен клонированный calagopus-addons):

ADDON_SRC=/path/to/calagopus-addons/mcp/backend-extensions/addons_calagopus_mcpserver/src npm test

Структура: src/tools/ (каталог и обработчики), src/content/ (поиск, резолвер зависимостей, установка, обновления), src/panel/ (клиент Client API и прокси к аддону), src/transport/http.ts, src/snippets.ts.

Лицензия

MIT