Подключение агентов ИИ к API Fabric для GraphQL с помощью локального сервера протокола контекста модели (MCP)

Представьте себе, как вы запрашиваете у GitHub Copilot "Покажи мне все продажи за последний квартал," и он автоматически выполняет запрос к вашему хранилищу данных Fabric, понимает его структуру и возвращает результаты — всё это без написания ни одной строки GraphQL. В этом руководстве показано, как сделать это возможным.

В этом руководстве вы создадите локальный сервер GraphQL MCP, который выступает в качестве моста между агентами ИИ и данными Microsoft Fabric. К концу у вас есть рабочий сервер разработки, который позволяет помощникам ИИ, таким как GitHub Copilot, Claude и другим агентам ИИ, естественно запрашивать данные Fabric с помощью языка беседы.

Что вы будете делать:

Настройка проверки подлинности, чтобы сервер GraphQL MCP смог безопасно получить доступ к Fabric
Включение интроспекции схемы, чтобы агенты ИИ могли автоматически обнаруживать структуру данных.
Развертывание локального сервера GraphQL MCP, который преобразует естественный язык в запросы GraphQL
Подключите GitHub Copilot или другие инструменты ИИ для запроса ваших данных в разговорном формате

Что такое протокол контекста модели (MCP)?

Протокол контекста модели (MCP) — это стандарт для подключения помощников ИИ к системам, в которых находятся данные, включая репозитории содержимого, бизнес-инструменты и среды разработки. Её цель заключается в том, чтобы помочь передовым моделям генерировать более качественные и релевантные ответы. Думайте о MCP, как порт USB-C для приложений искусственного интеллекта. Так же, как USB-C предоставляет стандартный способ подключения устройств к различным периферийным устройствам и аксессуарам, MCP предоставляет стандартный способ подключения моделей ИИ к внешним источникам данных и средствам.

Основные платформы ИИ, включая OpenAI, Microsoft Copilot Studio и Microsoft Foundry, приняли MCP в качестве стандартного способа интеграции агентов ИИ с внешними системами. Это делает MCP идеальным выбором для подключения агентов ИИ к данным Microsoft Fabric.

Почему GraphQL идеально подходит для MCP

GraphQL хорошо подходит для интеграции MCP, так как:

Интроспекция схемы: агенты ИИ могут автоматически обнаруживать доступные структуры данных и связи непосредственно из схемы GraphQL.
Гибкие запросы: агенты могут запрашивать именно те данные, которые им необходимы, одним запросом.
Безопасность типов: строгая типизация помогает агентам ИИ лучше понять форматы и ограничения данных
Эффективное получение данных: уменьшает чрезмерное получение и недостаточное получение данных.

API Microsoft Fabric для GraphQL упрощает интеграцию ваших lakehouses, хранилищ данных и баз данных Fabric с агентами ИИ через стандартизованный интерфейс GraphQL. Хотя API для GraphQL уже предоставляет мощные возможности запросов, настройка подключения для агентов ИИ может быть не столь простой, как это может быть.

С помощью простого локального сервера GraphQL MCP разработчики могут использовать агенты ИИ для обнаружения структуры данных Fabric, понимания доступных сведений и запросов к нему с помощью естественного языка — все через стандартизированный интерфейс MCP. Вам не нужно определять отдельное средство MCP на сервере для каждого типа GraphQL, запроса или мутации. Сервер GraphQL MCP интроспектирует эту схему GraphQL, позволяя агентам ИИ с самого начала понимать все доступные типы и операции.

Предпосылки

Прежде чем приступить к работе с этим руководством, убедитесь, что у вас есть:

Рабочая область Microsoft Fabric с соответствующими разрешениями. Роль администратора рабочей области необходима для настройки принципалов службы и активации интроспекции.
Создан и настроен API для элемента GraphQL. См. статью "Создание и добавление данных в API GraphQL " или "Создание API GraphQL" из базы данных SQL на портале Fabric.
Node.js установлен на компьютере разработки (включает npm)
Visual Studio Code, установленный на машине разработчика

Замечание

