MCP RUVDS

MCP-сервер для создания и управления VPS в RUVDS через API v2. Предоставляет инструменты (tools) для Cursor и других MCP-клиентов: список серверов, каталог (дата-центры, тарифы, ОС), создание/изменение VPS, баланс, действия, SSH-ключи, уведомления, платежи.

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

cp .env.example .env   # указать RUVDS_TOKEN
npm install && npm run build

Подключить сервер в настройках MCP Cursor (см. раздел Подключение в Cursor). После этого в чате с ИИ доступны инструменты ruvds_*.

Требования

• Node.js ≥ 18
• Токен API RUVDS (Bearer) из настроек аккаунта (раздел «Настройки» → API)

Установка

npm install

Настройка

Скопируйте .env.example в .env и укажите токен:

cp .env.example .env
# Отредактируйте .env: RUVDS_TOKEN=ваш_токен

Токен должен иметь нужные права:

• read — список серверов, каталог, баланс, действия, уведомления, платежи, SSH-ключи
• write — создание/изменение серверов, команды (power_on/off, reboot, shutdown), создание SSH-ключей
• remove — удаление серверов и SSH-ключей (при необходимости выдаётся в ЛК RUVDS)

Запуск

• Разработка: npm run dev
• Сборка: npm run build
• Запуск: npm start (или node dist/index.js)

Сервер работает по stdio: клиент (Cursor и др.) запускает процесс и общается через stdin/stdout.

---

Docker

Сборка образа:

docker build -t mcp-ruvds:latest .

Проверка образа

1. Быстрый запуск (контейнер ждёт ввода по stdio; выход — Ctrl+C):

docker run -i --rm -e RUVDS_TOKEN=ваш_токен mcp-ruvds:latest

Если токен не задан, сервер всё равно стартует, но вызовы к API будут возвращать ошибку.

2. Полная проверка (initialize + tools/list + опционально вызов API):

# без токена — только список инструментов
npm run test:mcp:docker

# с токеном — плюс вызов ruvds_list_datacenters
export RUVDS_TOKEN=ваш_токен
npm run test:mcp:docker

Контейнер при работе с Cursor запускает сам Cursor по мере обращения к MCP.

---

Подключение в Cursor

Cursor подключается к MCP по stdio: запускает процесс (или контейнер) и передаёт токен через переменные окружения.

Куда вписать настройки

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json
• Windows: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json
• Linux: ~/.config/Cursor/User/globalStorage/cursor.mcp/mcp.json

Либо: Cursor → Settings → MCP и добавить сервер в конфиг.

Вариант 1: запуск без Docker (Node.js на хосте)

В конфиге MCP добавьте блок ruvds (путь к проекту замените на свой):

{
  "mcpServers": {
    "ruvds": {
      "command": "node",
      "args": ["/полный/путь/к/mcp_ruvds.com/dist/index.js"],
      "env": {
        "RUVDS_TOKEN": "ваш_токен_из_ruvds"
      }
    }
  }
}

Перед этим выполните в каталоге проекта:

cd /полный/путь/к/mcp_ruvds.com
npm install
npm run build

Токен можно не хранить в конфиге: задайте переменную окружения в системе и в блоке ruvds укажите только "env": {} или не указывайте env — Cursor передаст переменные процесса в MCP.

Вариант 2: запуск через Docker

Соберите образ один раз:

cd /полный/путь/к/mcp_ruvds.com
docker build -t mcp-ruvds:latest .

В конфиге MCP добавьте:

{
  "mcpServers": {
    "ruvds": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "RUVDS_TOKEN",
        "mcp-ruvds:latest"
      ],
      "env": {
        "RUVDS_TOKEN": "ваш_токен_из_ruvds"
      }
    }
  }
}

• -i — держит stdin открытым для протокола MCP.
• --rm — удаляет контейнер после завершения.
• -e RUVDS_TOKEN — пробрасывает переменную из окружения Cursor в контейнер; значение задаётся в env.RUVDS_TOKEN.

