AI-ügynökök csatlakoztatása a GraphQL-hez készült Fabric API-hoz egy helyi Model Context Protocol (MCP) kiszolgálóval

Képzeld el, hogy megkérdezed a GitHub Copilot-t: "Mutasd meg az összes eladást az előző negyedévből", és automatikusan lekérdezi a raktáradat a Fabric-ben, megérti a sémát, és visszaadja az eredményeket – mindezt anélkül, hogy egyetlen sort sem írna GraphQL-ből. Ez az oktatóanyag bemutatja, hogyan teheti ezt lehetővé.

Ebben az oktatóban egy helyi GraphQL MCP szervert építesz, amely hídként működik az AI ügynökök és a Fabric adatok között. A folyamat végére egy működő fejlesztői kiszolgálóval rendelkezik, amely lehetővé teszi az olyan AI-asszisztensek számára, mint a GitHub Copilot, Claude és más AI-ügynökök, hogy természetes beszélgetési nyelven kérdezzék le a Fabric-adatokat.

A következő feladatokat fogja elvégezni:

Hitelesítés beállítása, hogy a GraphQL MCP-kiszolgáló biztonságosan hozzáférhessen a Fabrichez
Séma introspekció engedélyezése, hogy az AI-ügynökök automatikusan felfedezhessék a te adatstruktúrádat.
Helyi GraphQL MCP-kiszolgáló üzembe helyezése, amely természetes nyelvet fordít le GraphQL-lekérdezésekre
A GitHub Copilot vagy más AI-eszközök csatlakoztatása az adatok beszélgetési lekérdezéséhez

Mi az a Model Context Protocol (MCP)?

A Model Context Protocol (MCP) szabvány az AI-asszisztensek azon rendszerekhez való csatlakoztatására, ahol az adatok találhatók, beleértve a tartalomtárakat, az üzleti eszközöket és a fejlesztési környezeteket. Célja, hogy segítse a határmodelleket, hogy jobb, relevánsabb válaszokat hozhassanak létre. Gondoljunk az MCP-ra, mint egy USB-C portra az AI-alkalmazásokhoz. Ahogyan a USB-C szabványosított módot biztosít az eszközök különböző perifériákhoz és tartozékokhoz való csatlakoztatásához, az MCP szabványosított módot biztosít az AI-modellek külső adatforrásokhoz és eszközökhöz való csatlakoztatásához.

Az OpenAI, a Microsoft Copilot Studio és a Microsoft Foundry által is használt főbb AI-platformok szabványként elfogadták az MCP-t az AI-ügynökök külső rendszerekkel való integrálására. Ez ideális választássá teszi az MCP-t az AI ügynökök összekapcsolására a Fabric adataidhoz.

Miért ideális a GraphQL az MCP-hez?

A GraphQL jól használható MCP-integrációkhoz, mert:

Sémabevezetés: Az AI-ügynökök automatikusan felderíthetik az elérhető adatstruktúrákat és kapcsolatokat közvetlenül a GraphQL-sémából
Rugalmas lekérdezések: Az ügynökök pontosan azokat az adatokat kérhetik le, amelyekre egyetlen kérelemben szükségük van
Típusbiztonság: Az erős gépelés segít az AI-ügynököknek megérteni az adatformátumokat és a korlátozásokat
Hatékony adatlehívás: Csökkenti az adatok túlhívását és alulhívását

A Fabric GraphQL API-ja megkönnyíti, hogy Fabric házaidat, raktárait és adatbázisait egy szabványosított GraphQL interfészen keresztül mutassuk ki AI ügynököknek. Bár a GraphQL-hez készült API már hatékony lekérdezési képességeket biztosít, az AI-ügynökök kapcsolatának beállítása nem feltétlenül olyan egyszerű, mint amilyen lehet.

