Laravel kullanarak kendi MCP sunucunuzu oluşturun

Laravel uygulamanıza Claude ile entegrasyon yapmak için bir REST API oluşturmak yerine Model Context Protocol (MCP) üzerinden bazı araçlar sunarak modelin doğrudan bunları çağırmasını sağlamaktasınız. Resmi laravel/mcp paketi bu süreci oldukça kolaylaştırıyor. Bu makalede, bir çevrimiçi mağaza için küçük bir MCP sunucusu oluşturacağız: modelin çağırabileceği araçlar, okuyabileceği kaynaklar, giriş doğrulaması ve şeffaflık için bir test.

Aşağıdaki adımları izleyerek gerekli bileşenleri oluşturacağız.

Prerequisites

• Güncel bir Laravel uygulaması (12.x sürümü iyi çalışır).
• PHP 8.2 veya daha yeni bir sürüm.
• Composer.
• Bağlanmak için bir MCP istemcisi. Claude Desktop veya Claude Code bu işlemi yapabilir, ayrıca MCP Inspector ile test gerçekleştirebilirsiniz.

Step 1: Paketi Yükleme

Composer ile paketi çekin:

composer require laravel/mcp

Sonra sunucularınızın kaydedildiği yönlendirme dosyasını yayınlayın:

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

Bu, routes/ai.php dosyasını oluşturur. Bu dosyayı routes/web.php dosyası gibi ele alın: sunduğunuz her sunucu burada bir satır alacak.

Step 2: Sunucu Oluşturma

Bir sunucuya bağlanan istemci, bu sunucu üzerinden araçlar, kaynaklar ve ipuçlarını gruplandırır. Bir sunucu oluşturun:

php artisan make:mcp-server OrdersServer

Bu işlemle birlikte app/Mcp/Servers/OrdersServer.php dosyasını elde edersiniz. Sınıf, kimliğini özelliklerle taşır ve sunduğu şeyleri üç dizi ile listeler:

Instructions niteliğini atlamayın. Bu, sunucunun ne amaçla kullanıldığını istemciye iletmek için gönderilir, böylece model ne üzerinde çalıştığını bilmiş olur.

Step 3: Sunucuyu Kaydetme

Sunucu kaydedilmediği sürece hiçbir işlevi olmaz. routes/ai.php dosyasına kaydedilmesi gerekmektedir. İki tür sunucu vardır: Web sunucusu, uzaktan istemciler tarafından HTTP üzerinden erişilebilir ve yerel sunucu, aynı makinedeki ajanlar için Artisan komutu olarak çalışır.

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

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware(['auth:sanctum', 'throttle:60,1']);

Mcp::local('orders', OrdersServer::class);

Web sunucuları normal yönlendirme yollarıdır; bu nedenle, zaten kullandığınız middleware geçerlidir. 8. Adıma döneceğiz.

Step 4: Araç Oluşturma

Bu, gerçek işlemleri gerçekleştiren kısımdır. Bir araç oluşturun:

php artisan make:mcp-tool SearchOrdersTool

Bir araç iki yönteme sahiptir. schema, kabul ettiği argümanları açıklar ve handle, işlemi gerçekleştirip bir yanıt döner. Aşağıda, siparişleri okumaya yönelik bir arama işlemi bulunmaktadır:

validate([
            'status' => ['nullable', 'in:pending,shipped,delivered,cancelled'],
            'limit' => ['integer', 'between:1,50'],
        ]);

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

        if ($orders->isEmpty()) {
            return Response::text('No orders matched that search.');
        }

        return Response::structured([
            'count' => $orders->count(),
            'orders' => $orders->map(fn($order) => [
                'reference' => $order->reference,
                'status' => $order->status,
                'total' => $order->total,
                'placed_at' => $order->created_at->toIso8601String(),
            ])->all(),
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()->enum(['pending', 'shipped', 'delivered', 'cancelled'])
                ->description('Only return orders with this status.'),
            'limit' => $schema->integer()
                ->description('Maximum number of orders to return.')
                ->default(10),
        ];
    }
}

Bu araç, yukarıda tanımlanan sunucunun $tools dizisinde yer alır, bu nedenle istemci artık onu çağırabilir.

Step 5: Girişi Doğrulama ve Modelin Okuyacağı Hatalar Yazma

Şeması şekli belirler. Laravel’in doğrulayıcısı kuralları zorunlu kılar, bir denetleyicide olduğu gibi:

$validated = $request->validate([
            'reference' => ['required', 'string', 'max:32'],
        ], [
            'reference.required' => 'Provide the order reference, for example "ORD-10423".',
        ]);

Bu kısım genellikle atlanır. Hata mesajı modele geri döner ve model, ne yapması gerektiğini bildirir. "Referans alanı gereklidir" ifadesi onu hiçbir şey anlatmaz. "Sipariş referansını sağlayın, örneğin ORD-10423" ifadesi, bunu yeniden denemesi için bilgi verir. Doğrulama mesajlarını, onlara nasıl harekete geçeceğini söyleyen talimatlar gibi yazın.

