Yerel Model Bağlam Protokolü (MCP) sunucusuyla AI Aracılarını GraphQL için Doku API'sine bağlama

GitHub Copilot'a "Son çeyrekteki tüm satışları göster" sorusunu sorduğunu ve tek bir GraphQL satırı yazmadan Doku veri ambarınızı otomatik olarak sorgulamasını, şemayı anlamasını ve sonuçları döndürmesini istediğini düşünün. Bu öğretici, bunu nasıl mümkün kılabileceğinizi gösteriyor.

Bu öğreticide, yapay zeka aracıları ile Microsoft Fabric verileriniz arasında köprü görevi gören yerel bir GraphQL MCP sunucusu oluşturacaksınız. Sonunda GitHub Copilot, Claude ve diğer yapay zeka aracıları gibi yapay zeka yardımcılarının konuşma dilini kullanarak Doku verilerinizi doğal olarak sorgulamasını sağlayan çalışan bir geliştirme sunucunuz var.

Başaracakların:

GraphQL MCP sunucunuzun Doku'ya güvenli bir şekilde erişebilmesi için kimlik doğrulamasını ayarlama
Yapay zeka aracılarının veri yapınızı otomatik olarak bulabilmesi için şema giriş özelliğini etkinleştirin
Doğal dili GraphQL sorgularına çeviren yerel bir GraphQL MCP sunucusu dağıtma
Verilerinizi konuşma yoluyla sorgulamak için GitHub Copilot veya diğer yapay zeka araçlarını bağlama

Model Bağlam Protokolü (MCP) nedir?

Model Bağlam Protokolü (MCP), yapay zeka yardımcılarını içerik depoları, iş araçları ve geliştirme ortamları gibi verilerin bulunduğu sistemlere bağlamak için kullanılan bir standarttır. Amacı, sınır modellerinin daha iyi, daha ilgili yanıtlar üretmesine yardımcı olmaktır. MCP'i yapay zeka uygulamaları için USB-C bağlantı noktası gibi düşünün. USB-C cihazlarınızı çeşitli çevre birimlerine ve aksesuarlara bağlamak için standartlaştırılmış bir yol sağladığı gibi, MCP de yapay zeka modellerini dış veri kaynaklarına ve araçlarına bağlamak için standartlaştırılmış bir yol sağlar.

OpenAI, Microsoft Copilot Studio ve Microsoft Foundry gibi büyük yapay zeka platformları, yapay zeka aracılarını dış sistemlerle tümleştirmenin standart bir yolu olarak MCP'yi benimsemiştir. Bu, MCP'yi yapay zeka aracılarını Microsoft Fabric verilerinize bağlamak için ideal bir seçenek haline getirir.

GraphQL neden MCP için idealdir?

GraphQL, MCP tümleştirmeleri için uygundur çünkü:

Şema sorgulama: Yapay zeka ajanları, kullanılabilir veri yapılarını ve ilişkileri doğrudan GraphQL şemasından otomatik olarak keşfedebilir
Esnek sorgular: Aracılar tek bir istekte tam olarak ihtiyaç duydukları verileri isteyebilir
Tür güvenliği: Güçlü yazma, yapay zeka aracılarının veri biçimlerini ve kısıtlamalarını anlamasına yardımcı olur
Verimli veri getirme: Verilerin aşırı getirilme ve az getirilme durumlarını azaltır

GraphQL için Microsoft Fabric API'si, standart bir GraphQL arabirimi aracılığıyla Fabric lakehouse'larınızı, Veri Ambarlarınızı ve veritabanlarınızı yapay zeka aracılarının kullanımına sunmanızı kolaylaştırır. GraphQL için API zaten güçlü sorgulama özellikleri sağlasa da, yapay zeka aracıları için bağlantı kurmak olabildiğince kolay olmayabilir.

