Подключение через MCP (Model Context Protocol)

Платформа Unishift содержит встроенный сервер Model Context Protocol (MCP) в составе API Gateway. Сервер позволяет подключить внешние AI-ассистенты и среды разработки (Cursor, Claude Desktop, Claude Code, Windsurf, VS Code) напрямую к микросервисам платформы.

Подключение выполняется с использованием персонального токена доступа (Personal Access Token). Все запросы выполняются строго в контексте прав пользователя (доступные пространства, документы, задачи, команды) с фиксацией действий в журнале аудита.

1. Получение пользовательского токена

Для безопасного подключения MCP-клиента используется персональный Bearer-токен.

Через веб-интерфейс Unishift

Откройте веб-клиент платформы Unishift.
В правом верхнем углу нажмите на аватар профиля и перейдите в «Настройки пользователя».
В боковом меню выберите раздел «API-ключи» (Токены доступа).
Нажмите кнопку «Создать токен».
Заполните параметры:
- Название: понятное имя клиента (например, Cursor IDE, Claude Desktop Workstation).
- Примечание (опционально): цель использования или хост.
- Срок действия (TTL): выберите интервал (7 дней, 30 дней, 90 дней, 1 год).
Нажмите «Создать» и скопируйте сгенерированный токен.

Токен показывается один раз

Сохраните скопированное значение сразу. В целях безопасности полный ключ в открытом виде повторно не отображается.

Через API

Токен также можно выпустить программно:

bash

curl -X POST http://localhost:8090/api/v1/auth/tokens \
  -H "Authorization: Bearer <СЕССИОННЫЙ_ИЛИ_АДМИН_ТОКЕН>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cursor IDE Token",
    "note": "MCP integration",
    "ttl_seconds": 2592000
  }'

Ответ вернет созданный JWT в поле data.token.

2. Эндпоинты и транспорты MCP

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

Транспорт	URL / Эндпоинт	Назначение
Streamable HTTP (рекомендуемый)	`http://localhost:8090/mcp`	Cursor IDE, современные MCP-клиенты с поддержкой HTTP
Server-Sent Events (SSE)	`http://localhost:8090/mcp/sse`	Клиенты с поддержкой SSE (сообщения: `POST /mcp/messages`)
Stdio (CLI)	`gateway mcp`	Локальный CLI-транспорт через стандартные потоки ввода/вывода

Порты в Docker

При работе стека через Docker Compose замените порт 8090 на 18090 (или внешний порт вашего инсталляционного домена: https://unishift.your-domain.com/mcp).

3. Настройка клиентов

Cursor IDE

Добавьте конфигурацию в .cursor/mcp.json в корне проекта или в глобальный файл настроек Cursor:

json

{
  "mcpServers": {
    "unishift": {
      "url": "http://localhost:8090/mcp",
      "headers": {
        "Authorization": "Bearer <ВАШ_ПОЛЬЗОВАТЕЛЬСКИЙ_ТОКЕН>"
      }
    }
  }
}

Для использования SSE-транспорта укажите эндпоинт /mcp/sse:

json

{
  "mcpServers": {
    "unishift-sse": {
      "url": "http://localhost:8090/mcp/sse",
      "headers": {
        "Authorization": "Bearer <ВАШ_ПОЛЬЗОВАТЕЛЬСКИЙ_ТОКЕН>"
      }
    }
  }
}

Claude Desktop

В файле конфигурации claude_desktop_config.json:

json

{
  "mcpServers": {
    "unishift": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8090/mcp",
        "--header",
        "Authorization: Bearer <ВАШ_ПОЛЬЗОВАТЕЛЬСКИЙ_ТОКЕН>"
      ]
    }
  }
}

Claude Code CLI

Для подключения в терминале Claude Code:

bash

claude mcp add unishift http://localhost:8090/mcp --header "Authorization: Bearer <ВАШ_ПОЛЬЗОВАТЕЛЬСКИЙ_ТОКЕН>"

4. Доступные инструменты (Tools)

После подключения AI-агент получает доступ к набору инструментов платформы:

`rag_search`

