Generic MCP Araç Kutusu: Kendini Kaydeden Araçlar

Laravel uygulamalarında MCP sunucuları kurduğum sürede, bazı kalıplar dikkatimi çekti: sürekli aynı araçları yeniden yazıyorum. Her sunucu bir whoami komutuna ihtiyaç duyar. Logları takip etmek, başarısız işlere göz atmak, birini tekrar denemek, kuyruğun çalışıp çalışmadığını kontrol etmek gibi işlemler sürekli tekrarlanıyor. Bunlar domain logic değil; proje projeye kopyalayıp hafif modifiye edilen genel operasyonel yüzeyler.

Bunun üzerine bu araçları bir pakette toplamak gerektiğine karar verdim. Bugün cleaniquecoders/laravel-mcp-kit genel bir toolbox ile güncellendi — domain bağımlılığı olmayan, dolayısıyla paket içinde yer alması gereken birkaç araç. İlginç olan, araçların kendisi değil. Tamamen bir araç var olup olmamasını belirleyen iki kural var.

Toolbox gönderme problemi

Bir toolbox paketi içinde bir gerilim vardır. list_audits, issue_mcp_token, list_roles gibi gerçekten faydalı araçları göndermek istersiniz. Ancak list_audits yalnızca owen-it/laravel-auditing paketi yüklü olduğunda anlam kazanır. issue_mcp_token Sanctum gerektirir. list_roles içinse spatie/laravel-permission gerekir.

Naif bir yaklaşım — hepsini kaydetmek — bir ajan, alt paket yokken bir araca erişmeye çalıştığında patlar: bir fatal Class not found hatası alır ya da daha kötüsü, araç MCP araç listesinde mevcut gibi görünür fakat çağrıldığında hata verir. Bir ajan list_roles ‘un geçersiz olduğunu, mid-task sırasında anlayamaz.

Bu nedenle toolbox, kendi hakkında dürüst olmalıdır. Bir host, yığdığı desteğin destekleyebileceği araçları almalıdır — yarım bağlı özellikler olmadan, hayali girişler olmadan.

Kural 1: Mevcutluk ile tercih etme

Çözüm, bir aracın yalnızca destekleyici paketi (ve gereken bir tablo) gerçekte bulunduğunda kaydedilmesidir. Her koşullu araç bir statik soruya yanıt verir:

class ListAuditsTool extends McpKitTool
{
    public static function isAvailable(): bool
    {
        return class_exists(static::model());
    }

    protected static function model(): string
    {
        // Paketin kendi yapılandırmasından çözümlenir, böylece host'un
        // özel Audit modeli dikkate alınır, hard-coded olmaz.
        return config('audit.implementation', 'OwenIt\\Auditing\\Models\\Audit');
    }
}

Ve kayıt — sunucunun sergilediği şeyler için tek gerçek kaynak — bunu filtreler:

public static function tools(): array
{
    return array_values(array_filter([
        // Tier 1 — saf haliyle, her zaman açık (zero dependencies).
        WhoAmITool::class,
        SystemHealthTool::class,
        TailLogsTool::class,
        ListFailedJobsTool::class,
        RetryFailedJobTool::class,
        QueueStatusTool::class,

        // Tier 2 — yalnızca destekleyici paket mevcut olduğunda kayıtlı.
        ListAuditsTool::isAvailable() ? ListAuditsTool::class : null,
        IssueMcpTokenTool::isAvailable() ? IssueMcpTokenTool::class : null,
        ListRolesTool::isAvailable() ? ListRolesTool::class : null,
        GetUserPermissionsTool::isAvailable() ? GetUserPermissionsTool::class : null,
    ]));
}

array_filter null değerleri temizler; sunucu, hayatta kalabilen herhangi bir şeyle başlatılır. Sonradan Sanctum yükleyince token araçları bir sonraki başlatmada görünür hale gelir, kod değişikliğine gerek kalmaz. Auditing’i kaldırın ve list_audits sessizce kaybolur — sunucu kademeli olarak düşer, bir hata göstermeden.

Temel tasarım seçeneği, bunu tek bir yerde tutmaktır. TaskServer::boot() ToolRegistry::tools() okur, başka hiçbir şey kayıt kararını vermez. “Bu sunucu, bu yükle neyi sergiliyor?” diye merak ettiğinizde, okuyacağınız tam bir liste vardır. class_exists kontrollerini yirmi araç kurucusuna yayarsanız, anlamlandırılması zor bir sistem oluşturdunuz.

Belirtilmesi gereken ince bir detay var: isAvailable() bir statik yetenek kontrolüdür, ve araç handle() içinde de yeniden kontrol eder:

public function handle(Request $request): Response
{
    if (! static::isAvailable()) {
        return Response::error('Audit reading is unavailable — owen-it/laravel-auditing is not installed.');
    }
    // ...
}

Baskı ve kayış. Kayıt, kullanılamayan bir aracın asla handle()‘e erişmediğini sağlamalıdır — fakat eğer birisi onu doğrudan bağlarsa, araç temiz bir şekilde reddedilir, fatal bir hata vermeden. Bunu bir sözleşme gibi düşünün: kayıt, çalışamayacağınız zaman sizi aramayacağını taahhüt eder, yine de sözün tutulup tutulmadığını kontrol edersiniz.