Вы не администратор? Для некоторых действий, описанных в этом руководстве, требуются разрешения администратора. Если вы не являетесь администратором, вы по-прежнему можете завершить большую часть руководства, попросив администратора помочь с конкретными задачами. Каждый шаг, требующий разрешений администратора, четко помечен.

Шаг 1. Настройка доступа служебного принципала

Что вы делаете: Настройка учетных данных для неинтерактивной проверки подлинности, чтобы сервер GraphQL MCP смог получить доступ к Fabric без необходимости входа пользователя каждый раз.

Почему это важно: Сервер GraphQL MCP запускается в качестве фоновой службы, которую агенты ИИ вызывают автоматически. Он должен иметь собственное удостоверение (ролевое имя) с учетными данными для аутентификации в Fabric от имени вашего приложения, а не от имени конкретного пользователя.

Следуйте полному руководству по использованию субъектов-служб с API Fabric для GraphQL :

Создание регистрации приложений Azure (любой пользователь с разрешениями на создание регистраций приложений в идентификаторе Microsoft Entra)
Добавление секрета клиента в разделе "Сертификаты и секреты " (любой пользователь)
Включение субъектов-служб в параметрах клиента (требуется администратор клиента Fabric)
Предоставление разрешений API GraphQL и рабочей области (требуется роль администратора рабочей области или участника)

Подсказка

Не администратор? Вы можете выполнить первые два элемента самостоятельно. Для настройки клиента попросите администратора клиента Fabric включить параметр "Субъекты-службы могут использовать API Fabric" в разделе Администрирования>Настройки клиента>Параметры разработчика на портале администрирования. Попросите администратора рабочей области предоставить вашему сервисному принципалу доступ к рабочей области или конкретному API GraphQL.

По завершении установки зафиксировать эти три значения для конфигурации сервера GraphQL MCP:

Идентификатор клиента: найден в Microsoft Entra ID в разделе Обзор>Идентификатор клиента
Идентификатор клиента: найден в разделе "Регистрация приложений" в разделе "Обзор>приложения " (клиент)
Секрет клиента: значение секрета, отображаемое при создании нового секрета клиента (копировать сразу же)

Шаг 2. Включение интроспекции GraphQL (требуется администратор рабочей области)

Что вы делаете: Включение интроспекции позволяет серверу GraphQL MCP попросить API GraphQL "Какие данные у вас есть?" и получить полное описание всех доступных типов, полей и связей.

Почему это важно: Это "магия", которая делает запросы естественного языка возможными. При запросе Copilot "Показать мне клиентов", ИИ-агент сначала использует интроспекцию для обнаружения того, что существует тип customers, какие у него поля и как его запрашивать. Без интроспекции вам потребуется вручную задокументировать всю схему для ИИ.

Это важно

Для работы сервера GraphQL MCP необходимо включить интроспекцию. Это по умолчанию отключено в Fabric по соображениям безопасности. Только администраторы рабочих областей могут включить интроспекцию. Если вы не являетесь администратором, попросите администратора рабочей области выполнить этот шаг.

Следуйте полному руководству по API Microsoft Fabric для интроспекции GraphQL и экспорта схем, чтобы:

Включение интроспекции в параметрах API
Узнайте, как работают запросы интроспекции
Сведения о параметрах экспорта схемы

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

Шаг 3. Настройка сервера GraphQL MCP

Что вы делаете: Установка и настройка локального сервера Node.js, реализующего протокол контекста модели. Этот сервер выступает в качестве переводчика между агентами ИИ и API GraphQL Fabric.

Почему это важно: Сервер MCP предоставляет стандартизированный интерфейс, который понимают агенты ИИ. Когда агент ИИ подключается, он может обнаруживать доступные средства (интроспектирование и запросы), вызывать эти средства и получать ответы без написания пользовательского кода интеграции для каждой платформы ИИ.

Теперь, когда у вас есть учетные данные для аутентификации (шаг 1) и включена интроспекция (шаг 2), вы можете настроить сервер для их использования.

Клонирование примера репозитория

git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/MCP

Установка зависимостей

npm install

Настройка переменных среды

