Pripojenie AI Agents k rozhraniu API služby Fabric pre GraphQL s lokálnym kontextovým protokolom modelu (MCP) serverom

Predstavte si, že sa opýtate GitHub Copilot "Ukážte mi všetky predaje za posledný štvrťrok" a automaticky sa opýtate na váš Fabric data warehouse, pochopíte schému a vrátite výsledky – a to všetko bez toho, aby ste napísali jediný riadok v GraphQL. Tento tutoriál vám ukáže, ako to urobiť.

V tomto tutoriáli vytvoríte lokálny GraphQL MCP server, ktorý slúži ako most medzi AI agentmi a vašimi dátami Microsoft Fabric. Na konci máte funkčný vývojový server, ktorý umožňuje AI asistentom ako GitHub Copilot, Claude a ďalším AI agentom prirodzene dotazovať vaše Fabric dáta pomocou konverzačného jazyka.

Čo dosiahnete:

Nastavte autentifikáciu, aby váš GraphQL MCP server mohol bezpečne pristupovať k Fabric
Umožnite introspekciu schémy, aby AI agenti mohli automaticky objaviť vašu dátovú štruktúru
Nasadenie lokálneho GraphQL MCP servera, ktorý prekladá prirodzený jazyk do GraphQL dotazov
Pripojte GitHub Copilot alebo iné AI nástroje na konverzačné dotazy na vaše dáta

Aký je kontextový protokol modelu (MCP)?

Model Context Protocol (MCP) je štandard na prepojenie AI asistentov so systémami, kde sa nachádzajú dáta, vrátane obsahových repozitárov, obchodných nástrojov a vývojových prostredí. Jeho cieľom je pomôcť pohraničným modelom lepšie a relevantnejšie reakcie. Predstavte si MCP ako USB-C port pre aplikácie AI. Tak ako USB-C poskytuje štandardizovaný spôsob pripojenia vašich zariadení k rôznym periférnym funkciám a príslušenstvu, MCP poskytuje štandardizovaný spôsob pripojenia modelov AI k externým zdrojom údajov a nástrojom.

Hlavné AI platformy vrátane OpenAI, Microsoft Copilot Studio a Microsoft Foundry prijali MCP ako štandardný spôsob integrácie AI agentov s externými systémami. Vďaka tomu je MCP ideálnou voľbou na pripojenie agentov AI k údajom služby Microsoft Fabric.

Prečo je GraphQL ideálny pre MCP

GraphQL je vhodný pre integrácie MCP, pretože:

Introspekcia schémy: Agenti umelej inteligencie môžu automaticky zisťovať dostupné štruktúry údajov a vzťahy priamo zo schémy GraphQL
Flexibilné dotazy: agenti môžu požadovať presne tie údaje, ktoré potrebujú v jednej žiadosti
Bezpečnosť typov: Silné zadávanie pomáha agentom umelej inteligencie pochopiť formáty údajov a obmedzenia
Efektívne načítavanie údajov: Znižuje nadmernú načítavanie a nedostatočné načítavanie údajov

API Microsoft Fabric pre GraphQL uľahčuje vystavenie vašich Fabric jazerných domov, dátových skladov a databáz AI agentom prostredníctvom štandardizovaného rozhrania GraphQL. Zatiaľ čo rozhranie API pre GraphQL už poskytuje výkonné možnosti dotazovania, nastavenie pripojenia pre agentov AI nemusí byť také jednoduché, ako by mohlo byť.

S jednoduchým lokálnym GraphQL MCP serverom môžu vývojári pomocou AI agentov objaviť svoju Fabric dátovú štruktúru, pochopiť, čo je dostupné, a dotazovať sa pomocou prirodzeného jazyka – všetko cez štandardizované MCP rozhranie. Výhodou je, že nemusíte na serveri definovať samostatný MCP nástroj pre každý typ, dotaz alebo mutáciu GraphQL. Server GraphQL MCP introspekuje schému GraphQL a umožňuje AI agentom rozumieť všetkým dostupným typom a operáciám od začiatku.

Predpoklady

Pred začatím tohto kurzu sa uistite, že:

Pracovný priestor Microsoft Fabric s príslušnými oprávneniami. Úloha administrátora pracovného priestoru je potrebná na konfiguráciu princípov služieb a umožnenie introspekcie.
API pre položku GraphQL vytvorenú a nakonfigurovanú. Pozrite si Vytvoriť a pridať dáta do API pre GraphQL alebo Vytvoriť GraphQL API z vašej SQL databázy v portáli Fabric.
Node.js nainštalované na vašom vývojovom počítači (vrátane npm)
Visual Studio Code nainštalovaný na vašom vývojovom počítači

