MCP-szerver ügynökmemóriához: a Claude Code csatlakoztatása a HotKV-hoz

Az MCP-szerver a legegyszerűbb módja annak, hogy egy AI-asszisztens egyetlen csevegésnél tovább tartó memóriát kapjon. A Claude Code, a Cursor és a hasonló kliensek a csevegés végén elveszítik a csevegés kontextusát. Ennek orvoslására nyers adatbázis-hozzáférést adni nekik kockázatos. A hotkv-mcp a mi nyílt forráskódú MCP-szerverünk a HotKV-hoz. Egy rögzített eszközkészletet ad az asszisztensnek jegyzetekhez, beszélgetési előzményekhez, eseménynaplóhoz, prompt-sablonokhoz és dokumentumkereséshez. Mást nem kínál.

Röviden. A hotkv-mcp egy Apache-2.0 licencű MCP-szerver, amely a Claude Code-ot, a Cursort, a VS Code-ot vagy a saját ügynökét 28 rögzített eszközön keresztül köti egy HotKV-szerverhez. Nincs olyan eszköz, amely tetszőleges parancsot futtat, így az asszisztens nem tud adatot törölni vagy konfigurációt módosítani. A csak olvasható mód eltávolít minden író eszközt, a névtér pedig egyetlen kulcselőtagra korlátozza az ügynököt. Telepítse a pip install hotkv-mcp paranccsal, vagy futtassa az uvx segítségével.

Mi a Model Context Protocol

A Model Context Protocol, vagyis az MCP, nyílt szabvány AI-alkalmazások külső rendszerekhez, például adatforrásokhoz, eszközökhöz és munkafolyamatokhoz való csatlakoztatására. A projekt bevezetője egy AI-alkalmazások USB-C portjához hasonlítja. MCP-szóhasználatban az alkalmazás a kliens, és minden rendszert, amelyhez csatlakozik, egy szerver tesz elérhetővé.

A memória esetében ez azt jelenti, hogy az asszisztens egy elnevezett eszközt hív, például egyet, amely jegyzetet ment. A szerver dönti el, mit tehet az az eszköz. A modell soha nem kap saját adatbázis-kapcsolatot.

Mit tesz elérhetővé a HotKV MCP-szerver

A szerver a HotKV ügynökmemóriáját, prompt-nyilvántartását és dokumentumkeresését 28 eszközbe csomagolja. Minden eszköz az MCP-annotációiban deklarálja, hogy csak olvas, ír vagy töröl. A kliens így jóváhagyást kérhet a romboló eszközök előtt.

A memóriaeszközök az AI-ügynökmemória cikkben leírt tárolókra képeződnek le, nevezetesen a beszélgetési előzményekre, a munkajegyzetekre és az eseménynaplóra. Az embedding szerinti szemantikus felidézés nincs elérhetővé téve. A rag_search kulcsszavas relevancia szerint rangsorol, így nincs szüksége embeddingre.

A kulcs-, hash- és listaeszközök bármely HotKV-szerveren működnek. A memória-, prompt- és dokumentumkereső eszközök a HotKV AI-motorjait használják, amelyekhez azokat tartalmazó licenc kell. Licenc nélkül ezek az eszközök üzenetet adnak vissza arról, hogy a szerver nincs licencelve a funkcióra. A kulcseszközök tovább működnek. A HotKV Cloud Performance és Scale példányai tartalmazzák az AI-motorokat, ahogy az AI oldal leírja.

Telepítés és csatlakoztatás

A szerverhez Python 3.10 vagy újabb szükséges. A HotKV 0.3.0 szerverhez és a hivatalos hotkv-client csomaghoz íródott, az 1.0.0 verzió pedig a PyPI-n található. Telepítse a pip segítségével, vagy futtassa telepítés nélkül az uv használatával.

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

Claude Code

Adja hozzá egyetlen paranccsal. A -- elválasztja a Claude Code saját kapcsolóit a szervert indító parancstól, ahogy a Claude Code MCP-dokumentációja leírja.

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

Cursor és Claude Desktop

Az mcpServers fájlt olvasó kliensek ugyanezt a szervert JSON-bejegyzésként veszik át. A jelszót tartsa a HOTKV_URL környezeti változóban vagy a kliens titoktárolójában. A parancssor a gép más felhasználói számára látható. TLS-kapcsolathoz használja a hotkvs:// sémát.

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

Ellenőrizze, hogy működik

Futtassa a claude mcp list parancsot, hogy megerősítse, a szerver regisztrálva van. Aztán kérje meg az asszisztenst, hogy hívja meg a server_info eszközt. Az visszaadja a HotKV verzióját és a memóriahasználatot, valamint a kulcsok számát, ha nincs beállítva névtér. Azt is jelzi, hogy a szerver csak olvasható-e, és melyik névtérre van korlátozva. Ez megerősíti, hogy a védelmek érvénybe léptek.

Tartsa az ügynököt biztonságos korlátok között

Az a modell, amely eszközöket hívhat, rá is beszélhető arra, hogy visszaéljen velük, ezért a korlátok fontosabbak a funkcióknál.

Nincsenek tetszőleges parancsok

Nincs olyan eszköz, amely nyers parancsot futtat. Az asszisztens nem tud adatbázist kiüríteni vagy a szerver konfigurációját módosítani, mert a 28 eszköz egyike sem teszi ezeket. Bármely kulcsot elolvashat, amelyet az eszközök elérnek, ezért számít az alábbi névtér.

Csak olvasható mód