.env Создайте файл в корневом каталоге проекта с конфигурацией:

MICROSOFT_FABRIC_API_URL=https://your-fabric-endpoint/graphql
MICROSOFT_FABRIC_TENANT_ID=your_tenant_id_here
MICROSOFT_FABRIC_CLIENT_ID=your_client_id_here
MICROSOFT_FABRIC_CLIENT_SECRET=your_client_secret_here
SCOPE=https://api.fabric.microsoft.com/.default

Замените значения заполнителей следующими значениями:

MICROSOFT_FABRIC_API_URL: конечная точка GraphQL на портале Fabric
MICROSOFT_FABRIC_TENANT_ID. Идентификатор клиента Azure
MICROSOFT_FABRIC_CLIENT_ID: идентификатор клиента регистрации приложения
MICROSOFT_FABRIC_CLIENT_SECRET: секрет клиента регистрации приложения

Запуск сервера GraphQL MCP

node FabricGraphQL_MCP.js

Сервер запускается на http://localhost:3000, и экран отображает:

Microsoft Fabric GraphQL MCP server listening on port 3000
API URL: https://your-fabric-endpoint/graphql
Scope: https://api.fabric.microsoft.com/.default

Доступные средства MCP

Сервер GraphQL MCP предоставляет два основных средства:

`introspect-schema`

Назначение. Получение полной схемы GraphQL
Параметры: Нет
Использование: необходимо сначала вызвать перед выполнением запросов

`query-graphql`

Назначение. Выполнение запросов GraphQL к данным Fabric
Параметры:
- query (обязательно): строка запроса GraphQL
- variables (необязательно): объект переменных GraphQL
Использование: для всех операций извлечения и обработки данных

Общие сведения о рабочем процессе

Типичный рабочий процесс GraphQL MCP следует этому шаблону:

Обнаружение схем: агент ИИ должен сначала вызвать introspect-schema средство, чтобы понять схему и доступные данные
Планирование запросов: агент анализирует запрос естественного языка и схему GraphQL
Создание запросов: агент создает соответствующие запросы GraphQL
Выполнение: агент вызывает query-graphql средство с созданными запросами
Обработка ответов: Агент формирует и представляет результаты

Шаг 4. Тестирование сервера GraphQL MCP

Что вы делаете: Убедитесь, что сервер MCP может пройти проверку подлинности в Fabric, получить схему и выполнить запросы перед подключением агентов ИИ.

Почему это важно: Тестирование вручную гарантирует правильность настройки всего. Если эти тесты проходят, вы знаете, что агенты ИИ смогут успешно подключиться на шаге 5.

Проверка работоспособности сервера

Сначала убедитесь, что сервер запущен и может пройти проверку подлинности в Fabric.

Использование PowerShell:

Invoke-RestMethod -Uri "http://localhost:3000/health" -Method Get

Использование cURL:

curl http://localhost:3000/health

Вы должны получить ответ, указывающий, что сервер запущен, как показано ниже.

{"status":"healthy","server":"Microsoft Fabric GraphQL MCP Server","hasToken":true,"tokenExpiry":"2025-06-30T23:11:36.339Z"}

Тестирование интроспекции схемы

Затем убедитесь, что сервер может получить схему GraphQL с помощью интроспекции. Это вызывает introspect-schema инструмент MCP.

Использование PowerShell:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/call"
    params = @{
        name = "introspect-schema"
        arguments = @{}
    }
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

Использование cURL:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "introspect-schema",
      "arguments": {}
    }
  }'

Это должно возвращать определение схемы GraphQL.

Тестирование запроса GraphQL

Наконец, проверьте выполнение фактического запроса GraphQL через сервер MCP. В этом примере запрашивается все имена типов в схеме query-graphql с помощью средства MCP.

Использование PowerShell:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 2
    method = "tools/call"
    params = @{
        name = "query-graphql"
        arguments = @{
            query = "query { __schema { types { name } } }"
        }
    }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

Использование cURL:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "query": "query { __schema { types { name } } }"
      }
    }
  }'

Возвращается список всех типов в схеме GraphQL.

Шаг 5. Подключение агентов ИИ

