# MCP RUVDS

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

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

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

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

## Требования

- Node.js ≥ 18
- Токен API RUVDS (Bearer) из [настроек аккаунта](https://ruvds.com/pr855) (раздел «Настройки» → API)

## Установка

```bash
npm install
```

## Настройка

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

```bash
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

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

```bash
docker build -t mcp-ruvds:latest .
```

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

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

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

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

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

```bash
# без токена — только список инструментов
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` (путь к проекту замените на свой):

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

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

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

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

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

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

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

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

```json
{
  "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 наследует окружение, можно оставить только проброс в контейнер:

```json
"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](docs/ARCHITECTURE.md) — поток данных, как добавить инструмент, соглашения API.

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

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

1. **Документация** — README (этот файл), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). API: [OpenAPI RUVDS](https://ruvds.com/api-docs/openapi/ruvds-api-v2.yaml).
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](https://ruvds.com/api-docs/openapi/ruvds-api-v2.yaml)
- [Использование API](https://ruvds.com/ru-rub/use_api)

## Лицензия

MIT