Připojení agentů AI k rozhraní API fabric pro GraphQL pomocí místního serveru MCP (Model Context Protocol)

Představte si, že požádáte GitHub Copilot "Ukaž mi všechny prodeje z minulého čtvrtletí" a on automaticky vytvoří dotaz do datového skladu Fabric, porozumí schématu a vrátí výsledky – to vše bez psaní jediného řádku dotazu v GraphQL. V tomto kurzu se dozvíte, jak to udělat.

V tomto kurzu vytvoříte místní server MCP v GraphQL, který funguje jako most mezi agenty AI a vašimi daty Microsoft Fabric. Na konci máte funkční vývojový server, který umožňuje asistentům AI, jako je GitHub Copilot, Claude a další agenti umělé inteligence, přirozeně dotazovat data fabric pomocí konverzačního jazyka.

Čeho dosáhnete:

Nastavte ověřování, aby váš server GraphQL MCP mohl bezpečně přistupovat k Fabric.
Povolení introspekce schématu, aby agenti umělé inteligence mohli automaticky zjišťovat datovou strukturu
Nasazení místního serveru GraphQL MCP, který přeloží přirozený jazyk do dotazů GraphQL
Připojení GitHub Copilotu nebo jiných nástrojů AI k dotazování dat konverzálně

Co je protokol MCP (Model Context Protocol)?

Model Context Protocol (MCP) je standard pro připojení asistentů AI k systémům, kde se nacházejí data, včetně úložišť obsahu, obchodních nástrojů a vývojových prostředí. Jejím cílem je pomoci hraničním modelům lépe a relevantněji reagovat. Představte si MCP jako USB-C port pro aplikace umělé inteligence. Stejně jako USB-C poskytuje standardizovaný způsob připojení zařízení k různým periferním zařízením a příslušenství, MCP poskytuje standardizovaný způsob připojení modelů AI k externím zdrojům dat a nástrojům.

Hlavní platformy AI, včetně OpenAI, Microsoft Copilot Studia a Microsoft Foundry, přijaly MCP jako standardní způsob integrace agentů AI s externími systémy. Díky tomu je MCP ideální volbou pro připojení agentů AI k vašim datům Microsoft Fabric.

Proč je GraphQL ideální pro MCP

GraphQL je vhodný pro integrace MCP, protože:

Introspekce schématu: Agenti umělé inteligence mohou automaticky zjišťovat dostupné datové struktury a relace přímo ze schématu GraphQL.
Flexibilní dotazy: Agenti můžou požadovat přesně data, která potřebují v jediné žádosti.
Zabezpečení typů: Silné typování pomáhá agentům umělé inteligence porozumět formátům dat a omezením.
Efektivní načítání dat: Snižuje nadměrné a nedostatečné načítání dat

Rozhraní API Microsoft Fabric pro GraphQL usnadňuje zveřejnění vašich objektů Fabric Lakehouse, Datových skladů a databází agentům AI prostřednictvím standardizovaného rozhraní GraphQL. I když rozhraní API pro GraphQL už poskytuje výkonné možnosti dotazování, nastavení připojení pro agenty AI nemusí být tak jednoduché, jako by to mohlo být.

S jednoduchým místním serverem GraphQL MCP můžou vývojáři pomocí agentů AI zjistit datovou strukturu prostředků infrastruktury, pochopit, co je k dispozici, a dotazovat se na něj pomocí přirozeného jazyka – to vše prostřednictvím standardizovaného rozhraní MCP. Pohodlně nemusíte definovat samostatný nástroj MCP na serveru pro každý typ GraphQL, dotaz nebo mutaci. Server GraphQL MCP zkoumá schéma GraphQL, aby umožnil agentům AI porozumět všem dostupným typům a operacím hned od začátku.

Požadavky

Než začnete s tímto kurzem, ujistěte se, že máte:

Pracovní prostor Microsoft Fabric s příslušnými oprávněními. K konfiguraci služebních identit a povolení introspekce je potřeba role správce pracovního prostoru.
Rozhraní API pro položku GraphQL bylo vytvořeno a nakonfigurováno. Viz Vytvoření a přidání dat do rozhraní API pro GraphQL nebo vytvoření rozhraní GraphQL API z databáze SQL na portálu Fabric.
Node.js nainstalované na vývojovém počítači (včetně npm)
Visual Studio Code nainstalovaný na vývojovém počítači