Если RUVDS_TOKEN уже задан в системе и Cursor наследует окружение, можно оставить только проброс в контейнер:

"ruvds": {
  "command": "docker",
  "args": ["run", "-i", "--rm", "-e", "RUVDS_TOKEN", "mcp-ruvds:latest"]
}

Проверка в Cursor

После сохранения конфига перезапустите Cursor или перезагрузите MCP. В чате с AI должны появиться инструменты RUVDS (например, ruvds_list_servers, ruvds_list_datacenters). Можно написать: «Покажи список моих серверов в RUVDS» или «Какие дата-центры есть в RUVDS?».

Инструменты (Tools)

Tool	Описание
Серверы
ruvds_list_servers	Список VPS (пагинация, поиск, опция IP/paid_till)
ruvds_get_server	Один сервер по ID
ruvds_create_server	Создать VPS (datacenter, tariff, os_id/template_id, cpu, ram, drive, ip, payment_period и др.)
ruvds_change_server	Изменить конфиг (cpu, ram, drive, ip; опция get_price_only)
ruvds_delete_server	Удалить VPS
ruvds_server_action	Команда: power_on, power_off, shutdown, reboot
ruvds_server_cost	Стоимость продления
ruvds_server_networks	IP-адреса
ruvds_server_paid_till	Дата оплаты до
ruvds_server_power_state	Состояние питания (running/off/starting/stopping)
Каталог
ruvds_list_datacenters	Дата-центры
ruvds_list_tariffs	Тарифы (VPS, диски, доп. услуги, скидки)
ruvds_list_os	Образы ОС
ruvds_list_templates	Шаблоны (маркетплейс, снапшоты)
Прочее
ruvds_get_balance	Баланс (тип: default/bonus/partner, валюта)
ruvds_list_actions	Список действий (создание/изменение/команды)
ruvds_get_action	Статус действия по ID
ruvds_list_ssh_keys	SSH-ключи
ruvds_get_ssh_key	Один SSH-ключ
ruvds_create_ssh_key	Добавить ключ
ruvds_delete_ssh_key	Удалить ключ
ruvds_list_notifications	Оповещения
ruvds_notifications_count	Количество по статусу
ruvds_mark_notification_read	Отметить прочитанным/непрочитанным
ruvds_mark_all_notifications	Отметить все
ruvds_list_payments	Список платежей (только чтение)

Операции оплаты (продление с баланса) в текущей версии не реализованы.

Параметры API: datacenter, tariff_id, drive_tariff_id, os_id — числовые ID из каталога (ruvds_list_datacenters, ruvds_list_tariffs, ruvds_list_os). payment_period: 1–5 (обычно 1 = 1 мес, 3 = 3 мес, 5 = 12 мес со скидками; точные скидки в ruvds_list_tariffs → payment_period_discount).

Структура проекта

• src/index.ts — точка входа, MCP-сервер, stdio-транспорт, регистрация инструментов.
• src/tools/ — инструменты по группам: servers, catalog, balance, actions, ssh-keys, notifications, payments.
• src/ruvds/ — клиент HTTP (client.ts), обёртки API v2 (api.ts), типы (types.ts).
• Подробно: docs/ARCHITECTURE.md — поток данных, как добавить инструмент, соглашения API.

Для разработчиков и ИИ

Чтобы быстро разобраться и внести изменения:

1. Документация — README (этот файл), docs/ARCHITECTURE.md. API: OpenAPI RUVDS.
2. Добавить инструмент: реализовать вызов API в src/ruvds/api.ts при необходимости; в src/tools/*.ts зарегистрировать server.tool("ruvds_<name>", zodSchema, handler); возвращать jsonContent(result) или handleError(e); обновить таблицу инструментов в README.
3. Токен: обязателен для вызовов API; задаётся в RUVDS_TOKEN (env или конфиг MCP). Ошибка 401 — неверный или отсутствующий токен.
4. Проверка: npm run build && npm run test:mcp; с токеном дополнительно вызывается ruvds_list_datacenters.

Документация API

• RUVDS API v2 OpenAPI
• Использование API

Лицензия

MIT