Работа с MCP-сервером YTsaurus

MCP-сервер YTsaurus — это посредник между AI-ассистентом и кластерами YTsaurus. Он предоставляет нейросети набор инструментов для чтения данных и метаданных. Ассистент обращается к кластеру напрямую и работает с его актуальным состоянием, а не генерирует ответы по памяти.

Принцип работы

Вы ставите задачу на естественном языке, а ассистент сам выбирает и комбинирует нужные инструменты. Например, чтобы разобраться, почему не удаётся записать данные в таблицу, ассистент последовательно проверит существование пути, права пользователя и квоту аккаунта, а затем объяснит причину.

С помощью MCP-сервера нейросеть может:

• читать данные и метаданные — схему таблицы, примеры строк, содержимое директории;
• проверять права доступа — какие права есть у пользователя на объект;
• отслеживать квоты и ресурсы — свободное место на HDD и SSD, лимиты и текущую загрузку пулов;
• искать объекты — таблицы, файлы и другие узлы по имени и атрибутам.

Формат ответа можно уточнить прямо в промпте.

Установка

Установка и настройка сервера описана в разделе Установка MCP-сервера.

Примеры промптов

Анализ данных и структуры таблиц

• Посмотри структуру таблицы //home/team/users на кластере my_cluster и напиши Python-скрипт, который читает из неё колонку user_id.
• Выведи пример данных из таблицы //home/team/logs/today.
• В папке //home/team/data лежат таблицы. Определи их схему.

Управление правами и поиск объектов

• Почему мой скрипт падает с ошибкой доступа при записи в //home/team/output? Проверь права пользователя ivanov.
• Найди все таблицы с префиксом backup_ в директории //home/team и скажи, кто их владелец.

Работа с квотами и ресурсами

• Сколько места на SSD осталось у аккаунта my_account?
• Посмотри лимиты пула compute_pool на кластере my_cluster — может, упёрлись в квоту по CPU?

Справочник инструментов

В этом разделе описаны все инструменты, которые доступны AI-ассистенту. Вы можете ссылаться на их названия в своих промптах. Ниже — сводка по группам. Нажмите на имя инструмента, чтобы перейти к его описанию.

Навигация и поиск объектов

Таблицы: данные и схемы

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

Квоты и ресурсы

Инфраструктура

list_dir

Возвращает содержимое узла или каталога в кластере YTsaurus.

Результат содержит метаданные каждого узла: тип file, table или map_node, аккаунт, время создания, количество строк.

Параметры:

Пример запроса:

{
  "directory": "//home/team",
  "cluster": "my_cluster"
}

find

Ищет объекты в поддереве кластера.

Параметры:

Пример запроса:

{
  "root_path": "//home/team",
  "cluster": "my_cluster",
  "name": "log_*",
  "type": ["table"],
  "attributes": ["owner"],
  "attributes_to_match": {
    "owner": "ivanov"
  }
}

check_is_paths_exist

Проверяет наличие путей в кластере YTsaurus.

Список может содержать от 1 до 500 путей. Каждый путь должен начинаться с // и не заканчиваться /.

Параметры:

Пример запроса:

{
  "paths": ["//home/team/data", "//tmp/temp_table"],
  "cluster": "my_cluster"
}

common_client_read_table

Читает строки таблицы.

Параметры:

Пример запроса:

{
  "table": "//home/team/users",
  "method": "read_table",
  "cluster": "my_cluster"
}

common_client_sample_static_table

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

Параметры:

Пример запроса:

{
  "table": "//home/team/users[#0:#1]",
  "method": "read_table",
  "cluster": "my_cluster"
}

common_client_get_table_schema

Возвращает схему таблицы. Схема хранится в поле value, поле attributes содержит флаги strict и unique_keys.

Параметры:

Пример запроса:

{
  "table_path": "//home/team/users",
  "method": "get_table_schema",
  "cluster": "my_cluster"
}

common_client_infer_table_schema

Определяет схему таблицы по её содержимому. Используйте этот метод, если common_client_get_table_schema вернул пустую схему.

Параметры:

Пример запроса:

{
  "table": "//home/team/users",
  "method": "infer_table_schema",
  "cluster": "my_cluster"
}

check_permission

Проверяет право пользователя на доступ к указанному пути. Ответ содержит поле action с результатом проверки: allow — доступ разрешён, deny — доступ запрещён.

Параметры:

Пример запроса:

{
  "path": "//home/team",
  "cluster": "my_cluster",
  "permission": "read",
  "user_login": "user_login"
}

Пример результата:

{
  "action": "allow"
}

common_client_whoami

Возвращает информацию о текущем пользователе на кластере.

Параметры:

Пример запроса:

{
  "method": "get_current_user",
  "cluster": "my_cluster"
}

get_attributes_account

Возвращает атрибуты учётной записи на кластере.

Параметры:

Пример запроса:

{
  "account": "my_account",
  "cluster": "my_cluster",
  "attributes": ["resource_usage", "effective_acl"]
}

get_attributes_account_limits_disk

Возвращает дисковую квоту аккаунта и объём занятого места на HDD и SSD.

Значения возвращаются в байтах:

• resource_limits.disk_space_per_medium.default — квота аккаунта на HDD;
• resource_limits.disk_space_per_medium.ssd_blobs — квота аккаунта на SSD;
• resource_usage.disk_space_per_medium.default — занятое место на HDD;
• resource_usage.disk_space_per_medium.ssd_blobs — занятое место на SSD.

Другие ресурсы, такие как количество узлов, таблетов и статическая память, не учитываются.

Параметры:

Пример запроса:

{
  "account": "my_account",
  "cluster": "my_cluster",
  "attributes": ["resource_usage", "resource_limits"]
}

get_attributes_bundle

Возвращает значения атрибутов бандла на кластере: ограничения ресурсов с детализацией по количеству таблетов и статической памяти, а также квоты по CPU и памяти.

Параметры:

Пример запроса:

{
  "bundle": "my_bundle",
  "cluster": "my_cluster",
  "attributes": ["resource_limits", "resource_quota"]
}

get_attributes_pool

Возвращает атрибуты пула на кластере.

Параметры:

Пример запроса:

{
  "pool": "pool_name",
  "pool_tree": "pool_tree",
  "cluster": "my_cluster",
  "attributes": ["max_operation_count", "effective_acl"]
}

get_account_property

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

Параметры:

Пример запроса:

{
  "account": "my_account",
  "cluster": "my_cluster",
  "property": "childrens"
}

get_proxy

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

Параметры:

Пример запроса:

{
  "cluster": "my_cluster",
  "attributes": ["role", "version"],
  "proxy_type": "http"
}