A --read-only eltávolít minden írást végző eszközt, köztük a set, delete, hash_set, list_push eszközöket, a hozzáadó vagy törlő memóriaeszközöket, a prompt_save, rag_create és rag_ingest eszközöket. Az ügynök még látni sem látja őket. Használja olyan asszisztensekhez, amelyek a memóriát megnézhetik, de soha nem módosíthatják.

Névterek és méretkorlátok

A --namespace ELŐTAG mindent az adott előtag alatt tárol. Az ügynök soha nem látja az előtagot, és nem éri el a többi nevet. Minden ügynöknek olyan előtagot adjon, amely nem egy másik előtagjának eleje. Használja az agent-a és az agent-b neveket, ne az agent és az agent:b neveket, különben a rövidebb elérheti a hosszabb neveit.

Az eredmények is korlátozottak. A --max-value-bytes levágja a hosszú értékeket, és csonkoltként jelöli őket, alapértelmezés szerint 65 536 bájt után. A --max-items azt korlátozza, hány kulcsot, listaelemet vagy találatot ad vissza egy hívás, alapértelmezés szerint 200-at. Így egyetlen hatalmas érték nem tudja elárasztani a modell kontextusát. Egy teljes hash olvasása nincs elemszám-korlátozva, ezért a nagy hash-eket tartsa távol az ügynök névterétől.

A HTTP-átvitelnek nincs bejelentkezése

Az alapértelmezett stdio-átvitelt a kliens alfolyamatként indítja. Megosztott használatra futtathatja a hotkv-mcp --transport streamable-http parancsot, amely a 127.0.0.1:8000 címen figyel az /mcp útvonalon. Nem hitelesíti a hívókat. Tartsa localhoston, vagy tegye egy hitelesítő reverse proxy mögé, és adjon neki saját névteret.

Beállítás választása egy csapatnak

A megfelelő kapcsolók attól függnek, mire való az egyes ügynök. Az alábbi opciók mind parancssori kapcsolók. A --read-only és a --namespace környezeti változóval is rendelkezik, HOTKV_MCP_READ_ONLY és HOTKV_MCP_NAMESPACE.

Induljon a legszigorúbb sorból, amely elvégzi a feladatot. A hozzáférést könnyű később bővíteni, és nehéz visszavenni, amit az ügynök már megírt.

Egy első munkamenet, lépésről lépésre

Egy rövid próba megmutatja, mit tesznek a védelmek, mielőtt valódi jegyzetekkel megbízna a szerverben. Használjon eldobható névteret és egy helyi HotKV-szervert, amely licencelve van az AI-motorokra, mert a memóriaeszközök licenc nélkül nem működnek.

1. Csatlakozás névtérrel. Futtassa a claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial parancsot.
2. A korlátok ellenőrzése. Kérje meg az asszisztenst, hogy hívja a server_info eszközt, és jelentse a névteret és hogy a szerver csak olvasható-e. A trial névteret kell mondania, és hogy nem csak olvasható.
3. Jegyzet mentése. Kérje meg, hogy jegyezze meg, hogy a staging oldal egy adott címen található, az oldalról elnevezett jegyzet alatt. Az asszisztens a memory_set_note eszközt hívja, a munkamenet pedig első használatkor jön létre.
4. Visszaolvasás egy új csevegésben. Indítson új beszélgetést, és kérdezze meg, milyen jegyzetek léteznek ahhoz a munkamenethez. A memory_list_notes és a memory_get_note eszközt hívja, és a jegyzet még ott van.
5. Döntés naplózása. Kérje meg, hogy rögzítsen egy döntést az eseménynaplóban. A memory_log_event eszközt hívja, a memory_query_events pedig később visszahozza.
6. Az írási hozzáférés megvonása. Távolítsa el a régi bejegyzést, csatlakozzon újra a --read-only kapcsolóval, és ismételje meg a 4. lépést. Az olvasás továbbra is működik, az író eszközöket pedig már nem kínálja fel.

Ha a 6. lépés a leírtak szerint viselkedik, látta a két legfontosabb vezérlőt, a névteret és a csak olvasható módot.

Kezelje megbízhatatlan szövegként mindazt, amit az asszisztens tárol, amikor visszaolvassák, ahogy a memóriacikk elmagyarázza a tárolt szöveg megbízhatatlanként kezeléséről. A weboldalakról írt jegyzetek utasításokat hordozhatnak.

Hibaelhárítás

• „This HotKV server is not licensed for that feature.” A memória-, prompt- és dokumentumkereső eszközökhöz olyan HotKV-licenc kell, amely tartalmazza az AI-motorokat. A kulcs-, hash- és listaeszközök licenc nélkül is tovább működnek.
• A kapcsolat sikertelen. Ellenőrizze az URL-sémát. A hotkv://, a hotkvs:// (TLS), a redis:// és a rediss:// egyaránt működik, a jelszó pedig az URL-be kerül így: hotkv://:password@host:6379.
• Egy érték levágva jön vissza. Az eredmény csonkoltként van jelölve, amikor meghaladja a --max-value-bytes értéket. Emelje a korlátot, vagy tároljon kisebb értékeket.
• Hiányzik egy író eszköz. Keresse a --read-only kapcsolót a szerver argumentumai között, vagy a HOTKV_MCP_READ_ONLY értéket a környezetében.
• Az asszisztens nem találja a korábban elmentett nevet. Ellenőrizze, hogy ugyanazt a munkamenet- vagy ügynöknevet használta-e, és hogy a szerver ugyanazzal a névtérrel fut-e, mint korábban.
• Az uvx nem található. Telepítse az uv eszközt, vagy telepítse a csomagot a pip segítségével, és indítsa közvetlenül a hotkv-mcp programot.

Gyakran ismételt kérdések