Note

Nie si admin? Niektoré kroky v tomto tutoriáli vyžadujú administrátorské oprávnenia. Ak nie ste administrátor, väčšinu tutoriálu môžete dokončiť tým, že požiadate administrátora o pomoc s konkrétnymi úlohami. Každý krok, ktorý vyžaduje administrátorské oprávnenia, je jasne označený.

Krok 1: Konfigurácia prístupu objektu služby

Čo robíte: Nastavenie neinteraktívnych autentifikačných prihlasovacích údajov, aby váš GraphQL MCP server mohol pristupovať k Fabric bez nutnosti používateľa zakaždým sa prihlasovať.

Prečo je to dôležité: GraphQL MCP server beží ako služba na pozadí, ktorú AI agenti automaticky volajú. Potrebuje vlastnú identitu (servisný princíp) s prihlasovacími údajmi na autentifikáciu v Fabric v mene vašej aplikácie, nie v mene konkrétneho používateľa.

Postupujte podľa pokynov na stránke Používanie objektov služby s rozhraním API služby pre GraphQL a postupujte podľa nasledujúcich pokynov:

Vytvorte Azure App Registration (akýkoľvek používateľ s oprávneniami na vytváranie registrácií aplikácií v Microsoft Entra ID)
Pridajte klientské tajomstvo pod Certifikáty a tajomstvá (akýkoľvek používateľ)
Povolte service principals v nastaveniach vášho tenantu (vyžaduje Fabric tenant admin)
Udeľ oprávnenia svojmu GraphQL API a pracovnému priestoru (vyžaduje úlohu administrátora pracovného priestoru alebo prispievateľa)

Prepitné

Nie si admin? Prvé dva predmety si môžete splniť sami. Pre nastavenie tenantu požiadajte svojho Fabric tenant administrátora, aby povolil "Service principals can use Fabric APIs" v sekcii Admin portál> Nastavenia >nájomcuNastavenia vývojára. Pre oprávnenia pracovného priestoru požiadajte svojho administrátora pracovného priestoru, aby udelil vášmu hlavnému servisu prístup k pracovnému priestoru alebo konkrétnemu GraphQL API.

Po dokončení nastavenia zaznamenávajte tieto tri hodnoty pre konfiguráciu servera GraphQL MCP:

Tenant ID: Nájdené v Microsoft Entra ID pod prehľadom>Tenant ID
ID klienta: Nájdené vo vašej registrácii aplikácie pod prehľadom>ID aplikácie (klienta)
Klientské tajomstvo: Hodnota tajomstva zobrazená pri vytváraní nového klientského tajomstva (kopírovať okamžite—zobrazí sa len raz)

Krok 2: Zapnúť introspekciu v GraphQL (vyžaduje administráciu pracovného priestoru)

Čo robíte: Povolenie introspekcie umožňuje serveru GraphQL MCP opýtať sa vášho GraphQL API "Aké dáta máte?" a získať úplný popis všetkých dostupných typov, polí a vzťahov.

Prečo je to dôležité: Toto je tá "mágia", ktorá umožňuje robiť dotazy v prirodzenom jazyku. Keď sa opýtate Copilota "Ukážte mi zákazníkov", AI agent najprv použije introspekciu, aby zistil, že typ customers existuje, aké polia má a ako ho dotazovať. Bez introspekcie by si musel manuálne zdokumentovať celú schému pre AI.

Dôležité

Introspekcia musí byť zapnutá, aby server GraphQL MCP fungoval. Toto je v Fabric predvolene zakázané z bezpečnostných dôvodov. Introspekciu môžu povoliť len administrátori pracovného priestoru. Ak nie ste administrátor, požiadajte svojho administrátora pracovného priestoru, aby tento krok dokončil.

Postupujte podľa kompletného sprievodcu na Microsoft Fabric API pre GraphQL Introspekciu a Export schém, aby:

Povolte introspekciu vo svojich nastaveniach API
Pochopte, ako fungujú introspekčné dotazy
Naučte sa o možnostiach exportu schémy

Keď je introspekcia povolená, GraphQL MCP server môže dotazovať vašu štruktúru schémy a sprístupniť ju AI agentom.

Krok 3: Nastavte GraphQL MCP server

Čo robíte: Inštalácia a konfigurácia lokálneho Node.js servera, ktorý implementuje Model Context Protocol. Tento server slúži ako prekladač medzi AI agentmi a vaším Fabric GraphQL API.

