Phase 13: Tools & Protocols

MCP Server Oluşturma: Devletsiz Python ve TypeScript

Type: Build

Languages: Python, TypeScript

Prerequisites: Phase 13, Lesson 06

Time: ~85 minutes

Öğrenme Hedefleri

• İletişim zorunlu server/discoverMCP için 2026-07-28- Evet .
• Her istek üzerine protokol versiyonu ve istemci özelliklerini doğrulayın.
• Deterministik liste sırasıyla araçları, kaynakları ve ipuçlarını açıklayın.
• Geri dön .resultType, sunucu kimliği ve doğru sonuçları önbelleğe alıyor.
• Python ve TypeScript'te yeni satır sınırlı stüdyodan aynı devletsiz sözleşmeyi hizmet et.

Sorun

İlk mesajdan sonra müşteri yeteneklerini depolayan bir sunucu, oluşturulması kolay ve çalıştırılması zor. Aynı süreç sıralı müşteriye hizmet verebilir. Uzak bir talebe farklı bir işçiye düşebilir. Eski bir yetenek açıklaması yetki sınırları üzerinden davranış sızdırmasını sağlayabilir.

MCP 2026-07-28Bu uygulama, her istekleri kendi kendine tanımlayarak bu sorunun protokol kısmını çözer. Uygulama hala kalıcı notları, işleri veya açık durum ele geçirme işlemlerini tutabilir.

Bu ders, iki kez not sunucusu oluşturur. Python ve TypeScript sürümleri sadece protokol çekirdeği için standart kütüphanelerini kullanır.

Anlaşım

Modern gönderme döngüsü

textCopyread one JSON-RPC line
parse the envelope
if it is a notification, do not respond
validate params._meta for this request
route by method
wrap success with resultType and serverInfo
write one JSON-RPC response line
forget request-scoped metadata

Üç stüdyo kuralları hala geçerlidir:

• Sadece JSON-RPC mesajlarını stdout'a yazın.
• Mesajları yeni bir çizgiyle sınırlandır ve her cevabı sıfırla.
• Stdin EOF'e ulaştığında derhal çıkın.

Bu süreç ömrü, modern bir MCP seansı değil.

Başvuru onaylanması

Her talebin içinde:

jsonCopy{
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "notes-client",
        "version": "1.0.0"
      }
    }
  }
}

İlk iki alan gereklidir.clientInfomevcut kimlik biçimini doğrulayın, ancak onu kimlik doğrulama olarak değerlendirmeyin.

Eğer versiyon desteklenmiyorsa, return code -32022- Evet .requestedve supported. Kayıp istek metadata geçersiz params, kod -32602Daha önceki bir çağrıdan kayıp alanları asla doldurma.

İhtiyaclı keşif

Modern sunucular uygulamalı server/discover. Tam bir keşif sonucu desteklenen modern sürümleri, özellikleri, seçmeli talimatları, önbelleği ipuçları ve sonuçta sunucu kimliğini içerir _meta- ...

jsonCopy{
  "resultType": "complete",
  "supportedVersions": ["2026-07-28"],
  "capabilities": {
    "tools": {"listChanged": false},
    "resources": {"listChanged": false, "subscribe": false},
    "prompts": {"listChanged": false}
  },
  "ttlMs": 3600000,
  "cacheScope": "public",
  "_meta": {
    "io.modelcontextprotocol/serverInfo": {
      "name": "notes-server",
      "version": "2.0.0"
    }
  }
}

Discovery sunucuyu kilitlemez.tools/listBir keşif diye çağırmadan çünkütools/listzaten aynı talep metadataları taşıyor.

Araçlar

tools/listDevamlı sıralama, cevap önbelleğini iyileştirir ve model bağlamını istikrarlı tutar. Sonuç ayrıca ttlMsve cacheScope- Evet .

tools/callİçerik bloklarını gönderir ve isErrorProtokol zarfı veya yöntem parametreleri geçersiz olduğunda JSON-RPC hatası kullanın. Kullanın isError: truegeçerli bir araç çağrısı çalıştırıldığında ama araçın kendisi başarısız olduğunda.

Araç açıklamaları, uygulanma değil ipuçları kalır:

