Laravel Boost ve MCP Sunucuları: Yapay Zeka Ajandınızın Eksik Olduğu Bağlam

Özgün olarak hafiz.dev üzerinde yayımlanmıştır.

Laravel geliştiricileri AI kodlama ajanlarını kullanırken sıklıkla yapılması gereken hatalara düşüyorlar. Sorun, yanlış modeller veya kötü istemler seçmek değil; geliştiricilere kod tabanı, veritabanı şeması veya çerçeve belgeleri gibi gerekli bağlam bilgileri verilmeden bir şeyler inşa etmeleri istenmesidir. Claude Code, Cursor veya Copilot gibi teknolojiler bağlam katmanı olmadan bir Laravel projesinde kullanıldığında, bu ajanlar yeterli bilgiye erişemeden tahmin yaparlar ve çoğu zaman yanlış tahminlerde bulunurlar.

Laravel Boost bu sorunu çözmektedir. Herd’in MCP sunucusuyla birleştirildiğinde, AI’nin kod yazma şeklini gerçek anlamda dönüştüren bir bağlam sistemi oluşturur. Şimdi bu yapıların nasıl birlikte çalıştığını inceleyelim.

MCP Nedir ve Neden Önemlidir?

MCP, Model Context Protocol anlamına gelir. Bunu, AI ajanınız ve yerel geliştirme ortamınız arasında yapılandırılmış bir API olarak düşünün. Ajan, dosyalarınızı okuyup en iyisini ummak yerine, yapılandırılmış sorular sorabilir. “Veritabanı şeması nedir?” “Hangi rotalar mevcut?” “Hangi Livewire sürümü yüklü?”

Ajan artık tahmin etmez, sorar. Ve uygulamanız da yanıtlar.

Laravel ekosisteminde şimdi birlikte çalışan iki MCP sunucusu bulunmaktadır: Laravel Boost (Laravel ekibinin resmi paketi) ve Herd’in MCP sunucusu (Laravel Herd’i yerel geliştirme için kullanıyorsanız). Boost, uygulama düzeyindeki zeka ile ilgilenirken, Herd altyapı katmanını yönetir. Birlikte, AI ajanınıza yeni bir projeye katılan bir insan geliştiricinin günler alacak öğrenme sürecini hızlı bir şekilde kazandırır.

Laravel Boost Kurulumu: Üç Dakikalık Kurulum

Boost’u çalıştırmak oldukça basittir. PHP 8.2+ ve Laravel 10, 11 veya 12 gerektirir.

composer require laravel/boost --dev
php artisan boost:install

Kurulum komutu etkileşimlidir. İki önemli soru sorar: hangi özellikleri istediğiniz (kılavuzlar, beceriler, MCP sunucusu) ve kullandığınız AI ajanları (Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, Junie). Araçlarınızı seçtiğinizde, Boost uygun yapılandırma dosyalarını otomatik olarak oluşturur.

Claude Code için genellikle otomatik yapılandırılır. Eğer otomatik yapılandırılmazsa, manuel olarak ekleyebilirsiniz:

claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

Cursor için komut paletini açın, MCP Ayarlarına gidin ve laravel-boost‘u etkinleştirin. JetBrains/Junie kullananlar için ise komut paletinde “MCP Ayarları” arayın ve onay kutusunu işaretleyin. Bu kadar.

Tavsiyem: Oluşturulan dosyaları .gitignore dosyanıza ekleyin. .mcp.json, CLAUDE.md, AGENTS.md ve herhangi bir junie/ dizini, boost:install ile otomatik olarak yeniden oluşturulduğundan, bunları sürüm kontrolünde takip etmenin bir anlamı yoktur.

Üç Sütun: Kılavuzlar, Beceriler ve MCP Araçları

Boost, üç katman üzerinde çalışır ve ayırımı anlamak önemlidir çünkü her biri farklı amaçlar taşır.

Sütun 1: AI Kılavuzları

Kılavuzlar, AI ajanınızın bağlam penceresine önceden yüklenen talimat dosyalarıdır. Ajanı, projenizin nasıl çalıştığını, hangi sözleşmelere uyması gerektiğini ve hangi kalıpları kullanması gerektiğini öğretir.

