Tobias Hoffmann

Posted on May 19 • Originally published at apidog.com

Cursor Composer 2.5 ile API Nasıl Oluşturulur

Cursor Composer 2.5, bir ajanın sizin için API istemcileri ve rota işleyicileri yazmasını sağlayacak kadar hızlı ve uygun maliyetli. Sorun, üretilen kod gerçek bir servise dokunduğunda başlar: model, servisiniz aslında /orders sunarken ve farklı bir payload beklerken /v2/orders için temiz görünen bir istek yazabilir. Kod derlenir, lint’ten geçer, ancak çalışmaz. Bunu genellikle birkaç dosya sonra fark edersiniz.

Apidog'u bugün deneyin

Bu kılavuzda uygulanabilir iş akışı şu: Composer 2.5’i MCP üzerinden gerçek API spesifikasyonunuza bağlayın, kodu gerçek sözleşmeye göre ürettirin ve ekip arkadaşınıza göndermeden önce sonucu Apidog’da doğrulayın. Modele yeniyseniz, Cursor Composer 2.5 kılavuzu modelin ne olduğunu ve nasıl erişileceğini açıklar.

Agentik Modeller Neden API Şekillerini Tahmin Eder?

Composer 2.5, uzun ve çok adımlı ajan görevleri için tasarlanmıştır. Örneğin şu görevi verebilirsiniz:

“Faturalandırma hizmetimiz için bir istemci ekle ve ödeme akışına bağla.”

Model plan yapar, birkaç dosyayı düzenler, testleri çalıştırır ve hataları gidermeye çalışır. Bu, Composer 2’ye göre önemli bir geliştirmedir.

Ancak zayıf nokta şudur: Model API sözleşmenizi bilmiyorsa boşlukları tahmin eder.

Genellikle şunları üretir:

Yaygın REST endpoint adları
Sık kullanılan alan isimleri
Eğitim verisinde çok gördüğü sürüm önekleri
Genel authorization kalıpları

Sonuç doğru görünebilir ama gerçek servisinizle uyuşmayabilir.

Tipik belirtiler:

Neredeyse doğru endpoint’ler: /api/users/{id} yerine sizin endpoint’iniz /users/{userId} olabilir.
Request body içinde uydurulmuş veya yanlış alanlar.
Servisinizin gerçek authorization şeması yerine genel bir Bearer token varsayımı.

Bunu prompt ile kısmen azaltabilirsiniz. Ancak tüm OpenAPI dosyasını sohbete yapıştırmak kırılgandır, bağlam penceresini tüketir ve güncel kalması zordur. Daha sağlam çözüm: modele API spesifikasyonuna yapılandırılmış erişim vermektir.

Çözüm: Composer 2.5’i MCP ile Gerçek API Spesifikasyonunuza Bağlayın

Model Bağlam Protokolü, yani MCP, yapay zeka modellerine araç ve veri sağlamak için kullanılan açık bir standarttır. Cursor, MCP sunucularını destekler. Apidog MCP sunucusu, Apidog’daki API spesifikasyonunuzu Composer’ın kod yazarken sorgulayabileceği yapılandırılmış bir kaynak olarak sunar.

Pratik fark şudur:

MCP yoksa model endpoint ve şemaları tahmin eder.
MCP varsa model gerçek endpoint’leri, parametreleri, request/response şemalarını ve hata yapılarını okuyabilir.

Bu, Apidog MCP sunucusuyla vibe kodlama yaklaşımının Composer 2.5 gibi daha uzun görevleri taşıyabilen bir modelle uygulanmış halidir.

Adım 1: Apidog’da API Spesifikasyonunuzu Hazırlayın

Önce API sözleşmenizin model tarafından okunabilir ve güncel olduğundan emin olun.

Yapmanız gerekenler:

API’nizi Apidog’da tasarlayın veya içe aktarın.
Endpoint’lerin, şemaların, parametrelerin ve örneklerin güncel olduğunu kontrol edin.
Var olan dokümantasyonunuz varsa OpenAPI veya Postman koleksiyonu olarak içe aktarın.
Modelin takip edeceği doğruluk kaynağı bu spesifikasyon olacağı için eksik veya eski alanları temizleyin.

Örneğin Composer’a bir createOrder istemcisi yazdıracaksanız, spesifikasyonda en az şunlar net olmalı:

HTTP metodu
Path
Header gereksinimleri
Request body şeması
Başarılı response şeması
Doğrulama hataları
Authorization davranışı

Adım 2: Apidog MCP Sunucusunu Cursor’a Bağlayın

Cursor, MCP sunucularını projenizdeki yapılandırma dosyasından okur. Bu dosya genellikle şuradadır:

.cursor/mcp.json

Apidog MCP sunucusu npx ile çalışır ve Apidog projenize bağlanır. Tipik yapılandırma şu şekildedir:

