Экспериментальный функционал

MCP-сервер — компонент Deckhouse Development Platform (DDP), который реализует протокол MCP (Model Context Protocol) и обеспечивает взаимодействие внешних AI-клиентов (таких как LM Studio, Claude Desktop и других) с платформой. Сервер работает по JSON-RPC 2.0 и предоставляет набор инструментов для работы с ресурсами платформы и проксирования запросов во внешние инфраструктурные сервисы.

MCP — это открытый протокол для взаимодействия AI-моделей с внешними системами. Подробнее о протоколе можно узнать на официальном сайте MCP.

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

get_resources

Получить список ресурсов.

Параметры: нет.

Возвращает: список ресурсов.

Пример:

Получи список ресурсов

get_external_services

Получить список внешних сервисов (GitLab, SonarQube и т. д.).

Параметры: нет.

Возвращает: список внешних сервисов.

Пример:

Получи список внешних сервисов

get_resource_entities

Получить все сущности выбранного ресурса.

Параметры:

НазваниеТипОбязательностьОписание
resource_uuidстрокаДаUUID ресурса

Возвращает: список сущностей ресурса.

Пример:

Получи все сервисы и покажи название и дату создания

get_entity

Получить одну сущность по UUID.

Параметры:

НазваниеТипОбязательностьОписание
entity_uuidстрокаДаUUID сущности

Возвращает: данные одной сущности.

Пример:

Получи сущность с UUID 3fa85f64-5717-4562-b3fc-2c963f66afa6

get_entity_relations

Получить связи сущности.

Параметры:

НазваниеТипОбязательностьОписание
resource_uuidстрокаДаUUID ресурса
entity_slugстрокаДаИдентификатор сущности

Возвращает: список связей сущности.

Пример:

Получи связи сущности «api-gateway» ресурса «Сервисы»

get_external_data

Выполнить HTTP-запрос к внешнему сервису с учётными данными пользователя.

Параметры:

НазваниеТипОбязательностьОписание
external_service_uuidстрокаДаUUID внешнего сервиса
queryстрокаДаОписание запроса (например: «получить пайплайны проекта 123»)
api_pathстрокаДаПуть к API с параметрами запроса (например, пагинация)
methodстрокаНетHTTP-метод. По умолчанию: GET
bodyстрокаНетТело запроса для POST/PUT/PATCH (JSON-строка)

Учётные данные и заголовки берутся из настроек внешнего сервиса в платформе.

Возвращает: результат HTTP-запроса к внешнему сервису.

Пример:

Получи список проектов из внешнего сервиса GitLab

get_actions

Получить список действий.

Параметры: нет.

Возвращает: список действий.

Пример:

Получи список действий

get_datasources

Получить список источников данных.

Параметры: нет.

Возвращает: список источников данных.

Пример:

Получи список источников данных

get_processes

Получить список процессов.

Параметры: нет.

Возвращает: список процессов.

Пример:

Получи список процессов

Подключение MCP-сервера

LM Studio

  1. Получение параметров:

    • Войдите в Deckhouse Development Platform.
    • Получите ваш API-токен в разделе «Профиль».
    • Запишите URL вашей платформы (например, https://ddp.example.com).

  2. Настройка в LM Studio:

    • Откройте LM Studio.
    • Перейдите в настройки (Settings).
    • Найдите раздел «MCP Servers» или «Model Context Protocol».
    • Нажмите «Add Server» или «Добавить сервер».

  3. Конфигурация сервера (заполните следующие поля):

    • «Server Name»: DDP MCP Server (или любое удобное название).
    • «Server URL»: https://<DOMAIN>/api/v2/mcp.
    • «Transport»: HTTP или JSON-RPC.
    • «Authentication»:
      • «Type»: Bearer Token или аналог (заголовок Authorization).
      • «Header»: Authorization: Bearer <ваш_api_токен>.
      • «Token»: вставьте ваш API-токен платформы (из раздела «Профиль»).

  4. Проверка подключения:

    • Сохраните конфигурацию.
    • LM Studio попытается подключиться к серверу.
    • Если подключение успешно, вы увидите список доступных инструментов:
      • get_resources — получить список ресурсов.
      • get_external_services — получить список внешних сервисов (GitLab, SonarQube и т. д.).
      • get_resource_entities — получить все сущности выбранного ресурса.
      • get_entity — получить одну сущность по UUID.
      • get_entity_relations — получить связи сущности по ресурсу и идентификатору.
      • get_external_data — выполнить HTTP-запрос к внешнему сервису с учётными данными пользователя.
      • get_actions — получить список действий.
      • get_datasources — получить список источников данных.
      • get_processes — получить список процессов.

После успешного подключения вы можете использовать инструменты в диалогах с моделями.

Все вызовы будут выполняться с вашими правами доступа.

Подключение в других MCP-клиентах

MCP-сервер Deckhouse Development Platform совместим с любыми клиентами, поддерживающими протокол MCP через JSON-RPC 2.0.

Общие шаги подключения:

  1. «URL эндпоинта»: https://your-platform.com/api/v2/mcp.
  2. «Протокол»: JSON-RPC 2.0.
  3. «Аутентификация»:
    • Заголовок: Authorization: Bearer YOUR_API_TOKEN.
    • Где YOUR_API_TOKEN — ваш API-токен платформы (раздел «Профиль»).
  4. «Метод»: POST.

Пример запроса к MCP-серверу

HTTP-заголовки:

Authorization: Bearer your-api-token-here
Content-Type: application/json

Тело запроса:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_resource_entities",
    "arguments": {
      "resource_uuid": "uuid-нужного-ресурса"
    }
  }
}

Пример ответа от MCP-сервера

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"uuid\":\"...\",\"name\":\"Service 1\",\"properties\":{...}},...]"
      }
    ]
  }
}

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

Аутентификация:

  • Все запросы к MCP-серверу должны быть аутентифицированы с помощью API-токена из раздела «Профиль». Токен передаётся в заголовке Authorization: Bearer <api_token>.
  • Права доступа соответствуют правам вашего пользователя в платформе.

Права доступа:

  • Инструменты работают с теми же правами, что и пользователь.
  • Если у вас нет доступа к ресурсу, инструмент вернёт ошибку доступа.
  • Данные фильтруются в соответствии с вашими правами RBAC.

Устранение неполадок

Не удаётся подключиться к серверу

Если не получается подключиться к серверу:

  • Проверьте правильность URL (должен заканчиваться на /api/v2/mcp).
  • Убедитесь, что API-токен действителен.
  • Проверьте, что платформа доступна с вашего компьютера.
  • Проверьте настройки файрвола и прокси.

Ошибка аутентификации

Если не проходит аутентификация:

  • Проверьте правильность формата токена.
  • Убедитесь, что токен не истёк.
  • Убедитесь, что используется заголовок Authorization: Bearer <api_token>.

Инструмент возвращает ошибку доступа

Если при обращении к инструменту возвращается ошибка доступа:

  • Убедитесь, что у вашего пользователя есть права на доступ к запрашиваемому ресурсу.
  • Проверьте правильность названия или идентификатора ресурса.
  • Обратитесь к администратору платформы для проверки прав доступа.

Данные не возвращаются

В случае отсутствия ответа:

  • Проверьте правильность параметров запроса.
  • Убедитесь, что ресурс существует и содержит сущности.
  • Проверьте логи платформы для получения детальной информации об ошибке.