Poznámka:

Nejste správce? Některé kroky v tomto kurzu vyžadují oprávnění správce. Pokud nejste správce, můžete většinu kurzu dokončit tak, že požádáte správce, aby vám pomohl s konkrétními úkoly. Každý krok, který vyžaduje oprávnění správce, je jasně označený.

Krok 1: Konfigurace přístupu služebního objektu

Co děláte: Nastavení neinteraktivních přihlašovacích údajů pro ověření, aby váš server MCP v GraphQL mohl přistupovat k Fabric, aniž by uživatel musel pokaždé provádět přihlášení.

Proč na tom záleží: Server McP GraphQL běží jako služba na pozadí, kterou agenti umělé inteligence volají automaticky. Potřebuje svou vlastní identitu (služba principála) s přihlašovacími údaji pro autentizaci do Fabric jménem vaší aplikace, nikoli jménem konkrétního uživatele.

Postupujte podle kompletní příručky pro použití instančních objektů s rozhraním Fabric API pro GraphQL:

Vytvoření registrace aplikace Azure (libovolný uživatel s oprávněními k vytváření registrací aplikací v Microsoft Entra ID)
Přidání tajného klíče klienta do certifikátů a tajných kódů (libovolný uživatel)
Povolení služebních principálů v nastavení tenanta (vyžaduje správce tenanta Fabric)
Udělení oprávnění k rozhraní GraphQL API a pracovnímu prostoru (vyžaduje roli správce nebo přispěvatele pracovního prostoru)

Návod

Nejste správce? První dvě položky můžete dokončit sami. V případě nastavení tenanta požádejte správce tenanta Fabric, aby v části Administrační portál>Nastavení tenanta>Nastavení pro vývojáře povolil "služební účty mohou používat rozhraní API Fabric". V případě oprávnění pracovního prostoru požádejte správce pracovního prostoru, aby vašemu principálu služby udělil přístup k pracovnímu prostoru nebo ke konkrétnímu GraphQL API.

Po dokončení instalace zachyťte tyto tři hodnoty pro konfiguraci serveru McP GraphQL:

ID tenanta: Nalezeno v Microsoft Entra ID v části Přehled>ID tenanta
ID klienta: Nachází se v registraci aplikace v části Přehled>aplikace (id klienta)
Tajný klíč klienta: Hodnota tajného klíče zobrazená při vytváření nového tajného klíče klienta (okamžitě zkopírujte—zobrazuje se pouze jednou)

Krok 2: Povolení introspekce GraphQL (vyžaduje správce pracovního prostoru)

Co děláte: Povolení introspekce umožňuje serveru GraphQL MCP požádat rozhraní GraphQL API o to, jaká data máte? a získat úplný popis všech dostupných typů, polí a relací.

Proč na tom záleží: To je "magie", která umožňuje dotazy v přirozeném jazyce. Když se zeptáte Copilotu Zobrazit zákazníky, agent AI nejprve pomocí introspekce zjistí, že customers typ existuje, jaká pole má a jak se na něj dotazovat. Bez introspekce byste museli ručně zdokumentovat celé schéma umělé inteligence.

Důležité

Aby server MCP GraphQL fungoval, musí být povolena introspekce. Ve výchozím nastavení je toto ve Fabric zakázáno z bezpečnostních důvodů. Introspekci můžou povolit jenom správci pracovního prostoru. Pokud nejste správce, požádejte správce pracovního prostoru, aby tento krok dokončil.

Postupujte podle kompletní příručky na Microsoft Fabric API pro introspekci GraphQL a export schémat k:

Povolení introspekce v nastavení rozhraní API
Pochopte, jak fungují introspektivní dotazy
Informace o možnostech exportu schématu

Po povolení introspekce může server GraphQL MCP dotazovat strukturu schématu a zpřístupnit ho agentům AI.

Krok 3: Nastavení serveru McP v GraphQL

Co děláte: Instalace a konfigurace místního Node.js serveru, který implementuje kontextový protokol modelu. Tento server funguje jako překladač mezi agenty AI a vaším rozhraním API GraphQL Fabric.

