🎯 Обзор

Полная реализация сервера MCP (Model Context Protocol) для Microsoft Fabric Real-Time Intelligence (RTI).

Этот сервер позволяет AI-агентам взаимодействовать с сервисами Fabric RTI через интерфейс MCP, предоставляя инструменты для запросов данных, анализа и потоковой обработки.

Примечание

Этот проект находится в Public Preview и реализация может существенно измениться до General Availability (GA).

🔍 Как это работает

Сервер Fabric RTI MCP выступает в роли мостa между AI-агентами и сервисами Microsoft Fabric RTI:

🔄 MCP Protocol: Использует Model Context Protocol для представления возможностей Fabric RTI в виде инструментов
🏗️ Natural Language to KQL: AI-агенты могут преобразовывать запросы на естественном языке в KQL-запросы и управление Eventstreams
💡 Secure Authentication: Использует Azure Identity для бесшовного и безопасного доступа к ресурсам
⚡ Real-time Data Access: Прямое подключение к Eventhouse и Eventstreams для анализа данных в режиме реального времени
📊 Unified Interface: Единый интерфейс для аналитических и стриминговых нагрузок с интеллектуальными подсказками по параметрам

✨ Поддерживаемые сервисы

Eventhouse (Kusto): Выполняйте KQL-запросы к Microsoft Fabric RTI через Eventhouse и Azure Data Explorer (ADX).

Eventstreams: Управляйте Microsoft Fabric Eventstreams для обработки данных в реальном времени:

Список Eventstreams в рабочих пространствах
Получить детали и определения Eventstream
Создать новые Eventstreams
Обновлять существующие Eventstreams
Удалять Eventstreams

Activator: Создавайте и управляйте триггерами Microsoft Fabric Activator для оповещений в реальном времени:

Создавать новые триггеры с мониторингом источника KQL
Настраивать уведомления по электронной почте и Teams при наступлении условия
Список артефактов Activator в рабочих пространствах

Map: Создавайте и управляйте Microsoft Fabric Map для визуализации геопространственных данных:

Создать новую карту из предоставленной конфигурации
Визуализировать данные на картах
Список элементов Map в рабочих пространствах
Удаление элементов Map

🧠 Навыки Copilot