Egy egyszerű helyi GraphQL MCP-kiszolgálóval a fejlesztők AI-ügynökökkel fedezhetik fel a Fabric-adatstruktúrájukat, megismerhetik az elérhető lehetőségeket, és természetes nyelv használatával kérdezhetik le őket – mindezt a szabványosított MCP-felületen keresztül. Kényelmesen nem kell külön MCP-eszközt definiálnia a kiszolgálón minden GraphQL-típushoz, lekérdezéshez vagy mutációhoz. A GraphQL MCP-kiszolgáló felderíti a GraphQL-sémát, ami lehetővé teszi a mesterséges intelligencia ügynökök számára az összes elérhető típus és művelet megértését a kezdetektől fogva.

Előfeltételek

Mielőtt elkezdené ezt az oktatóanyagot, győződjön meg arról, hogy:

Egy Fabric munkaterület megfelelő jogosultságokkal. Munkaterület-rendszergazdai szerepkörre van szükség a szolgáltatásazonosítók konfigurálásához és a betekintés engedélyezéséhez.
GraphQL-elemhez készült és konfigurált API. Lásd: Adatok létrehozása és hozzáadása a GraphQL-hez készült API-hoz vagy a GraphQL API létrehozása az SQL-adatbázisból a Fabric portálon.
Node.js telepítve a fejlesztői gépen (az npm-et is beleértve)
A Visual Studio Code telepítve van a fejlesztői gépen

Megjegyzés:

Nem rendszergazda? Az oktatóanyag egyes lépései rendszergazdai engedélyeket igényelnek. Ha ön nem rendszergazda, akkor is elvégezheti az oktatóanyag nagy részét, ha megkéri a rendszergazdát, hogy segítsen bizonyos feladatok elvégzésében. Minden olyan lépés, amely rendszergazdai engedélyeket igényel, egyértelműen meg van jelölve.

1. lépés: Szolgáltatásnév-hozzáférés konfigurálása

A művelet leírása: Nem interaktív hitelesítési hitelesítő adatok beállítása, hogy a GraphQL MCP-kiszolgáló anélkül férhessen hozzá a Fabrichez, hogy a felhasználónak minden alkalommal be kellene jelentkeznie.

Miért fontos ez: A GraphQL MCP-kiszolgáló háttérszolgáltatásként fut, amelyet az AI-ügynökök automatikusan meghívnak. Saját identitásra (szolgáltatásnévre) van szüksége, amely hitelesítő adatokkal rendelkezik ahhoz, hogy az alkalmazás nevében hitelesítse a Fabricet, nem pedig egy adott felhasználó nevében.

Kövesse a Szolgáltatási identitások használata a Fabric API for GraphQL-lel című teljes útmutatót, hogy:

Azure-alkalmazásregisztráció létrehozása (bármely felhasználó, aki jogosult alkalmazásregisztrációk létrehozására a Microsoft Entra ID-ban)
Titkos ügyfélkód hozzáadása a Tanúsítványok > titkos kódok alatt (bármely felhasználó)
Szolgáltatásnevek engedélyezése a bérlői beállításokban (a Fabric-bérlő rendszergazdáját igényli)
Engedélyek megadása a GraphQL API-hoz és a munkaterülethez (munkaterület-rendszergazdai vagy közreműködői szerepkör szükséges)

Jótanács

Nem rendszergazda? Az első két elemet saját maga is elvégezheti. A bérlői beállításnál kérje meg a Fabric-bérlő rendszergazdáját, hogy engedélyezze a "Szolgáltatásnevek használhatják a Fabric API-kat" beállítást a Felügyeleti portál>bérlői beállításai> területen. Munkaterülethez való hozzáférésért kérje meg a munkaterület rendszergazdáját, hogy adjon hozzáférést a szolgáltatásazonosítónak a munkaterületen vagy egy adott GraphQL API-hoz.

A telepítés befejezésekor rögzítse a GraphQL MCP-kiszolgáló konfigurációjának alábbi három értékét:

Bérlőazonosító: Megtalálható a Microsoft Entra-azonosítóban az Áttekintés>bérlőazonosító alatt
Ügyfélazonosító: Az alkalmazásregisztrációban található az áttekintési>alkalmazás (ügyfél) azonosítója alatt
Titkos ügyfélkód: Az új ügyfél titkos kódjának létrehozásakor megjelenő titkos kód (azonnal másolás – ez csak egyszer jelenik meg)

2. lépés: A GraphQL introspection engedélyezése (munkaterület-rendszergazda szükséges)