Семантический и полнотекстовый поиск по корпоративной базе знаний RAG (документы, регламенты, заметки, технические спецификации, контекст задач) с фильтрацией по пространству или по всем доступным пространствам пользователя.

Входные параметры:
- query (string, обязательно): поисковый запрос или вопрос (поддерживаются ключи задач, например PA-123).
- space_id (string, опционально): идентификатор пространства (UUID, space-<uuid> или человекочитаемое имя, например «Разработка» или «Core Team»). Если не указан — поиск выполняется по всем пространствам, к которым у пользователя есть доступ.
- scopes (array of strings, опционально): точный перечень RAG-скоупов (например ["space-c1f7b889-..."]). При передаче переопределяет space_id.
- limit (integer, опционально): максимальное количество фрагментов (по умолчанию 5, максимум 20).
- token (string, опционально): явная передача Bearer-токена (если клиент работает через stdio transport без HTTP Authorization заголовка).
Результат: список релевантных текстовых фрагментов с указанием названия источника (Source: «...») и метаданных.

`list_spaces`

Возвращает список всех рабочих пространств, к которым у текущего пользователя есть доступ (включая ID, имя, описание и готовый идентификатор RAG-скоупа).

Входные параметры:
- query (string, опционально): фильтрация пространств по подстроке имени или ID.
Результат: массив пространств с полями id, name, description, scope (space-<uuid>).

`list_services`

Возвращает перечень зарегистрированных микросервисов платформы, базовые URL и статусы готовности (health probes).

Входные параметры:
- check_health (boolean, опционально): опрашивать ли live health probes сервисов.
Возвращаемые сервисы: spaces, documents, task-tracker, command-manager, storage, flow-manager, scheduler, env-manager, spark-grid, ai-router, notifications и др.

`get_service_api`

Запрашивает актуальную OpenAPI / Swagger спецификацию выбранного сервиса напрямую из работающего инстанса.

Входные параметры:
- service_name (string, обязательно): имя сервиса (например, task-tracker, documents, spaces).
- filter (string, опционально): фильтрация путей по подстроке (например, tasks, export, search).
Результат: список доступных маршрутов, схема параметров и тел запросов/ответов. Позволяет модели динамически адаптироваться к текущей версии API без хардкода контрактов.

`call_service_api`

Выполняет реальный HTTP-запрос (GET, POST, PUT, DELETE, PATCH) к любому сервису платформы через Gateway.

Входные параметры:
- service_name (string, обязательно): целевой микросервис.
- method (string, обязательно): GET, POST, PUT, DELETE, PATCH.
- path (string, обязательно): путь метода, начиная с / (например, /api/v1/spaces).
- query_params (object, опционально): query-параметры URL.
- headers (object, опционально): дополнительные заголовки (например, X-Space-ID).
- body (any, опционально): JSON-тело запроса.

5. Практические кейсы применения

Подключение Unishift через MCP превращает агент внутри IDE в полноценного участника рабочих процессов команды.

Кейс 1: Работа с задачами трекера прямо в кодовой базе

Разработчик работает над фичей в IDE и формулирует запрос:

«Посмотри описание задачи TASK-428 в Unishift, реализуй требуемые валидации в контроллере и переведи задачу в статус Review с комментарием со ссылкой на измененные файлы».

Что делает AI-агент:

Вызывает call_service_api (GET /api/v1/tasks/... в task-tracker) и получает полное описание задачи, критерии приемки (Acceptance Criteria) и обсуждение в комментариях.
Изучает кодовую базу, пишет нужный код и тесты.
Вызывает call_service_api (PATCH /api/v1/tasks/:id), меняя статус на In Review, и добавляет комментарий с перечнем затронутых файлов и инструкцией по проверке.

Кейс 2: Поиск регламентов и синхронизация документации (RAG & Documents)

«Найди в базе знаний пространства Backend правила версионирования API и создай новую страницу с описанием нашего сервиса платежей».

Что делает AI-агент:

Вызывает rag_search с параметрами {"query": "правила версионирования API", "space_id": "Backend"} и получает точные выдержки из архитектурных регламентов (ADR) и стандартов компании с цитированием источников.
Проектирует документацию в соответствии с найденными стандартами.
Сохраняет готовую статью напрямую в соответствующий раздел базы знаний через call_service_api (POST /api/v1/documents).