Boost, Laravel için ve Laravel ekosistemindeki 16’dan fazla paket için kılavuzlar ile birlikte gelir. boost:install komutunu çalıştırdığınızda, yüklü paketlerinizi composer.json üzerinden algılar ve yalnızca ilgili kılavuzları oluşturur. Livewire kullanıyorsanız, Livewire’a özgü sözleşmeler alırsınız. Filament kullanıyorsanız, o kılavuzlar da gelir. Inertia kullanmıyorsanız, o kılavuzlar bağlam alanını boşa harcamaz.

Kılavuzlar ayrıca sürüm bilincine sahiptir. Eğer Livewire 3’te iseniz, Livewire 3 kalıplarını alırsınız. Livewire 2 kalıplarını değil. Bu, göründüğünden daha önemli bir meseledir. Gerçekten defalarca AI, Livewire 3 projesi için wire:model.defer önerdi.

Burada çoğu insanın gözden kaçırdığı bir şey: kendi kılavuzlarınızı ekleyebilirsiniz. Proje kökünüzde bir .ai/guidelines/ dizini oluşturup .blade.php veya .md dosyalarını yerleştirin. Boost, bunları yükleme sırasında kendi kılavuzlarıyla birleştirir. Bu, ekipler için gerçekten güçlü bir yer.

Sütun 2: Ajan Becerileri

Beceriler, Boost 2.0 ile tanıtıldı ve kılavuzlarla ilgili gerçek bir sorunu çözdü: bağlam aşırılığı. Kılavuzlar her seferinde önceden yüklenir. Eğer 50 sayfa talimatı kılavuzlara doldurursanız, ajanın bağlam penceresi, gerçek kod üzerinde çalışmaya başlamadan dolmuş olur.

Beceriler farklıdır. Sadece ajanın ilgili bir şey üzerinde çalışırken talep üzerine yüklenir. Bir Livewire bileşeni mi oluşturuyorsunuz? Livewire yeteneği aktive olur. Pest testleri mi yazıyorsunuz? Pest yeteneği devreye girer. Tailwind düzeninde mi çalışıyorsunuz? O yetenek yüklenir.

Boost 2.0, birçok içeriği kılavuzlardan becerilere taşıyarak, varsayılan kılavuzları yaklaşık %40 daha hafif hale getirmiştir. Sonuç, daha odaklanmış bir bağlam ve ajandanızdan daha yüksek kaliteli bir çıktı elde etmenizi sağlar.

Sütun 3: MCP Sunucusu (15+ Araç)

Asıl sihir burada gerçekleşiyor. MCP sunucusu, AI ajanın çalışmakta olan Laravel uygulamanızla programatik olarak etkileşimde bulunmasını sağlayan 15’ten fazla aracı açığa çıkarıyor. Dosyalarınızı okumak yerine, uygulamanızla etkileşimde bulunur.

Ajanınızın Boost’un MCP’si aracılığıyla yapabileceği işlemler:

Uygulama İçi Keşif: PHP ve Laravel sürümlerinizi, veritabanı motorunu, yüklü ekosistem paketlerini ve tüm Eloquent modellerinizi okuyarak ajanın tam olarak ne ile çalıştığını bilmesini sağlar.

Veritabanı Erişimi: Tablolar, sütunlar, ilişkiler dahil olmak üzere tam şemanızı inceleyebilir, veritabanınıza sorgu çalıştırabilir ve veri yapınızı anlayabilirsiniz. Ajan migration yazması gerektiğinde, zaten mevcut olanları bilir.

Rota Analizi: Uygulamanızdaki tüm rotaları listeleyip inceleyebilir. Ajan, bir kontrolör metodunu önerdiğinde, mevcut rotaların hangi isimlendirmenin kullanıldığını anlar.

Artisan Entegrasyonu: Mevcut Artisan komutlarını listeleyip bunları çalıştırabilir. Ajanın php artisan make:model komutunu çalıştırmasını istiyorsanız, bunu yapabilir.

Tinker ile Kodu Çalıştırma: Uygulamanız bağlamında rastgele PHP kodu çalıştırabilir. Ajan, varsayımlarını test edebilir ve bir çözüme karar vermeden önce davranışları doğrulayabilir. Bu özellik göz ardı edilmemelidir. Bu, ajanın User::active()->count()‘ın beklediği şeyleri döndürüp döndürmediğini kontrol edebilmesi anlamına gelir.

