Ajan belleği için MCP sunucusu: Claude Code'u HotKV'ye bağlayın

MCP sunucusu, bir yapay zeka asistanına tek bir sohbetten uzun süren bir bellek vermenin en basit yoludur. Claude Code, Cursor ve benzeri istemciler bir sohbet bittiğinde onun bağlamını kaybeder. Bunu düzeltmek için onlara ham veritabanı erişimi vermek risklidir. hotkv-mcp, HotKV için açık kaynaklı MCP sunucumuzdur. Bir asistana notlar, konuşma geçmişi, bir olay günlüğü, prompt şablonları ve belge araması için sabit bir araç seti verir. Başka hiçbir şey sunmaz.

Kısaca. hotkv-mcp, Claude Code'u, Cursor'u, VS Code'u veya kendi ajanınızı 28 sabit araçla bir HotKV sunucusuna bağlayan, Apache-2.0 lisanslı bir MCP sunucusudur. Keyfi bir komut çalıştıran bir araç yoktur; bu yüzden asistan verileri silemez veya yapılandırmayı değiştiremez. Salt okunur mod her yazma aracını kaldırır ve bir ad alanı ajanı tek bir anahtar önekiyle sınırlar. pip install hotkv-mcp ile kurun veya uvx ile çalıştırın.

Model Context Protocol nedir

Model Context Protocol, kısaca MCP, yapay zeka uygulamalarını veri kaynakları, araçlar ve iş akışları gibi harici sistemlere bağlamak için açık bir standarttır. Projenin tanıtımı onu yapay zeka uygulamaları için bir USB-C portuna benzetir. MCP terimleriyle uygulama istemcidir ve bağlandığı her sistem bir sunucu tarafından sunulur.

Bellek için bu, asistanın bir notu kaydeden gibi adlandırılmış bir aracı çağırması demektir. O aracın neler yapabileceğine sunucu karar verir. Model hiçbir zaman kendine ait bir veritabanı bağlantısı edinmez.

HotKV MCP sunucusu neleri sunar

Sunucu, HotKV'nin ajan belleğini, prompt kayıt defterini ve belge aramasını 28 araçta toplar. Her araç, MCP ek açıklamalarında yalnızca okuyup okumadığını, yazıp yazmadığını veya silip silmediğini bildirir. Bir istemci böylece yıkıcı olanlar için onay isteyebilir.

Bellek araçları, yapay zeka ajan belleği yazısında anlatılan depolarla, yani konuşma geçmişi, çalışma notları ve olay günlüğüyle eşleşir. Embedding ile anlamsal hatırlama sunulmaz. rag_search anahtar sözcük ilgisine göre sıralar, bu yüzden embedding gerektirmez.

Anahtar, hash ve liste araçları herhangi bir HotKV sunucusuna karşı çalışır. Bellek, prompt ve belge arama araçları HotKV'nin yapay zeka motorlarını kullanır; bunlar onları içeren bir lisans gerektirir. Lisans yoksa bu araçlar, sunucunun o özellik için lisanslı olmadığını belirten bir ileti döndürür. Anahtar araçları çalışmaya devam eder. HotKV Cloud Performance ve Scale örnekleri, Yapay zeka sayfasının anlattığı gibi yapay zeka motorlarını içerir.

Kurun ve bağlayın

Sunucu Python 3.10 veya daha yenisini gerektirir. HotKV sunucusu 0.3.0 ve resmi hotkv-client paketine karşı yazıldı ve 1.0.0 sürümü PyPI'dadır. pip ile kurun ya da uv kullanarak kurmadan çalıştırın.

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

Tek komutla ekleyin. --, Claude Code MCP belgelerinin anlattığı gibi Claude Code'un kendi seçeneklerini sunucuyu başlatan komuttan ayırır.

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

Cursor ve Claude Desktop

Bir mcpServers dosyası okuyan istemciler aynı sunucuyu bir JSON girdisi olarak alır. Parolayı HOTKV_URL ortam değişkeninde veya istemcinin gizli bilgi deposunda tutun. Bir komut satırı makinenin diğer kullanıcılarına görünür. TLS bağlantısı için hotkvs:// kullanın.

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

Çalıştığını denetleyin

Sunucunun kayıtlı olduğunu doğrulamak için claude mcp list çalıştırın. Ardından asistandan server_info aracını çağırmasını isteyin. HotKV sürümünü ve bellek kullanımını, ad alanı ayarlanmamışsa ayrıca anahtar sayısını döndürür. Sunucunun salt okunur olup olmadığını ve hangi ad alanıyla sınırlı olduğunu da bildirir. Bu, güvenlik önlemlerinizin devreye girdiğini doğrular.

Ajanı güvenli sınırlar içinde tutun

Araç çağırabilen bir model, onları kötüye kullanması için de ikna edilebilir; bu yüzden sınırlar özelliklerden daha önemlidir.

Keyfi komut yok

Ham bir komut çalıştıran bir araç yoktur. Asistan bir veritabanını boşaltamaz veya sunucunun yapılandırmasını değiştiremez, çünkü 28 aracın hiçbiri bunları yapmaz. Araçların eriştiği her anahtarı okuyabilir; aşağıdaki ad alanının önemi bu yüzdendir.

Salt okunur mod