Что вы делаете: Настройка средств ИИ для использования локального сервера MCP в качестве источника данных.

Почему это важно: Здесь все складывается воедино. После подключения агенты ИИ могут обнаруживать схему Fabric с помощью интроспекции и создавать запросы GraphQL на основе запросов на естественном языке. ИИ обрабатывает синтаксис запросов— вы просто задаете вопросы на простом английском языке.

GitHub Copilot в Visual Studio Code

Установка расширения GitHub Copilot в VS Code

Настройте сервер GraphQL MCP в параметрах Copilot:

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

В чате Copilot сначала попросите интроспектировать схему, а затем попробуйте задать соответствующий вопрос, связанный с интроспектированными данными на естественном языке, например:

Cursor IDE

Открытие параметров курсора

Добавьте конфигурацию сервера MCP:

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

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

То, что вы создали

Поздравляю! Теперь у вас есть рабочий сервер GraphQL MCP, который:

Аутентификация в Fabric с использованием учетных данных служебного субъекта.
Экспонирует схему данных Fabric с помощью интроспекции
Преобразует запросы агента ИИ в запросы GraphQL
Возвращает данные в формате, который могут понять и представить агенты ИИ.

Теперь агенты ИИ (например, GitHub Copilot) могут:

Автоматическое обнаружение данных, доступных в рабочей области Fabric
Создание правильных запросов GraphQL на основе вопросов естественного языка
Получение и форматирование результатов без написания кода запроса

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

Вопросы безопасности

Хотя локальный сервер GraphQL MCP должен быть реализован только в целях разработки, как описано в этом руководстве, он реализован с помощью транспорта HTTP, что упрощает его использование в качестве отправной точки для более сложных интеграции с клиентом или веб-сервером. Если вы развертываете серверы GraphQL MCP в рабочей среде:

Для хранения секретов используйте Azure Key Vault вместо файлов .env
Реализация соответствующих правил авторизации, безопасности сети и брандмауэра
Включение ведения журнала аудита для всех запросов GraphQL
Используйте службу приложений Azure или службы контейнеров для размещения.
Реализация ограничения скорости и проверки подлинности для конечных точек MCP
Регулярная смена клиентских секретов и сертификатов

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

Распространенные проблемы и решения

Ошибки проверки подлинности

Убедитесь, что регистрация приложений Azure имеет правильные разрешения
Убедитесь, что субъекты-службы включены в клиенте Fabric
Убедитесь, что срок действия секрета клиента не истек

Ошибка интроспекции схемы

Подтверждение включения интроспекции в параметрах API GraphQL
Убедитесь, что URL-адрес конечной точки GraphQL является правильным.
Проверка сетевого подключения к рабочей области Fabric

Агент ИИ не распознает средства

Перезапуск клиента ИИ после изменения конфигурации
Проверка доступности URL-адреса сервера MCP
Проверка журналов сервера для любых сообщений об ошибках

Ошибки выполнения запроса

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-21

Поделиться через

Подключение агентов ИИ к API Fabric для GraphQL с помощью локального сервера протокола контекста модели (MCP)

Что такое протокол контекста модели (MCP)?

Почему GraphQL идеально подходит для MCP

Предпосылки

Шаг 1. Настройка доступа служебного принципала

Шаг 2. Включение интроспекции GraphQL (требуется администратор рабочей области)

Шаг 3. Настройка сервера GraphQL MCP

Клонирование примера репозитория

Установка зависимостей

Настройка переменных среды

Запуск сервера GraphQL MCP

Доступные средства MCP

introspect-schema

query-graphql

Общие сведения о рабочем процессе

Шаг 4. Тестирование сервера GraphQL MCP

Проверка работоспособности сервера

Тестирование интроспекции схемы

Тестирование запроса GraphQL

Шаг 5. Подключение агентов ИИ

GitHub Copilot в Visual Studio Code

Cursor IDE

То, что вы создали

Вопросы безопасности

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

Распространенные проблемы и решения

Связанный контент

Обратная связь

Дополнительные ресурсы

`introspect-schema`

`query-graphql`