Laravel ile Filament Kullanarak MCP Sunucusu Nasıl Oluşturulur

Orijinal makale hafiz.dev adresinde yayınlanmıştır.

Filament projelerinde bir Laravel MCP sunucusu oluşturmak, Claude Code veya Cursor kullanıyorsanız yaşadığınız hayal kırıklıklarını aşmanıza yönelik ciddi bir çözüm sunar. Kısacası, Laravel MCP, uygulamanızın veritabanı şemasını anlamakta güçlük çeken bir aracıdan ziyade, kontrol ettiğiniz bir sunucu üzerinden sorgulama yapar. Burada, hangi bilgilerin görünür olacağına ve nasıl bir yapı sunulacağına siz karar veriyorsunuz.

Bu eğitimde, bir e-ticaret sipariş yönetimi kurulumuna özel, pratik bir Laravel MCP sunucusu oluşturmayı öğreneceksiniz. Örnekler, tipik bir sahiplik yapısını takip edecek. İlerledikçe Eloquent verilerinizi filtrelerle açığa çıkaracak, yöneticinizin panel yapısını haritalayacak araçlar oluşturacağız ve her şeyi hem yerel geliştirme hem de uzaktan HTTP erişimi için yapılandıracağız.

Neden Filament Projeleri Bu Haliyle Gerektiriyor?

MCP eğitimleri genellikle yalnızca ham veritabanı tablolarını açığa çıkarmakla sınırlı. Ancak, Filament uygulamalarının ihtiyaç duyduğu çok daha fazlası var. Filament projelerinde alan mantığı, Eloquent modelleri ile Filament Kaynakları arasında bölünmüştür. Kaynaklar, verilerin nasıl filtrelendiğini, formların nasıl yapılandığını, hangi sütunların gösterileceğini ve izinlerin nasıl çalıştığını tanımlar. Ancak bu, veritabanı şemasında yer almaz.

Sadece veritabanı erişimine sahip bir yapay zeka aracı, yalnızca hangi sütunların mevcut olduğunu söyleyebilir. Hangi OrderResource sayfalarının kayıtlı olduğunu, oluşturma formunun nasıl göründüğünü veya özel widget’larınızın veriyi nasıl çektiğini bilemez. İşte bu boşluğu, Filament’i anlayan bir MCP sunucusu doldurur. Verilere ve yöneticinize iki katmanlı yapı ile erişim sağlarsınız.

Gereksinimler

Aşağıdakilere ihtiyacınız olacak:

• Laravel 12 veya 13 ( laravel/mcp paketi daha eski sürümleri desteklemiyor)
• Çalışan bir Filament v3+ kurulumu
• PHP 8.2 veya daha yüksek

Filament ile yeniyken, devam etmeden önce Filament ile yönetim panelleri oluşturma kılavuzunu gözden geçirin. Bu kılavuz, panel kurulumu ve kaynak yapısı içeriklerini detaylı bir şekilde ele alıyor.

Laravel MCP Kurulumu

Tek tek bir Composer komutu ile başlayın:

composer require laravel/mcp

Ardından, rota dosyasını yayınlayın:

php artisan vendor:publish --tag=ai-routes

Bu işlem, routes/ai.php dosyasını oluşturur. Bunu routes/api.php gibi düşünün ama AI istemcileri için. Bu dosyada MCP sunucularınızı kaydedeceksiniz, her birinin hangi ara katmanın çalışacağını kontrol edeceksiniz ve hangi sunucuların yerel (stdio tabanlı) hangilerinin web (HTTP tabanlı) olduğuna karar vereceksiniz. İkisinin de aynı dosyada karıştırılabilmesi mümkündür.

Filament Sunucusu Oluşturma

Üreticiyi çalıştırın:

php artisan make:mcp-server FilamentAdminServer

Yeni sınıf, app/Mcp/Servers/FilamentAdminServer.php adresinde bulunacaktır. Bu sınıftaki PHP öznitelikleri çoğu kişinin fark ettiğinden daha önemlidir. #[Instructions] özniteliği, AI modelinin bu sunucuyla ilgili okuyacağı ilk şeydir. Ne zaman bu sunucuyu sorgulayacağınızı belirler, dolayısıyla belirsiz talimatlar belirsiz bir aracı davranışına yol açar.

"Veri erişimi sağlar" demek, araca hiçbir şey söylemez. "Filament yönetim kaynaklarına, Eloquent verilere ve panel navigasyonuna yapılandırılmış erişim sağlar" demek ise, bu sunucunun ne zaman kullanılacağını tam olarak belirtir. Burada ne kadar net olursanız, aracı doğru aracı kullanması için o kadar az kez manuel olarak yönlendirmek zorunda kalırsınız.

Gerekli veri yapısını oluşturduktan sonra, $tools dizisine ekleyin. Her araç için örüntü, girişleri net bir şekilde doğrulamak, belirli alan seçimi ile sorgulama yapmak ve yapılandırılmış çıktı döndürmektir. Bunu yaptıktan sonra, yeni her bir araç 10 dakika kadar sürer.

