Server MCP pro paměť agentů: připojte Claude Code k HotKV

Server MCP je nejjednodušší způsob, jak dát AI asistentovi paměť, která vydrží déle než jeden chat. Claude Code, Cursor a podobní klienti ztratí kontext chatu, když skončí. Dát jim kvůli tomu přímý přístup k databázi je riskantní. hotkv-mcp je náš open-source server MCP pro HotKV. Dává asistentovi pevnou sadu nástrojů pro poznámky, historii konverzace, log událostí, šablony promptů a vyhledávání v dokumentech. Nic víc nenabízí.

Stručně. hotkv-mcp je server MCP pod licencí Apache-2.0, který připojuje Claude Code, Cursor, VS Code nebo vašeho vlastního agenta k serveru HotKV pomocí 28 pevných nástrojů. Neexistuje nástroj, který by spustil libovolný příkaz, takže asistent nemůže vymazat data ani změnit konfiguraci. Režim jen pro čtení odstraní všechny nástroje pro zápis a jmenný prostor omezí agenta na jeden prefix klíčů. Nainstalujte ho pomocí pip install hotkv-mcp nebo ho spusťte pomocí uvx.

Co je Model Context Protocol

Model Context Protocol, neboli MCP, je otevřený standard pro připojování AI aplikací k externím systémům, například ke zdrojům dat, nástrojům a workflow. Úvod projektu ho přirovnává ke konektoru USB-C pro AI aplikace. V terminologii MCP je aplikace klient a každý systém, ke kterému se připojuje, zpřístupňuje server.

Pro paměť to znamená, že asistent volá pojmenovaný nástroj, například ten, který uloží poznámku. Server rozhoduje, co tento nástroj smí. Model nikdy nedostane vlastní připojení k databázi.

Co zpřístupňuje server HotKV MCP

Server obaluje paměť agentů, registr promptů a vyhledávání v dokumentech HotKV do 28 nástrojů. Každý nástroj ve svých anotacích MCP deklaruje, zda jen čte, zapisuje nebo maže. Klient pak může u destruktivních požádat o schválení.

Paměťové nástroje odpovídají úložištím popsaným v článku Paměť AI agentů, tedy historii konverzace, pracovním poznámkám a logu událostí. Sémantické vybavování pomocí embeddingů zpřístupněno není. rag_search řadí podle relevance klíčových slov, takže žádné nepotřebuje.

Nástroje pro klíče, hashe a seznamy fungují s libovolným serverem HotKV. Nástroje pro paměť, prompty a vyhledávání v dokumentech používají AI jádra HotKV, která vyžadují licenci, jež je zahrnuje. Bez ní tyto nástroje vrátí zprávu, že server není pro danou funkci licencován. Nástroje pro klíče fungují dál. Instance HotKV Cloud Performance a Scale AI jádra zahrnují, jak popisuje stránka o AI.

Instalace a připojení

Server vyžaduje Python 3.10 nebo novější. Byl napsán proti serveru HotKV 0.3.0 a oficiálnímu balíčku hotkv-client a verze 1.0.0 je na PyPI. Nainstalujte ho pomocí pip, nebo ho spusťte bez instalace pomocí uv.

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

Claude Code

Přidejte ho jedním příkazem. Znaky -- oddělují vlastní volby Claude Code od příkazu, který server spouští, jak popisuje dokumentace MCP pro Claude Code.

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

Cursor a Claude Desktop

Klienti, kteří čtou soubor mcpServers, berou stejný server jako položku JSON. Heslo držte v proměnné prostředí HOTKV_URL nebo v úložišti tajemství klienta. Příkazový řádek vidí ostatní uživatelé stroje. Pro připojení přes TLS použijte hotkvs://.

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

Ověření, že to funguje

Spusťte claude mcp list a ověřte, že je server zaregistrován. Pak požádejte asistenta, aby zavolal nástroj server_info. Vrátí verzi HotKV a využití paměti a, když není nastaven jmenný prostor, také počet klíčů. Hlásí také, zda je server jen pro čtení a na který jmenný prostor je omezen. To potvrdí, že vaše ochranná opatření začala platit.

Držte agenta v bezpečných mezích

Model, který může volat nástroje, lze také přemluvit, aby je zneužil, proto na mezích záleží víc než na funkcích.

Žádné libovolné příkazy

Neexistuje nástroj, který by spustil surový příkaz. Asistent nemůže vymazat databázi ani změnit konfiguraci serveru, protože to nedělá žádný z 28 nástrojů. Může číst jakýkoli klíč, ke kterému nástroje dosáhnou, proto záleží na jmenném prostoru níže.

Režim jen pro čtení