Proč na tom záleží: Server MCP poskytuje standardizované rozhraní, kterému agenti AI rozumí. Když se agent AI připojí, může zjistit, jaké nástroje jsou k dispozici (introspection a dotazování), volat tyto nástroje a přijímat odpovědi – to vše bez psaní vlastního integračního kódu pro každou platformu AI.

Teď, když máte přihlašovací údaje pro ověřování (krok 1) a povolenou introspekci (krok 2), jste připraveni nakonfigurovat server tak, aby je používal.

Klonování ukázkového úložiště

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

Nainstalujte závislosti

npm install

Konfigurace proměnných prostředí

Vytvořte .env soubor v kořenovém adresáři projektu s vaší konfigurací:

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

Zástupné hodnoty nahraďte:

MICROSOFT_FABRIC_API_URL: Koncový bod GraphQL z portálu Fabric
MICROSOFT_FABRIC_TENANT_ID: ID tenanta Azure
MICROSOFT_FABRIC_CLIENT_ID: ID klienta registrace aplikace
MICROSOFT_FABRIC_CLIENT_SECRET: Tajný klíč klienta registrace aplikace

Spuštění serveru McP v GraphQL

node FabricGraphQL_MCP.js

Server se spustí http://localhost:3000 a zobrazí:

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

Dostupné nástroje MCP

Server McP GraphQL poskytuje dva hlavní nástroje:

`introspect-schema`

Účel: Načte kompletní schéma GraphQL.
Parametry: Žádné
Použití: Před vytvořením dotazů musí být nejprve volána.

`query-graphql`

Účel: Provede dotazy GraphQL na vaše data Fabric.
Parametry:
- query (povinné): Řetězec dotazu GraphQL
- variables (volitelné): Objekt proměnných GraphQL
Použití: Pro všechny operace načítání a manipulace s daty

Principy pracovního postupu

Typický pracovní postup MCP pro GraphQL se řídí tímto vzorem:

Zjišťování schématu: Agent AI musí nejprve volat introspect-schema nástroj, aby porozuměl schématu a dostupným datům.
Plánování dotazů: Agent analyzuje požadavek přirozeného jazyka a schéma GraphQL.
Generování dotazů: Agent vytvoří odpovídající dotazy GraphQL.
Spuštění: Agent volá query-graphql nástroj s vygenerovanými dotazy.
Zpracování odpovědí: Formáty agentů a zobrazení výsledků

Krok 4: Otestování serveru GraphQL MCP

Co děláte: Ověření, že se server MCP může autentizovat k Fabric, načíst vaše schéma a vykonávat dotazy, před připojením agentů AI.

Proč na tom záleží: Ruční testování zajišťuje, že je všechno správně nakonfigurované. Pokud tyto testy projdou, víte, že agenti AI se můžou úspěšně připojit v kroku 5.

Ověření stavu serveru

Nejprve ověřte, že je server spuštěný a může se ověřit ve Fabric.

Pomocí PowerShellu:

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

Pomocí cURL:

curl http://localhost:3000/health

Měli byste obdržet odpověď, která značí, že je server spuštěný, podobně jako:

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

Úvod do testovacího schématu

Dále ověřte, že server může načíst schéma GraphQL prostřednictvím introspekce. Tím se introspect-schema volá nástroj MCP.

Pomocí PowerShellu:

$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

Pomocí 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": {}
    }
  }'

Definice schématu GraphQL by měla být vrácena.

Testování dotazu GraphQL

Nakonec otestujte spuštění skutečného dotazu GraphQL prostřednictvím serveru MCP. Tento příklad dotazuje všechny názvy typů ve vašem schématu query-graphql pomocí nástroje MCP.

Pomocí PowerShellu:

$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

Pomocí 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 } } }"
      }
    }
  }'

Vrátí seznam všech typů ve schématu GraphQL.

Krok 5: Připojení agentů AI

Co děláte: Konfigurace nástrojů AI pro použití místního serveru MCP jako zdroje dat

Proč na tom záleží: To je místo, kde všechno přichází dohromady. Po připojení mohou agenti AI zjistit schéma Fabric pomocí introspekce a generovat dotazy GraphQL na základě přirozených jazykových požadavků. AI zpracovává syntaxi dotazu – stačí položit otázky v prosté angličtině.

GitHub Copilot v editoru Visual Studio Code

Instalace rozšíření GitHub Copilot ve VS Code

Nakonfigurujte server GraphQL MCP v nastavení Copilotu:

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