İlk Araç: Siparişleri Listeleme

Filament uygulamaları için en yararlı araç, aracıya iş mantığı filtreleri ile gerçek verileri sorgulama olanağı veren bir araçtır, ham SQL değil. ListOrdersTool oluşturalım:

php artisan make:mcp-tool ListOrdersTool

İşte tam uygulama:

validate([
            'status' => 'nullable|string|in:pending,processing,completed,cancelled',
            'limit' => 'nullable|integer|min:1|max:50',
        ], [
            'status.in' => 'Status must be one of: pending, processing, completed, cancelled.',
            'limit.max' => 'Limit cannot exceed 50 records.',
        ]);

        $orders = Order::query()
            ->with('customer')
            ->when(!empty($validated['status']), fn($q) => $q->where('status', $validated['status']))
            ->latest()
            ->limit($validated['limit'] ?? 10)
            ->get();

        return Response::structured($orders->map(fn($order) => [
            'id' => $order->id,
            'reference' => $order->reference,
            'status' => $order->status,
            'total' => $order->total,
            'customer_name' => $order->customer?->name,
            'created_at' => $order->created_at->toDateTimeString(),
        ])->toArray());
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()->enum(['pending', 'processing', 'completed', 'cancelled'])->description('Filter orders by status. Omit to return all statuses.'),
            'limit' => $schema->integer()->description('Number of records to return. Defaults to 10, max 50.')->default(10),
        ];
    }
}

Burada dikkate değer üç karar var. İlk olarak, Response::structured() yapay zeka istemcisinin ayrıştırıp yorumlayabileceği uygun bir JSON nesnesi döndürür, sadece bir metin bloğu değil. İkinci olarak, #[IsReadOnly] istemciye bu aracın herhangi bir durumu değiştirmediğini belirtir, böylece onay talep etmeden serbestçe çağrılabilir. Son olarak, doğrulama hata mesajları yapay zeka için, insan formu için yazılmıştır. Belirsizliği giderir.

Her aracınızı sunucunun $tools dizisine kaydedin. Böylece, eksiksiz bir komut akışı kurulabilir.

Daha Derin Bir Araç: Tek Bir Kayıt Alma

Liste aracı iyi bir başlangıçtır, ancak araçların sıklıkla bir kaydı tam ayrıntılarla incelemesine ihtiyaç duyarız. Bu, aracın liste aracını çağırıp bir özet döndürmesi ve ardından tam kayıt üzerinde hangi ilişkilerin ve alanların mevcut olduğunu tahmin etmeye çalışması gerektiği noktayı ortadan kaldırır.

php artisan make:mcp-tool GetOrderTool

validate([
            'id' => 'required|integer|exists:orders,id',
        ], [
            'id.required' => 'You must provide an order ID.',
            'id.exists' => 'No order found with that ID. Use the list-orders tool first to find valid IDs.',
        ]);

        $order = Order::with(['customer', 'items.product', 'statusHistory'])
            ->findOrFail($validated['id']);

        return Response::structured([
            'id' => $order->id,
            'reference' => $order->reference,
            'status' => $order->status,
            'total' => $order->total,
            'customer' => [
                'id' => $order->customer?->id,
                'name' => $order->customer?->name,
                'email' => $order->customer?->email,
            ],
            'items' => $order->items->map(fn($item) => [
                'product_name' => $item->product?->name,
                'quantity' => $item->quantity,
                'unit_price' => $item->unit_price,
            ])->toArray(),
            'created_at' => $order->created_at->toDateTimeString(),
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'id' => $schema->integer()->description('The database ID of the order to retrieve.')->required(),
        ];
    }
}

id.exists doğrulama mesajı, araca ne yapması gerektiğini açıkça söylemiş olur. Bu, geliştirdiğiniz her araçta dikkate alınması gereken bir kalıptır. Güzel bir MCP doğrulama hatası, aracın bir sonraki eylemini yönlendirir, sadece başarısızlığı bildirip kaybetmez.

Her iki aracı da sunucunuza ekleyin:

protected array $tools = [
    ListOrdersTool::class,
    GetOrderTool::class,
];

Bir Kaynak Eklemek: Filament Navigasyonunu Açığa Çıkarma

Araçlar sorguları yönetirken, kaynaklar bağlamı yönetir. Gerçek bir fark vardır. Bir araç talep üzerine çalışır ve taze veri döndürür. Bir kaynak, aracının bir kez okuyacağı ve kendini güncelleyebilmesi için uygulamanızın haritası gibidir. Hangi kaynakların mevcut olduğunu, hangi modelin yönetildiğini ve doğru yönetim paneli URL’lerinin ne olduğunu belirler.

php artisan make:mcp-resource FilamentNavigationResource

