# 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>` ושומר תוכן לשחזור.
- התהליך מתבצע מקומית בזמן ריצה, ללא אחסון קבוע מחוץ לזיכרון הריצה.

## מבנה הפרויקט

- `src/` – קוד המקור
- `src/tools/` – פונקציות עזר
- `src/storage/` – אחסון placeholder רוחבי לזמן ריצה
- `tests/` – טסטים יחידה

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

```bash
npm install
npm start
```

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

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

```bash
npm run dev
```

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

```bash
npm test
```

### דוגמת שימוש

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

```bash
npm install
npm start
```

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

```bash
npm run dev
```

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

```bash
npm test
```

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

## כלים בשרת MCP

- `compress_code` – מסיר הערות, docstrings וקווים ריקים מקוד
- `compress_json` – בודק JSON וממזג אותו לשורה אחת
- `optimize_prompt` – מוציא חותמות זמן ו-UUIDים ומעביר אותם לסוף הפרומפט
- `redact_content` – מחליף תוכן ארוך מעל 500 תווים ב-placeholder
- `hydrate` – מקבל placeholder או טקסט המכיל אותו ומחזיר את התוכן המקורי

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

```ts
{
  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

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

```mermaid
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`.
זה הופך את התהליך לאוטומטי, שקוף, וממוקד בהקטנת עלויות התקשורת עם המודל.

## מדידת טוקנים

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

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

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

## טסטים

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

- בדיקת הסרת comments מקוד
- בדיקת minify של JSON
- בדיקת replacement של placeholder ארוך
- בדיקת אופטימיזציית prompt עם timestamps ו-UUID

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

```bash
npm test
```

## הערות נוספות

- אין `node_modules` בתיעוד, וניתן להריץ את הפרויקט אחרי `npm install` בתוך פחות מ-3 דקות.
- יש טסטים שמכסים את הלוגיקה המרכזית; ניתן להריץ אותם באמצעות `npm test`.