Ana içeriğe geç

partner-center-mcp'yi yazarken öğrendiklerim

· 7 dakikalık okuma

Partner Center REST API'siyle geliştirme yapmak, Microsoft Learn'de yaşamak demek. Microsoft, Partner Center .NET SDK'sını Haziran 2023'te arşivledi ve partner'ları REST API'lere yönlendiriyor; ama SDK hâlâ arama sonuçlarında çıkıyor. Emekliye ayrılmış graph.windows.net audience'ı için token isteyip 900420 hatasıyla 401 alan kod da öyle. Bu materyalle eğitilmiş bir model, hepsini kendinden emin bir şekilde yeniden üretiyor.

partner-center-mcp, güncel dokümantasyonu agent'ın yanına koymak için yazdığım MCP server. Bu yazı arkasındaki kararları ve bir MCP server tasarlayan herkese söyleyeceklerimi anlatıyor.

Ne yapıyor?​

Partner Center REST API'si için bir bilgi ve kod üretme asistanı. Bir subscription'ın nasıl iptal edileceğini sorduğunuzda doğrulanmış method'u, path'i ve header'ları, bir kod örneğini, dokümantasyonun uyardığı kısıtları ve cevabın kontrol edildiği docUrl'i döndürüyor.

Tool'lar birkaç gruba ayrılıyor. Bazıları bir şey arıyor: senaryolar, enum değerleri, resource alanları, hata kodları. Bazıları üretiyor: pc_generate_call curl, C#, TypeScript ya da PowerShell ile bir REST çağrısı yazıyor, arşivlenmiş SDK ile asla. Bazıları lint ediyor: pc_check_auth, graph.windows.net audience'ı ve ADAL gibi emekli auth kalıplarını işaretliyor; pc_validate_request bir çağrıyı bilinen senaryolarla karşılaştırıyor. pc_migrate_from_sdk, arşivlenmiş SDK kodunu karşılık gelen REST senaryolarına çeviriyor. Bir grup pc_plan_* tool'u da New Commerce satın alımı ya da GDAP onboarding gibi sıralı iş akışları döndürüyor.

npx partner-center-mcp ile çalışıyor; varsayılan olarak stdio üzerinden, isteğe bağlı bir Streamable HTTP varyantıyla. Aynı bilgi paketi NuGet'te bir .NET server olarak da yayınlanıyor.

Server'ın asla ne yapmayacağına karar verin​

En önemli karar neyin dışarıda kalacağıydı. partner-center-mcp hiçbir credential tutmuyor ve Partner Center'ı hiç çağırmıyor. Paketle gelen bir bilgi paketini okuyor, yedek olarak da Microsoft Learn'de arama yapıyor.

Bu tek karar zor problemlerin çoğunu ortadan kaldırıyor. Sızacak bir token, zarar görecek bir tenant yok; bir prompt injection'ın bir satın alıma dönüşmesinin yolu yok. Her tool dürüstçe readOnlyHint: true ve destructiveHint: false olarak işaretlenebiliyor.

Annotation'ların en kötü durumu anlatması gerekiyor, bu yüzden istisnalar da beyan ediliyor: pc_search_docs ve enrich: true ile çağrılan pc_get_scenario ağa çıkıyor; pc_build_request her çağrıda yeni bir MS-RequestId üretiyor. Bu yüzden hiçbiri idempotent ve offline olduğunu iddia etmiyor. Spesifikasyon, server güvenilir değilse client'ların annotation'ları güvenilmez saymasını söylüyor; yani bunlar garanti değil, bilgi. Doğru tutmak için bir sebep daha.

Genel tavsiyem: tool'ları seçmeden önce server'ın asla yapamaması gereken şeyleri yazın. Hâlâ işe yarayan en küçük server, genellikle kapsadığı API'den çok daha küçüktür.

Dar tool'lar ve hangi kardeşin kullanılacağı​

Server'da her biri tek bir iş yapan otuza yakın tool var. Bu, normalde önereceğimden fazla ve bir bedeli var: modelin doğru olanı seçmesi gerekiyor. Bu yükü açıklamalar taşıyor. Her biri tool'un ne zaman kullanılacağını ve onun yerine hangi kardeşinin tercih edilmesi gerektiğini söylüyor. Bu, pc_lookup_error'ın kısaltılmış açıklaması:

Look up a Partner Center error by its numeric code or HTTP status ...
Use this when you already have a clean code. If you have a raw error response,
pc_decode_error is better. For a symptom described in prose with no code at all,
use pc_diagnose. Read-only, offline, deterministic.

Her parametrenin de bir açıklaması var ve soru soramayan bir okuyucu için yazılmış: "Matched exactly, so strip surrounding text first." Her tool'un ayrıca bir title'ı ve beyan edilmiş bir outputSchema'sı var.

Genel ders şu: bir tool açıklaması sözleşmenin tamamıdır. Model kaynak kodunuzu hiç görmez. İki tool örtüşüyorsa aradaki çizgiyi açıklama çekmeli, yoksa model onu rastgele çeker. Bunu bir LLM'in doğru kullanabileceği tool'lar tasarlamak yazısında daha ayrıntılı anlattım.

Cevapları modelin hafızasına değil, dokümantasyona dayandırın​

Server'ın var olma sebebi, sorunun modelin hafızası olması. Bu yüzden cevaplar modelden değil, veriden geliyor.