getResources())
            ->map(fn($resourceClass) => [
                'class' => $resourceClass,
                'model' => $resourceClass::getModel(),
                'plural_label' => $resourceClass::getPluralModelLabel(),
                'index_url' => $resourceClass::getUrl('index'),
            ])
            ->values()
            ->toArray();

        return Response::structured([
            'panel_id' => $panel->getId(),
            'resources' => $resources,
        ]);
    }
}

Sunucunuzun $resources dizisine kaydedin. Claude Code bu kaynağı bir oturumun başında okuduğunda, her bir yöneticideki kaynak için kesin sınıf adını, hangi modelin yönetildiğini ve doğru dizin URL’sini bilir. Bu, pratikte yararlı bir bölüm yapısı oluşturur.

Sunucunun Kaydedilmesi

routes/ai.php dosyasını açın. İki seçeneğiniz var.

Claude Code veya Cursor yerel olarak çalışıyorsa, local kullanın. Sunucu, MCP istemcisinin stdio üzerinden başlattığı bir alt süreç olarak çalışır:

use App\Mcp\Servers\FilamentAdminServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::local('filament-admin', FilamentAdminServer::class);

Uzaktan HTTP istemcileri (web tabanlı bir AI asistanı, harici bir ajan veya yerel makinenizin dışındaki herhangi bir şey için) web kullanın ve kimlik doğrulama ara katmanını ekleyin:

Mcp::web('/mcp/filament', FilamentAdminServer::class)
    ->middleware(['auth:sanctum', 'throttle:mcp']);

İkisi de aynı dosyada aynı anda yaşayabilir. İşte her şeyin bağlandığında tam akış görünümü:

flowchart TD
    A[Claude Code / Cursor] -->|calls tool or reads resource| B[FilamentAdminServer]
    B --> C{Request type}
    C -->|ListOrdersTool| D[Eloquent query with filters]
    C -->|GetOrderTool| E[findOrFail with relations]
    C -->|FilamentNavigationResource| F[Filament panel + resources]
    D --> G[Response::structured]
    E --> G
    F --> G
    G --> A

MCP Denetleyici ile Test Etme

Gerçek bir istemcide bağlantıdan önce, her şeyin çalıştığını doğrulamak için yerleşik denetleyiciyi kullanın. Yerel bir sunucu için:

php artisan mcp:start filament-admin --inspector

Denetleyici, her bir aracı manuel olarak çağırabileceğiniz ve ham JSON yanıtlarını inceleyebileceğiniz bir tarayıcı arayüzü sağlar. Bu, eksik eager yüklemeleri, doğrulama kuralı uyumsuzluklarını veya geçerli sürümdeki Filament API yöntemlerinin mevcut olup olmadığını yakalamanın en hızlı yoludur.

Güvenlik: Atlanmaması Gerekenler

Tüm bunlar, yerel geliştirme aşamasını geçmeden önce birkaç şeyi doğru yapmak önemli. Yazma araçlarını shouldRegister ile sınırlandırın. Verileri oluşturan, güncelleyen veya silen bir tool'un görünmesini sağlamak için izinleri kontrol etmelisiniz:

public function shouldRegister(Request $request): bool
{
    return $request->user()?->hasRole('admin') ?? false;
}

shouldRegister false dönerse, araç mevcut araçlar listesinde görünmez. Ajan, göremediği bir şeye erişemez. Bu, arka planda bir kimlik doğrulama hatası döndürecee bir durumda daha iyidir.

Web sunucuları için Sanctum kullanın. auth:sanctum ara katmanı ile Mcp::web() kaydınız, istemcilerin geçerli bir jeton almasını gerektirir. AI entegrasyonları için kısa süreli geçerliliğe sahip jetonlar verin, tıpkı dış API istemcileri için yaptığınız gibi. Farklı ajanlar veya oturumlar arasında aynı jetonları yeniden kullanmayın.

Asla ham Eloquent modelleri döndürmeyin. Her zaman açığa çıkardığınız alanların seçimini gerçekleştirin. Yukarıda kullanılan alan eşleştirmeleri bilerek yapılmıştır.

Ne Zaman Özel Sunucu Yapmalıyım Vs. Boost Kullanmalıyım?

Yerel geliştirmede Claude Code ile Laravel Boost, aracınıza şema denetimi, günlük okuma ve Tinker erişimi sağlar. Bu tür ihtiyaçlar için özel bir MCP sunucusuna ihtiyacınız yoktur.

Özel bir sunucu oluşturun, eğer iş mantığına uygun sorgulara ihtiyaç duyduysanız, yalnızca ham şemak erişimi yeterli gelmiyorsa. Ayrıca birden fazla Filament panelleriniz varsa, her biri için izinleri ve görünürlük özelliklerini ayarlamak için de kullanılır.

Tüm bu unsurlar, iyi tasarlanmış bir Laravel MCP sunucusu oluşturarak Filament uygulamanızı güçlü hale getirmeniz konusunda size yol gösterecektir. İlgili anahtar kelimeler arasında Web Geliştirme, Yazılım Mimarisi, Cloud Hosting ve Veritabanı Optimizasyonu gibi terimler de yer alabilir.