Prečo je to dôležité: MCP server poskytuje štandardizované rozhranie, ktorému AI agenti rozumejú. Keď sa AI agent pripojí, môže zistiť, aké nástroje sú dostupné (introspekcia a dotazovanie), zavolať im tieto nástroje a dostať odpovede – a to všetko bez toho, aby ste museli písať vlastný integračný kód pre každú AI platformu.

Teraz, keď máte autentifikačné prihlasovacie údaje (Krok 1) a povolenú introspekciu (Krok 2), ste pripravení nakonfigurovať server na ich používanie.

Klonovanie vzorového odkladacieho priestoru

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

Závislosti inštalácie

npm install

Konfigurácia premenných prostredia

.env Vytvorte súbor v koreňovom adresári projektu s vašou konfiguráciou:

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

Nahraďte hodnoty zástupného symbolu nasledujúcimi:

MICROSOFT_FABRIC_API_URL: Váš koncový bod GraphQL z portálu služby Fabric
MICROSOFT_FABRIC_TENANT_ID: Vaše ID nájomníka platformy Azure
MICROSOFT_FABRIC_CLIENT_ID: ID klienta registrácie aplikácie
MICROSOFT_FABRIC_CLIENT_SECRET: Tajný kód klienta registrácie aplikácie

Spusti GraphQL MCP server

node FabricGraphQL_MCP.js

Server sa spustí a http://localhost:3000 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

GraphQL MCP server poskytuje dva hlavné nástroje:

`introspect-schema`

Účel: Načíta úplnú schému GraphQL
Parametre: Žiadne
Použitie: Pred vytvorením dotazov sa musí najskôr ť volaný.

`query-graphql`

Účel: Spustí dotazy GraphQL na základe údajov služby Fabric
Parametre:
- query (povinné): Reťazec dotazu GraphQL
- variables (voliteľné): objekt premenných GraphQL
Použitie: pre všetky operácie načítania a manipulácie s údajmi

Porozumenie pracovnému postupu

Typický pracovný postup GraphQL MCP nasleduje tento vzorec:

Objavovanie schémy: AI agent musí najskôr zavolať nástroj, introspect-schema aby pochopil schému a dostupné dáta
Plánovanie dotazov: Agent analyzuje vašu požiadavku v prirodzenom jazyku a schému GraphQL
Generovanie dotazov: Agent vytvorí vhodné dotazy GraphQL
Vykonávanie: Agent volá query-graphql nástroj s generovanými dotazmi
Spracovanie odpovede: Formáty agenta a zobrazuje výsledky

Krok 4: Otestujte GraphQL MCP server

Čo robíte: Overenie, či váš MCP server dokáže autentifikovať k Fabric, získať vašu schému a vykonať dotazy – pred pripojením AI agentov.

Prečo je to dôležité: Manuálne testovanie zabezpečuje, že je všetko správne nastavené. Ak tieto testy prejdú, viete, že AI agenti sa dokážu úspešne pripojiť v kroku 5.

Overenie stavu servera

Najprv si overte, že server beží a vie sa autentifikovať cez Fabric.

Používanie PowerShellu:

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

Použitie cURL:

curl http://localhost:3000/health

Mala by sa vám zobraziť odpoveď, že server je spustený, podobne ako:

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

Testovanie schémy introspekcie

Ďalej overte, či server dokáže získať vašu schému GraphQL prostredníctvom introspekcie. Toto volá introspect-schema nástroj MCP.

Používanie 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

Použitie 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": {}
    }
  }'

Tým by sa mala vrátiť definícia schémy GraphQL.

Testovanie dotazu GraphQL

Nakoniec otestujte vykonanie skutočného GraphQL dotazu cez MCP server. Tento príklad dotazuje na všetky názvy typov vo vašej schéme pomocou nástroja query-graphql MCP.

Používanie 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

Použitie 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 } } }"
      }
    }
  }'

Tým sa zobrazí zoznam všetkých typov vo vašej schéme GraphQL.

Krok č. 5: Pripojenie agentov AI

Čo robíte: Konfigurujem AI nástroje tak, aby používali váš lokálny MCP server ako zdroj dát.

Prečo je to dôležité: Tu sa všetko spája. Po pripojení môžu vaši AI agenti objaviť vašu Fabric schému prostredníctvom introspekcie a generovať GraphQL dotazy na základe požiadaviek v prirodzenom jazyku. AI spravuje syntax dotazov – jednoducho sa pýtate jednoduchou angličtinou.

GitHub Copilot v programe Visual Studio Code

Inštalácia rozšírenia GitHub Copilot v nástroji VS Code

Nakonfigurujte GraphQL MCP server vo svojich nastaveniach Copilota:

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

V chate Copilot sa najprv požiadajte, aby ste introspektovali schému a potom sa pokúsili položiť príslušnú otázku súvisiacu s introspektovanými údajmi v prirodzenom jazyku, napríklad:

