MCP-сервер

MCP-сервер — это компонент Deckhouse Development Platform, который реализует протокол 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

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

Параметры:

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

Пример:

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

get_entity

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

Параметры:

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

Пример:

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

get_entity_relations

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

Параметры:

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

Пример:

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

get_external_data

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

Параметры:

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

Возвращает: результат 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://ddp.example.com/api/v2/mcp.
     • Замените ddp.example.com на адрес вашей платформы.
   • 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>.

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

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

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

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