Yapılandırma Erişimi: Yapılandırma değerlerinizi ve mevcut anahtarları okuyabilir. Artık sıralama sürücüsü ayarları veya önbellek yapılandırmaları hakkında tahmin yürütmek zorundasınız.

Log Okuma: Uygulama loglarını ve tarayıcı hatalarını okuyabilir. Bir şey bozulduğunda, ajan, hata mesajını gerçek bir şekilde okuyabilir, böylece siz kütük izlerini kopyalayıp yapıştırmak zorunda kalmazsınız.

Dokümantasyon Arama: Laravel’in yayınlanmış dokümantasyon API’sine, yüklediğiniz paket sürümlerine göre filtrelenmiş olarak sorgu gönderebilir. Bu özellik, 17.000’den fazla indekslenmiş doküman kaydıyla birlikte gelir. Ajan, belongsToMany‘ın sizin tam Laravel versiyonunuzda nasıl çalıştığını öğrenmek istediğinde, doğru yanıtı alır.

Altyapı Bağlamı İçin Herd’in MCP Sunucusunu Eklemek

Eğer yerel geliştirme için Laravel Herd kullanıyorsanız (ve macOS veya Windows üzerinde çalışıyorsanız, kesinlikle kullanmalısınız), bir ikinci MCP sunucusu kurmalısınız. İyi haber, Boost, Herd’i algıladığında otomatik olarak Herd MCP sunucusunu kurar.

Herd’in MCP’si, farklı bir bağlam katmanı ekler. Boost, uygulama düzeyindeki zeka ile ilgilenirken, Herd altyapınızı kapsar:

Site Bilgisi: Yerel URL’niz, ortam değişkenleri, PHP sürümü, Node sürümü. Ajan, yerel kurulumunuzu tam olarak bilir.

Hizmet Keşif: Hangi hizmetlerin çalıştığını (MySQL, Redis, Typesense, Laravel Reverb) ve her biri için bağlantı bilgilerini gösterir. Artık, ajanın Memcached çalıştırırken Redis komutları önerdiğini düşünmenize gerek yoktur.

Debug İşlemleri: Beni çok etkileyen bir özellik. Herd’in MCP’sinde, debug_site istemi, gerçekleştirilen sorguları, dağıtılan görevleri, logları, dump çağrılarını ve dışarıya yapılan HTTP isteklerini kayıt altına alır. Ajana “yavaş sayfa yüklemesini debug et” dediğinizde, gerçek sorgu kaydını çeker.

Birlikte çalışan yapılandırma, .mcp.json dosyanızda şöyle görünür:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    },
    "herd": {
      "command": "php",
      "args": ["/Applications/Herd.app/Contents/Resources/herd-mcp.phar"],
      "env": {
        "SITE_PATH": "/path/to/your/project"
      }
    }
  }
}

İki MCP sunucusu, biri uygulama mantığını, diğeri yerel ortamınızı kapsıyor. Ajanınız artık büyük resmi görmektedir.

Kılavuzlara Yönelik “Başlangıçta Durdurma” Yaklaşımı

Jeffrey Way’in Laracasts’ta gösterdiği bir iş akışı ipucu, Boost’un özel kılavuzları ile yapabileceğiniz en değerli şey olduğuna inanıyorum.

Her seferinde AI ajanın bir hata yaptığında, sadece düzeltip geçmeyin. Kılavuzlarınızı güncelleyin. Ajan, Livewire 3 projesinde wire:model.defer kullanıyorsa, özel kılavuzlarınıza şöyle bir satır ekleyin: “Livewire 3’te, wire:model varsayılan olarak geciktirilmiştir. .defer modifikörü artık mevcut değildir. Gerçek zamanlı etkileşim ihtiyacı yoksa , wire:model.live kullanın.” Ajan iş mantığını kontrolörler içinde mi koydu? Ekleyin: “Tüm iş mantığı, app/Actions/ altında Action sınıflarına konulur.”

Bu, “başlangıçta durdurma” yaklaşımıdır. Deseni düzeltin, sadece durumu değil. Zamanla, özel kılavuzlarınız takımınızın sözleşmelerinin ve projenizin belirli quirklərinin yaşayan bir belgesi haline gelir. Ajan, her düzeltme ile daha iyi hale gelir çünkü düzeltmeler kalıcıdır.