Basit bir yerel GraphQL MCP sunucusuyla geliştiriciler yapay zeka aracılarını kullanarak Doku veri yapılarını keşfedebilir, kullanılabilir olanları anlayabilir ve standartlaştırılmış MCP arabirimi aracılığıyla doğal dil kullanarak sorgulayabilir. Uygun bir şekilde, her GraphQL türü, sorgusu veya mutasyonu için sunucuda ayrı bir MCP aracı tanımlamanız gerekmez. GraphQL MCP sunucusu, yapay zeka aracılarının kullanıma hazır olan tüm türleri ve işlemleri anlamasını güçlendiren GraphQL şemasını gözden geçirir.

Önkoşullar

Bu öğreticiye başlamadan önce şunları yaptığınızdan emin olun:

Uygun izinlere sahip bir Microsoft Fabric çalışma alanı. Hizmet sorumlularını yapılandırmak ve introspection'ı etkinleştirmek için bir çalışma alanı yöneticisi rolü gereklidir.
GraphQL öğesi için oluşturulan ve yapılandırılan bir API. Fabric portalında bkz. GraphQL için API oluşturma ve API'ye veri ekleme veya SQL veritabanınızdan GraphQL API oluşturma.
Geliştirme makinenizde yüklü Node.js (npm içerir)
Geliştirme makinenizde yüklü Visual Studio Code

Uyarı

Yönetici değil misiniz? Bu öğreticideki bazı adımlar için yönetici izinleri gerekir. Yönetici değilseniz, yöneticinizden belirli görevlerle ilgili yardım isteyerek öğreticinin büyük bölümünü tamamlayabilirsiniz. Yönetici izinleri gerektiren her adım açıkça işaretlenir.

1. Adım: Hizmet sorumlusu erişimini yapılandırma

Yaptığınız şey: GraphQL MCP sunucunuzun her seferinde kullanıcının oturum açmasına gerek kalmadan Doku'ya erişebilmesi için etkileşimli olmayan kimlik doğrulama kimlik bilgilerini ayarlama.

Bu neden önemlidir: GraphQL MCP sunucusu, yapay zeka aracılarının otomatik olarak çağırdiği bir arka plan hizmeti olarak çalışır. Uygulamanız adına Fabric'de kimlik doğrulaması yapmak için belirli bir kullanıcı adına değil, kendi kimliğine (hizmet sorumlusu) ve kimlik bilgilerine ihtiyacı vardır.

GraphQL için Fabric API ile Hizmet Sorumlularını Kullanma konusundaki rehberin tamamını takip edin:

