🤖 Руководство по использованию MCP-интеграции

Подключите AI-ассистентов напрямую к панели C³ CELERITY для автоматизированного управления.

📖 Что такое MCP?

Model Context Protocol (MCP) — это протокол, который позволяет AI-ассистентам (Claude, Cursor и др.) напрямую взаимодействовать с панелью C³ CELERITY.

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

Через MCP AI может:

📋 Требования

🔐 Создание API-ключа

Пошаговая инструкция

1. 🖱 Откройте панель → Settings → API Keys

2. ➕ Нажмите Создать MCP API-ключ

3. ✏️ Укажите название ключа (например, "Claude Assistant")

4. 🎛 Выберите права:

   Тип	Scopes	Применение
   🟢 Базовые	mcp:enabled + права на чтение	Только чтение (по умолчанию)
   🟡 Расширенные	users:write, nodes:write, sync:write	Операции записи

5. 📋 Скопируйте ключ — показывается только один раз!

⚠️ Важно: Храните API-ключ в безопасном месте. Вы не сможете увидеть его снова.

🔌 Подключение AI-клиентов

🖥 Claude Desktop

Добавьте в файл конфигурации Claude Desktop:

{
  "mcpServers": {
    "celerity": {
      "url": "https://your-panel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

📝 Cursor IDE

Создайте файл .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "celerity": {
      "url": "https://your-panel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

🔧 Кастомный клиент

Любой HTTP-клиент с поддержкой SSE может подключиться:

curl -X POST https://your-panel.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'

🛠 Доступные инструменты

🔍 query — Чтение данных

Универсальный инструмент для получения данных из панели.

Параметры:

{
  "name": "query",
  "arguments": {
    "resource": "users",
    "filter": { "enabled": true },
    "limit": 50
  }
}

👤 manage_user — Управление пользователями

Требуется scope: users:write

Доступные действия: create | update | delete | enable | disable | reset_traffic

{
  "name": "manage_user",
  "arguments": {
    "action": "create",
    "userId": "user123",
    "data": {
      "username": "Иван Иванов",
      "trafficLimit": 107374182400,
      "maxDevices": 3,
      "groups": ["groupId1"]
    }
  }
}

🖥 manage_node — Управление серверами

Требуется scope: nodes:write

Доступные действия: create | update | delete | sync | setup | reset_status | update_config

{
  "name": "manage_node",
  "arguments": {
    "action": "setup",
    "id": "nodeId123",
    "setupOptions": {
      "installHysteria": true,
      "setupPortHopping": true,
      "restartService": true
    }
  }
}

📁 manage_group — Управление группами

Требуется scope: nodes:write

Доступные действия: create | update | delete

🔗 manage_cascade — Каскадные туннели

Требуется scope: nodes:write

Доступные действия: create | update | delete | deploy | undeploy | reconnect

💻 execute_ssh — Выполнение команд

Требуется scope: nodes:write

Выполняет shell-команду на сервере и возвращает вывод.

{
  "name": "execute_ssh",
  "arguments": {
    "nodeId": "nodeId123",
    "command": "systemctl status hysteria-server"
  }
}

🖥 ssh_session — Интерактивная SSH-сессия

Требуется scope: nodes:write

Доступные действия: start | input | close

⚙️ system_action — Системные операции

Требуется scope: sync:write

Доступные действия: sync_all | clear_cache | backup | kick_user

🗺 get_topology — Топология сети

Требуется scope: nodes:read

Возвращает все активные ноды и связи между ними.

❤️ health_check — Проверка состояния

✅ Scope не требуется

Возвращает uptime, статус синхронизации, статистику кэша, использование памяти.

📝 Готовые промпты

Промпты — это предустановленные сценарии, которые появляются как slash-команды в Claude Desktop (например, /panel_overview).

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

📊 "Покажи состояние всех серверов"

AI выполнит:

👤 "Создай пользователя testuser с лимитом 50 ГБ"

AI выполнит:

manage_user → action=create, userId=testuser, trafficLimit=53687091200

🔧 "Почему нода DE-01 не работает?"

AI выполнит:

🖥 "Настрой новый сервер 192.168.1.100"

AI использует промпт setup_new_node:

🔑 Права доступа (Scopes)

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

📚 Источники