Step 6: İstemciye Araç Davranışını Anlatma

Notasyonlar, bir aracın davranışını tanımlar, ancak ne yaptığını değiştirmez. İstemci, araçları sunarken kullanıcıdan onay alıp almadığını belirlemek için bunları kullanır. İşte bu kısım:

validate([
            'reference' => ['required', 'string', 'max:32'],
        ]);

        $order = Order::where('reference', $validated['reference'])->firstOrFail();

        if ($order->status !== 'cancelled') {
            $order->update(['status' => 'cancelled']);
        }

        return Response::text("Order {$order->reference} is cancelled.");
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'reference' => $schema->string()
                ->description('The reference of the order to cancel.')
                ->required(),
        ];
    }
}

Sunucuya eklemek için CancelOrderTool::class öğesini $tools dizisine ekleyin.

Step 7: Bir Kaynak ve İpucu Ekleme

Araçlar, eylemlerdir. Diğer iki temel ise resmi tamamlar.

Kaynak, modelin çekebileceği okuma-hakkında bağlamdır. Argüman yoktur, yalnızca içerik döndüren bir handle yöntemi vardır:

Bir ipucu, istemcinin sunabileceği yeniden kullanılabilir bir şablondur. Argümanlarını tanımlar ve mesajları döner:

string('reference');

        return [
            Response::text('You write friendly customer service messages.')
                ->asAssistant(),
            Response::text("Draft a short update for the customer about order {$reference}."),
        ];
    }
}

Bu kaynakları make:mcp-resource ve make:mcp-prompt ile oluşturun, ardından sunucunun $resources ve $prompts dizilerine kaydedin.

Step 8: Sunucuyu Güvence Altına Alma

Bir web MCP sunucusu, verilerinizi okuma ve değiştirme yetkisine sahip bir halkalığa sahiptir. Bunu açık bırakmak, bir yönetici API'sini kimlik doğrulaması olmadan yayınlamak gibidir. Çünkü bu normal bir yol olduğu için, middleware ile korumanız gerekmektedir.

Basit bir seçenek, Laravel Sanctum ile bir jetondur. İstemci bunu Authorization başlığında gönderir:

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware(['auth:sanctum', 'throttle:60,1']);

Üçüncü taraf istemciler için, Laravel Passport ile OAuth 2.1 daha güçlü bir seçimdir. Keşif yönlendirmelerini kaydedin ve Passport'un korumasını uygulayın:

Mcp::oauthRoutes();

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware('auth:api');

Bir kullanıcı kimlik doğruladıktan sonra, istek doğrudan araşmaları alır, bu yüzden $request->user() normal gibi çalışır. Ayrıca, bir aracı kullanıcı bazında gizlemek için shouldRegister yöntemi kullanabilirsiniz:

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

shouldRegister yöntemi false dönerse, bu araç istemci listesinin içine asla görünmeyecek ve çağrılamayacaktır. Bir sunucu, farklı kullanıcılar için farklı araçlara sahiptir.

Step 9: Denetleme ve Test Etme

Gerçek bir istemci sunucuya dokunmadan önce iki şey denetlenir.

MCP Inspector, bir sunucuya bağlanır ve araçlarını, kaynaklarını ve ipuçlarını listeleyerek bunları manuel olarak çağırmanızı sağlar. Kayıtlı bir sunucuya ismi ile yönlendirin:

php artisan mcp:inspector orders

Bu, istemci ayarlarını kopyalamak için basit bir çıktı verir. Eğer sunucu kimlik doğrulama gerektiriyorsa başlık eklemeyi unutmayın.

Otomatik testler için normal bir test yazarak, kaydeden temel araçları çağırabilirsiniz. Yanıt, doğrulama yardımcılarına sahiptir:

create([
        'reference' => 'ORD-10423',
        'status' => 'shipped',
    ]);

    $response = OrdersServer::tool(CancelOrderTool::class, [
        'reference' => 'ORD-10423',
    ]);

    $response
        ->assertOk()
        ->assertSee('ORD-10423 is cancelled');

    expect($order->fresh()->status)->toBe('cancelled');
});

Hatalar ve bildirimler için uygun doğrulama yardımcıları ve kimliği doğrulanmış kullanıcılar için test yaparken actingAs yardımcı fonksiyonu mevcuttur.

Tamaşenisyat Sponsorum

Bir boş Laravel uygulamasından, okuma aracı, yazma aracı, kaynak, ipucu, kimlik doğrulama ve test ile birlikte bir MCP sunucusuna geçtiniz. Model artık bir standart arayüz aracılığıyla uygulamanızla çalışıyor ve herhangi bir protokol kodu yazmanız gerekmiyor. Buradaki desen basit: bir araç ekleyin, açıklmasını net bir şekilde verin ve okunabilir hata mesajları ile geçerli hale getirin, ardından doğru middleware ile kapatın.

Gerçek bağlantılar kurundukça, deneyimlerinizi paylaşabilirsiniz.