İçeriğe atla

Teknik Tarifler

Günlük Maguyva MCP işleri için pratik tarifler. Her tarif araçları ve sıralamayı verir; eksiksiz bir parametre başvurusu değildir. Araç parametreleri için MCP API Başvurusu, ilk kurulum için Hızlı Başlangıç bağlantısını kullanın.

Doğru aracı seçin#

Çoğu soru tek bir çağrıyla başlar. Yalnızca ilk yanıt fazla geniş veya yetersizse daha ayrıntılı bir araca geçin.

  • intelligent_search — doğal dille sorulan her kod tabanı sorusunda buradan başlayın; semantic, symbol, yapısal ve dependency aramaları arasında yönlendirir.
  • find_symbol — işlev, sınıf veya değişken adını zaten biliyorsanız kullanın.
  • dependency_search — düzenlemeden önce ve sonra etki alanını görmek için çağıranları, bağımlıları ve değişiklik etkisini bulun.
  • get_task_context — tanımadığınız bir alan için görev açıklamasına bağlı, sınırlı bir dosya, symbol ve bağımlılık paketi alın.
  • repository_context — erişilebilir depoları listeleyin veya bir depo adının nasıl çözümlendiğini inceleyin.
  • operation="guidance" ile ask_maguyva — araç seçimi ve Maguyva kullanımı için yerel yardım alın; depoda değişiklik yapmaz.

İstemciyi kurun ve doğrulayın#

Maguyva'yı MCP istemcinize ekleyin ve gerçek depo listesiyle bağlantıyı doğrulayın.

  1. app.maguyva.ai içinde bir API anahtarı oluşturun (anahtarlar mgv_ ile başlar).
  2. İyi bildiğiniz en az bir GitHub deposunu bağlayıp indeksleyin.
  3. İstemcinizi Kurulum Kılavuzu ile yapılandırın (Claude Code eklentisi veya Cursor, VS Code, Windsurf, Zed ve diğerleri için yerel uzak sunucu ayarı).
  4. Ajanınıza "Hangi depoları bağladım?" diye sorun; bu, kimlik doğrulamayı ve repository_context aracını uçtan uca sınar.
  5. Yanıtını değerlendirebileceğiniz gerçek bir depo sorusu sorun. İndekslenmiş ağaçtan dosya yolları ve satır numaraları görmelisiniz.

Anahtarlar, köprüler veya eksik depolarda mı takıldınız? Sorun Giderme.

Düzenlemeden önce sorun#

Paylaşılan kodu değiştirmeden önce symbol haritasını ve etki alanını çıkarın. Maguyva araçları depolarınızı değiştirmez; istemcinizin yerelde uygulayacağı düzenlemeyi kanıtla besler.

  1. Symbol adını biliyorsanız tanımları ve kullanımları bulmak için find_symbol aracını çağırın.
  2. Yalnızca görev açıklamanız varsa ("SSO ekle", "faturalandırma webhook’unu düzelt"), get_task_context veya intelligent_search ile başlayın.
  3. Paylaşılan bir symbol üzerinde değişiklik yapmadan önce, bağımlı/etki analiziyle dependency_search aracını çağırın (PR tarzı etki için değişen yolları da iletebilirsiniz); böylece etki alanını görürsünüz.
  4. Atıf yapılan dosyaları açın (diskteki dosyalar için yerel okuma, uzak veya çapraz depo yolları için get_file) ve planı gerçek kodla doğrulayın.
  5. Düzenlemeden sonra aynı symbol’leri dependency_search ile yeniden kontrol edin; istemciniz destekliyorsa düzenleme sonrası doğrulamayı da kullanın ve çağıranların beklendiği gibi çözümlendiğini doğrulayın.

Tüm parametreler: MCP API Başvurusu.

Ara, sonra değiştir#

Varsayılan ajan döngüsü: keşfet → symbol’leri sabitle → kanıta dayanarak düzenle.

  1. intelligent_search ve doğal dilli bir sorguyla başlayın ("oturum süresi nasıl doluyor", "yeniden deneme mantığı nerede").
  2. İlk sonuç penceresi gürültülüyse dil veya yol filtreleriyle daraltın.
  3. Aynı belirsiz soruyu tekrar sormak yerine umut veren sonuçları find_symbol veya dependency_search ile derinleştirin.
  4. get_file aracını yalnızca diskte bulunmayan belirli bir indekslenmiş yola ihtiyacınız olduğunda kullanın.
  5. Düzenlemeyi normal istemci araçlarınızda yapın. Maguyva keşif ve doğrulama içindir; yazma aracı değildir.

Bu döngünün neden çalıştığı: Nasıl Çalışır.

Boş veya yetersiz sonuçlar#

Araçlar işe yarar sonuç vermiyorsa sorguyu sonsuza dek yeniden yazmadan önce depo çözümleme ve indeksleme sorunlarını giderin.

  1. Deponun app.maguyva.ai içinde bağlı olduğunu ve indekslemenin tamamlandığını doğrulayın.
  2. Depo dizesini kontrol edin: "owner/repo" varsayılan dalı kullanır; "owner/repo:branch" belirli bir dalı sabitler. Eşleştirme büyük/küçük harfe duyarsızdır ama fuzzy değildir; yazım hataları otomatik düzeltilmez.
  3. repository_context aracını action="info" ile çağırın ve çözümleme meta verilerini (örneğin metadata.resolution_reason) inceleyin.
  4. repository değerini yalnızca MCP istemciniz istek varsayılanı sağlıyorsa veya anahtar tam olarak bir depoya erişebiliyorsa atlayın; aksi hâlde açıkça iletin.
  5. Daha belirgin bir sorguyla, find_symbol üzerinden bilinen bir symbol adıyla veya dil/yol filtresiyle yeniden deneyin. Bağlantı bozuksa Sorun Giderme bağlantısını kullanın.

Kurulum sorunları: Sorun Giderme.

Birden çok depoda çalışın#

Bir anahtar birden fazla depoyu görebildiğinde doğru indekslenmiş depoyu hedefleyin.

  1. Anahtarınızın arayabildiği tam slug’ları öğrenmek için repository_context aracını action="list" ile bir kez çağırın.
  2. Varsayılan olmayan bir depoya ihtiyacınızda repository değerini arama ve symbol araçlarına açıkça iletin (örneğin "owner/other-repo" veya "owner/other-repo:develop").
  3. Ayrı çağrılarda depoları özellikle karşılaştırmıyorsanız bir soru = bir depo kuralını koruyun.
  4. Dosya, geçerli çalışma ağacınız olmayan indekslenmiş bir depodaysa get_file aracını kullanın.
  5. Unutmayın: araçlar GitHub’a geri yazmaz; çoklu depo bağlamı yalnızca okuma ve planlama içindir.

Depo biçimi ayrıntıları: MCP API Başvurusu.

Maguyva'da yeni misiniz? Önce Hızlı Başlangıç adımlarını tamamlayın, sonra günlük çalışma döngüleri için buraya dönün.

Sonraki adımlar#