Headroom Mini

Headroom Mini הוא שרת MCP מקומי לניתוב וייעול טוקנים עבור פרומפטים ושליחת תוכן ל-LLM.

מה הפרויקט עושה

• מיישם שרת MCP (@modelcontextprotocol/sdk) עם כלים ל:

  • דחיסת קוד (compress_code)

  • דחיסת JSON (compress_json)

  • אופטימיזציית פרומפטים (optimize_prompt)

  • הזרקת placeholder הפיכה (redact_content)

  • שחזור תוכן דרך placeholder (hydrate)

• משתמש בספרייה gpt-tokenizer כדי להדפיס סטטיסטיקת טוקנים ברורה לכל פעולה.

• מנהל מזהי placeholder עם HEADROOM_REDACTED_LOGS_ID_<NUM> ושומר תוכן לשחזור.

• התהליך מתבצע מקומית בזמן ריצה, ללא אחסון קבוע מחוץ לזיכרון הריצה.

Related MCP server: slimctx-token-optimizer

מבנה הפרויקט

• src/ – קוד המקור

• src/tools/ – פונקציות עזר

• src/storage/ – אחסון placeholder רוחבי לזמן ריצה

• tests/ – טסטים יחידה

איך להתקין ולהריץ

npm install
npm start

הפקודה npm start תבנה את הקוד לפני ההרצה בעזרת prestart.

לריצה מהירה בסביבת פיתוח (בלי תהליך בנייה נפרד):

npm run dev

להרצת הטסטים:

npm test

דוגמת שימוש

1. התקנה והרצה:

npm install
npm start

2. הפעלת שרת MCP מקומי:

npm run dev

3. בדיקת יחידות:

npm test

להגשה: יש לכלול את כל הקבצים במקור ללא node_modules ובלי dist.

כלים בשרת MCP

• compress_code – מסיר הערות, docstrings וקווים ריקים מקוד

• compress_json – בודק JSON וממזג אותו לשורה אחת

• optimize_prompt – מוציא חותמות זמן ו-UUIDים ומעביר אותם לסוף הפרומפט

• redact_content – מחליף תוכן ארוך מעל 500 תווים ב-placeholder

• hydrate – מקבל placeholder או טקסט המכיל אותו ומחזיר את התוכן המקורי

דוגמת schema של כלי MCP

{
  name: "compress_code",
  description: "Compresses code by removing comments and whitespace",
  inputSchema: {
    type: "object",
    properties: {
      code: { type: "string" }
    },
    required: ["code"]
  }
}

זהו המבנה שבו סוכן AI יכול לזהות מתי להפעיל כלי דחיסה לפני שליחה ל-LLM.

תשובה לחלק 1.1

1. למה הזזת שדות דינמיים לסוף זה חשוב?

הזזת שדות דינמיים כמו חותמות זמן או UUID לסוף הפרומפט שומרת על החלק ה"קבוע" של הטקסט זהה בין בקשות שונות. זה מאפשר למודלים ולהיצעי cache של ספקים לזהות שהפרומפט הוא אותו פרומפט עם שינויים קטנים, וכך נמנע "cache miss". ההשפעה הכלכלית היא חיסכון משמעותי בעלויות שימוש ב-API, כי מודלים לא צריכים לנתח שוב ולקדד מחדש פרומפטים שבהם רק הנתונים הדינמיים השתנו.

2. כיצד לולאת פידבק עם placeholders עובדת?

במנגנון זה התוכן המלא נחתך כשגדול מדי, ובמקומו מוחדר מזהה מיוחד כגון: [HEADROOM_REDACTED_LOGS_ID_1]. אם המודל צריך את התוכן המקורי בשיחה הבאה, הוא יכול לבקש אותו במפורש. השרת יכול להזרים חזרה את התוכן דרך hydrate, ובכך לשמור על דחיסה ראשונית ועדיין לאפשר שחזור מלא של המידע במידת הצורך.

תשובה לחלק 1.2

תרשים זרימה של מחזור חיים

flowchart LR
  Dev["מפתח/ת (Cursor IDE)"] --> Client["Cursor / MCP Client"]
  Client --> Server["Headroom-Mini MCP Server"]
  Server --> LLM["מודל יעד (Anthropic / Claude)"]

  subgraph preprocessing ["Headroom-Mini Processing"]
    TokenCount["Token Counting"]
    CacheAnalysis["בדיקת cache / ניתוח סטטי"]
    CompressCode["דחיסת קוד / JSON"]
    PromptOptimize["אופטימיזציית פרומפט"]
    Redact["הזרקת placeholders"]
    Hydration["לולאת פידבק / Hydrate"]
  end

  Client --> TokenCount
  TokenCount --> CacheAnalysis
  CacheAnalysis --> CompressCode
  CompressCode --> PromptOptimize
  PromptOptimize --> Redact
  Redact --> LLM
  LLM --> Hydration
  Hydration --> Server

הסבר זרימה

• המפתח כותב קוד או פרומפט ב-Cursor.

• Cursor שולח את הבקשה לשרת MCP המקומי.

• Headroom-Mini סופר טוקנים, מנתח שדות דינמיים, דוחס קוד/JSON ויכול להחליף תוכן גדול ב-placeholders.

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

תשובה לחלק 3

שימוש ביכולות AI פנימיות של Cursor

בפרויקט זה ניתן היה לנצל את יכולות ה-AI של Cursor כדי להבין את מבנה המלל והכלים של Headroom, וליצור את ה-schema של הכלים בצורה מדויקת. ה־README כולל הסברים על כל כלי והטמעה של שרת MCP, מה שמ יוצר ממשק ברור עבור סוכן.

איך סוכן AI משתמש ב-schema של כלי MCP?

כאשר מגדירים כלי MCP עם name, description ו־inputSchema, סוכן AI יכול להבין באיזה תנאים כדאי להפעיל כל כלי. למשל, אם הטקסט מכיל JSON גדול, הסוכן יכול להפעיל compress_json לפני שליחה. זה יאפשר לו לבחור האם לנסות דחיסה או hydration בהתאם לבקשה ולתוכן.

איך Cursor יכול להפעיל את הכלים

בממשק של Cursor, סוכן ה-AI יכול לבחור כלי MCP מתוך הרשימה שהוגדרה לו ולהפעילו בזמן כתיבת בקשה או שליחת פרומפט. לדוגמה, אם המשתמש כותב בקשה עם קוד ארוך, הסוכן יכול לבחור compress_code; אם יש JSON גדול, הוא יכול לבחור compress_json; ואם יש צורך בשחזור תוכן, הוא יכול להשתמש ב-hydrate. זה הופך את התהליך לאוטומטי, שקוף, וממוקד בהקטנת עלויות התקשורת עם המודל.

מדידת טוקנים

דוגמה להדפסה שנמצאת בזמן הריצה:

Original tokens: 2450
Optimized tokens: 1320
Saved tokens: 1130 (46%)

המדידה הזאת מתבצעת באמצעות gpt-tokenizer ומאפשרת לראות את ההשפעה המעשית של הדחיסה.

טסטים

הפרויקט כולל טסטים למקרים קריטיים:

• בדיקת הסרת comments מקוד

• בדיקת minify של JSON

• בדיקת replacement של placeholder ארוך

• בדיקת אופטימיזציית prompt עם timestamps ו-UUID

ניתן להריץ את כל הטסטים עם:

npm test

הערות נוספות

• אין node_modules בתיעוד, וניתן להריץ את הפרויקט אחרי npm install בתוך פחות מ-3 דקות.

• יש טסטים שמכסים את הלוגיקה המרכזית; ניתן להריץ אותם באמצעות npm test.