{
  "mcpServers": {
    "apidog-api-spec": {
      "command": "npx",
      "args": ["-y", "apidog-mcp-server@latest", "--project=<your-project-id>"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

Buradaki değerler hesabınıza ve Apidog projenize özeldir:

<your-project-id>: Apidog projenizin kimliği
<your-access-token>: Apidog erişim belirteciniz
apidog-api-spec: Cursor içinde kullanacağınız MCP sunucusu adı

Tam komut, proje kimliği ve token için Apidog MCP kurulum kılavuzunu izleyin.

Yapılandırmayı ekledikten sonra Cursor’ı yeniden başlatın. Bu adım önemlidir; Cursor yeni MCP sunucusunu yeniden başlatmadan görmeyebilir.

Adım 3: Composer 2.5’in Spesifikasyonu Gördüğünü Doğrulayın

Kod üretmeye başlamadan önce bağlantıyı test edin.

Cursor’da bir ajan oturumu açın, model seçiciden composer-2.5 seçin ve önce salt okunur bir soru sorun:

“apidog-api-spec MCP sunucusunu kullanarak, siparişler kaynağı altındaki endpoint’leri ve bir sipariş oluşturmak için gerekli alanları listeleyin.”

Beklenen sonuç:

Gerçek endpoint’lerin listelenmesi
Gerçek request alanlarının dönmesi
Spesifikasyonda tanımlı hata yanıtlarının görünmesi

Eğer model genel bilgilerle cevap veriyorsa, büyük olasılıkla MCP bağlantısı çalışmıyordur. Şunları kontrol edin:

.cursor/mcp.json doğru konumda mı?
Sunucu adı prompt’ta doğru yazıldı mı?
APIDOG_ACCESS_TOKEN geçerli mi?
Proje kimliği doğru mu?
Cursor yeniden başlatıldı mı?

Adım 4: Kodu Sözleşmeye Göre Ürettirin

Bağlantı doğrulandıktan sonra gerçek görevi verin. Prompt içinde MCP kaynağını açıkça adlandırın.

Örnek prompt:

“Doğruluk kaynağı olarak apidog-api-spec sunucusunu kullanarak, sipariş API’si için TypeScript istemcisi yaz. Sipariş oluşturma ve sipariş alma çağrılarını dahil et. İstek ve yanıt şemalarını spesifikasyonla birebir eşleştir. Spesifikasyonda tanımlı 422 doğrulama yanıtı için hata işleme ekle.”

Bu tür bir prompt üç şeyi netleştirir:

Model hangi veri kaynağını kullanacağını bilir.
Endpoint ve şema tahmin etmemesi gerektiğini anlar.
Hata senaryolarını da sözleşmeye göre ele alır.

Örneğin modelden şu tarz bir istemci üretmesini isteyebilirsiniz:

type CreateOrderRequest = {
  // Bu alanlar model tarafından spesifikasyondan okunmalı
};

type OrderResponse = {
  // Response şeması spesifikasyonla eşleşmeli
};

type ValidationErrorResponse = {
  // 422 yanıtı spesifikasyondaki yapıya göre üretilmeli
};

export async function createOrder(
  payload: CreateOrderRequest,
  token: string
): Promise<OrderResponse> {
  const response = await fetch("/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`
    },
    body: JSON.stringify(payload)
  });

  if (response.status === 422) {
    const error = (await response.json()) as ValidationErrorResponse;
    throw error;
  }

  if (!response.ok) {
    throw new Error(`Order creation failed: ${response.status}`);
  }

  return response.json() as Promise<OrderResponse>;
}

Buradaki önemli nokta örnek kodun şekli değil, alanların ve endpoint’lerin gerçek spesifikasyondan gelmesidir. Composer 2.5 uzun görevleri sürdürebildiği için istemciyi, tipleri, hook’ları ve testleri birden fazla dosyada tutarlı şekilde oluşturabilir.

Güvenmeden Önce Doğrulayın: Apidog Test Döngüsü

Modeli gerçek API sözleşmesine bağlamak halüsinasyonları ciddi şekilde azaltır. Ancak doğrulamayı ortadan kaldırmaz.

Çünkü:

Spesifikasyon gerçek servisin gerisinde kalmış olabilir.
Model bir edge case’i yanlış yorumlayabilir.
Ortam bazlı authorization veya header davranışları farklı olabilir.
Backend henüz tamamlanmamış olabilir.

Bu nedenle akışı Apidog ile kapatın.

1. Oluşturulan Çağrıları Gerçek İstek Olarak Gönderin

Composer 2.5’in ürettiği endpoint, header ve payload’ları alın. Bunları gerçek veya mock bir ortamda Apidog üzerinden çalıştırın.

Kontrol edin:

Status code beklenenle aynı mı?
Response body şemayla uyumlu mu?
Authorization doğru çalışıyor mu?
Zorunlu header’lar eksiksiz mi?
Validation hataları doğru formatta mı dönüyor?

2. Çalışan Çağrıları Teste Dönüştürün

Doğruladığınız istekleri otomatik test senaryosu olarak kaydedin.

Böylece bir sonraki kırılma:

Kullanıcıda,
staging ortamında,
manuel QA sırasında

değil, CI sürecinde yakalanır.

3. Henüz Hazır Olmayan Endpoint’leri Mock’layın

Model, backend henüz tamamlanmadan bir endpoint için istemci yazdıysa Apidog’un mock sunucusunu kullanabilirsiniz. Mock sunucu, spesifikasyona uygun gerçekçi yanıtlar döndürür.

Bu özellikle frontend geliştirmede faydalıdır:

Backend beklenmeden UI akışı geliştirilebilir.
Response şekli sözleşmeye bağlı kalır.
Daha sonra gerçek servis geldiğinde entegrasyon daha az sürpriz içerir.

Bu yaklaşım, yapay zeka ajanları ve API testi içindeki desenlerle de uyumludur.

Temel prensip:

Model ilk taslağı API sözleşmesine göre yazar; siz bu taslağın gerçek veya mock bir sunucuya karşı çalıştığını doğrularsınız.

Gerçekçi Bir Uçtan Uca Örnek

Bir ödeme servisine iade özelliği eklediğinizi varsayalım.

Uygulanabilir akış:

İade endpoint’leri ve şemaları Apidog projenizde hazırdır.
Apidog MCP sunucusu Cursor’a bağlıdır.
Cursor’da composer-2.5 seçilidir.
Composer’a şu prompt’u verirsiniz:

“apidog-api-spec kullanarak iade istemcisini ve onu çağıran bir React hook’unu oluştur. Spesifikasyonda gerekli olan idempotency-key header’ını dahil et. Request, response ve hata şemalarını birebir takip et.”

Composer 2.5 şunları üretir:

Refund API istemcisi
TypeScript tipleri
React hook
Gerekirse test dosyaları
idempotency-key header kullanımını içeren çağrılar

Ardından Apidog’da doğrulama yaparsınız:

Gerçek bir iade oluşturma isteği gönderin.
idempotency-key header’ının doğru işlendiğini kontrol edin.
Aynı isteği tekrar gönderin.
Spesifikasyonda tanımlıysa 409 yanıtını doğrulayın.
Başarılı iade ve tekrar eden istek senaryolarını test olarak kaydedin.

Bu akışın engellediği hata sınıfı önemlidir: idempotency header’ını unutan bir istemcinin staging veya production ortamında çift iade oluşturması.

Sıkça Sorulan Sorular

Composer 2.5 MCP’yi destekliyor mu?

Evet. Composer 2.5, MCP sunucuları dahil Cursor’ın ajan araç setine erişebilir. Model seçiciden composer-2.5 seçin ve MCP sunucusunu projenizde yapılandırın. Model seçimi için Composer 2.5 kılavuzuna bakabilirsiniz.

Composer 2.5 ile MCP kullanmak için Apidog’a ihtiyacım var mı?

Yapılandırılmış bir API spesifikasyon kaynağına ihtiyacınız var. Bu yazıdaki yol Apidog MCP sunucusu üzerinden ilerler, çünkü aynı yerde test ve mock özelliklerini de kullanabilirsiniz. Alternatifler için Cursor için en iyi MCP sunucuları özetine bakabilirsiniz.

Modeli spesifikasyona bağlamak tüm halüsinasyonları durdurur mu?

Hayır, ancak en büyük hata kategorisini azaltır: yanlış endpoint ve yanlış şema üretimi. Model tahmin etmek yerine gerçek sözleşmeyi okur. Yine de test gereklidir; çünkü spesifikasyon çalışan servisten sapabilir veya model bir edge case’i yanlış yorumlayabilir.

Küçük bir proje için buna değer mi?

Eğer model gerçek bir API’ye dokunuyorsa, evet. Kurulum çoğunlukla tek seferlik bir yapılandırma dosyasıdır. Karşılığında her oluşturulan çağrı, genel bir tahmin yerine API sözleşmenizle hizalanır.

Sonuç

Composer 2.5, ajanların gerçek API işlerini üstlenmesini sağlayacak kadar güçlü ve hızlıdır. Ancak bu hız, model gerçek sözleşmenize göre kod yazarsa faydaya dönüşür.

Uygulanabilir akış şu:

API spesifikasyonunuzu Apidog’da güncel tutun.
Apidog MCP sunucusunu Cursor’a bağlayın.
Composer 2.5’e MCP kaynağını açıkça kullandırın.
Üretilen çağrıları Apidog ile gerçek veya mock ortamda doğrulayın.
Çalışan çağrıları otomatik testlere dönüştürün.

Temellendirilmiş üretim + doğrulama, ajan hızını gerçekten teslim edilen özelliklere dönüştüren iş akışıdır.

DEV Community