Kural 2: Her araç için kapılar ve yalnızca uuid

Mevcutluk, bir aracın varlığını belirler. Yetkilendirme, bu çağrıyı yapanın bunu kullanıp kullanamayacağını belirler. Bunlar farklı boyutlardır ve toolbox bunları ayrı tutar.

Her araç, gerekli yeteneğini hard-coded bir izin adı yerine yapılandırmadan okur:

protected function ability(): string
{
    return $this->configuredAbility();
}

Bu dolaylılık gözüktüğünden daha önemlidir. Uygulamanız muhtemelen izinlerini view-audits olarak adlandırmıyordur; kendi şemasına, kendi korumasına, kendi rol adlarına sahiptir. Tüm yetenekleri config('mcp-kit.abilities.*') üzerinden yönlendirerek, host, kitin genel yeteneğini, kendi izin sisteminin gerçekten kullandıklarına yeniden haritalar. Paket, ne korunması gerektiği hakkında bir görüş gönderirken; host, kim geçidi geçebilir konusunda tam kontrolu elinde tutar.

Kuralın diğer yarısı: okumalar #[IsReadOnly] ile etiketlenir ve yazmalar çağrılabilir bir İşleme yönlendirilir — asla araçta doğrudan değil. retry_failed_job kendisi bir işi yeniden yönlendirmez; bir RetryFailedJob işlem çağırır. Araç, MCP biçimindeki kapıdır; İşlem durumu gerçekten değiştiren şeydir ve bağımsız olarak test edilebilir ve MCP dışında tekrar kullanılabilir.

Ve kimlik sadece uuid ile kalır. Araçlar, yalnızca genel UUID’leri yayar ve alır, asla iç otomatik artan id’leri değil. Bir ajan — veya transkripti okuyan herhangi biri — sizin ardışık birincil anahtarlarınızı görmez, bu da satır sayılarını sızdırır ve sıralamayı kolaylaştırır. Genel id uuid’dir; iç id içerde kalır.

Güzel bir kazanç: imza ile dışa aktarma deseni

Genelleme açısından iyi bir örnek olan bir aracı vurgulamak gerekir. export_logs dev bir log metnini MCP yanıtına yerleştirmez — bu, bir bağlam penceresini patlatabilir. Bunun yerine, kesimi diske yazar ve kısa ömürlü bir imzalı indirme URL’si verir:

// araç içinde:
return $this->download($contents, );

İmza, yeteneklerin kendisidir. Laravel’in signed middleware’i, bozulmuş veya süresi dolmuş bir bağlantının reddedilmesi için yeterlidir, bu nedenle indirme rotasında ikinci bir kimlik doğrulama katmanına ihtiyacınız yoktur — URL ya doğrulur ya da doğrulanmaz. Ajan bir bağlantı alır, insan (veya çağıran sistem) bir kez alır ve bağlantı bir zamanlayıcı ile sona erer. Büyük yükler, konuşmayı tıkamaktansa yan kapıdan çıkar.

Kayıt testleri, yalnızca araçları değil

Burada test edilmesi gereken en önemli şey, herhangi bir tek araç değil — kayıt mantığıdır, çünkü bu kısım dallara sahiptir. Bir aracın mutlu yolu bozulduğunda hemen fark edersiniz; ancak kayıtta sessizce kaybolan bir aracı fark etmeyebilirsiniz.

it(, function () {
    expect(ListAuditsTool::isAvailable())
        ->toBe(class_exists(\OwenIt\Auditing\Models\Audit::class));
});

it(, function () {
    $tools = ToolRegistry::tools();

    // Tier-1 araçlar zorunlu — her zaman burada.
    expect($tools)
        ->toContain(WhoAmITool::class)
        ->toContain(SystemHealthTool::class);
});

it(, function () {
    foreach (ToolRegistry::tools() as $tool) {
        if (method_exists($tool, )) {
            expect($tool::isAvailable())->toBeTrue();
        }
    }
});

O son test benim için çok önemli. Tasarımın dayandığı ilkeyi doğrular: eğer kayıtlıysa, çalışır. Her şey bunun altındadır.

Geçmeyeceğim sınır

Toolbox yalnızca genel olanla sınırlıdır. Herhangi bir domain ilişkisi — kimlik senkronizasyonu, geçit sağlama, dizin varlık kontrolü, iş kurallarınız — host uygulamasında, proje özelindeki İşlemelerin arkasında kalır. Kit, size genel omurgayı verir: ops, işler, loglar, tokenler, erişim önceliği deseni, imzalı URL yardımcı. Domain, sizin olmalı ve öyle olmalıdır; çünkü “genel” bir paket iş mantığınızı tanımaya başladığı gün, tekrar kullanılabilir olmaktan çıkar.

Tüm felsefe tek cümlede: omurgayı gönderin, organları değil. Kendini kaydeden, kendine kapı koyan ve yapamayacağı şeyleri yapıyormuş gibi davranmayan bir toolbox — ve domaininizi tam yerinde bırakır.

Açık kaynak, bu nedenle katman tabloları ve tam araç listesi depo üzerindedir: github.com/cleaniquecoders/laravel-mcp-kit.