V chatu Copilot nejprve požádejte o provedení introspekce schématu a zkuste položit relevantní otázku související s prozkoumanými daty v přirozeném jazyce, například:

IDE Cursor

Otevřít nastavení kurzoru

Přidejte konfiguraci serveru MCP:

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

Nejprve v chatu požádejte o introspekci schématu a poté zkuste položit otázku týkající se introspektovaných dat v přirozeném jazyce.

Co jste vytvořili

Gratulujeme! Teď máte funkční server McP GraphQL, který:

Ověřuje ve Fabric pomocí přihlašovacích údajů aplikačního objektu.
Zveřejňuje schéma dat infrastruktury prostřednictvím introspekce.
Přeloží požadavky agenta AI na dotazy GraphQL.
Vrací data ve formátu, kterému mohou agenti umělé inteligence rozumět a prezentovat.

Vaši agenti AI (například GitHub Copilot) teď můžou:

Automaticky zjistit, jaká data jsou k dispozici v pracovním prostoru Fabric
Generování správných dotazů GraphQL na základě otázek v přirozeném jazyce
Načtení a formátování výsledků bez psaní kódu dotazu

Tento místní server je určený pro vývoj a učení. V následujících částech najdete důležité informace o produkčních nasazeních a běžných scénářích řešení potíží.

Bezpečnostní aspekty

I když by se místní server GraphQL MCP měl implementovat pro účely vývoje, jak je popsáno v tomto kurzu, implementuje se s přenosem HTTP, což usnadňuje jeho použití jako výchozí bod pro složitější integrace klienta nebo webového serveru. Pokud nasazujete servery McP GraphQL v produkčním prostředí:

Použití služby Azure Key Vault k ukládání tajných .env kódů místo souborů
Implementujte správné autorizace, zabezpečení sítě a pravidla brány firewall.
Povolení protokolování auditu pro všechny dotazy GraphQL
Použití služby Azure App Service nebo Container Instances k hostování
Implementace omezování rychlosti a ověřování pro koncové body MCP
Pravidelná obměna tajných klíčů a certifikátů klientů

Řešení problémů

Běžné problémy a řešení

Chyby ověřování

Ověření, že registrace aplikace Azure má správná oprávnění
Zkontrolujte, jestli jsou ve vašem prostředí Fabric povolené servisní účty.
Ujistěte se, že nevypršela platnost tajného klíče klienta.

Selhání introspekce schématu

Ověřte, že je v nastavení rozhraní GraphQL API povolené introspekce.
Zkontrolujte správnost adresy URL koncového bodu GraphQL.
Ověření síťového připojení k pracovnímu prostoru Fabric

Agent AI nerozpozná nástroje

Po změně konfigurace restartujte klienta AI.
Ověření přístupnosti adresy URL serveru MCP
Kontrola chybových zpráv v protokolech serveru

Chyby spouštění dotazů

Kontrola protokolovaných dotazů a chyb v konzole serveru
Ujistěte se, že vaše dotazy odpovídají dostupnému schématu.
Zkontrolujte, jestli máte příslušná oprávnění pro požadovaná data.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-01-21

Sdílet prostřednictvím

Připojení agentů AI k rozhraní API fabric pro GraphQL pomocí místního serveru MCP (Model Context Protocol)

Co je protokol MCP (Model Context Protocol)?

Proč je GraphQL ideální pro MCP

Požadavky

Krok 1: Konfigurace přístupu služebního objektu

Krok 2: Povolení introspekce GraphQL (vyžaduje správce pracovního prostoru)

Krok 3: Nastavení serveru McP v GraphQL

Klonování ukázkového úložiště

Nainstalujte závislosti

Konfigurace proměnných prostředí

Spuštění serveru McP v GraphQL

Dostupné nástroje MCP

introspect-schema

query-graphql

Principy pracovního postupu

Krok 4: Otestování serveru GraphQL MCP

Ověření stavu serveru

Úvod do testovacího schématu

Testování dotazu GraphQL

Krok 5: Připojení agentů AI

GitHub Copilot v editoru Visual Studio Code

IDE Cursor

Co jste vytvořili

Bezpečnostní aspekty

Řešení problémů

Běžné problémy a řešení

Související obsah

Váš názor

Další materiály

`introspect-schema`

`query-graphql`