• readOnlyHint
• destructiveHint
• idempotentHint
• openWorldHint

Ev sahibi bunları onay ve sunum için kullanmalıdır.

Kaynaklar

resources/listsabit URI tanımlayıcılarını gönderir. resources/readBu da, tıklanan içeriği geri gönderir.2026-07-28, yani her ikisi de ttlMsve cacheScope- Evet .

KullanımcacheScope: "private"Kullanıcıya özgü not verileri için. Paylaşılan bir önbelleğe yetki bağlamlarında özel bir yanıt yeniden kullanılamaz.

Modern değişim teslimatı kullanmıyor resources/subscribeBir müşteri açılıyor .subscriptions/listenve istekler resourceSubscriptions10. dersi bu akışı oluşturur.

İpuçlar

prompts/list- Bu, gizliden gizlenebilir ve belirleyici.prompts/getgösterilen prompt sonucu tamamlanmıştır, ancak bu, önbelleğe alınan veya önbelleğe alınan sonuçlardan biri değildir.

Her başarılı sonuç yazılır.

Örnekler her başarı için bir ambalaj kullanır:

pythonCopydef complete(payload):
    return {
        "resultType": "complete",
        **payload,
        "_meta": {SERVER_INFO_KEY: SERVER_INFO},
    }

Listesi, okuma ve keşif işçileri ekle ttlMsEk olarak .cacheScopeBu sarkıtı merkezileştirmek bir işlemcinin modern sonuç alanlarını sessizce atmasını engeller.

Sunucu tarafından başlatılan istekler yok

Modern bir sunucu bir istemci talebi ile ilgili bildirimler gönderebilir veya istemci tarafından açılan bir bildirimlere gönderebilir subscriptions/listenKendi JSON-RPC talebini göndermemelidir.

Bir işlemci örnekleme, çıkartma veya kök girişi gerektiğinde, bir gönderir.input_requiredSonuç. Müşteri gömülü giriş isteklerini yerine getirir ve orijinal yöntemi yeni bir istek kimliği ile tekrar dener. 11. ders, çok yönlü bir yolculuğu istek biçimini kapsar.

Açıkça miras verenlik

İki çağ sunucuları da 2025-11-25Modern bir şekilde hareket etmeyi seçer._metaalanlar mevcut ve geleneksel davranışlar .initialize- Evet .

Bir 2026-07-28Eskiden gelen el sıkışması yoluyla talep edin.resultTypeBu dersdeki kod kasıtlı olarak modern, bu yüzden değişkenleri görünür kalır.

Kullan

Python sunucusunun son demo ve testlerini çalıştır:

bashCopycd code
python3 main.py --demo
python3 -m unittest discover tests -v

TypeScript portunu TypeScript çalıştırıcı ile çalıştır:

bashCopynpx tsx main.ts --demo

Demo gönderir server/discoverBu sayede, her bir primitif listelenir, araçları çağrıştırır ve desteklenmeyen bir sürüm hatasını gösterir.

Gönder

Bu ders gemileri outputs/skill-mcp-server-scaffolder.md. Bir keşif sözleşmesi, talep başına doğrulama, belirleyici cache listeleri ve seçmeli olarak izole edilmiş bir miras adaptörü ile modern bir sunucu planı üretir.

Egzersizler

1. Bir talebinden özellikleri kaldırın ve sunucu, önceki talebin açıklamasını tekrar kullanmadığını kanıtlayın.
2. Değiştir TOOLS- Evet .PROMPTSTüm liste sonuçlarının sabit kaldığını onaylayın.
3. Yıkıcı bir ekle.notes_deleteBu araçlar, yetki kontrolünü gerçekleştiricinin içinde yaptırmak için kullanılır.destructiveHintSadece bir UX ipucu olarak.
4. Ekleresources/templates/list- Evet .ttlMs- Evet .cacheScope, ve belirleyici bir düzenleme.
5. için ayrı bir miras adaptörü oluşturun2025-11-25Modern bir talebin asla girmediğini kanıtlayan testler ekleyin.

Anahtar Terimler

Daha Fazla Okumak

• MCP Specification 2026-07-28
• MCP Server Discovery
• MCP Tools
• MCP Resources
• MCP Prompts
• MCP stdio Transport

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.