Azure Uygulama Kaydı oluşturma (Microsoft Entra Id'de uygulama kaydı oluşturma izinlerine sahip tüm kullanıcılar)
Sertifikalar ve gizli anahtarlar (herhangi bir kullanıcı) altına bir istemci gizli anahtarı ekleyin
Kiracı ayarlarında hizmet ilkelerini etkinleştirme (Fabric kiracı yöneticisi gerektirir)
GraphQL API'nize ve çalışma alanınıza izin verme (çalışma alanı yöneticisi veya katkıda bulunan rolü gerektirir)

Tavsiye

Yönetici değil misiniz? İlk iki öğeyi kendiniz tamamlayabilirsiniz. Kiracı ayarı için, Doku kiracı yöneticinizden Yönetici portalı>Kiracı ayarları> altında "Hizmet sorumluları Doku API'lerini kullanabilir" seçeneğini etkinleştirmesini isteyin. Çalışma alanı izinleri için çalışma alanı yöneticinizden hizmet sorumlusuna çalışma alanı veya belirli GraphQL API'sine erişim izni vermesini isteyin.

Kurulumu tamamladığınızda GraphQL MCP sunucu yapılandırması için şu üç değeri yakalayın:

Kiracı Kimliği: Microsoft Entra ID'de Genel Bakış altında >Kiracı Kimliği bulunur
İstemci Kimliği: Uygulama Kaydınızda Genel Bakış>Uygulaması (istemci) Kimliği altında bulunur
Müşteri Sırrı: Yeni bir müşteri sırrı oluşturduğunuzda görüntülenen gizli değer (hemen kopyalayın—yalnızca bir kez gösterilir)

2. Adım: GraphQL introspection'ı etkinleştirme (çalışma alanı yöneticisi gerektirir)

Yaptığınız şey: İçe aktarmayı etkinleştirmek, GraphQL MCP sunucusunun GraphQL API'nize "Hangi verileriniz var?" sorusunu sormasını ve kullanılabilir tüm türlerin, alanların ve ilişkilerin tam açıklamasını almasını sağlar.

Bu neden önemlidir: Bu, doğal dil sorgularını mümkün kılan "büyü"dür. Copilot'a "Müşterileri göster" sorusunu sorduğunuzda, yapay zeka aracısı ilk olarak bir customers türün var olduğunu, hangi alanlara sahip olduğunu ve nasıl sorgulandığını keşfetmek için iç gözlem kullanır. İç gözlem olmadan, yapay zeka için şemanızın tamamını el ile belgelemelisiniz.

Önemli

GraphQL MCP sunucusunun çalışması için introspection etkinleştirilmelidir. Bu, güvenlik nedeniyle Fabric'de varsayılan olarak devre dışı bırakılır. Yalnızca çalışma alanı yöneticileri iç gözlemi etkinleştirebilir. Yönetici değilseniz çalışma alanı yöneticinizden bu adımı tamamlamasını isteyin.

GraphQL için Microsoft Fabric API'sinde Giriş ve Şema Dışarı Aktarma kılavuzunun tamamını izleyin:

API ayarlarınızda introspection'ı etkinleştirme
İçe dönük sorguların nasıl çalıştığını anlama
Şema dışarı aktarma seçenekleri hakkında bilgi edinin

Giriş etkinleştirildikten sonra GraphQL MCP sunucusu şema yapınızı sorgulayabilir ve yapay zeka aracılarının kullanımına sunabilir.

3. Adım: GraphQL MCP sunucusunu ayarlama

Yaptığınız şey: Model Bağlam Protokolü uygulayan yerel bir Node.js sunucusu yükleme ve yapılandırma. Bu sunucu, yapay zeka aracıları ile Doku GraphQL API'niz arasında çevirici işlevi görür.

Bu neden önemlidir: MCP sunucusu, yapay zeka aracılarının anladığı standartlaştırılmış bir arabirim sağlar. Bir yapay zeka aracısı bağlandığında, her bir yapay zeka platformu için özel entegrasyon kodu yazmanıza gerek kalmadan, hangi araçların mevcut olduğunu keşfeder (içgözlem ve sorgulama yaparak), bu araçları çağırır ve yanıtlar alır.

Artık kimlik doğrulama kimlik bilgileriniz (1. Adım) ve içgiriş etkin (2. Adım) olduğuna göre, sunucuyu bunları kullanacak şekilde yapılandırmaya hazırsınız demektir.

Örnek depoyu klonlayın

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

Bağımlılıkları yükleme

npm install

Ortam değişkenlerini yapılandırma

Yapılandırmanızla proje kökünde bir .env dosya oluşturun:

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

Yer tutucu değerlerini şununla değiştirin:

MICROSOFT_FABRIC_API_URL: Fabric portalından GraphQL uç noktanız
MICROSOFT_FABRIC_TENANT_ID: Azure kiracı kimliğiniz
MICROSOFT_FABRIC_CLIENT_ID: Uygulama kaydı istemci kimliğiniz
MICROSOFT_FABRIC_CLIENT_SECRET: Uygulama kaydı istemci gizli anahtarınız

GraphQL MCP sunucusunu başlatma

node FabricGraphQL_MCP.js

Sunucu http://localhost:3000 üzerinde başlar ve ekrana gelir:

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

Kullanılabilir MCP araçları

GraphQL MCP sunucusu iki ana araç sağlar:

`introspect-schema`

Amaç: GraphQL şemasının tamamını alır
Parametreler: Yok
Kullanım: Sorgular yapmadan önce çağrılmalıdır

`query-graphql`

Amaç: Fabric verilerinizde GraphQL sorguları yürütür
Parametreler:
- query (gerekli): GraphQL sorgu dizesi
- variables (isteğe bağlı): GraphQL değişkenleri nesnesi
Kullanım: Tüm veri alma ve işleme işlemleri için

İş akışını anlama

Tipik GraphQL MCP iş akışı şu deseni izler:

Şema Bulma: AI aracısı şemayı introspect-schema ve kullanılabilir verileri anlamak için önce aracıyı çağırmalıdır
Sorgu Planlama: Aracı, doğal dil isteğinizi ve GraphQL şemasını analiz eder
Sorgu Oluşturma: Aracı uygun GraphQL sorguları oluşturur
Yürütme: Aracı, aracıyı query-graphql oluşturulan sorgularla çağırır
Yanıt İşleme: Aracı sonuçları biçimlendirip sunar

4. Adım: GraphQL MCP sunucusunu test edin

Yaptığınız şey: Yapay zeka aracılarını bağlamadan önce MCP sunucunuzun Doku'da kimlik doğrulaması gerçekleştirebildiğini, şemanızı alabildiğini ve sorguları yürütebildiğini doğrulama.

Bu neden önemlidir: El ile test, her şeyin doğru yapılandırılmasını sağlar. Bu testler başarılı olursa, 5. Adımda yapay zeka aracılarının başarıyla bağlanabildiğini biliyorsunuz.

Sunucu durumunu doğrulama

İlk olarak, sunucunun çalıştığını ve Fabric'de kimlik doğrulaması yapabiliyor olduğunu onaylayın.

PowerShell’i kullanarak:

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

cURL'ü Kullanma:

curl http://localhost:3000/health

Sunucunun çalıştığını belirten aşağıdakine benzer bir yanıt almalısınız:

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

Şema iç denetimini test edin

Ardından sunucunun betimleme yoluyla GraphQL şemanızı alabildiğini kontrol edin. Bu, introspect-schema MCP aracını çağırır.

PowerShell’i kullanarak:

$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 Kullanımı:

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

Bu, GraphQL şema tanımınızı döndürmelidir.

GraphQL sorgusunu test edin

Son olarak, MCP sunucusu aracılığıyla gerçek bir GraphQL sorgusu yürütmeyi test edin. Bu örnek, MCP aracını kullanarak şemanızdaki tüm tür adlarını sorgular query-graphql .

PowerShell’i kullanarak:

$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'ü Kullanma:

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

Bu, GraphQL şemanızdaki tüm türlerin listesini döndürür.

5. Adım: Yapay zeka aracılarını bağlama

Yaptığınız şey: Yerel MCP sunucunuzu veri kaynağı olarak kullanmak için yapay zeka araçlarını yapılandırma.

Bu neden önemlidir: Burası her şeyin bir araya geldiği yer. Bağlandıktan sonra yapay zeka aracılarınız iç gözlem aracılığıyla Doku şemanızı bulabilir ve doğal dil isteklerine göre GraphQL sorguları oluşturabilir. Yapay zeka sorgu söz dizimini işler; yalnızca soruları düz İngilizce sorarsınız.

Visual Studio Code'da GitHub Copilot

VS Code'da GitHub Copilot uzantısını yükleme

Copilot ayarlarınızda GraphQL MCP sunucusunu yapılandırın:

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

Copilot sohbetinde önce şemayı incelemeyi ve ardından introspeksiyon yapılan verilerle ilgili doğal dilde bir soru sormayı deneyin, örneğin:

İmleç IDE

İmleç ayarlarını açma

MCP sunucu yapılandırmasını ekleyin:

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

Sohbette, önce şemayı incelemeyi isteyin, ardından incelenmiş verilerle ilgili doğal dilde bir soru sormayı deneyin.

Oluşturduğunuz şey

Tebrikler! Artık şu şekilde çalışan bir GraphQL MCP sunucunuz var:

Hizmet sorumlusu kimlik bilgilerini kullanarak Fabric'te kimlik doğrulaması yapar
Özdüşünüm aracılığıyla Fabric veri şemanızı kullanıma sunar
Yapay zeka aracısı isteklerini GraphQL sorgularına çevirir
Yapay zeka aracılarının anlayabileceği ve sunabileceği biçimde veri döndürür

Yapay zeka aracılarınız (GitHub Copilot gibi) artık:

Fabric çalışma alanınızda hangi verilerin mevcut olduğunu otomatik olarak keşfedin
Doğal dil sorularını temel alarak doğru GraphQL sorguları oluşturma
Sorgu kodu yazmadan sonuçları alma ve biçimlendirme

Bu yerel sunucu geliştirme ve öğrenmeye yöneliktir. Aşağıdaki bölümlerde üretim dağıtımları ve yaygın sorun giderme senaryolarıyla ilgili önemli noktalar ele alınmalıdır.

Güvenlikle ilgili dikkat edilmesi gerekenler

Yerel GraphQL MCP sunucusunun yalnızca bu öğreticide açıklandığı gibi geliştirme amacıyla uygulanması gerekir ancak HTTP aktarımı ile uygulanır ve bu da daha karmaşık istemci-sunucu veya web tabanlı tümleştirmeler için başlangıç noktası olarak kullanılmasını kolaylaştırır. GraphQL MCP sunucularını üretim ortamında dağıtıyorsanız:

Dosyalar yerine gizli dizileri depolamak için Azure Key Vault kullanma .env
Uygun yetkilendirme, ağ güvenliği ve güvenlik duvarı kurallarını uygulama
Tüm GraphQL sorguları için denetim günlüğünü etkinleştirme
Barındırma için Azure App Service veya Container Instances kullanma
MCP uç noktaları için hız sınırlama ve kimlik doğrulaması uygulama
İstemci gizli anahtarlarını ve sertifikaları düzenli olarak yenileyin.

Sorun giderme

Yaygın sorunlar ve çözümler

Kimlik doğrulama hataları

Azure Uygulama Kaydınızın doğru izinlere sahip olduğunu doğrulayın
Fabric kiracınızdaki hizmet ilkelerinin etkinleştirildiğini kontrol edin.
İstemci gizli anahtarınızın süresinin dolmadığından emin olun

Şema iç gözlemi başarısız oluyor

GraphQL API ayarlarınızda içgörü özelliğinin etkinleştirildiğini onaylayın
GraphQL uç nokta URL'nizin doğru olup olmadığını denetleyin
Fabric çalışma alanınıza ağ bağlantısını doğrulayın

Yapay zeka aracısı araçları tanımıyor

Yapılandırma değiştikten sonra yapay zeka istemcinizi yeniden başlatın
MCP sunucusu URL'sinin erişilebilir olduğunu doğrulama
Hata iletileri için sunucu günlüklerini denetleme

Sorgu yürütme hataları

Sunucu konsolunu, günlüğe kaydedilen sorgular ve hatalar için gözden geçirin.
Sorgularınızın kullanılabilir şemayla eşleştiğinden emin olun
İstenen veriler için uygun izinlere sahip olup olmadığınızı denetleyin

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-21

Aracılığıyla paylaş

Yerel Model Bağlam Protokolü (MCP) sunucusuyla AI Aracılarını GraphQL için Doku API'sine bağlama

Model Bağlam Protokolü (MCP) nedir?

GraphQL neden MCP için idealdir?

Önkoşullar

1. Adım: Hizmet sorumlusu erişimini yapılandırma

2. Adım: GraphQL introspection'ı etkinleştirme (çalışma alanı yöneticisi gerektirir)

3. Adım: GraphQL MCP sunucusunu ayarlama

Örnek depoyu klonlayın

Bağımlılıkları yükleme

Ortam değişkenlerini yapılandırma

GraphQL MCP sunucusunu başlatma

Kullanılabilir MCP araçları

introspect-schema

query-graphql

İş akışını anlama

4. Adım: GraphQL MCP sunucusunu test edin

Sunucu durumunu doğrulama

Şema iç denetimini test edin

GraphQL sorgusunu test edin

5. Adım: Yapay zeka aracılarını bağlama

Visual Studio Code'da GitHub Copilot

İmleç IDE

Oluşturduğunuz şey

Güvenlikle ilgili dikkat edilmesi gerekenler

Sorun giderme

Yaygın sorunlar ve çözümler

İlgili içerik

Geri Bildirim

Ek kaynaklar

`introspect-schema`

`query-graphql`