Bir .ai/guidelines/project-conventions.md dosyası oluşturarak, her seferde ajanın bir şeyleri yanlış yaptığında kurallar eklemeye başlayın:

## Proje Sözleşmeleri
- İş mantığı için Action sınıfları kullanın, asla kalın kontrolörler değil
- Her zaman Pest testleri yazın, PHPUnit değil
- İstek doğrulaması için Laravel Data DTO'larını kullanın
- Kuyruk isimleri şu biçimi izlemelidir: {domain}-{action} (örneğin, billing-process-payment)
- Tüm API yanıtları, ham JSON değil, ApiResponse sınıfımızı kullanmalıdır
- Mümkünse özelleştirilmiş anahtarlarla rota model bağlamasını kullanın

Çarpıcı olması gerekmiyor. Projenizin gerçekten nasıl çalıştığı konusunda dürüst olmalı.

Bağlamın Farkı Yarattığı Durum: Gerçek Bir Örnek

Boost’un sonucunu değiştirdiği bir senaryoyu inceleyelim.

Boost olmadan Claude Code’a şu şekilde sorabilirsiniz: “Kullanıcıları CSV olarak dışa aktarma özelliği ekle.” Ajan, dosyalarınıza bakarak bir Kullanıcı modeli görecek ve genel bir CSV dışa aktarma oluşturmaya çalışacaktır. Muhtemelen fputcsv kullandığı ya da yüklü olmayan bir paketi kullanmaya çalışacaktır. Oluşturulan kod izole bir şekilde çalışır ama uygulamanıza uygun olmayabilir.

Boost ile aynı istek, tamamen farklı bir iş akışını tetikler. Ajan, önce app-info aracını kullanarak yüklü paketlerinizi kontrol eder. Laravel Excel’in yüklü olduğunu görür. Rotalarınızı routes aracıyla kontrol ederek isimlendirme desenini bulur. Kullanıcı modelinizi schema aracıyla inceleyerek hangi sütunların mevcut olduğunu anlar. Dokümanları kontrol ederek mevcut Laravel Excel API’sını doğrular.

Sonuç? Mevcut paketlerinizi kullanan, isimlendirme sözleşmelerinize uyan ve gerçek veritabanı şemanızla çalışan kod. Genel değil, sizin kodunuz.

Bu, çok kiracılı bir SaaS uygulaması gibi karmaşık bir şey üzerinde çalışıyorsanız daha da önemlidir; burada ajan, kiracı kapsamını, veritabanı ayrımını ve özel yönlendirme stratejinizi anlamalıdır.

Eğer AI destekli özellikleri Laravel ile geliştiriyorsanız, bağlamın kalite çıktısı için ne kadar önemli olduğunu zaten biliyorsunuz. Aynı ilke, kodunuzu yazan AI için de geçerlidir. Daha fazla bağlam, daha iyi kod demektir. Her seferinde.

Boost’u Güncel Tutmak

Boost aktif olarak geliştirilmektedir (Şubat 2026 itibarıyla v2.1.3). Kılavuzlar ve beceriler, Laravel ekosistem paketleri yeni sürümler yayınladıkça evrim geçirir. Bunu belirli aralıklarla çalıştırmalısınız:

php artisan boost:update

Bu, yerel kılavuzlarınızı ve becerilerinizi, yüklü paketleriniz için mevcut sürümlerle eşleşecek şekilde güncelleyerek yeniler. Genel bir alışkanlık olarak, bunu composer update sonrası çalıştırmak iyidir, özellikle büyük paket sürümleri yükseltilirken.

Eğer bir ekip içinde çalışıyorsanız, bir kural belirleyin: paketleri güncelleyen kişi boost:update komutunu çalıştırmalı ve ajanın hala doğru şekilde davrandığını doğrulamalıdır. .ai/guidelines/ içindeki özel kılavuzlar güncelleme komutundan etkilenmez, böylece projenize özel kurallar bütünlüğünü korur.

Hızlı Karşılaştırma: Boost Kullanmak vs. Kullanmak İstememek

AI’yi Laravel ile kullanmak için Boost’a kesinlikle ihtiyacınız yoktur. Kendi CLAUDE.md dosyalarınızı yazabilir, bağlam belgelerini manuel olarak güncelleyebilir ve istemlerde ilgili bilgileri kopyalayıp yapıştırabilirsiniz. Bazı geliştiriciler bunu başarılı bir şekilde yapmaktadır.