В этом репозитории есть KQL Copilot Skill (.github/skills/kql//) — он дает AI-агентам глубокие знания KQL при написании, отладке или ревью запросов Kusto. Навык охватывает:

Подводные камни синтаксиса и схемы самокоррекции для распространённых ошибок KQL
Динамическая дисциплина типов, шаблоны соединений, ловушки с datetime
Безопасные для памяти шаблоны запросов и дисциплина по размеру результатов
Расширенные функции: графовые запросы, сравнение векторов, геопространственные операции, временные ряды
Шаблоны запросов для дедупликации, топ-N, сессии, поворот и многое другое
Полную карту ошибок к исправлениям для быстрого восстановления

Навык ссылается на инструменты Fabric RTI MCP (kusto_query, kusto_command, kusto_sample_entity и др.), чтобы агенты знали, как выполнять запросы через этот MCP-сервер.

🚧 Скоро

Другие RTI-элементы

🔍 Примеры подсказок

Eventhouse Analytics:

"Получить базы данных в моём Eventhouse"
"Вывести 10 строк из таблицы 'StormEvents' в Eventhouse"
"Что можно рассказать о данных StormEvents?"
"Проанализировать StormEvents и найти тренды за прошлые 10 лет"
"Проанализировать команды в таблице 'CommandExecution' и классифицировать их по рискам — низкий/средний/высокий"
"Перед выполнением этого запроса проверь план исполнения и скажи, дорогой ли он"
"Сравнить два подхода к запросу и сказать, который эффективнее"
"Проверить состояние кластера — достаточно ли мощности для большой аналитической задачи?"

Eventstream Management:

"Перечислить все Eventstreams в моём рабочем пространстве"
"Покажи детали моего IoT-Eventstream"
"Создать новый Eventstream для обработки данных датчиков"
"Обновить существующий Eventstream, добавив новую цель"

Activator Alerts:

"Используя таблицу StormEvents, оповестить по email при наводнении в Иллинойсе"
"Создать тревожное оповещение в Teams, если уровень успеха падает ниже 95%"
"Перечислить все артефакты Activator в моём рабочем пространстве"

Map Visualization:

"Перечислить все элементы Map в моём рабочем пространстве"
"Создать новую Map и добавить LakeHouse как источник данных к элементу Map 'MyMap'"
"Удалить элемент Map с именем 'MyMap' из моего рабочего пространства"

Available tools

Eventhouse (Kusto) - 13 Tools + 1 Optional:

kusto_known_services - Перечислить все доступные Kusto-сервисы, сконфигурированные в MCP
kusto_query - Выполнить KQL-запросы в указанной базе данных
kusto_command - Выполнить команды управления Kusto (.show, .create, .alter, .drop)
kusto_list_entities - Перечень сущностей (базы данных, таблицы, внешние таблицы, материализованные представления, функции, графы) в кластере или базе
kusto_describe_database - Получить схему всех сущностей в базе
kusto_describe_database_entity - Получить детальную схему конкретной сущности (таблица, внешняя таблица, материализованное представление, функция, граф)
kusto_graph_query - Выполнить графовые запросы с использованием снимков или временных графов
kusto_sample_entity - Получить образцы записей из таблицы, внешней таблицы, материализованного представления или функции
kusto_ingest_inline_into_table - Внедрить данные в формате CSV в указанную таблицу
kusto_get_shots (когда настроена KUSTO_SHOTS_TABLE) - Найти семантически похожие сохранённые KQL-запросы с локальными векторными представлениями (SLM) или Azure OpenAI embeddings
kusto_deeplink_from_query - Сгенерировать deeplink URL для открытия KQL-запроса в Azure Data Explorer Web Explorer или Microsoft Fabric query workbench
kusto_show_queryplan - Получить план выполнения KQL-запроса без его выполнения. Возвращает плановые статистики (PlanSize, RelopSize), дерево логических операторов и подсказки по исполнению (оценочные количества строк, параллельность/распределение, информация по скану по каждому shard с обнаружением фильтра). Полезно для сравнения подходов к запросам, выявления дорогих соединений и проверки синтаксиса перед исполнением.
kusto_diagnostics - Запуск набора диагностических команд кластера и объединённое резюме. Разделы: пропускная способность (ресурсные слоты), кластер (узлы/аппаратное обеспечение), основные роли (разрешения вызывающего лица), внутренние диагностики (здоровье/использование), группы рабочих нагрузок, rowstores, и ошибки ingest (последние 24 часа). Каждый раздел выполняется независимо — проблемы с разрешениями в одном разделе не блокируют другие.

Eventstreams - 17 Tools:

Core Operations (6 инструментов):

eventstream_list - Перечислить все Eventstreams в вашем Fabric workspace
eventstream_get - Получить подробную информацию о конкретном Eventstream
eventstream_get_definition - Получить полный JSON-описание Eventstream
eventstream_create - Создать новые Eventstreams с пользовательской конфигурацией (автоподключение потока по умолчанию)
eventstream_update - Изменить настройки и назначения существующих Eventstreams
eventstream_delete - Удалить Eventstreams и связанные ресурсы

Builder Tools (11 инструментов):

Сессии: eventstream_start_definition, eventstream_get_current_definition, eventstream_clear_definition
Источники: eventstream_add_sample_data_source, eventstream_add_custom_endpoint_source
Потоки: eventstream_add_derived_stream
Назначения: eventstream_add_eventhouse_destination, eventstream_add_custom_endpoint_destination
Валидация: eventstream_validate_definition, eventstream_create_from_definition, eventstream_list_available_components

💡 Подсказка: Все инструменты работают с естественным языком! Просто опишите, что хотите сделать, и AI-агент автоматически выберет подходящие инструменты.

Activator - 2 Tools:

activator_list_artifacts - Перечислить все артефакты Activator в Fabric workspace
activator_create_trigger - Создать новые триггеры Activator с мониторингом источника KQL и оповещениями по электронной почте/Teams

Map - 7 Tools:

map_list - Перечислить все элементы Map в вашем Fabric workspace
map_get - Получить подробную информацию о конкретном элементе Map
map_get_definition - Получить полное JSON-описание элемента Map
map_create - Создать новый элемент Map из предоставленной конфигурации
map_update_definition - Заменить полный JSON-описание существующего Map
map_update - Частично обновить свойства существующего Map
map_delete - Удалить элемент Map и его конфигурацию

Getting Started

Требования

Установите либо стабильную версию, либо версию для инсайдеров VS Code:

💫 Stable release

🔮 Insiders release
Установите расширения GitHub Copilot и GitHub Copilot Chat
Установите uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

или см. здесь другие варианты установки: other install options

Откройте VS Code в пустой папке

Установка из PyPI (Pip)

Сервер Fabric RTI MCP доступен на PyPI, поэтому его можно установить через pip. Это самый простой способ установки сервера.

Из VS Code

1. Откройте палитру команд (Ctrl+Shift+P) и выполните команду `MCP: Add Server`
2. Выберите установку из Pip
3. При запросе введите имя пакета `microsoft-fabric-rti-mcp`
4. Следуйте инструкциям, чтобы установить пакет и добавить его в ваш settings.json или ваш mcp.json

Процесс должен завершиться настройками ниже в вашем файле settings.json или mcp.json.

settings.json

{
    "mcp": {
        "servers": {
            "fabric-rti-mcp": {
                "command": "uvx",
                "args": [
                    "microsoft-fabric-rti-mcp"
                ],
                "env": {
                    "KUSTO_SERVICE_URI": "https://help.kusto.windows.net/",
                    "KUSTO_SERVICE_DEFAULT_DB": "Samples",
                    "FABRIC_API_BASE": "https://api.fabric.microsoft.com/v1"
                }
            }
        }
    }
}

Примечание: Все переменные окружения являются необязательными. KUSTO_SERVICE_URI и KUSTO_SERVICE_DEFAULT_DB задают настройки кластера и базы по умолчанию. AZ_OPENAI_EMBEDDING_ENDPOINT настраивает метод вставки по умолчанию AOAI, используемый kusto_get_shots.

From GitHub Copilot CLI

Используйте интерактивную команду внутри сессии GitHub Copilot CLI:

/mcp add

Или вручную добавьте в ваш файл ~/.copilot/mcp-config.json:

{
    "mcpServers": {
        "fabric-rti-mcp": {
            "command": "uvx",
            "args": [
                "microsoft-fabric-rti-mcp"
            ],
            "env": {
                "KUSTO_SERVICE_URI": "https://help.kusto.windows.net/",
                "KUSTO_SERVICE_DEFAULT_DB": "Samples",
                "FABRIC_API_BASE": "https://api.fabric.microsoft.com/v1"
            }
        }
    }
}

Для дополнительной информации см. документацию GitHub Copilot CLI: GitHub Copilot CLI documentation.

🔧 Ручная установка (установка из исходников)

Убедитесь, что установлен Python 3.10+ и добавлен в PATH.
Клонируйте репозиторий
Установите зависимости (pip install . или uv tool install .)
Добавьте ниже приведённые настройки в ваш vscode settings.json или ваш mcp.json файл.
Измените путь, чтобы он соответствовал расположению репозитория на вашем устройстве.
Измените URI кластера в настройках на соответствующий вашему кластеру.
Измените базу данных по умолчанию кластера в настройках на соответствующую вам базу данных.
Измените точку вставки embeddings в настройках на вашу. Этот шаг необязателен и нужен только если вы предоставляете таблицу shots

{
    "mcp": {
        "servers": {
            "fabric-rti-mcp": {
                "command": "uv",
                "args": [
                    "--directory",
                    "C:/path/to/fabric-rti-mcp/",
                    "run",
                    "-m",
                    "fabric_rti_mcp.server"
                ],
                "env": {
                    "KUSTO_SERVICE_URI": "https://help.kusto.windows.net/",
                    "KUSTO_SERVICE_DEFAULT_DB": "Samples",
                    "FABRIC_API_BASE": "https://api.fabric.microsoft.com/v1"
                }
            }
        }
    }
}

🐛 Отладка MCP Server локально

Если у вас установлен Python и репозиторий склонирован:

Установить локально

pip install -e ".[dev]"

Настроить

Следуйте инструкциям из раздела ручная установка.

Подключить отладчик

Запустите MCP-сервер обычным образом из клиента, который будет вызывать его инструменты, затем поставьте точку останова на исполняемой строке. Если вы изменили исходники Python после запуска сервера, перезапустите MCP-сервер перед присоединением.

Вариант 1: Подключиться по Process ID

Нажмите F5 и выберите «Python Debugger: Attach by Process ID». VS Code нужно получить PID процесса Python, который запускает

-m fabric_rti_mcp.server

Вы можете определить его одним из способов:

VS Code process picker: выберите соответствующий процесс Python из списка. Если отображаются несколько связанных процессов, выберите самый глубокий дочерний Python-процесс, запускающий -m fabric_rti_mcp.server, а не обёртку uv.
Manual PID lookup: если VS Code просит ввести PID, а не выводит список процессов, найдите его через Task Manager или PowerShell:
- В Task Manager откройте Details, включите столбцы PID и Command line и найдите соответствующий процесс python.exe.
- В PowerShell выполните:

$servers = @(Get-CimInstance Win32_Process | Where-Object {
    $_.Name -eq "python.exe" -and
    $_.CommandLine -match "-m\s+fabric_rti_mcp\.server"
})

$servers |
    Where-Object { $_.ProcessId -notin $servers.ParentProcessId } |
    Sort-Object CreationDate -Descending |
    Select-Object -First 1 ProcessId, CommandLine

Введи возвращённый ProcessId в запрос VS Code.

В более новых версиях Windows wmic.exe может быть отключен или удалён. Некоторые версии отладчика Python всё ещё используют его для заполнения списка процессов, что может привести к сбоям. Ручные методы выше не требуют WMIC.

Вариант 2: Внедрить debugpy и подключиться через порт 5678

В этом репозитории есть конфигурация запуска Python Debugger: Attach to Fabric RTI MCP и задача предварительной сборки Inject debugger into Fabric RTI MCP. Этот Windows-специфичный вариант использует PowerShell для поиска самого глубокого процесса Fabric RTI MCP Python, внедряет debugpy и подключает VS Code к 127.0.0.1:5678.

Убедитесь, что MCP-сервер уже запущен.
Нажмите F5 и выберите Python Debugger: Attach to Fabric RTI MCP.
Ожидайте появления панели инструментов отладки VS Code.
Вызывайте нужный инструмент из той же сессии клиента MCP, которая запустила подключённый сервер.

Не добавляйте debugpy --listen в команду MCP-сервера. У некоторых клиентов может быть более одной сессии, что приведёт к конфликтам портов. Если запущено несколько сессий клиента MCP, закройте посторонние сессии, чтобы отладчик присоединился к нужному процессу.

🧪 Тестирование MCP Server

Через GitHub Copilot

Откройте GitHub Copilot в VS Code и переключитесь в режим Agent
Вы должны увидеть Fabric RTI MCP Server в списке инструментов
Попробуйте подсказки, которые инструктируют агента использовать RTI-инструменты, например:

Eventhouse: "List my Kusto tables" или "Show me a sample from the StormEvents table"

Eventstreams: "List all Eventstreams in my workspace" или "Show me details of my data processing Eventstream"
Агент должен уметь использовать инструменты Fabric RTI MCP Server чтобы выполнить ваш запрос

⚙️ Конфигурация

Сервер MCP можно настроить с использованием следующих переменных окружения:

Обязательные переменные окружения

Нет — сервер будет работать с настройками по умолчанию для демонстрационных целей.

Необязательные переменные окружения

Переменная	Сервис	Описание	По умолчанию	Пример
KUSTO_SERVICE_URI	Kusto	URI-узла по умолчанию Kusto	Нет	https://mycluster.westus.kusto.windows.net
KUSTO_SERVICE_DEFAULT_DB	Kusto	Имя базы данных по умолчанию для запросов Kusto	NetDefaultDB	MyDatabase
AZ_OPENAI_EMBEDDING_ENDPOINT	Kusto	Точка доступа Azure OpenAI, используемая, когда `kusto_get_shots` выбирает embedding_method="aoai"	Нет	https://your-resource.openai.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2024-10-21;impersonate
KUSTO_KNOWN_SERVICES	Kusto	JSON-массив предварительно сконфигурированных сервисов Kusto	Нет	[{"service_uri":"https://cluster1.kusto.windows.net","default_database":"DB1","description":"Prod"}]
KUSTO_EAGER_CONNECT	Kusto	Приключение к базовому сервису на старте (не рекомендуется)	false	true or false
KUSTO_ALLOW_UNKNOWN_SERVICES	Kusto	Безопасностное ограничение на разрешение соединений с сервисами вне KUSTO_KNOWN_SERVICES	true	true or false
KUSTO_SHOTS_TABLE	Kusto	Включить kusto_get_shots и задать таблицу shots по умолчанию	Нет	MyDatabase.ShotsTable
KUSTO_SHOTS_EMBEDDING_METHOD	Kusto	Метод вставки по умолчанию для kusto_get_shots	aoai	slm or aoai
KUSTO_SHOTS_SLM_MODEL	Kusto	Модель SLM по умолчанию для kusto_get_shots	harrier-v1-270m	harrier-v1-270m
FABRIC_API_BASE	Global	Базовый URL для Microsoft Fabric API	https://api.fabric.microsoft.com/v1	https://api.fabric.microsoft.com/v1
FABRIC_BASE_URL	Global	Базовый URL для веб-интерфейса Microsoft Fabric	https://fabric.microsoft.com	https://fabric.microsoft.com
FABRIC_RTI_ALLOWED_TOOLS	Global	Список имён сервисов через запятую или полные названия инструментов, которые expose	All tools	kusto,map_get
FABRIC_RTI_KUSTO_DEEPLINK_STYLE	Kusto	Переопределение автоматического определения стиля deeplink	None	adx или fabric

FABRIC_RTI_ALLOWED_TOOLS принимает имена сервисов, получаемых из зарегистрированных модулей *_tools, и полные имена инструментов.

Shots Embedding Configuration

Все поддерживаемые пути AOAI и SLM возвращают нормализованные вектора L2. kusto_get_shots использует их известную величину, чтобы вычислять косинусное сходство без повторного расчета величины вектора для каждого снимка. Пользовательские или вручную созданные значения EmbeddingVector также должны быть нормализованы по L2.

SLM embeddings

kusto_get_shots по умолчанию использует Azure OpenAI embeddings ради обратной совместимости. Чтобы использовать локальные SLM-встраивания, установите embedding_method в slm для конкретного вызова, или установите KUSTO_SHOTS_EMBEDDING_METHOD=slm на MCP-сервере. Настройте модель по умолчанию на сервере через KUSTO_SHOTS_SLM_MODEL; по умолчанию harrier-v1-270m. Явные аргументы инструмента перекрывают эти значения по умолчанию сервера. База данных, которую вы запрашиваете, должна содержать заранее развернутую функцию slm_embeddings_fl. Следуйте документации функции SLM embeddings и выберите либо Azure Data Explorer, либо Microsoft Fabric в левой панели для инструкций развертывания.

Документированная реализация slm_embeddings_fl поддерживает:

Модель	Размерности вектора
jina-v2-small	512
e5-small-v2	384
harrier-v1-270m (по умолчанию)	640

Пример аргументов SLM:

{
  "prompt": "Find a few storm events in Texas",
  "cluster_uri": "https://mycluster.westus.kusto.windows.net",
  "database": "MyDatabase",
  "shots_table_name": "Shots",
  "embedding_method": "slm",
  "slm_model_name": "harrier-v1-270m"
}

Промпт SLM индексируется с префиксом query:. Значения EmbeddingVector таблицы должны использовать ту