Bir tərtibatçı GitHub və DEV.to API-larını birləşdirən MCP serveri yazarkən maraqlı bir qərarla üzləşib: aşağı səviyyəli JSON-RPC protokolu ilə birbaşa işləmək, yoxsa FastMCP dekoratorlarından istifadə etmək? O, praktikada 8 alət yazdıqdan sonra qəti nəticəyə gəlib – əgər işiniz sadəcə bir neçə REST API-ni alətə çevirməkdirsə, aşağı səviyyəli yanaşma lazımsız mürəkkəblikdir.
Niyə əl ilə yazmaq problemlidir?
MCP serverinin əsasında JSON-RPC dayanır. Hər yeni alət üçün tərtibatçı əl ilə aşağıdakı addımları yerinə yetirməlidir: alətin adını, təsvirini və JSON sxemini qeydiyyatdan keçirmək, dispatcher yazmaq, dönüş dəyərini TextContent/ImageContent qablaşdırmasına çevirmək. Bütün bunlar avtomatlaşdırılmadıqda hər alətlə xətti olaraq artan iş yükü yaradır. Tərtibatçı deyir: “8 alət üçün 8 sxem bloku, bir if/elif dispatcher zənciri və 8 cavab qablaşdırma əməliyyatı – bunların heç biri GitHub və ya DEV.to çağırışının əsl məntiqi ilə bağlı deyil.”
Alternativ olaraq FastMCP dekoratoru (@mcp.tool()) istifadə edildikdə hər şey dəyişir: tip göstəricisi (repo: str) avtomatik JSON sxeminə çevrilir, docstring alətin təsviri olur, qaytarma tipi cavab formasını təyin edir. Yeni alət əlavə etmək üçün sadəcə funksiya yazıb üstünə @mcp.tool() qoymaq kifayətdir. Dispatcher yeniləmək, TextContent yazmaq, protokol qatına toxunmaq lazım deyil.
İki real çətinlik
FastMCP'in hər şeyi sehrli şəkildə həll etdiyini düşünmək səhvdir. İlk problem – dönüş tipinin gizli məcburiyyəti. Məsələn, list_articles funksiyasında per_page parametri üçün tip göstəricisi qoymaq kifayət deyil – sərhədləri əl ilə yoxlamaq (min(per_page, 30)) lazımdır. “Dekorator sxem generasiyasını pulsuz verir, amma arqument validasiyasını yox” – deyə tərtibatçı xəbərdarlıq edir.
İkinci problem – səhv idarəsi. _gh() funksiyası HTTPError qaldırdıqda FastMCP onu “xəta baş verdi” kimi agentə ötürür. Agent “404, repo adı səhvdir” kimi məlumatlandırıcı xəta görmək istəyir. Bu səbəbdən bəzi alətlərdə HTTP status kodlarını əl ilə yoxlamaq və agentin başa düşəcəyi mesajlara çevirmək lazım gəlir. “Amma bu problemlər aşağı səviyyəli API ilə də mövcuddur – sadəcə daha çox kod yazmaq lazımdır” – deyə tərtibatçı əlavə edir.
Nəticədə, tərtibatçının qərarı aydındır: bu layihə üçün FastMCP dekoratorları düzgün seçimdir. “Aşağı səviyyəli API protokol nəzarəti, xüsusi daşımalar və qeyri-standart danışıqlar üçün lazımdır. 8 REST API qurğusunu agentə çevirirsinizsə, siz o ‘kimsə’ deyilsiniz – və protokol qatındakı mürəkkəblik heç bir real probleminizlə bağlı deyil” – deyə o yekunlaşdırır.
