API'nizi MCP Sunucusuna Nasıl Dönüştürürsünüz

API'nizin Claude veya Cursor gibi yapay zeka ajanlarıyla sohbet edebilmesini, uç noktalarınızı akıllı, konuşkan araçlara dönüştürmesini hiç dilediniz mi? Kemerlerinizi bağlayın, çünkü Stainless ve bir OpenAPI spesifikasyonu kullanarak API'nizi bir MCP sunucusuna dönüştürme konusuna dalıyoruz. Bu konuşkan rehber, kurulumdan dağıtıma kadar süreci, çalıştığını kanıtlayacak bir testle birlikte size adım adım gösterecek. API'nizi yapay zeka dostu hale getirmek için Model Bağlam Protokolü'nü (MCP) eğlenceli ve anlaşılır bir şekilde kullanacağız. Başlayalım!

MCP Sunucusu Nedir ve Neden Önemsemelisiniz?

Model Bağlam Protokolü (MCP), yapay zeka sistemleri için evrensel bir el sıkışma gibidir. Yapay zeka istemcilerinin (Claude Desktop, Cursor veya VS Code Copilot gibi) API'nizle doğal dil veya programlanabilir komutlar kullanarak etkileşim kurmasını sağlayan JSON-RPC tabanlı bir standarttır. Bir MCP sunucusu, API'nizin uç noktalarını yapay zeka ajanlarının anlayabileceği ve kullanabileceği araçlara çeviren bir köprü görevi görür.

API'nizi neden bir MCP sunucusuna dönüştürmelisiniz? Oyunun kurallarını değiştiren bir özelliktir:

• Yapay Zeka Destekli Etkileşim: Yapay zeka ajanlarının API'nizi "Kullanıcı verilerini getir" veya "Yeni bir sipariş oluştur" gibi basit komutlarla çağırmasına izin verin.
• Kolay Otomasyon: Stainless, OpenAPI spesifikasyonunuzdan minimum kodlama ile bir MCP sunucusu oluşturarak süreci otomatikleştirir.
• Ölçeklenebilirlik: API'nizi yerel geliştirme araçlarından üretim düzeyindeki uygulamalara kadar birden fazla yapay zeka istemcisine açın.
• Geliştirici Dostu: API'nizi yeniden yazmanıza gerek yok; sadece bir MCP katmanı ekleyin ve ağır işi yapay zekaya bırakın.

İster bir ödeme platformu, ister bir içerik API'si veya özel bir hizmet geliştiriyor olun, API'nizi bir MCP sunucusuna dönüştürmek onu daha akıllı ve daha erişilebilir hale getirir.

Stainless Nasıl Bir Rol Oynuyor?

Stainless, OpenAPI spesifikasyonlarından SDK'lar ve şimdi de MCP sunucuları oluşturmak için geliştiricinin en iyi arkadaşıdır. Deneysel MCP sunucusu oluşturma özelliği, OpenAPI tanımınızı alır ve bir MCP sunucusu olarak kullanıma hazır bir TypeScript alt paketi çıkarır. Bu, API'nizin uç noktalarının hiç çaba harcamadan yapay zeka tarafından erişilebilir araçlar haline gelmesi demektir. Hadi nasıl yapıldığını görelim!

API'nizi Stainless ile Bir MCP Sunucusuna Dönüştürme

Ön Koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

