שרת MCP לזיכרון סוכנים: מחברים את Claude Code ל-HotKV

שרת MCP הוא הדרך הפשוטה ביותר לתת לעוזר AI זיכרון שנמשך יותר מצ'אט אחד. Claude Code, Cursor ולקוחות דומים מאבדים את הקשר הצ'אט כשהוא נגמר. מתן גישה גולמית למסד נתונים כדי לתקן זאת מסוכן. hotkv-mcp הוא שרת ה-MCP בקוד פתוח שלנו ל-HotKV. הוא נותן לעוזר ערכה קבועה של כלים להערות, היסטוריית שיחה, יומן אירועים, תבניות פרומפט וחיפוש במסמכים. הוא לא מציע שום דבר אחר.

בקצרה. hotkv-mcp הוא שרת MCP ברישיון Apache-2.0 שמחבר את Claude Code, את Cursor, את VS Code או את הסוכן שלכם לשרת HotKV דרך 28 כלים קבועים. אין כלי שמריץ פקודה שרירותית, ולכן העוזר לא יכול למחוק נתונים או לשנות הגדרות. מצב קריאה בלבד מסיר כל כלי כתיבה, ומרחב שמות מגביל את הסוכן לקידומת מפתחות אחת. מתקינים עם pip install hotkv-mcp או מריצים עם uvx.

מהו Model Context Protocol

Model Context Protocol, או MCP, הוא תקן פתוח לחיבור יישומי AI למערכות חיצוניות כמו מקורות נתונים, כלים ותהליכי עבודה. ההקדמה של הפרויקט משווה אותו ליציאת USB-C ליישומי AI. במונחי MCP היישום הוא הלקוח, וכל מערכת שהוא מתחבר אליה נחשפת על ידי שרת.

בזיכרון המשמעות היא שהעוזר קורא לכלי בשם, כמו כלי ששומר הערה. השרת קובע מה הכלי הזה רשאי לעשות. המודל אף פעם לא מקבל חיבור משלו למסד הנתונים.

מה שרת ה-MCP של HotKV חושף

השרת עוטף את זיכרון הסוכנים, רישום הפרומפטים והחיפוש במסמכים של HotKV ב-28 כלים. כל כלי מצהיר בהערות ה-MCP שלו אם הוא רק קורא, כותב או מוחק. לקוח יכול אז לבקש אישור לפני הכלים ההרסניים.

כלי הזיכרון ממופים למאגרים שתוארו בזיכרון לסוכני AI, כלומר היסטוריית שיחה, הערות עבודה ויומן האירועים. שליפה סמנטית לפי embedding אינה חשופה. rag_search מדרג לפי רלוונטיות מילות מפתח, ולכן אינו צריך אחת כזו.

כלי המפתחות, ה-hashes והרשימות עובדים מול כל שרת HotKV. כלי הזיכרון, הפרומפטים והחיפוש במסמכים משתמשים במנועי ה-AI של HotKV, שדורשים רישיון הכולל אותם. בלעדיו, הכלים האלה מחזירים הודעה שהשרת אינו מורשה לפיצ'ר. כלי המפתחות ממשיכים לעבוד. מופעי Performance ו-Scale ב-HotKV Cloud כוללים את מנועי ה-AI, כפי שמתואר בעמוד ה-AI.

התקנה וחיבור

השרת דורש Python 3.10 ומעלה. הוא נכתב מול שרת HotKV 0.3.0 וחבילת hotkv-client הרשמית, וגרסה 1.0.0 נמצאת ב-PyPI. מתקינים אותו עם pip, או מריצים בלי התקנה עם uv.

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

Claude Code

מוסיפים אותו בפקודה אחת. ה--- מפריד בין האפשרויות של Claude Code עצמו לבין הפקודה שמפעילה את השרת, כפי שתיעוד ה-MCP של Claude Code מתאר.

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

Cursor ו-Claude Desktop

לקוחות שקוראים קובץ mcpServers מקבלים את אותו שרת כרשומת JSON. שומרים את הסיסמה במשתנה הסביבה HOTKV_URL או במאגר הסודות של הלקוח. שורת פקודה גלויה למשתמשים אחרים במכונה. משתמשים ב-hotkvs:// לחיבור TLS.

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

בודקים שזה עובד

מריצים claude mcp list כדי לוודא שהשרת רשום. אחר כך מבקשים מהעוזר לקרוא לכלי server_info. הוא מחזיר את גרסת HotKV ואת צריכת הזיכרון, וכן את מספר המפתחות כשלא נקבע מרחב שמות. הוא גם מדווח אם השרת במצב קריאה בלבד ולאיזה מרחב שמות הוא מוגבל. כך מאשרים שאמצעי ההגנה שלכם נכנסו לתוקף.

שומרים על הסוכן בתוך גבולות בטוחים

מודל שיכול לקרוא לכלים אפשר גם לשכנע לנצל אותם לרעה, ולכן המגבלות חשובות יותר מהיכולות.

בלי פקודות שרירותיות

אין כלי שמריץ פקודה גולמית. העוזר לא יכול למחוק מסד נתונים או לשנות את הגדרות השרת, כי אף אחד מ-28 הכלים לא עושה זאת. הוא יכול לקרוא כל מפתח שהכלים מגיעים אליו, ולכן מרחב השמות שלהלן חשוב.

מצב קריאה בלבד