Bilgi paketi data/ içinde JSON olarak duruyor. Her dosya yüklenirken bir zod şemasıyla doğrulanıyor; bozuk veri bir cevapta değil, başlangıçta patlıyor. Her senaryo doğrulandığı docUrl'i ve son kontrol edildiği tarihi taşıyor; 185 tanesi de Learn sayfasının yayınladığı cevap örneğiyle geliyor, böylece alan adları tahmin edilmek yerine okunabiliyor.

Pakette cevap yoksa pc_search_docs Microsoft Learn'de arama yapıyor. Başarılı sonuçlar sınırlı bir cache'te on dakika tutuluyor. Canlı arama başarısız olursa sonuç boş geliyor, ama yanında bunu söyleyen ve derlenmiş pakete geri yönlendiren bir note oluyor; hiçbir şey bulamamış bir arama gibi görünmüyor. Açıklaması da modele önce doğrulanmış, offline tool'ları denemesini söylüyor.

Kimsenin kontrol etmediği bir paket, bayat bir hafızadan ibaret kalır; bu yüzden doğrulama işin içine gömülü. npm run check-pack her pull request'te offline çalışıyor ve her senaryonun method'unu, path'ini ve header'larını, Learn sayfalarının söylediklerinin commit'lenmiş bir anlık görüntüsüyle karşılaştırıyor. npm run check-docs her hafta GitHub Actions'ta çalışıyor, referans verilen her sayfayı yeniden çekiyor ve bir sayfa taşındığında, kaldırıldığında ya da paketin dayandığı bir alanı değiştirdiğinde bir issue açıyor.

Dokümanlara dayandırmak bir kez eklenip bırakılan bir özellik değil, bir bakım taahhüdü. Bir server'ı dokümanlara dayandırıyorsanız, dokümanlar değiştiğinde bunu nasıl öğreneceğinizi de planlayın.

Modelin üzerine işlem yapabileceği hatalar​

Her tool aynı zarfla cevap veriyor: başarıda { ok, data }, hatada { ok: false, error, suggestions? }. Bulunamayan bir şey asla tahminle doldurulmuyor. Bilinmeyen bir senaryo id'si, yakın ya da geçerli id'leri listeleyen suggestions ile geri dönüyor; bir lint bulgusu da bir düzeltme taşıyor:

{
"ok": false,
"findings": [
{
"severity": "error",
"message": "Path matches a known scenario but the method POST is wrong; expected GET.",
"fix": "Use GET for /v1/customers/{customer-id}/subscriptions."
}
]
}

Bir model için yazılan hata mesajı, junior bir geliştirici için yazılanla aynı işi görmeli: neyin yanlış olduğunu ve doğru bir girdinin neye benzediğini söylemeli. Sıfırdan başlıyorsanız, spesifikasyondaki tool sonucunun isError işareti tam da bu hatalar için var ve client'ların bu sonuçları modele iletmesi bekleniyor ki model kendini düzeltebilsin. partner-center-mcp ise hatayı kendi zarfının içinde bildiriyor ve bunu outputSchema'sı tarif ediyor.

Çıktıyı beyan edin, sonra kablo üzerinden test edin​

Bir outputSchema beyan etmek, SDK'nın uyguladığı bir söz: her tool'un structured content'ini döndürmeden önce doğruluyor. Gerçek payload ile uyuşmayan bir şema, çalışan bir tool'u çağrı anında bir hataya çeviriyor. Repository bu yolu uçtan uca test ediyor. Bir test suite'i HTTP server'ı başlatıyor ve not-found yolu dahil her tool'u gerçek transport üzerinden, gerçek bilgi paketiyle çağırıyor. O testteki bir yorum, suggestions şemada beyan edilmeden önce client'ları bozan yolun tam da not-found yolu olduğunu kayda geçiriyor.

Bir MCP server için unit test yetmez, çünkü tüketici bir model. Repository'de iki katman daha var. npm run eval deterministik bir golden-case suite'i çalıştırıyor; örneğin üretilen kodun token helper'ını içerdiğini ve graph.windows.net'ten hiç bahsetmediğini doğruluyor. npm run eval:llm ise gerçek bir modele tool isimlerini ve açıklamalarını doğal dilde bir soruyla birlikte veriyor ve beklenen tool'lardan birini seçip seçmediğine bakıyor. Açıklamalarınızın işe yarayıp yaramadığını söyleyen tek test bu ikincisi.

HTTP başka bir tehdit modeli​

stdio üzerinde server'la yalnızca onu başlatan process konuşabilir. Streamable HTTP varyantı ise başka bir konu: o bir web server. Kendine ait bir authentication'ı yok; bu yüzden varsayılan olarak 127.0.0.1'e bağlanıyor, istek gövdelerini 1 MiB ile sınırlıyor ve ne loopback ne de açıkça izin verilmiş olan bir tarayıcı Origin'ini reddediyor. Rastgele bir web sayfasının yerel bir server'ı yönetmesini engelleyen bu son kontrol; spesifikasyon da aynı sebeple server'ların Origin'i doğrulamasını zorunlu tutuyor.

Server'ınız HTTP üzerinden çalışabiliyorsa, o modu kendi tehdit modeli olan ayrı bir ürün gibi ele alın.

Deneyin​

claude mcp add partner-center -- npx -y partner-center-mcp

VS Code, Visual Studio, Cursor ve diğer host'ların ayarları README'de. Resmî olmayan bir topluluk projesi; Microsoft ile bir bağlantısı yok. Yeni senaryolar ve dokümantasyon düzeltmeleri GitHub'da memnuniyetle karşılanır.