--read-only, set, delete, hash_set, list_push, ekleyen veya temizleyen bellek araçları, prompt_save, rag_create ve rag_ingest dahil, yazan her aracı kaldırır. Ajan onları göremez bile. Belleğe danışması ama onu asla değiştirmemesi gereken asistanlar için kullanın.

Ad alanları ve boyut sınırları

--namespace PREFIX, her şeyi o önek altında saklar. Ajan öneki asla görmez ve diğer adlara ulaşamaz. Her ajana, başkasının başlangıcı olmayan bir önek verin. agent ve agent:b yerine agent-a ve agent-b kullanın; aksi halde kısa olan, uzun olanın adlarına ulaşabilir.

Sonuçlar da sınırlandırılmıştır. --max-value-bytes uzun değerleri keser ve bunları kesilmiş olarak işaretler; varsayılanı 65.536 bayttır. --max-items, bir çağrının kaç anahtar, liste öğesi veya isabet döndürebileceğini sınırlar; varsayılanı 200'dür. Bu nedenle tek bir devasa değer modelin bağlamını taşıramaz. Bir hash'in tamamını okumak öğe sınırına tabi değildir; bu yüzden büyük hash'leri bir ajanın ad alanının dışında tutun.

HTTP aktarımında oturum açma yoktur

Varsayılan stdio aktarımı, istemci tarafından bir alt süreç olarak başlatılır. Paylaşımlı kullanım için 127.0.0.1:8000 üzerinde /mcp adresinde dinleyen hotkv-mcp --transport streamable-http çalıştırabilirsiniz. Çağıranların kimliğini doğrulamaz. Onu localhost'ta tutun veya doğrulama yapan bir ters vekilin arkasına koyun ve ona kendi ad alanını verin.

Bir ekip için kurulum seçmek

Doğru bayraklar, her ajanın ne için olduğuna bağlıdır. Aşağıdaki her seçenek bir komut satırı bayrağıdır. --read-only ve --namespace için ayrıca ortam değişkenleri de vardır: HOTKV_MCP_READ_ONLY ve HOTKV_MCP_NAMESPACE.

İşi gören en kısıtlı satırdan başlayın. Erişimi sonradan genişletmek kolaydır, bir ajanın zaten yazdıklarını geri almak zordur.

İlk oturum, adım adım

Kısa bir deneme, sunucuya gerçek notlar emanet etmeden önce güvenlik önlemlerinin ne yaptığını gösterir. Atılabilir bir ad alanı ve yapay zeka motorları için lisanslı yerel bir HotKV sunucusu kullanın; çünkü bellek araçları o lisans olmadan çalışmaz.

1. Bir ad alanıyla bağlanın. claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial komutunu çalıştırın.

2. Sınırları denetleyin. Asistandan server_info çağırmasını ve ad alanını ile sunucunun salt okunur olup olmadığını bildirmesini isteyin. trial demeli ve salt okunur olmadığını söylemelidir.

3. Bir not kaydedin. Ondan, hazırlık sitesinin belirli bir adreste durduğunu, sitenin adını taşıyan bir not altında hatırlamasını isteyin. Asistan memory_set_note çağırır ve oturum ilk kullanımda oluşturulur.

4. Yeni bir sohbette geri okuyun. Yeni bir konuşma başlatın ve o oturum için hangi notların var olduğunu sorun. memory_list_notes ve memory_get_note çağırır ve not hâlâ oradadır.

5. Bir kararı günlüğe kaydedin. Ondan olay günlüğüne bir karar kaydetmesini isteyin. memory_log_event çağırır ve memory_query_events onu daha sonra geri getirir.

6. Yazma erişimini kaldırın. Eski girdiyi kaldırın, --read-only ile yeniden bağlanın ve 4. adımı tekrarlayın. Okuma hâlâ çalışır ve yazan araçlar artık sunulmaz.

7. adım anlatıldığı gibi davranırsa, en önemli iki denetimi, ad alanını ve salt okunur modu görmüş olursunuz.

Asistanın sakladığı her şeye geri okunduğunda güvenilmez metin gözüyle bakın; bellek makalesinin saklanan metne güvenilmez gözüyle bakma bölümünde açıkladığı gibi. Web sayfalarından yazılan notlar talimat taşıyabilir.

Sorun giderme

• "This HotKV server is not licensed for that feature." Bellek, prompt ve belge arama araçları, yapay zeka motorlarını içeren bir HotKV lisansı gerektirir. Anahtar, hash ve liste araçları lisanssız da çalışmaya devam eder.
• Bağlantı başarısız oluyor. URL şemasını denetleyin. hotkv://, hotkvs:// (TLS), redis:// ve rediss:// çalışır ve parola URL'ye hotkv://:password@host:6379 biçiminde konur.
• Bir değer kesik geliyor. Sonuç --max-value-bytes sınırını aştığında kesilmiş olarak işaretlenir. Sınırı yükseltin veya daha küçük değerler saklayın.
• Bir yazma aracı eksik. Sunucunun argümanlarında --read-only ya da ortamında HOTKV_MCP_READ_ONLY arayın.
• Asistan daha önce kaydettiği bir adı bulamıyor. Aynı oturum veya ajan adını kullandığını ve sunucunun daha önceki ad alanıyla çalıştığını denetleyin.
• uvx bulunamıyor. uv kurun ya da paketi pip ile kurun ve hotkv-mcp'yi doğrudan başlatın.

Sık sorulan sorular