Кейс 3: Запуск и проверка команд на изолированных раннерах (Command Manager)

«Запусти тестовый прогон миграций для сервиса биллинга на dev-раннере и покажи вывод».

Что делает AI-агент:

Запрашивает через call_service_api список доступных зарегистрированных команд в command-manager.
Инициирует выполнение команды через раннер (POST /api/v1/executions).
Читает логи выполнения и предоставляет краткую сводку об успешности миграции без необходимости открывать терминал или настраивать SSH-доступ.

Кейс 4: Триггер сквозных пайплайнов автоматизации (Flow Manager)

«Запусти пайплайн сборки тестового стенда после последних коммитов».

Что делает AI-агент:

Находит нужный граф в flow-manager.
Запускает исполнение процесса с входными параметрами ветки.
Отслеживает завершение нод графа и сообщает результат.

Кейс 5: Безопасный аудит переменных окружения (Env Manager)

«Проверь, заданы ли в пространстве backend-services ключи для S3 и NATS».

Что делает AI-агент:

Запрашивает реестр ключей в env-manager для рабочего пространства проекта.
Проверяет наличие обязательных переменных без компрометации самих секретных значений.

Кейс 6: Сквозной сценарий подготовки релиза

«Собери список всех готовых задач из трекера для релиза 2.4.0, составь Release Notes, сохрани их в документацию и отправь уведомление в командный чат».

Что делает AI-агент:

Запрашивает задачи со статусом Ready for Release в task-tracker.
Формирует структурированный список изменений (Features, Fixes, Breaking Changes).
Создает страницу в documents в разделе Releases / 2.4.0.
Отправляет уведомление со ссылкой через сервис notifications.

6. Безопасность и аудит

Принцип наименьших привилегий: токен ограничен ролью пользователя (admin / user) и доступными ему пространствами.
Аудит действий: каждый вызов через call_service_api оставляет в системных логах и NATS событие с идентификатором пользователя (X-User-ID), IP-адресом и затронутым ресурсом.
Быстрый отзыв: при подозрении на компрометацию токен можно мгновенно отозвать в веб-интерфейсе в разделе «API-ключи» без сброса основного пароля.

Подключение через MCP (Model Context Protocol) ​

1. Получение пользовательского токена ​

Через веб-интерфейс Unishift ​

Через API ​

2. Эндпоинты и транспорты MCP ​

3. Настройка клиентов ​

Cursor IDE ​

Claude Desktop ​

Claude Code CLI ​

4. Доступные инструменты (Tools) ​

rag_search ​

list_spaces ​

list_services ​

get_service_api ​

call_service_api ​

5. Практические кейсы применения ​

Кейс 1: Работа с задачами трекера прямо в кодовой базе ​

Кейс 2: Поиск регламентов и синхронизация документации (RAG & Documents) ​

Кейс 3: Запуск и проверка команд на изолированных раннерах (Command Manager) ​

Кейс 4: Триггер сквозных пайплайнов автоматизации (Flow Manager) ​

Кейс 5: Безопасный аудит переменных окружения (Env Manager) ​

Кейс 6: Сквозной сценарий подготовки релиза ​

6. Безопасность и аудит ​

Подключение через MCP (Model Context Protocol)

1. Получение пользовательского токена

Через веб-интерфейс Unishift

Через API

2. Эндпоинты и транспорты MCP

3. Настройка клиентов

Cursor IDE

Claude Desktop

Claude Code CLI

4. Доступные инструменты (Tools)

`rag_search`

`list_spaces`

`list_services`

`get_service_api`

`call_service_api`

5. Практические кейсы применения

Кейс 1: Работа с задачами трекера прямо в кодовой базе

Кейс 2: Поиск регламентов и синхронизация документации (RAG & Documents)

Кейс 3: Запуск и проверка команд на изолированных раннерах (Command Manager)

Кейс 4: Триггер сквозных пайплайнов автоматизации (Flow Manager)

Кейс 5: Безопасный аудит переменных окружения (Env Manager)

Кейс 6: Сквозной сценарий подготовки релиза

6. Безопасность и аудит