A művelet leírása: Az introspection engedélyezése lehetővé teszi, hogy a GraphQL MCP-kiszolgáló megkérdezze a GraphQL API-t "Milyen adatokkal rendelkezik?", és teljes leírást kap az összes elérhető típusról, mezőről és kapcsolatról.

Miért fontos ez: Ez az a "varázslat", amely lehetővé teszi a természetes nyelvi lekérdezéseket. Amikor megkérdezi a Copilottól a "Mutasd meg az ügyfeleket" kérdést, az AI-ügynök először introspection használatával deríti fel, hogy létezik-e típus customers , milyen mezőkkel rendelkezik, és hogyan kérdezheti le. Önvizsgálat nélkül manuálisan kell dokumentálnia az AI teljes struktúráját.

Fontos

A GraphQL MCP-kiszolgáló működéséhez engedélyezni kell az introspection használatát. Ez biztonsági okokból alapértelmezés szerint le van tiltva a Fabric rendszerben. Csak a munkaterület rendszergazdái engedélyezhetik az introspection-t. Ha ön nem rendszergazda, kérje meg a munkaterület rendszergazdáját, hogy végezze el ezt a lépést.

Kövesse a Fabric API teljes útmutatóját a GraphQL Introspection és Schema Export céljából:

Önvizsgálat engedélyezése az API-beállításokban
Az introspekciós lekérdezések működésének ismertetése
Tudnivalók a sémaexportálási lehetőségekről

Az introspection engedélyezése után a GraphQL MCP-kiszolgáló lekérdezheti a sémastruktúrát, és elérhetővé teheti az AI-ügynökök számára.

3. lépés: A GraphQL MCP-kiszolgáló beállítása

A művelet leírása: A Model Context Protocolt implementáló helyi Node.js-kiszolgáló telepítése és konfigurálása. Ez a kiszolgáló fordítóként működik az AI-ügynökök és a Fabric GraphQL API között.

Miért fontos ez: Az MCP-kiszolgáló egy szabványosított felületet biztosít, amelyet az AI-ügynökök ismernek. Amikor egy AI-ügynök csatlakozik, felfedezheti, hogy milyen eszközök érhetők el (bevezető és lekérdezés), meghívhatja ezeket az eszközöket, és válaszokat kaphat – mindezt anélkül, hogy egyéni integrációs kódot ír az egyes AI-platformokhoz.

Most, hogy rendelkezik hitelesítési hitelesítő adatokkal (1. lépés) és engedélyezte az introspekciót (2. lépés), készen áll arra, hogy ezeket beállítsa a kiszolgálón.

A mintaadattár klónozása

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

Függőségek telepítése

npm install

Környezeti változók konfigurálása

Hozzon létre egy .env fájlt a projekt gyökérkönyvtárában a saját konfigurációjával.

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

Cserélje le a helyőrző értékeket a következőre:

MICROSOFT_FABRIC_API_URL: A GraphQL-végpont a Fabric portálról
MICROSOFT_FABRIC_TENANT_ID: Az Azure-bérlő azonosítója
MICROSOFT_FABRIC_CLIENT_ID: Az alkalmazásregisztrációs ügyfél azonosítója
MICROSOFT_FABRIC_CLIENT_SECRET: Az alkalmazásregisztrációs ügyfél titkos kódja

A GraphQL MCP-kiszolgáló indítása

node FabricGraphQL_MCP.js

A kiszolgáló beindul http://localhost:3000 és megjelenik:

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

Elérhető MCP-eszközök

A GraphQL MCP-kiszolgáló két fő eszközt biztosít:

`introspect-schema`

Cél: A teljes GraphQL-séma lekérése
Paraméterek: Nincs
Használat: Először meg kell hívni, mielőtt lekérdezéseket lehetne készíteni

`query-graphql`

Cél: GraphQL-lekérdezések végrehajtása a Fabric-adatokon
Paraméterek:
- query (kötelező): A GraphQL lekérdezési sztringje
- variables (nem kötelező): GraphQL-változók objektuma
Használat: Az összes adatlekérési és -kezelési művelethez

A munkafolyamat ismertetése