Ama bakım yükü gerçektir. Paketler değiştiğinde bu dosyaları güncellemeniz gerekir. Veritabanı şeması bilgilerini içermeyi unutmamalısınız. Hangi sözleşmelerin hangi kod parçaları için önemli olduğunu takip etmelisiniz. Boost, bunların tümünü otomatikleştirir.

Dokümantasyon arama aracı, her zaman API belgelerini bağlam pencerelerine biçimlendirip yapıştırma süresinden tasarruf etmemi sağlıyor. Sadece JSON yapılandırma dosyalarınızı kontrol etmek veya bir yanıt yapısını doğrulamak gibi basit şeyler bile, ajanın uygulamanızı zaten tanıması durumunda daha hızlı hale gelir. Tinker entegrasyonu, ajanın varsayımlarını doğrulamasına olanak tanır; bu da “doğru görünüyor ama çalışmıyor” kodu üretimini önemli ölçüde azaltır.

Sıkça Sorulan Sorular

Laravel Boost, Docker veya WSL ortamlarında çalışır mı?

Evet, ancak MCP sunucusunun konteyneriniz içinde çalıştığında IDE ile iletişim kurmasını sağlamak için ekstra yapılandırma gerektirebilir. Ana sorun veritabanı bağlantısıdır; eğer .env dosyanız mysql‘ı veritabanı sunucu konumu olarak gösteriyorsa, dışarıda çalışan MCP sunucusu bu hostname’i çözemez. Çözüm, MCP sunucusunu aynı konteyner içinde çalıştırmaktır. .mcp.json dosyanızı kullanmak için docker compose exec olarak ayarlamanız gerekecek.

Boost, eski Laravel sürümlerinde kullanılabilir mi?

Boost, PHP 8.2 veya daha yüksek versiyonlarda Laravel 10, 11 ve 12’yi destekler. Kılavuzlar sürüm bilincine sahiptir, bu nedenle belirli sürümünüze uygun talimatlar alırsınız. Eğer hâlâ Laravel 9 veya altındaysanız, önce yükseltmeniz gerekir.

Boost, kodumu dış sunuculara gönderiyor mu?

MCP sunucusu tamamen yerel olarak çalışmaktadır. Tek dış çağrı, belgeler arama API’sıdır; bu, sorgunuzu ve yüklü paket sürümlerinizi Laravel’in barındırılan arama uç noktasına gönderir ve ilgili belgeleri geri döner. Gerçek uygulama kodunuz bilgisayarınızda kalır.

Boost’un oluşturduğu dosyaları sürüm kontrolüne eklemeli miyim?

Bu dosyaları .gitignore dosyanıza eklemenizi öneririm. .mcp.json, CLAUDE.md, AGENTS.md ve ajana özel dizinler, boost:install ile yeniden oluşturulmaktadır. Her geliştirici kurulum komutunu çalıştırabilir ve kendi IDE ve tercihlerine göre yapılandırılmış dosyaları alabilir.

Boost, sadece iyi bir CLAUDE.md dosyası yazmaya kıyasla nasıl?

İyi bir CLAUDE.md özenle bakım yapıldığında size oldukça yol aldırabilir. Ancak Boost’un avantajı, ölçek ve bakım sağlamasıdır. 16’dan fazla paket için kılavuzlar, sürüm bilincine sahip belgeler ve ajana uygulamalarınıza canlı erişim sağlamasıdır. Bunun bazılarını manuel olarak tekrarlayabilirsiniz, ancak paket güncelleme talepleriyle sürekli güncel tutmak zor bir iş.

Sıradaki Adımlar

Eğer zaten AI kullanıyorsanız Laravel geliştirmede, Boost’u eklemek sadece üç dakika alır ve ilk istemden itibaren kod kalitesindeki farkı görebilirsiniz. Kurulumunu yapın, etkileşimli kurulumu çalıştırın ve yapmaya başlayın. Sonrasında “başlangıçta durdurma” yöntemini benimseyerek özel kılavuzlar oluşturun ve ajanınızın zamanla daha akıllı hale geldiğini görün.

Bağlam problemi gerçektir, ancak bu sorun çözüldü. AI ajanın sadece kapıyı açmanızı bekliyor.