regru-cloud-mcp
# regru-cloud-mcp
Read-only MCP-сервер для **Рег.облака** (облачные серверы Reg.ru, [CloudVPS API](https://developers.cloudvps.reg.ru)).
Позволяет MCP-агенту (ZCode, Claude, Cursor и т.п.) безопасно, **только для чтения**, отвечать на вопросы:
- сколько денег осталось на балансе облака и на сколько их хватит;
- что потребляет баланс — детализация по каждому ресурсу (серверы, бэкапы, IP-адреса);
- какие серверы подняты, их статус, конфигурация (CPU/RAM/диск/ОС), IP-адреса, регионы;
- цены ресурсов за час/месяц, список снэпшотов и SSH-ключей.
Мутирующих операций нет принципиально: сервер обращается только к GET-эндпоинтам API.
## Инструменты
| Инструмент | API-эндпоинт | Что возвращает |
| ----------------- | --------------------- | ------------------------------------------------------------------------------ |
| `cloud_balance` | `GET /v1/balance_data`| Баланс, бонусный баланс, hourly/monthly cost, days/hours left, детализация потребления |
| `cloud_servers` | `GET /v1/reglets` | Все серверы: статус, ОС, тариф, vcpus/memory/disk, IP, PTR, регион, бэкапы |
| `cloud_server` | `GET /v1/reglets/{id}`| Один сервер подробно (+ фактическое использование диска) |
| `cloud_prices` | `GET /v1/prices` | Прайс-лист всех ресурсов (час/месяц) |
| `cloud_snapshots` | `GET /v1/snapshots` | Снэпшоты: имя, размер, базовый образ |
| `cloud_ssh_keys` | `GET /v1/account/keys`| SSH-ключи: имя, fingerprint, публичный ключ |
## Где взять токен
Панель управления **Облачными серверами** Рег.облака → вкладка **«Настройки»** → API-токен.
> ⚠️ Токен открывает **полный** доступ к вашим облачным VPS (создание/удаление и т.д.).
> Держите его в секрете; при компрометации смените его там же в панели.
> Этот MCP-сервер, в отличие от токена, ничего менять не умеет — только читать.
## Настройка в ZCode
Добавьте сервер в пользовательский конфиг `~/.zcode/cli/config.json` (в Windows: `C:\Users\<вы>\.zcode\cli\config.json`):
```json
{
"mcp": {
"servers": {
"regru": {
"command": "npx",
"args": ["-y", "github:vl336/regru-cloud-mcp"],
"env": {
"REGRU_CLOUD_TOKEN": "<ваш API-токен>"
}
}
}
}
}
```
Затем перезапустите ZCode. Токен вводите сами — он нужен только в этом конфиге.
> Токен передаётся процессу сервера через переменную окружения самим клиентом и не попадает в контекст агента. Сервер не логирует токен и не возвращает его в результатах инструментов.
### Альтернативные способы установки
Через npm-пакет (если опубликован):
```json
"regru": {
"command": "npx",
"args": ["-y", "regru-cloud-mcp"],
"env": { "REGRU_CLOUD_TOKEN": "<токен>" }
}
```
Через глобальную установку:
```bash
npm install -g github:vl336/regru-cloud-mcp
```
```json
"regru": {
"command": "regru-cloud-mcp",
"env": { "REGRU_CLOUD_TOKEN": "<токен>" }
}
```
## Разработка
```bash
npm install
npm run build # компиляция в dist/
npm run smoke # см. ниже
```
### Smoke-тест
Выполняет пару реальных read-only запросов (баланс + первые серверы) и печатает результат. Токен читается **только** из переменной окружения процесса:
```bash
# Git Bash / Linux / macOS
REGRU_CLOUD_TOKEN=<токен> npm run smoke
# Windows CMD
set REGRU_CLOUD_TOKEN=<токен> && npm run smoke
```
Переменные окружения:
| Переменная | Назначение |
| ---------------------- | ------------------------------------------------- |
| `REGRU_CLOUD_TOKEN` | обязательный API-токен Рег.облака |
| `REGRU_CLOUD_API_BASE` | необязательный base URL (по умолчанию `https://api.cloudvps.reg.ru`) |
## Лицензия
[MIT](LICENSE)
TDQS
Scored across 6 tools
Most tools target clearly distinct resources: balance, prices, snapshots, SSH keys, and servers. The main risk is cloud_servers (list all VPS) versus cloud_server (single-server details), which differ only by singular/plural and could be misselected, though the descriptions clarify the id requirement.
All six tools follow the same predictable cloud_<resource> snake_case pattern. Although they are noun-based rather than verb_noun, the convention is uniform and readable across the entire set.
Six tools is a reasonable, well-scoped count for an informational cloud API wrapper, and each tool covers a distinct data area. It is slightly thin for a full cloud-management surface, but not excessive or trivial.
The surface is entirely read-only: it can list servers, balances, prices, snapshots, and SSH keys, but cannot create, delete, start, stop, reboot, resize, or snapshot anything. These are major lifecycle gaps for a server named regru-cloud-mcp and will force agents to fail on common management tasks.