A Tipikus GraphQL MCP-munkafolyamat a következő mintát követi:

Sémafelderítés: Az AI-ügynöknek először meg kell hívnia az eszközt a introspect-schema séma és a rendelkezésre álló adatok megértéséhez
Lekérdezéstervezés: Az ügynök elemzi a természetes nyelvi kérést és a GraphQL-sémát
Lekérdezés létrehozása: Az ügynök megfelelő GraphQL-lekérdezéseket hoz létre
Végrehajtás: Az ügynök meghívja az query-graphql eszközt a létrehozott lekérdezésekkel
Válaszfeldolgozás: Ügynökformátumok és az eredmények megjelenítése

4. lépés: A GraphQL MCP-kiszolgáló tesztelése

A művelet leírása: Annak ellenőrzése, hogy az MCP-kiszolgáló képes-e hitelesítést végezni a Fabricben, lekérni a sémát, és lekérdezéseket végrehajtani az AI-ügynökök csatlakoztatása előtt.

Miért fontos ez: A manuális tesztelés biztosítja, hogy minden megfelelően legyen konfigurálva. Ha ezek a tesztek sikeresek, tudja, hogy az AI-ügynökök sikeresen tudnak csatlakozni az 5. lépésben.

Kiszolgáló állapotának ellenőrzése

Először ellenőrizze, hogy a kiszolgáló fut-e, és képes-e hitelesítést végezni a Fabricben.

A PowerShell használatával:

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

A cURL használata:

curl http://localhost:3000/health

A következőhöz hasonló választ kell kapnia, amely jelzi, hogy a kiszolgáló fut:

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

Sémabetekintés tesztelése

Ezután ellenőrizze, hogy a kiszolgáló introspekcióval le tudja-e kérni a GraphQL-sémát. Ez meghívja az introspect-schema MCP eszközt.

A PowerShell használatával:

$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

A cURL használata:

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

Ennek a GraphQL-sémadefiníciót kell visszaadnia.

GraphQL-lekérdezés tesztelése

Végül tesztelje egy tényleges GraphQL-lekérdezés végrehajtását az MCP-kiszolgálón keresztül. Ez a példa az MCP eszközzel lekérdezi a séma összes típusnevét query-graphql .

A PowerShell használatával:

$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

A cURL használata:

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

Ez a GraphQL-séma összes típusának listáját adja vissza.

5. lépés: AI-ügynökök csatlakoztatása

Amit csinálsz: MI-eszközök konfigurálása a helyi MCP-kiszolgáló adatforrásként való használatára.

Miért fontos ez: Itt jön össze minden. A csatlakozás után az AI-ügynökök bevezető művelettel felfedezhetik a Fabric-sémát, és természetes nyelvi kérések alapján GraphQL-lekérdezéseket hozhatnak létre. Az AI kezeli a lekérdezés szintaxisát – csak egyszerű angol nyelven tehet fel kérdéseket.

GitHub Copilot a Visual Studio Code-ban

A GitHub Copilot-bővítmény telepítése a VS Code-ban

Konfigurálja a GraphQL MCP-kiszolgálót a Copilot-beállításokban:

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

A Copilot csevegésben először kérdezze meg a séma feltérképezését, majd próbáljon meg természetes nyelven feltenni egy releváns kérdést a feltérképezett adatokkal kapcsolatban, például:

Kurzor IDE

A Kurzor beállításainak megnyitása

Adja hozzá az MCP-kiszolgáló konfigurációját:

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

A csevegésben először kérje meg, hogy vizsgálja meg a sémát, majd próbáljon meg természetes nyelven feltenni egy kapcsolódó kérdést a vizsgált adatokkal kapcsolatban.

Amit építettél

Gratulálok! Most már rendelkezik egy működő GraphQL MCP-kiszolgálóval, amely:

Azonosítás a Fabric szolgáltatás-alapú azonosító hitelesítő adataival
A Fabric-adatsémát felfedi introspection révén
Mesterséges intelligencia ügynök kéréseinek átalakítása GraphQL-lekérdezésekké
Olyan formátumú adatokat ad vissza, amely az AI-ügynökök számára érthető és megjeleníthető