• OpenAPI Spesifikasyonu: API'niz için geçerli bir OpenAPI (Swagger) dosyası (örn. openapi.yaml veya openapi.json).
• Stainless Hesabı: Bir proje oluşturmak için stainless.com adresinden kaydolun.
• Apidog Hesabı: OpenAPI Spesifikasyonunuzu test etmek için (https://apidog.com/ adresini ziyaret edin).
• Node.js 20+: Yerel test ve MCP sunucusunu çalıştırmak için (nodejs.org/en/download).
• npm: Paket yönetimi için Node.js ile birlikte gelir.
• MCP Uyumlu İstemci: Test için Claude Desktop, Cursor veya VS Code Copilot.
• API Anahtarı: API'niz kimlik doğrulama gerektiriyorsa, bir API anahtarı hazır bulundurun.

Adım 1: OpenAPI Spesifikasyonunuzu Apidog ile Test Etme

OpenAPI spesifikasyonunuzu bir MCP sunucusuna dönüştürmeden önce veya sonra bile onu test etmek harika olacaktır. İşte burada Apidog işe yarar! Apidog'un sezgisel platformu, API'nizin uç noktalarının MCP entegrasyonuna hazır olduğundan emin olmak için OpenAPI spesifikasyonunuzu içe aktarmanıza ve test etmenize olanak tanır. İşte nasıl yapılacağı:

1. Apidog'u Ziyaret Edin ve Kaydolun veya Giriş Yapın:

• Bir hesabınız varsa Giriş Yap'a (sağ üst) tıklayın veya talimatları izleyerek bir hesap oluşturmak için Kaydol'a tıklayın.

2. Yeni Bir Proje Oluşturun ve OpenAPI Spesifikasyonunuzu İçe Aktarın:

• Giriş yaptıktan sonra, kontrol panelinde Proje Oluştur'a tıklayın.
• Proje oluşturma sayfasında, İçe Aktar'a tıklayın.
• OpenAPI dosyanızın URL'sini girin (örn. https://my-api.com/openapi.yaml) veya yerel openapi.yaml veya openapi.json dosyanızı seçmek için veya bir dosya yükle'ye tıklayın.

• Apidog dosyayı ayrıştıracak ve hesabınızda yeni bir API oluşturacaktır (bu, karmaşık spesifikasyonlar için birkaç dakika sürebilir).

3. API Ayarlarını Yapılandırın:

• Başarılı bir içe aktarmanın ardından, ayarlar sayfasına yönlendirileceksiniz. API'nizin adını, açıklamasını ve kimlik doğrulama gereksinimlerini (örn. API anahtarı veya OAuth) özelleştirin.

4. Uç Noktaları Ekleyin ve Test Edin:

• Uç noktaları ve dokümantasyonu eklemek veya düzenlemek için Apidog'un arayüzünü kullanın.
• MCP sunucunuzu oluşturmadan önce uç noktalarınızın beklendiği gibi çalıştığını doğrulamak için bunları doğrudan Apidog'da test edin.

Apidog ile test yapmak, OpenAPI spesifikasyonunuzun sağlam olduğundan emin olmanızı sağlar, bu da Stainless MCP oluşturma sürecini daha sorunsuz ve MCP sunucunuzu daha güvenilir hale getirir.

Adım 2: TypeScript ile Bir Stainless Projesi Kurma

Bir Stainless Projesi Oluşturun:

• stainless.com adresine giriş yapın ve yeni bir proje oluşturun.
• API'nizin uç noktalarını tanımlamak için OpenAPI spesifikasyonunuzu (YAML veya JSON) yükleyin.
• Hedef dil olarak TypeScript'i seçin (MCP sunucusu oluşturma TypeScript gerektirir, ancak eski node hedefleri desteklenmektedir).

MCP Sunucusu Oluşturmayı Etkinleştirin:

• Projenizin SDK Ekle bölümünde, oluşturmayı etkinleştirmek için MCP Sunucusu'nu seçin.
• Bu, projenizde packages/mcp-server altında bir alt paket oluşturur.

Adım 3: MCP Sunucusu Oluşturmayı Yapılandırma

Stainless proje ayarlarınızda, MCP sunucusu seçeneklerini yapılandırın. Şunları içeren bir yapılandırma dosyası (örn. stainless.yaml) oluşturun veya düzenleyin:

targets:
  typescript:
    package_name: my-org-name
    production_repo: null
    publish:
      npm: false
    options:
      mcp_server:
        package_name: my-org-name-mcp
        enable_all_resources: true

• package_name: MCP sunucusu paketinizi adlandırın (varsayılan olarak SDK adınızın sonuna -mcp eklenir).
• enable_all_resources: true: Varsayılan olarak tüm API uç noktalarını MCP araçları olarak gösterir.

Bu, Stainless'a API'nizin uç noktalarını yapay zeka tarafından erişilebilir araçlar olarak uygulayan bir MCP sunucusu alt paketi oluşturmasını söyler.

Adım 4: Uç Nokta Görünürlüğünü ve Araç Açıklamalarını Özelleştirme

Varsayılan olarak, OpenAPI spesifikasyonunuzdaki tüm uç noktalar MCP aracı haline gelir. Özelleştirmek için:

1. Belirli Uç Noktaları Seçin:

• enable_all_resources: false olarak ayarlayın ve belirli kaynakları veya yöntemleri etkinleştirin:

resources:
  users:
    mcp: true
    methods:
      create:
        mcp: true
  orders:
    methods:
      create:
        mcp: true
        endpoint: post /v1/orders

2. Araç Meta Verilerini İnce Ayar Yapın:

• Daha iyi yapay zeka etkileşimi için araç adlarını ve açıklamalarını özelleştirin:

resources:
  users:
    methods:
      create:
        mcp:
          tool_name: create_user
          description: Creates a new user profile with name and email.

Bu, MCP sunucunuzun yalnızca istediğiniz uç noktaları, net ve yapay zeka dostu açıklamalarla göstermesini sağlar.

Adım 5: Araç Filtreleme ve Dinamik Araçlarla Büyük API'leri Yönetme

Çok sayıda uç noktası olan API'ler (>50) için, her birini ayrı bir araç olarak göstermek, bir yapay zekanın bağlam penceresini aşırı yükleyebilir. Şu stratejileri kullanın:

1. Araç Filtreleme:

• Araçları çalışma zamanında kaynak, işlem türü (örn. okuma/yazma) veya özel etiketlere göre filtreleyin:

npx -y my-org-mcp --resource=users

2. Dinamik Araçlar Modu:

• Üç meta-aracı göstermek için dinamik araçları etkinleştirin: list_api_endpoints, get_api_endpoint_schema ve invoke_api_endpoint. Bu, büyük API'ler için etkileşimi basitleştirir:

npx -y my-org-mcp --tools=dynamic

Dinamik araçlar, yapay zekanın uç noktaları dinamik olarak keşfetmesine ve çağırmasına olanak tanıyarak bağlam aşırı yüklenmesini azaltır.

Adım 6: MCP Sunucunuzu Oluşturun ve Yayınlayın

MCP Sunucusunu Oluşturun:

• SDK'nızı oluşturduğunuzda Stainless, MCP sunucusunu packages/mcp-server içinde oluşturur.
• Stainless projenizde oluşturma komutunu çalıştırın (ayrıntılar için projenizin README.md dosyasını kontrol edin).

npm'e Yayınlayın:

• Stainless ayarlarınızda bir üretim deposu yapılandırın.
• MCP sunucusunu ayrı bir npm paketi olarak yayınlayın (örn. my-org-name-mcp):

npm publish

Adım 7: MCP İstemcileri İçin Kurulum ve Yapılandırma

Yayınladıktan sonra, yapay zeka istemcileriyle kullanmak üzere MCP sunucu paketinizi yerel veya uzak olarak kurun. Claude Desktop için:

1. Paketi Kurun:

• Yerel olarak test ediyorsanız, packages/mcp-server dizinine gidin ve README.md talimatlarını izleyin.
• Uzak kullanım için npm aracılığıyla kurun:

npm install my-org-name-mcp

2. Claude Desktop'ı Yapılandırın:

• claude_desktop_config.json dosyasını açın (macOS: ~/Library/Application Support/Claude, Windows: %APPDATA%\Claude).

• Ekle:

{
  "mcpServers": {
    "my_org_api": {
      "command": "npx",
      "args": ["-y", "my-org-mcp"],
      "env": {
        "MY_API_KEY": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  }
}

• my-org-mcp'yi paket adınızla ve MY_API_KEY'i API anahtarınızla değiştirin.
• Kaydedin ve Claude Desktop'ı yeniden başlatın.

3. Diğer İstemciler:

• Cursor veya VS Code Copilot için, aynı yapılandırmayı ilgili ayarlarına (örn. VS Code için settings.json veya Cursor'ın Araçlar ve Entegrasyonlar paneli) ekleyin.

Adım 8: MCP Sunucunuzu Test Edin

MCP sunucunuzu test edelim! Claude Desktop'ta (veya başka bir MCP istemcisinde) şu komutu deneyin:

alex@example.com

API'nizin bir POST /users uç noktası varsa (OpenAPI spesifikasyonunuzda tanımlandığı gibi), MCP sunucusu bu komutu bir API çağrısına çevirecek, bir kullanıcı oluşturacak ve şöyle bir yanıt döndürecektir:

User created: { "name": "Alex", "email": "alex@example.com", "id": "123" }

Bu, MCP sunucunuzun çalıştığını ve yapay zeka odaklı etkileşimlere hazır olduğunu doğrular.

Sorun Giderme İpuçları

• Oluşturma Hataları mı? OpenAPI spesifikasyonunuzun geçerli olduğundan ve Stainless projenizde TypeScript'in etkinleştirildiğinden emin olun.
• İstemci Bağlanmıyor mu? MCP yapılandırmanızdaki paket adını ve API anahtarını doğrulayın ve istemciyi yeniden başlatın.
• Komut Çalışmıyor mu? Uç nokta yapılandırmalarınızı kontrol edin ve istenen eylemin gösterilen bir araçla eşleştiğinden emin olun.
• Bağlam Aşırı Yüklenmesi mi? Dinamik araçlar modunu etkinleştirin veya büyük API'ler için kaynakları filtreleyin.

MCP Sunucuları İçin En İyi Uygulamalar

• Araçları Odaklanmış Tutun: Bağlam şişkinliğini önlemek için yapay zekanızın ihtiyaç duyduğu uç noktaları gösterin.
• Net Açıklamalar: Komut doğruluğunu artırmak için LLM dostu araç açıklamaları yazın.
• Büyük API'ler İçin Dinamik Araçları Kullanın: Bağlam alanından tasarruf etmek için büyük API'leri meta-araçlarla basitleştirin.
• Güvenli Kimlik Doğrulama: Üretimde API anahtarları için ortam değişkenleri veya OAuth kullanın.
• Önce Yerel Olarak Test Edin: npm'e yayınlamadan önce test etmek için README.md talimatlarını kullanın.

Sonuç

Ve işte bu kadar! Stainless kullanarak API'nizi nasıl bir MCP sunucusuna dönüştüreceğinizi, OpenAPI spesifikasyonunuzu yapay zeka için hazır bir güç merkezine dönüştürmeyi öğrendiniz. Uç noktaları yapılandırmaktan kullanıcı oluşturma komutuyla test etmeye kadar, bu rehber API'nizi Claude veya Cursor gibi yapay zeka ajanlarıyla köprülemeyi kolaylaştırır. İster küçük bir projeyi geliştiriyor olun, ister bir üretim API'sini ölçeklendiriyor olun, MCP sunucusu daha akıllı, konuşkan entegrasyonlara biletinizdir.

Denemeye hazır mısınız? OpenAPI spesifikasyonunuzu alın, Stainless'ı çalıştırın ve API'nizin yapay zeka dünyasında parlamasına izin verin.