--read-only odstraní každý nástroj, který zapisuje, včetně set, delete, hash_set, list_push, paměťových nástrojů, které přidávají nebo mažou, prompt_save, rag_create a rag_ingest. Agent je ani nevidí. Použijte ho u asistentů, kteří mají do paměti nahlížet, ale nikdy ji měnit.

Jmenné prostory a limity velikosti

--namespace PREFIX ukládá všechno pod tento prefix. Agent prefix nikdy nevidí a nemůže dosáhnout na jiné názvy. Dejte každému agentovi prefix, který není začátkem jiného. Použijte agent-a a agent-b, ne agent a agent:b, jinak může kratší dosáhnout na názvy delšího.

Výsledky jsou také omezeny. --max-value-bytes ořízne dlouhé hodnoty a označí je jako zkrácené, s výchozí hodnotou 65 536 bajtů. --max-items omezuje, kolik klíčů, položek seznamu nebo zásahů volání vrátí, ve výchozím stavu 200. Jediná obrovská hodnota tedy nemůže zaplavit kontext modelu. Čtení celého hashe počtem položek omezeno není, proto velké hashe držte mimo jmenný prostor agenta.

Přenos přes HTTP nemá přihlášení

Výchozí přenos stdio spouští klient jako podproces. Pro sdílené použití můžete spustit hotkv-mcp --transport streamable-http, který naslouchá na 127.0.0.1:8000 na cestě /mcp. Volající neověřuje. Nechte ho na localhostu nebo ho dejte za reverzní proxy, která ověřuje, a dejte mu vlastní jmenný prostor.

Volba nastavení pro tým

Správné přepínače závisí na tom, k čemu je každý agent. Každá volba níže je přepínač příkazového řádku. --read-only a --namespace mají také proměnné prostředí, HOTKV_MCP_READ_ONLY a HOTKV_MCP_NAMESPACE.

Začněte od nejpřísnějšího řádku, který stačí. Přístup je snadné později rozšířit a těžké vzít zpět to, co agent už zapsal.

První relace krok za krokem

Krátké vyzkoušení ukáže, co ochranná opatření dělají, dřív než serveru svěříte skutečné poznámky. Použijte jednorázový jmenný prostor a lokální server HotKV s licencí pro AI jádra, protože paměťové nástroje bez této licence nefungují.

1. Připojte se s jmenným prostorem. Spusťte claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Zkontrolujte meze. Požádejte asistenta, aby zavolal server_info a nahlásil jmenný prostor a zda je server jen pro čtení. Měl by říct trial a že jen pro čtení není.
3. Uložte poznámku. Požádejte ho, aby si zapamatoval, že testovací web (staging) žije na dané adrese, v poznámce pojmenované podle webu. Asistent zavolá memory_set_note a relace se při prvním použití vytvoří.
4. Přečtěte ji v novém chatu. Začněte novou konverzaci a zeptejte se, jaké poznámky pro tu relaci existují. Zavolá memory_list_notes a memory_get_note a poznámka tam pořád je.
5. Zalogujte rozhodnutí. Požádejte ho, aby zaznamenal rozhodnutí do logu událostí. Zavolá memory_log_event a memory_query_events ho později vrátí.
6. Odeberte mu přístup k zápisu. Odstraňte starou položku, připojte se znovu s --read-only a zopakujte krok 4. Čtení stále funguje a nástroje pro zápis už nejsou nabízeny.

Pokud se krok 6 chová, jak je popsáno, viděli jste dvě kontroly, na kterých záleží nejvíc, jmenný prostor a režim jen pro čtení.

Cokoli asistent uloží, berte při čtení zpět jako nedůvěryhodný text, jak vysvětluje článek o paměti v části ukládaný text berte jako nedůvěryhodný. Poznámky zapsané z webových stránek mohou nést instrukce.

Řešení potíží

• „This HotKV server is not licensed for that feature.“ Nástroje pro paměť, prompty a vyhledávání v dokumentech vyžadují licenci HotKV, která zahrnuje AI jádra. Nástroje pro klíče, hashe a seznamy fungují i bez ní.
• Připojení selže. Zkontrolujte schéma URL. Funguje hotkv://, hotkvs:// (TLS), redis:// i rediss:// a heslo patří do URL jako hotkv://:password@host:6379.
• Hodnota se vrátí oříznutá. Výsledek je označen jako zkrácený, když překročí --max-value-bytes. Zvyšte limit nebo ukládejte menší hodnoty.
• Chybí nástroj pro zápis. Hledejte --read-only v argumentech serveru nebo HOTKV_MCP_READ_ONLY v jeho prostředí.
• Asistent nenajde název, který dříve uložil. Zkontrolujte, že použil stejný název relace nebo agenta a že server běží se stejným jmenným prostorem jako dřív.
• uvx nebylo nalezeno. Nainstalujte uv, nebo nainstalujte balíček pomocí pip a spusťte hotkv-mcp přímo.

Často kladené otázky