--read-only מסיר כל כלי שכותב, כולל set, delete, hash_set, list_push, כלי הזיכרון שמוסיפים או מנקים, prompt_save, rag_create ו-rag_ingest. הסוכן אפילו לא רואה אותם. משתמשים בו לעוזרים שצריכים להתייעץ עם הזיכרון אבל לעולם לא לשנות אותו.

מרחבי שמות ומגבלות גודל

--namespace PREFIX שומר הכול תחת הקידומת הזו. הסוכן אף פעם לא רואה את הקידומת ולא יכול להגיע לשמות אחרים. תנו לכל סוכן קידומת שאינה תחילת קידומת של אחר. השתמשו ב-agent-a וב-agent-b, ולא ב-agent וב-agent:b, אחרת הקצרה יכולה להגיע לשמות של הארוכה.

גם התוצאות מוגבלות. --max-value-bytes חותך ערכים ארוכים ומסמן אותם כקטועים, עם ברירת מחדל של 65,536 בייטים. --max-items מגביל כמה מפתחות, פריטי רשימה או תוצאות קריאה מחזירה, 200 כברירת מחדל. ערך ענק בודד לא יכול אפוא להציף את ההקשר של המודל. קריאת hash שלם אינה מוגבלת בפריטים, ולכן כדאי להשאיר hashes גדולים מחוץ למרחב השמות של הסוכן.

לתעבורת ה-HTTP אין התחברות

תעבורת ברירת המחדל, stdio, מופעלת על ידי הלקוח כתהליך משנה. לשימוש משותף אפשר להריץ hotkv-mcp --transport streamable-http, שמאזין ב-127.0.0.1:8000 ב-/mcp. הוא לא מאמת קוראים. השאירו אותו ב-localhost או שימו אותו מאחורי reverse proxy שמאמת, ותנו לו מרחב שמות משלו.

בוחרים הגדרה לצוות

הדגלים הנכונים תלויים במטרת כל סוכן. כל אפשרות להלן היא דגל שורת פקודה. ל---read-only ול---namespace יש גם משתני סביבה, HOTKV_MCP_READ_ONLY ו-HOTKV_MCP_NAMESPACE.

התחילו מהשורה המגבילה ביותר שעושה את העבודה. קל להרחיב גישה אחר כך, וקשה לקחת בחזרה את מה שסוכן כבר כתב.

סשן ראשון, צעד אחר צעד

ניסיון קצר מראה מה אמצעי ההגנה עושים לפני שסומכים על השרת עם הערות אמיתיות. השתמשו במרחב שמות חד-פעמי ובשרת HotKV מקומי שמורשה למנועי ה-AI, כי כלי הזיכרון לא עובדים בלי הרישיון הזה.

1. מתחברים עם מרחב שמות. מריצים claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. בודקים את המגבלות. מבקשים מהעוזר לקרוא ל-server_info ולדווח על מרחב השמות ועל כך אם השרת במצב קריאה בלבד. הוא צריך לומר trial ושלא קריאה בלבד.
3. שומרים הערה. מבקשים ממנו לזכור שאתר ה-staging נמצא בכתובת מסוימת, בהערה על שם האתר. העוזר קורא ל-memory_set_note, והסשן נוצר בשימוש הראשון.
4. קוראים אותה בצ'אט חדש. פותחים שיחה חדשה ושואלים אילו הערות קיימות לסשן הזה. הוא קורא ל-memory_list_notes ול-memory_get_note, וההערה עדיין שם.
5. רושמים החלטה. מבקשים ממנו לרשום החלטה ביומן האירועים. הוא קורא ל-memory_log_event, ו-memory_query_events מחזיר אותה מאוחר יותר.
6. מסירים את הרשאת הכתיבה שלו. מסירים את הרשומה הישנה, מתחברים מחדש עם --read-only וחוזרים על צעד 4. הקריאה עדיין עובדת, והכלים שכותבים כבר לא מוצעים.

אם צעד 6 מתנהג כמתואר, ראיתם את שתי הבקרות החשובות ביותר, מרחב השמות ומצב קריאה בלבד.

התייחסו לכל מה שהעוזר שומר כאל טקסט לא אמין כשהוא נקרא בחזרה, כפי שמאמר הזיכרון מסביר בהתייחסות לטקסט שמור כאל לא אמין. הערות שנכתבו מעמודי אינטרנט יכולות לשאת הוראות.

פתרון בעיות

• "This HotKV server is not licensed for that feature." כלי הזיכרון, הפרומפטים והחיפוש במסמכים דורשים רישיון HotKV הכולל את מנועי ה-AI. כלי המפתחות, ה-hashes והרשימות ממשיכים לעבוד בלעדיו.
• החיבור נכשל. בדקו את סכמת ה-URL. hotkv://, hotkvs:// (TLS), redis:// ו-rediss:// כולם עובדים, והסיסמה נכנסת ל-URL כך: hotkv://:password@host:6379.
• ערך חוזר קטוע. התוצאה מסומנת כקטועה כשהיא חורגת מ---max-value-bytes. הגדילו את המגבלה או שמרו ערכים קטנים יותר.
• כלי כתיבה חסר. חפשו --read-only בארגומנטים של השרת או HOTKV_MCP_READ_ONLY בסביבה שלו.
• העוזר לא מוצא שם ששמר קודם. בדקו שהשתמש באותו שם סשן או סוכן, ושהשרת רץ עם אותו מרחב שמות כמו קודם.
• uvx לא נמצא. התקינו את uv, או התקינו את החבילה עם pip והפעילו את hotkv-mcp ישירות.

שאלות נפוצות