# timeweb-mcp

MCP-сервер для [Timeweb Cloud](https://timeweb.cloud): управление облачными серверами, доменами, DNS-записями и просмотр баланса из Claude (Desktop, Code, Cowork) и любых других MCP-клиентов.

> MCP (Model Context Protocol) — открытый протокол, через который AI-ассистенты подключаются к внешним сервисам. Этот сервер даёт ассистенту руки для вашей инфраструктуры в Timeweb Cloud: «покажи баланс», «какой статус у сервера», «добавь A-запись для нового поддомена» — без захода в панель.

Эндпоинты сверены с официальным [sdk-javascript](https://github.com/timeweb-cloud/sdk-javascript). Не аффилирован с Timeweb.

## Возможности

| Группа | Инструменты |
|---|---|
| Аккаунт | `account_status`, `account_finances` (баланс и прогноз списаний) |
| Серверы | `list_servers`, `get_server`, `get_server_logs`, `list_server_presets`, `list_os_images`, `server_power`⚠️, `create_server`⚠️💰, `delete_server`⚠️☠️ |
| Домены и DNS | `list_domains`, `get_domain`, `get_name_servers`, `list_dns_records`, `create_dns_record`, `update_dns_record`, `delete_dns_record`⚠️ |
| SSH | `server_diagnostics` (read-only осмотр), `service_control`⚠️ (systemctl), `ssh_exec`⚠️ (любая команда) |

В плагин входит скилл **timeweb-ops** — инструкция для ассистента: типовые сценарии (подключить домен к серверу, поднять VPS, следить за балансом), протокол подтверждений и обработка ошибок. Срабатывает сам на фразы вроде «покажи мои серверы» или «добавь A-запись».

**Безопасность встроена в инструменты:**

- ⚠️ — операция выполняется только с явным параметром `confirm: true`; без него ассистент получает отказ и должен переспросить вас.
- ☠️ — `delete_server` дополнительно требует `expected_name`: имя сверяется с реальным именем сервера, и при несовпадении удаление отклоняется. Защита от «удалил не тот id».
- Токен хранится в файле с правами 600 и не передаётся через аргументы команд (не светится в списке процессов).

## Установка как плагин Claude (самый простой способ)

Плагин ставится прямо из git — токен настраивается один раз (см. [Токен API](#1-токен-api)):

```
/plugin marketplace add https://github.com/<your-name>/timeweb-mcp
/plugin install timeweb-mcp@k2spam-tools
```

Внутри плагина — самодостаточный бандл (`mcp/server.cjs`), ничего собирать и устанавливать не нужно. Альтернатива: скачать готовый `build/timeweb-mcp-v<версия>.plugin` из релизов и установить файлом (Cowork: перетащить в чат → Save plugin).

## Установка вручную (как обычный MCP-сервер)

Требования: Node.js ≥ 18.

```bash
git clone https://github.com/<your-name>/timeweb-mcp.git
cd timeweb-mcp
npm install
npm run build
```

### 1. Токен API

Панель Timeweb Cloud → **API и Terraform** → создать токен.

Токен кладётся на диск **один раз**, дальше сервер находит его сам:

**macOS / Linux:**

```bash
mkdir -p ~/.config/timeweb-mcp
# вставьте токен (например, из буфера обмена):
cat > ~/.config/timeweb-mcp/token   # вставить, затем Ctrl+D
chmod 600 ~/.config/timeweb-mcp/token
```

**Windows (PowerShell):**

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\timeweb-mcp"
Set-Content "$env:USERPROFILE\.config\timeweb-mcp\token" "<ваш токен>"
```

Для отладки можно переопределить файл переменной окружения `TIMEWEB_CLOUD_TOKEN`.

### 1b. SSH-доступ к серверам

Инструменты `server_diagnostics` / `service_control` / `ssh_exec` ходят на серверы по SSH. **Настраивать ничего не нужно:**

- **Адрес не обязателен.** Достаточно назвать сервер по имени (`nanospace-node-de`) или id — IP подтянется через API по вашему токену. IP/домен тоже можно передать напрямую.
- **Ключ искать не нужно.** Коннектор находит все приватные ключи в `~/.ssh` (по парным `*.pub`) и передаёт их `ssh` — он сам подберёт подходящий (плюс работает ssh-agent). Можно указать конкретный ключ параметром `key` или через `TIMEWEB_SSH_KEY`, но обычно не требуется.

> Важно: SSH-ключ — единственный способ попасть в шелл. API-токен Timeweb шелл-доступа **не даёт** (у API нет метода «выполнить команду»), это ограничение самого SSH, а не коннектора.

**Защита — на уровне поведения ассистента:** `server_diagnostics` только читает; `ssh_exec` и мутирующие действия `service_control` требуют `confirm: true`, который ассистент подставляет лишь после вашего явного согласия в чате. Команды из веб-страниц/файлов/вывода других инструментов не выполняются.

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

**Claude Code:**

```bash
claude mcp add timeweb -- node /абсолютный/путь/к/timeweb-mcp/dist/index.js
```

**Claude Desktop / Cowork:** Настройки → Connectors → Add custom connector, команда:

```
node /абсолютный/путь/к/timeweb-mcp/dist/index.js
```

**Любой другой MCP-клиент** (конфиг в формате `mcpServers`):

```json
{
  "mcpServers": {
    "timeweb": {
      "command": "node",
      "args": ["/абсолютный/путь/к/timeweb-mcp/dist/index.js"]
    }
  }
}
```

### 3. Проверка

```bash
npm run inspect
```

Откроется MCP Inspector — вызовите `list_servers` или `account_finances` и убедитесь, что API отвечает. Либо просто спросите ассистента: «какой баланс на таймвебе?»

## Примеры использования

- «Покажи все мои серверы и их статус»
- «Сколько денег осталось на балансе и на сколько хватит?»
- «Добавь A-запись `app.example.com` → `1.2.3.4`»
- «Перезагрузи сервер N» — ассистент переспросит, инструмент потребует `confirm: true`
- «Какие тарифы есть под небольшой Node-сервис? Покажи пресеты до 500 ₽/мес»

## Разработка

```bash
npm run watch    # tsc --watch
npm run inspect  # MCP Inspector
npm run bundle   # esbuild → mcp/server.cjs (самодостаточный бандл для плагина)
npm run plugin   # полный дистрибутив: версия → бандл → build/timeweb-mcp-v<версия>.plugin
```

Структура: `src/index.ts` — сервер и инструменты, `src/client.ts` — тонкий HTTP-клиент API, `.claude-plugin/` — манифесты плагина и маркетплейса, `mcp/server.cjs` — коммитится в репо (нужен для установки плагина из git).

Версионирование: единственный источник версии — `package.json`; `npm run plugin` синхронизирует её в `plugin.json` и имя `.plugin`-файла. Релиз: поднять версию (`npm version patch|minor`), `npm run plugin`, закоммитить и запушить с тегом.

## Ограничения и планы

- [ ] `account_finances` — эндпоинт из Python SDK, проверяется на живом аккаунте (если 404 — используйте `account_status`).
- [ ] Формат тела `create_server` может потребовать уточнения под конкретный пресет (av_zone, bandwidth).
- [ ] Регистрация доменов через API (`domains-requests`).
- [ ] Статистика нагрузки сервера (`/statistics`).

PR и issues приветствуются.

## Лицензия

[MIT](LICENSE)