Ide kurzora

Otvorenie nastavení kurzora

Pridajte konfiguráciu servera MCP:

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

V chate sa najprv požiadajte, aby ste si vyskúšali schému a potom sa pokúsili položiť príslušnú otázku súvisiacu s introspektovanými údajmi v prirodzenom jazyku.

To, čo si vybudoval

Blahoželáme! Teraz máte funkčný GraphQL MCP server, ktorý:

Autentifikuje sa do Fabric pomocou prihlasovacích údajov service principal
Odhaľuje vašu dátovú schému Fabric prostredníctvom introspekcie
Prekladá požiadavky AI agentov na GraphQL dotazy
Vracia údaje vo formáte, ktorému AI agenti rozumejú a prezentujú

Vaši AI agenti (ako GitHub Copilot) teraz môžu:

Automaticky zistite, aké dáta sú dostupné vo vašom pracovnom priestore Fabric
Generujte správne dotazy v GraphQL na základe otázok v prirodzenom jazyku
Získajte a formátujte výsledky bez toho, aby ste písali akýkoľvek dotazovací kód

Tento lokálny server je určený na vývoj a učenie. Nasledujúce sekcie sa venujú dôležitým úvahám pri produkčných nasadeniach a bežných scenároch riešenia problémov.

Dôležité informácie týkajúce sa zabezpečenia

Hoci lokálny GraphQL MCP server by mal byť implementovaný len na vývojové účely, ako je popísané v tomto tutoriáli, je implementovaný pomocou HTTP transportu, čo uľahčuje jeho použitie ako východiskový bod pre zložitejšie klient-server alebo webové integrácie. Ak nasadzujete GraphQL MCP servery v produkcii:

Použitie služby Azure Key Vault na ukladanie tajného .env kódu namiesto súborov
Implementujte správnu autorizáciu, sieťovú bezpečnosť a firewall pravidlá
Povolenie zapisovania do denníka auditu pre všetky dotazy GraphQL
Použitie služby Azure App Service alebo container Instances na hosťovanie
Obmedzenie rýchlosti implementácie a overovanie pre koncové body MCP
Pravidelne rotujte klientske tajomstvá a certifikáty

Riešenie problémov

Bežné problémy a riešenia

Chyby overenia

Overenie registrácie aplikácie v Azure má správne povolenia
Skontrolujte, či sú povolené objekty služby v nájomníkovi služby Fabric
Uistite sa, že vaše tajomstvo klienta nie je expirované

Introspekcia schémy zlyhá

Potvrdenie povolenia introspekcie v nastaveniach rozhrania GraphQL API
Skontrolujte, či je vaša URL adresa koncového bodu GraphQL správna
Overenie sieťového pripojenia k pracovnému priestoru služby Fabric

Agent AI nástroje nerozpoznáva

Reštartovanie klienta AI po zmene konfigurácie
Overenie dostupnosti URL adresy servera MCP
Prípadné chybové hlásenia nájdete v denníkoch servera

Chyby spúšťaia dotazov

Kontrola serverovej konzoly s zaznamenanými dotazmi a chybami
Zabezpečte, aby vaše dotazy zodpovedali dostupnej schéme.
Skontrolujte, či máte príslušné povolenia pre požadované údaje

Pripomienky

Bola táto stránka užitočná?

Last updated on 2026-01-20

Zdieľať cez

Pripojenie AI Agents k rozhraniu API služby Fabric pre GraphQL s lokálnym kontextovým protokolom modelu (MCP) serverom

Aký je kontextový protokol modelu (MCP)?

Prečo je GraphQL ideálny pre MCP

Predpoklady

Krok 1: Konfigurácia prístupu objektu služby

Krok 2: Zapnúť introspekciu v GraphQL (vyžaduje administráciu pracovného priestoru)

Krok 3: Nastavte GraphQL MCP server

Klonovanie vzorového odkladacieho priestoru

Závislosti inštalácie

Konfigurácia premenných prostredia

Spusti GraphQL MCP server

Dostupné nástroje MCP

introspect-schema

query-graphql

Porozumenie pracovnému postupu

Krok 4: Otestujte GraphQL MCP server

Overenie stavu servera

Testovanie schémy introspekcie

Testovanie dotazu GraphQL

Krok č. 5: Pripojenie agentov AI

GitHub Copilot v programe Visual Studio Code

Ide kurzora

To, čo si vybudoval

Dôležité informácie týkajúce sa zabezpečenia

Riešenie problémov

Bežné problémy a riešenia

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií

`introspect-schema`

`query-graphql`