Az AI-ügynökök (például a GitHub Copilot) mostantól:

A Fabric-munkaterületen elérhető adatok automatikus felderítése
Helyes GraphQL-lekérdezések létrehozása természetes nyelvi kérdések alapján
Eredmények lekérése és formázása lekérdezési kód írása nélkül

Ez a helyi kiszolgáló fejlesztésre és tanulásra szolgál. Az alábbi szakaszok a termelési telepítések kritikus szempontjait és a gyakori hibaelhárítási forgatókönyveket ismertetik.

Biztonsági szempontok

Bár a helyi GraphQL MCP-kiszolgálót fejlesztési célokra csak az oktatóanyagban leírtak szerint kell implementálni, http-átvitelsel implementálva, így egyszerűbben használható kiindulópontként összetettebb ügyfélkiszolgálói vagy webes integrációkhoz. Ha GraphQL MCP-kiszolgálókat helyez üzembe éles környezetben:

Az Azure Key Vault használata fájlok helyett titkok tárolására
Megfelelő engedélyezési, hálózati biztonsági és tűzfalszabályok implementálása
Minden GraphQL-lekérdezés naplózásának engedélyezése
Az Azure App Service vagy a Container Instances használata üzemeltetéshez
Sebességkorlátozás és hitelesítés implementálása az MCP-végpontokhoz
Ügyfél titkos kulcsainak és tanúsítványainak rendszeres elforgatása

Hibaelhárítás

Gyakori problémák és megoldások

Hitelesítési hibák

Ellenőrizze, hogy az Azure-alkalmazásregisztráció rendelkezik-e a megfelelő engedélyekkel
Ellenőrizze, hogy a szolgáltatási főszereplők engedélyezve vannak-e a Fabric bérlői környezetében
Győződjön meg arról, hogy az ügyfél titkos kódja nem járt le

A sémabevezetés sikertelen

Ellenőrizze, hogy engedélyezve van-e az introspection a GraphQL API-beállításokban
Ellenőrizze, hogy a GraphQL-végpont URL-címe helyes-e
Hálózati kapcsolat ellenőrzése a Fabric-munkaterülethez

Az AI-ügynök nem ismeri fel az eszközöket

A konfigurációs módosítások után indítsa újra az AI-ügyfelet
Ellenőrizze, hogy az MCP-kiszolgáló URL-címe elérhető-e
Ellenőrizze a kiszolgálónaplókat, hogy vannak-e hibaüzenetek

Lekérdezésvégrehajtási hibák

A naplózott lekérdezések és hibák áttekintése a kiszolgálókonzolon
Győződjön meg arról, hogy a lekérdezések megfelelnek az elérhető sémának
Ellenőrizze, hogy rendelkezik-e megfelelő engedélyekkel a kért adatokhoz

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-08-05

AI-ügynökök csatlakoztatása a GraphQL-hez készült Fabric API-hoz egy helyi Model Context Protocol (MCP) kiszolgálóval

Mi az a Model Context Protocol (MCP)?

Miért ideális a GraphQL az MCP-hez?

Előfeltételek

1. lépés: Szolgáltatásnév-hozzáférés konfigurálása

2. lépés: A GraphQL introspection engedélyezése (munkaterület-rendszergazda szükséges)

3. lépés: A GraphQL MCP-kiszolgáló beállítása

A mintaadattár klónozása

Függőségek telepítése

Környezeti változók konfigurálása

A GraphQL MCP-kiszolgáló indítása

Elérhető MCP-eszközök

introspect-schema

query-graphql

A munkafolyamat ismertetése

4. lépés: A GraphQL MCP-kiszolgáló tesztelése

Kiszolgáló állapotának ellenőrzése

Sémabetekintés tesztelése

GraphQL-lekérdezés tesztelése

5. lépés: AI-ügynökök csatlakoztatása

GitHub Copilot a Visual Studio Code-ban

Kurzor IDE

Amit építettél

Biztonsági szempontok

Hibaelhárítás

Gyakori problémák és megoldások

Kapcsolódó tartalom

Visszajelzés

További források

`introspect-schema`

`query-graphql`