שרת ה-MCP — חיבור Claude ל-CodeKeeper

שרת MCP (Model Context Protocol) שחושף את CodeKeeper ל-Claude: הקבצים והאוספים האישיים של כל משתמש, ולאדמין — גם דפדפן הריפו מעל ה-Repo Sync Engine. עובד מול Claude.ai (Custom Connector דרך OAuth 2.1), שהמחבר שלו מגיע גם ל-Claude Desktop ול-Claude Code שמחובר עם החשבון, ומול Claude Code שמחובר בדרך אחרת (טוקן אישי). הפירוט ב-חיבור לקוחות.

קוד: mcp_server/ · תכנון מלא: FEATURE_SUGGESTIONS/FEATURE_MCP_CLAUDE_INTEGRATION.md

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

מה זה נותן

  • Claude קורא ומחפש בקבצים השמורים שלך ישירות — בלי העתק-הדבק ובלי צילומי מסך.

  • שמירה (יצירה/עדכון) מאחורי הרשאת write מפורשת — עדכון תוכן תמיד יוצר גרסה חדשה (append-only), אף פעם לא דורס. הסייג: codekeeper_update_file_description נוגע במטא-דאטה ולא בתוכן, ולכן הוא כן דורס — את התיאור של הגרסה האחרונה, בלי ליצור גרסה ובלי לשמור את הערך הקודם. ראו עדכון תיאור בלי גרסה חדשה.

  • לאדמין: קריאה וחיפוש בכל הריפואים המשוקפים (תיעוד, קוד, מסמכי תכנון).

ארכיטקטורה בקצרה

Claude.ai / Claude Code
     │  Streamable HTTP (+OAuth 2.1 או Bearer PAT)
     ▼
שירות MCP נפרד (ASGI, uvicorn)  ── import ישיר ──▶  database/ → MongoDB
     │                                              (code_snippets, collections)
     └── דפדפן ריפו (אדמין) ──▶ bare mirrors בדיסק המקומי (REPO_MIRROR_PATH)
  • ה-user_id נגזר תמיד מהטוקן — לעולם לא מקלט הלקוח.

  • מכבד את חוק ה-Smart Projection: רשימות קבצים וחיפוש מחזירים מטא-דאטה בלבד; תוכן מלא רק בבקשה מפורשת לקובץ בודד. החריג הוא כלי רשימת הפתקים (codekeeper_list_notes, codekeeper_list_board_notes, codekeeper_list_repo_notes): פתק הוא ישות קטנה, חסומה ב-MAX_NOTE_CHARS, והרשימה מחזירה את גופו כברירת מחדל (include_content=true); בשני הראשונים include_content=false משאיר את הגוף במסד ומחזיר במקומו את גודלו — ראו קריאת פתק בודד — codekeeper_get_note.

מודל הריצה של הכלים

גופי הכלים נכתבים סינכרוניים, ו-AdminAwareFastMCP.add_tool מעביר כל אחד לחוט עובד בזמן הרישום. זו נקודה אחת שמכסה את כל הכלים, ולא החלטה שחוזרת בכל כלי בנפרד — הכלי הבא נולד נכון בלי שאיש יזכור.

עד #3379 השרת לא עשה את זה, וה-docstring טען שכן. ה-SDK קורא גוף סינכרוני ישירות (return fn(**arguments)), כלומר בקשה איטית אחת עצרה את כל הסשנים בתהליך ולא רק את הקורא שלה. האמונה השגויה היא הסיבה שאיש לא בדק, ולכן הסעיף הזה קיים: תיאור שגוי של מודל ריצה הוא מה שמסתיר את הבאג הבא.

יש שני יעדים, ולא אחד:

  • קריאות הולכות ל-asyncio.to_thread, כלומר למאגר ברירת המחדל של לולאת האירועים — ומאז #3391 המאגר הזה הוא שלנו: attach_read_pool ב-mcp_server/server.py מתקין אותו בעליית ה-lifespan של אפליקציית ה-ASGI, וגודלו נגזר ממכסת הזיכרון של הקונטיינר. כמה קריאות רצות במקביל; כמה בדיוק, ולמה דווקא מהזיכרון — בהמשך הסעיף.

  • כתיבות הולכות למאגר ייעודי בעל worker יחיד. לכן גוף כתיבה אחד רץ בכל רגע, והתור מוסר אותם לעובד לפי סדר ההגעה — queue.SimpleQueue הוא FIFO.

גודל מאגר הקריאות נגזר ממכסת הזיכרון, לא ממספר המעבדים. עד #3391 המאגר היה ברירת המחדל של CPython, min(32, os.cpu_count() + 4), ו-CPython עצמו מתעד ש-os.cpu_count() ”אינו שקול למספר המעבדים שהתהליך הנוכחי יכול להשתמש בהם“: בקונטיינר הוא מדווח את ליבות המארח. שורת הקיבולת בייצור הראתה בדיוק את זה — read pool 12 threads (os.cpu_count=8, usable=8) מול cpu quota cgroup v2: 0.50 cpu, כלומר 12 חוטים על חצי מעבד. לקריאת מונגו או דיסק זה לא מזיק, החוטים ישנים; לפרסור בפייתון טהור אין מקביליות ב-CPU בגלל ה-GIL, ולכן מאגר רחב קונה רק מקביליות בזיכרון — 12 עצי פרסור בו-זמנית, בלי תפוקה. החסם האמיתי הוא הזיכרון, וממנו נגזר הגודל:

(מגבלת הזיכרון − קו הבסיס − שוליים) ÷ עלות פרסור אחד
  • מגבלת הזיכרון נקראת מ-cgroup בזמן ריצה, כמו שמכסת ה-CPU כבר נקראת: memory.max ב-v2 (max פירושו ללא מגבלה) ו-memory/memory.limit_in_bytes ב-v1 (שם ”ללא מגבלה“ נקרא כמספר סמוך ל-LONG_MAX). היא אינה מקובעת בקוד — השירות כבר עבר תוכנית ואזור פעם אחת. הקורא: _memory_limit ב-mcp_server/server.py, לצד _cpu_budget.

  • קו הבסיס (_PROCESS_BASELINE_BYTES, ‏92MiB) הוא ה-RSS של השירות בשקט בייצור, כפי שנמדד במדדי Render ב-2026-09-19; השוליים (_NON_PARSE_MARGIN_BYTES, ‏64MiB) הם הפער בין קו הבסיס לשיאי העבודה שנצפו באותם מדדים ביום שאחריו — כל מה שהתהליך מחזיק ואינו הפרסור המתוקצב.

  • עלות פרסור אחד היא _PARSE_RSS_PER_INPUT_BYTE כפול הקלט הגדול ביותר שפרסור יכול לקבל, MAX_FILE_SIZE_FOR_DISPLAY: ‏``codekeeper_docs_get_section`` קורא דרך RepoBackend.get_file בלי lines, ולכן בלי max_size, ודוחה too_large לפני שהוא מפרסר. והצרכן השני, codekeeper_get_file עם toc או section, מפרסר קובץ שמור — קובץ שכל משתמש כתב, ושאף מראה אינה חוסמת — ולכן מודד את הקובץ עצמו, בבתים של UTF-8 (היחידה שהעלות מתומחרת בה), מול אותה תקרה, ודוחה too_large_for_sections לפני הפרסור (ראו קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)). הקבוע מיובא ולא מועתק בשני המקומות, כדי שהתקציב ושני הסירובים יזוזו עם התקרה. הקבוע נמדד על services.md_parser (‏``markdown-it-py`` הנעוץ) — היקר מבין שני הפרסרים שהכלי מריץ: codekeeper_docs_get_section מריץ services.rst_parser על docs/*.rst ו-services.md_parser על *.md, ומסלול ה-RST זול בהרבה. כל המספרים כאן נמדדו מחדש ב-2026-09-27 בשיטה המתוקנת — איפוס VmHWM רגע לפני הפרסור, 40 סידורי זיכרון לכל מדידה, וחסם עליון שהוא המקסימום ועוד פיגור המונים של הקרנל (השיטה: סקריפטים שימושיים). קורפוס ה-RST של הריפו משוכפל עד תקרת הקריאה מגיע ל-2.0 בתים לכל בית קלט (השיטה שלפני האיפוס לא הראתה ממנו כלום — השיא שלפני הפרסור הסתיר אותו), העמוד הצפוף ביותר (docs/modules/index.rst) משוכפל עד התקרה ל-7.0, וצורה עוינת של כותרת בת תו אחד בכל שורה ל-90.8 בלי תקרה — 44.3MiB לפרסור אחד, מעל 35.2MiB שהנוסחה מקצה לחוט. לכן יש ל-RST תקרת סקשנים מאז הסקירה של #3429 — היום MAX_SECTIONS (50,000), ברירת המחדל של שני הפרסרים, שהכלי אינו דורס — ו-too_many_sections חוזר במקום פרסור של הקובץ כולו: אותה צורה עוינת נעצרת ב-20.2MiB (41.4 בתים לכל בית קלט), בתוך ההקצאה, ואף עמוד אמיתי אינו מתקרב לתקרה (ראו איך docs_get_section מוצא כותרת). העלות לכל בית קלט היא שיא ה-RSS בזמן הפרסור — מה שכמה פרסורים במקביל מחזיקים יחד — והיא נגזרת מ**צפיפות** המסמך ולא מגודלו: משוכפלים עד תקרת הקריאה, קורפוס ה-Markdown של הריפו מגיע ל-24.6 בתים לכל בית קלט, והמסמך הצפוף ביותר בו (CLOUD.md, כ-170 טוקנים ל-KB) ל-72.4 — 73.2 כחסם עליון (על 3.0.0, באותו סקריפט: 24.7 ו-72.8, חסם 73.6 — כלומר השדרוג ל-4.2.0 אינו מזיז את העלות). הצורה הזו עולה יותר מהקבוע, ותמיד עלתה: 72 נקבע ב-#3429 ממדידה אחת שלה (71.7) מעוגלת כלפי מעלה; על 40 סידורי זיכרון אותה צורה על הפרסר של אז (3.0.0) נעה בין 71.2 ל-72.8, כלומר 71.7 היה הגרלה, והשיטה שבאה אחריה — שבה השיא שלפני הפרסור הסתיר כחצי MB — קראה אותה נמוך עוד יותר (70.1 ו-71.2). הקבוע מחזיק רק בזכות התקרות של #3391 (#3467): הכלי דוחה את שתי הצורות המשוכפלות בתקרת השורות לפני הפרסור, ולכן הסקריפט חותך כל קלט למה שהכלי עוד מפרסר, ומה שמכריע את הקבוע הוא הקלט העוין. ומאז #3391 הקבוע חוסם גם את הקלט העוין — בתוך התקרות של הפרסר. בלי תקרות, קובץ עוין של שורות-תבליט בודדות עולה כ-292 בתים לבית, כלומר כ-142.5MiB לפרסור אחד, מה ששום רוחב מאגר אינו סופג; ותקרת הכותרות אינה נוגעת בו, כי אין בו אף כותרת. md_parser מסרב לקובץ ארוך מ-MAX_LINES לפני הפרסור ועוצר פרסור ב-MAX_TOKENS, והקלט הגרוע שנמצא תחת שתיהן נכנס ב-_PARSE_COST_BYTES: החסם העליון שלו הוא 69.02 בתים לכל בית של תקרת הקריאה — 95.9% מהקבוע, מרווח של 4.1% בלבד. זה לא הממוצע ולא ריצה טיפוסית: השיא הגבוה ביותר שנמדד על פני הסידורים (34,959,360 בתים; הפיזור 92.2%–94.8% מ-_PARSE_COST_BYTES, כך שמי שמריץ פעם אחת ומקבל פחות פגש סידור ולא שינוי), ועוד פיגור המונים של הקרנל. מדידה עתידית שעוברת את 72 אינה רעש — החסם כבר כולל את שניהם, ולכן מעבר שלו פירושו שהפרסור התייקר. איך החסם נבנה והפיזור המלא — ליד _PARSE_RSS_PER_INPUT_BYTE; הקלט — ליד MAX_TOKENS ב- services/md_parser.py; ואיך נבחרו שני המספרים — ב- איזה קובץ docs_get_section קורא, ובאיזה ריפו. ‏``scripts/measure_md_parse_cost.py`` מודד את המספרים מחדש לשני הפרסרים, כולל הקלט העוין כמו שהכלי מקבל אותו, ויוצא בקוד 1 כשמשהו כבר אינו נכנס — מריצים אותו כשאחד מהם משתנה.

  • ההחזקה הגדולה ביותר של חוט קריאה אינה הפרסור, וזו החלטה מתועדת. כלי האדמין codekeeper_get_repo_file עם outline=true או lines= קורא עד RANGE_READ_MAX_BYTES (‏10MiB), והמראה טוענת blob שמתחת לתקרה כולו לזיכרון לפני הפענוח והחיתוך (blob שמעליה נדחה מ-git cat-file -s בלי להיקרא — ראו #3433 למטה). נמדד מחדש ב-2026-09-27, עם האיפוס ועל 40 סידורי זיכרון (בסוגריים — החסם העליון), ברתמה שאינה בריפו, כי הסקריפט מודד רק את הפרסור: outline של קובץ RST בגודל 10MB מחזיק לאורך המסלול כולו 80.8MiB (81.2) בשכפול ריאליסטי ו-91.6MiB (92.0) עם כותרות עוינות. הפרסור לבדו הוא 61.2MiB (שורת outline_densest_real של הסקריפט), והשאר הוא הטקסט של 10MB והקריאה שהביאה אותו; השיטה שלפני האיפוס שמה את הפרסור לבדו על 51MiB, כי חוצץ הקריאה של 10MB הסתיר את ההפרש. קריאת lines= של webapp/static/js/md_preview.bundle.js האמיתי (7MB) מחזיקה 29.6MiB (29.9). כלומר ההחזקה הגדולה ביותר מגיעה עד פי 2.6 מ-35.2MiB שהמחלק מקצה לחוט. המחלק נשאר מתומחר לפי הפרסור בכוונה: הפרסור הוא מה שהכלי הציבורי יכול לעלות בכל רגע; קריאות הטווח הן אדמין בלבד; ההחזקה הגדולה ביותר על קובץ שקיים היום במראות — קריאת הבאנדל — קטנה מההקצאה של חוט אחד, ולכן נכנסת גם ברוחב מלא; וה-81–92MiB דורשים קובץ RST של 10MB, שאין באף ריפו משוקף (הגדול ביותר כאן, docs/mcp-server.rst, קטן מ-250KB ב-2026-09-27). תמחור לפי הצורה הזו היה מצמצם את המסלול הציבורי ל-3 חוטים (לפי 92MiB) בגלל צורה שאין לה מקור. מה שכן השתנה בגלל זה הוא התקרה (למטה); והשורש — לחסום את הקריאה במקור — נסגר ב-#3433: get_file_at_commit שואל את מאגר האובייקטים לגודל (git cat-file -s <sha>:<path>) לפני git show, ולכן max_size הוא חסם על מה שנקרא ולא בדיקה בדיעבד. נמדד מחדש (אותו יום, אותה שיטה): קובץ של 12MB שנדחה עלה 22MiB שיא לפני, ואפס אחרי; קובץ של 7MB שמתחת לתקרה עולה 14MiB לפני ואחרי, כי אותו כן קוראים.

  • רצפה (_READ_POOL_FLOOR, ‏2): כדי שקריאת מונגו תקועה אחת לא תשבית את השאר. שניים הוא הגודל הקטן ביותר עם התכונה הזאת, וכל יחידה מעליו היא זיכרון שהחשבון אמר שאין. תקרה (_READ_POOL_CAP, ‏12): הרוחב שהייצור כבר הריץ לפני #3391. מעליה עוד חוטים הם רק עוד פרסורים מקבילים תחת ה-GIL, ומעבר לתוכנית גדולה לא ירחיב את המאגר — על בסיס מחלק שמתאר את הפרסור ולא את קריאות הטווח — בלי שאיש החליט. הגרסה הראשונה של ה-PR נקבה ב-32, התקרה ש-CPython בחר ל-executor ברירת המחדל שלו; הסקירה של #3429 הורידה אותה.

  • כשאין מגבלה שאפשר לקרוא — הקובץ חסר, אינו ניתן לפענוח, או אומר ”ללא מגבלה“ — הגודל הוא הרצפה, ולא cpu_count + 4, המספר שהגזירה הזאת באה להפסיק להישען עליו. הקצה השמרני נבחר בכוונה: מאגר צר מדי הוא איטיות גלויה, ושורת הקיבולת אומרת למה; מאגר רחב מדי הוא OOM שאיש לא מייחס. ה-fallback נרשם גם כ-WARNING נפרד, כי מסלול גרוע שאיש לא מדווח עליו הוא זה שנשאר.

על תוכנית הייצור (0.5c-512mb): ‏(512MiB − 92MiB − 64MiB) ÷ 35.2MiB = 10 חוטים, במקום 12. ‏``_read_pool_size`` היא הפונקציה הטהורה שעושה את החשבון, וכל אחד מהתנאים — הגזירה, הרצפה, התקרה וה-fallback — מעוגן בטסט למספר שחושב ביד, כך שמימוש שמחזיר קבוע נופל.

איפה ההתקנה קורית, ולמה שם. ‏``loop.set_default_executor`` דורש לולאה רצה ומקבל רק ThreadPoolExecutor, ו-build_app רץ בזמן ייבוא, לפני שיש ל-uvicorn לולאה. ‏``FastMCP.streamable_http_app()`` בונה את אפליקציית Starlette עם lifespan= משלה, ולכן on_startup אינו רץ כלל — עטיפת ה-lifespan היא ה-seam היחיד, אותו seam שניקוז ה-PostHog כבר משתמש בו. המאגר נבנה שלם ומתפרסם בהצבה אחת. הוא אינו נסגר ביציאה מה-lifespan: ה-executor ברירת המחדל שייך ללולאה, ו-asyncio.run של uvicorn סוגר אותו ב-shutdown_default_executor עם המתנה — קריאה שבאמצע מסתיימת בדיפלוי, כמו כתיבה. ומכיוון שהשירות רץ כתהליך אחד (uvicorn בלי --workers; בלוגים Started server process פעם אחת לכל מופע), המאגר הזה הוא כל מקביליות הקריאה של השירות.

הכתיבות אינן נועלות מנעול על המאגר המשותף, וזה נמדד ולא הוכרע בטעם: כותב שחסום על מנעול עדיין תופס חוט שהקוראים צריכים, ומנעול גם אינו מבטיח סדר. עם מאגר נפרד, קורא שנשלח בזמן ש-40 כתיבות ממתינות חוזר מיד; קודם הוא חיכה שניות.

contextvars מועתקים במפורש בדרך לכתיבה. asyncio.to_thread מעתיק את ההקשר בעצמו, ו-loop.run_in_executor אינו מעתיק — ובלי ההעתקה get_access_token() מחזיר None בתוך העובד, כלומר require_write ו- require_admin מפסיקים לראות מי שואל.

המחיר, במפורש: תור אחד פירושו שכתיבות של משתמשים שונים ממתינות זו לזו. קריאות לעולם אינן ממתינות לכתיבה. כל כתיבה רושמת שורה שמפרידה בין זמן ההמתנה בתור לזמן הריצה, כי סכום אחד אינו מבדיל בין שמירה איטית לשמירה שחיכתה; מעל 10 שניות המתנה — יותר מגוף כתיבה שלם לפי ה-p95 — היא נרשמת כאזהרה.

הרמה נבחרה במודע: info ולא debug. הרמה שבתוקף בשירות היא INFO, כך ש-debug אינו שקט אלא נעדר — וזו בדיוק התקלה שהשורות האלה נולדו ממנה. הנפח אינו יכול להתפרץ: worker יחיד מריץ כתיבה אחת בכל רגע וגוף כתיבה נמדד ב-4.3–4.9 שניות ב-p50, כלומר השורה חסומה בסביבות שלוש-עשרה לדקה תהיה התנועה אשר תהיה. ורישום של המקרה האיטי בלבד היה אומר מתי ההמתנה חריגה בלי לומר לעולם מהי ההמתנה הרגילה — המספר שכל החלטה על רוחב התור נשענת עליו.

ומה שהופך את השורות לנראות בכלל: תהליך ה-MCP לא הגדיר לוגים בעצמו, ומה שכן הגדיר אותם הוא FastMCP.__init__ שמסתיים ב-configure_logging. לכן שורה שנרשמה לפני בניית שרת ה-MCP נזרקה במקום. שורת הקיבולת נרשמת מתוך ה-lifespan, מיד אחרי שמאגר הקריאות הותקן — מאוחר עוד יותר מ-build_mcp — ומהמאגר שהותקן בפועל: היא קוראת את _max_workers שלו ואינה מחשבת מספר בנפרד, כי רשומה שמתארת מצב ומתעדכנת בנפרד ממנו היא בדיוק מה שמשקר בשקט. ‏``mcp_server/app.py`` מגדיר לוגים כבר בייבוא (‏``LOG_LEVEL``, ברירת מחדל INFO) כדי שגם רשומות מוקדמות יותר ייראו.

ביטול, כפי שנמדד: בקשת כתיבה שבוטלה בזמן שהיא עדיין בתור אינה רצה כלל. בקשה שבוטלה אחרי שהגוף התחיל רצה עד הסוף, כי גוף סינכרוני אינו ניתן להפסקה — הקורא מפסיק להמתין, הכתיבה קורית. לקוח שעבר timeout וניסה שוב מייצר אפוא כתיבה שנייה, לא החלפה של הראשונה.

כלי כתיבה אינו יכול להיות async def. מאגר בעל worker יחיד מסדר בטור גופים סינכרוניים; גוף אסינכרוני היה מחזיר לעובד קורוטינה ורץ על הלולאה בלי תור ובלי סדר, בזמן שהכלי עדיין מוצהר ככתיבה. הרישום נכשל במפורש במקרה הזה, כי זו הנקודה היחידה שבה אפשר לראות את זה.

הכלים

בלוק ה-``instructions``. לצד הטבלאות כאן, השרת מחזיר ב-initialize בלוק קצר שמקבץ את הכלים לפי משימות: איזה כלי לבחור מבין כלים אחים, איזה פרוטוקול עובר בין כלים (conflict ← codekeeper_get_note ← ניסיון חוזר), ואילו עובדות מפתיעות (מילים שלמות בלבד, לא אידמפוטנטי). עם טעינת כלים מושהית זה מה שהסוכן רואה בתחילת הסשן, לצד שמות הכלים, ולכן כלי שהבלוק אינו מזכיר כמעט לא מתגלה. הבלוק נבנה ב-build_instructions (mcp_server/server.py), ו**אורכו חסום ב-CLIENT_INSTRUCTIONS_MAX_CHARS``** — Claude Code מעביר לסוכן רק את התחלת הבלוק, ומה שמעבר לה אינו מגיע (המקור, הגרסה והתאריך בהערה שליד הקבוע); בלוק ארוך יותר מדווח בעלייה בשורת WARNING שנוקבת בשמות הכלים שנפלו. **מי שמוסיף כלי מוסיף אותו גם לבלוק**, אחרת ``tests/test_mcp_instructions.py נופל: הוא משווה את השמות שבתוך התקרה ל-tools/list של אדמין, בתצורת הייצור ודרך session אמיתי של הפרוטוקול. שלושה חלקים בבלוק נבנים ולא מוקלדים: רשימת הריפואים שכלי התיעוד מגיש (ראו איזה קובץ docs_get_section קורא, ובאיזה ריפו), תקרת הבאץ« של השרת (batch_item_cap), והמשפט על get_more_tools — רק כשהכלי באמת ברשימה (ראו ”מדידת שימוש“ למטה). ובשרת בלי מראה (בלי repo_backend) השורות על כלי המראה ועל כלי התיעוד יורדות, כי הכלים האלה אינם נרשמים אז, ופתקי הריפו נשארים.

כלי משתמש (לכל משתמש מחובר):

כלי

תיאור

codekeeper_list_files

רשימת קבצים (מטא-דאטה, עם עימוד)

codekeeper_search_code

חיפוש טקסט מלא ($text של מונגו) על שם הקובץ, התיאור, התגיות ותוכן הקוד → מטא-דאטה של הקבצים התואמים, בלי התוכן. מתאים למילים שלמות; ראו איך מחפשים קובץ ופתק — codekeeper_search_code ו-codekeeper_search_notes

codekeeper_get_file

תוכן מלא של קובץ (לפי שם/מזהה, אופציונלית גרסה). lines=[start, end] מחזיר רק את הטווח המבוקש — ראו קריאת טווח שורות. query="..." מחזיר את המופעים של המחרוזת בקובץ במקום את התוכן, בצורת התשובה של codekeeper_search_repo — ראו חיפוש בתוך קובץ שמור (query). ובקובץ Markdown: toc=true מחזיר את מפת הכותרות — max_depth משאיר בה רק את הרמות העליונות — ו-section="..." סעיף אחד עם ניווט — אותן פונקציות של codekeeper_docs_get_section, ראו קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section). את הבתים עצמם, לדיסק של הסוכן בלי לעבור בהקשר — GET /api/agent/download לפי file_id; הפקודה בתיאור הפרמטר, ראו הורדת קובץ לדיסק בלי לעבור דרך המודל. בקריאה לפי file_id, file.is_latest אומר אם זו עדיין הגרסה שקריאה לפי השם מחזירה — ראו האם זו הגרסה האחרונה — is_latest

codekeeper_save_file

כתיבה: יצירת קובץ חדש. שם שכבר תפוס נדחה ב-file_exists, ולעדכון קובץ קיים יש codekeeper_edit_file, codekeeper_multi_edit_file ו-codekeeper_append_file. בכפוף למגבלת MAX_CODE_SIZE — ברירת מחדל 100K תווים, ניתנת להגדלה בקונפיג. התוכן נשמר בדיוק כמו שנשלח, בכל כלי הכתיבה של קבצים: בלי ניקוי תווים ובלי קיצוץ רווחים או newline — ראו ניקוי קוד מודבק (Pasted-code cleanup). תוכן שכבר קיים כקובץ בסביבת הסוכן עולה ב-PUT /api/agent/upload ונשמר לפי upload_id במקום code — ראו העלאת תוכן בלי לעבור דרך המודל. description עד FILE_DESCRIPTION_MAX_CHARS תווים; ארוך ממנה — הקובץ נשמר בלי התיאור, ו-description_saved: false עם max_chars ו-actual_chars — ראו תיאור ארוך בשמירה — description_saved. דורש write

codekeeper_edit_file

כתיבה: מצא-והחלף מדויק בקובץ קיים (old_string → new_string) — בלי לשלוח את כל הקובץ. old_string צריך להופיע פעם אחת בדיוק, אחרת ambiguous_match עם מספר המופעים; replace_all=true מחליף את כולם. נשמר כגרסה חדשה, ורק הטקסט שהוחלף משתנה: שאר הקובץ נשאר תו בתו. לכמה מקומות באותו קובץ — codekeeper_multi_edit_file, בגרסה אחת. expected_content_sha256 מסרב לכתוב אם הקובץ השתנה מאז שנקרא — ראו עריכה על מה שקראתם — expected_content_sha256. expected_unicode_escapes מסרב לכתוב כש-escape של יוניקוד שנועד להיות טקסט לא הגיע לכלי כטקסט — ראו escape של יוניקוד שהגיע כטקסט — expected_unicode_escapes. דורש write

codekeeper_multi_edit_file

כתיבה: כמה עריכות מדויקות בקובץ קיים, בגרסה אחת: רשימת זוגות edits, וכל זוג הוא בדיוק הארגומנטים של codekeeper_edit_file בלי file_name. הזוגות מוחלים לפי הסדר, כל זוג על התוצאה של הזוג שלפניו, והכל או כלום: זוג שנכשל מחזיר את ה-index שלו, ושום דבר לא נכתב. עד MAX_EDIT_PAIRS זוגות בקריאה. expected_content_sha256 כמו ב-codekeeper_edit_file, וזוג יכול לשאת expected_unicode_escapes משלו. ראו כמה עריכות בגרסה אחת — codekeeper_multi_edit_file. זוגות שיש במחרוזות שלהם לוכסן שנועד להיות טקסט יכולים להגיע כקובץ JSON שהועלה — edits_upload_id במקום edits — והשרת מפענח אותו פעם אחת בדיוק; ראו הזוגות כקובץ — edits_upload_id. דורש write

codekeeper_append_file

כתיבה: הוספת טקסט לסוף קובץ קיים (גרסה חדשה). expected_content_sha256 כמו ב-codekeeper_edit_file. טקסט שכבר קיים כקובץ בסביבת הסוכן — upload_id במקום content, ראו העלאת תוכן בלי לעבור דרך המודל. דורש write

codekeeper_update_file_description

כתיבה: החלפת ה-description של קובץ קיים, בלי לשלוח את התוכן ובלי לגעת בו. אינו יוצר גרסה — ראו עדכון תיאור בלי גרסה חדשה. תיאור בלבד; תגיות אינן משתנות. עד FILE_DESCRIPTION_MAX_CHARS תווים; ארוך ממנה נדחה ב-description_too_long עם max_chars ו-actual_chars, חוץ מהטקסט שכבר שמור. דורש write

codekeeper_list_versions

היסטוריית גרסאות של קובץ. version_created_at הוא מתי כל גרסה נשמרה, ולא updated_at — זה שדה של הקובץ ובר-שינוי, ולכן שורת היסטוריה שנשענת עליו יכולה לתאר רגע מאוחר יותר. ראו docs/database/detailed-schema.rst. ה-id של כל גרסה הוא ה-file_id של פקודת ההורדה שבתיאור הכלי — ראו הורדת קובץ לדיסק בלי לעבור דרך המודל

codekeeper_list_notes

פתקים דביקים של קובץ (לפי file_name) — אותם פתקים שמוצגים ב-UI של הוובאפ. include_content=false מחזיר את השורות בלי הגוף, עם גודלו ועם מספר שרשורי התגובות הפתוחים — ראו קריאת פתק בודד — codekeeper_get_note

codekeeper_get_note

פתק בודד לפי note_id: הגוף הנוכחי בדיוק כפי שהוא מאוחסן, הכותרת, הצבע, version — מספר הגוף הנוכחי (null לגוף ריק), שנקרא באותה קריאה תחומה כמו הגוף — ואיפה הפתק יושב, בדיוק בארגומנטים שכלי הרשימה המתאים דורש; ואחריו שרשורי התגובות שעליו (threads). part="threads" מחזיר רק את השרשורים, בלי הגוף, ו-thread_id שרשור אחד. פתק של משתמש אחר, ופתק ריפו למי שאינו אדמין — not_found; פתק שנערך ממש ברגע הקריאה — conflict. ראו קריאת פתק בודד — codekeeper_get_note ו-שרשורי תגובות על פתקים — codekeeper_comment_note

codekeeper_show_note

פתק בודד לפי note_id, מוצג למשתמש בתוך השיחה — כותרת, צבע וגוף — במארח שמציג MCP Apps. אותו שער ואותה צורה של codekeeper_get_note, בלי השרשורים ובלי version; לקוח שאינו מציג תצוגה מקבל את הפתק המלא כטקסט. ראו תצוגה בתוך Claude — MCP App

codekeeper_create_note

כתיבה: יצירת פתק דביק על קובץ קיים; line אופציונלי מעגן לשורת מקור (בלעדיו הפתק צף). דורש write

codekeeper_update_note

כתיבה: עדכון חלקי של פתק לפי note_id (תוכן/שורה/צבע/מוזער) — דורס במקום, אבל התוכן הקודם נשמר כגרסה. דורש write

codekeeper_note_str_replace

כתיבה: מצא-והחלף מדויק בתוך פתק (old_string → new_string) — בלי לשלוח את כל גוף הפתק. אותה סמנטיקה ואותם נוסחי שגיאה כמו codekeeper_edit_file, כולל סירוב על התאמה מרובה. וכמו שם, אורך התוצאה נבדק לפני שהיא נבנית: תוצאה ארוכה מ-MAX_NOTE_CHARS נענית content_too_long עם max, ושום דבר לא נכתב — ראו כמה עריכות בגרסה אחת — codekeeper_multi_edit_file, ”גודל, לפני שהתוצאה נבנית“. דורש write

codekeeper_comment_note

כתיבה: תגובה בשרשור שעל פתק — בלי לגעת בפתק עצמו. בלי thread_id: שרשור חדש. עם thread_id: תשובה — שרשור שנפתר נפתח מחדש, אלא אם reopen=false. thread_id עם resolve=true: סגירה, ו-body אופציונלי כמשפט סיכום. working_on חובה בכל קריאה לכלי, גם בסגירה בלי תגובה; שם הכותב מגיע מהחיבור ולא מפרמטר. אותה הרשאה בדיוק של codekeeper_get_note, מאותו קוד. ראו שרשורי תגובות על פתקים — codekeeper_comment_note. דורש write

codekeeper_list_note_versions

הגרסאות הקודמות של פתק (מטא-דאטה בלבד: מספר, זמן, ואורך בתווים — לא בבתים כמו content_bytes של הרשימה הרזה), החדשה תחילה

codekeeper_get_note_version

תוכן של גרסה קודמת אחת. הגוף הנוכחי הוא codekeeper_get_note, שגם אומר באיזה מספר הגוף הזה ייקרא כאן כשיידרס דרך השרת הזה (עריכה מהוובאפ אינה נכנסת להיסטוריה). השחזור עצמו הוא codekeeper_update_note עם התוכן שנקרא

codekeeper_list_boards

הלוחות של המשתמש — משטחים שנושאים פתקים שאינם שייכים לשום קובץ. מייצר את לוח ברירת המחדל בקריאה הראשונה

codekeeper_list_board_notes

הפתקים שעל לוח יחיד (לפי board_id מתוך codekeeper_list_boards). include_content=false מחזיר את השורות בלי הגוף, עם גודלו ועם מספר שרשורי התגובות הפתוחים — הזרימה ללוח גדול: רשימה קטנה ואחריה codekeeper_get_note. ראו קריאת פתק בודד — codekeeper_get_note

codekeeper_create_board_note

כתיבה: פתק חדש על לוח — בלי קובץ. mode הוא surface (יושב על הלוח, ברירת מחדל) או screen (צף מול המסך). title אופציונלי, וייחודי בתוך הלוח. דורש write

codekeeper_search_notes

חיפוש פתק במקומות שפתק יכול לשבת בהם — קובץ, לוח, או קובץ בריפו משוקף. לפי שם כברירת מחדל; search_content=true מרחיב גם לגוף הפתק, ו-include_archived=true מוסיף את פתקי הארכיון, שבלעדיו מוסתרים. התאמה על חלק מהמחרוזת, בלי תלות ברישיות. כל פגיעה אומרת איפה הפתק יושב, בדיוק בארגומנטים שכלי הרשימה המתאים דורש — ולעולם אינה נושאת תוכן; את הפתק קוראים ב-codekeeper_get_note לפי המזהה שבפגיעה. לפגיעה מהארכיון אין כלי רשימה. ראו איך מחפשים קובץ ופתק — codekeeper_search_code ו-codekeeper_search_notes

codekeeper_list_collections / codekeeper_get_collection / codekeeper_get_collection_items

האוספים והקבצים שבתוכם

codekeeper_add_to_collection

כתיבה: שיוך קובץ שמור קיים לאוסף קיים. codekeeper_save_file אינו משייך לאוסף, ולכן זו הקריאה השנייה שמשלימה אותו. נכשל במפורש כשהאוסף או הקובץ אינם קיימים. דורש write

codekeeper_docs_get_section

סקשן בודד מקובץ תיעוד — RST או Markdown, לפי הריפו — במקום קובץ שלם. בלי section — עץ הכותרות של העמוד, ועם max_depth רק הרמות העליונות שלו (איך docs_get_section מוצא כותרת). מחזיר גם breadcrumb, תת-סקשנים ושכנים לניווט. קובץ שלם: whole_document=true — הקובץ כולו משורה 1, כולל front matter ומה שלפני הכותרת הראשונה, בלי פרסור (ולכן גם קובץ שמפת הכותרות מסרבת לו), מדופדף כמו סעיף: כל עוד truncated הוא true ממשיכים מ-next_offset (איזה קובץ docs_get_section קורא, ובאיזה ריפו). לאדמין גם codekeeper_read_batch ו-codekeeper_get_repo_file. עדיף על codekeeper_get_repo_file לקריאת תיעוד לפי סעיפים. איזה ריפו מגיש אילו נתיבים ובאיזה פורמט — ב-איזה קובץ docs_get_section קורא, ובאיזה ריפו; איך נמצאת כותרת, כולל קיצור המזהה (K11) וכותרות שנושאות בקטיקים — ב-איך docs_get_section מוצא כותרת

כלי אדמין (דפדפן הריפו — מוסתרים וחסומים לכל משתמש אחר):

כלי

תיאור

codekeeper_list_repos

הריפואים המשוקפים (מטא-דאטה)

codekeeper_list_repo_tree

נתיבי קבצים בריפו (עימוד, סינון תיקייה/ref; בלי תוכן). include_stats=true מוסיף entries עם גודל וספירת שורות לכל נתיב — ראו גודל וספירת שורות ברשימת הריפו

codekeeper_get_repo_file

תוכן קובץ בודד (עד 500KB לקובץ מלא, עד 10MB עם lines; קובץ בינארי ← מטא-דאטה בלבד). lines=[start, end] כמו ב-codekeeper_get_file, באותה סמנטיקה בדיוק — ראו קריאת טווח שורות

codekeeper_search_repo

חיפוש טקסט בריפו (קטעים קצרים עם path+line, עם תקרות). context_lines=N (0‑10) מחזיר גם context_before ו-context_after לכל פגיעה, במקום למשוך את הקובץ כולו רק כדי לראות את הסביבה. total הוא כמה מופעים יש בריפו ולא כמה הוחזרו, וקוד חיצוני וקבצים מקומפלים מוחרגים מהחיפוש ומהספירה כברירת מחדל — ראו כמה מופעים יש באמת (total מול total_at_least). ההתאמה אינה רגישה לרישיות כברירת מחדל; case_sensitive=true מבקש התאמה מדויקת. file_pattern מצמצם את החיפוש לתבנית נתיב אחת של גיט, או מחריג אחת (:(exclude)assets/vendor) — ראו סינון לפי נתיב (file_pattern)

codekeeper_read_batch

כמה סעיפי תיעוד וקבצים מהמראות בקריאת כלי אחת, במקום קריאה לכל אחד — למשל כל הדפוסים שסבב ריוויו חייב לקרוא. כל פריט עובר דרך ה-handler של הכלי שהוא משקף (codekeeper_docs_get_section או codekeeper_get_repo_file), ולכן התשובה שלו זהה בית-בית לזו של הכלי הבודד, כולל סירובים. כל פריט נספר כקריאה אחת מול מכסת הקצב — ראו קריאה קבוצתית — codekeeper_read_batch

codekeeper_list_repo_notes

פתקים דביקים על קובץ בריפו משוקף (repo_name + repo_path) — אותם פתקים שמוצגים בדפדפן הריפו בוובאפ. מחזיר orphaned: true כשהנתיב כבר אינו בעץ המשוקף, והפתקים עצמם חוזרים בכל מקרה

codekeeper_list_repo_note_paths

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

codekeeper_create_repo_note

כתיבה: פתק חדש על קובץ בריפו משוקף. mode כמו בלוח; title אופציונלי, וייחודי על אותו קובץ. דורש write

הערה

דפדפן הריפו הוא קריאה בלבד לצמיתות (החלטת עיצוב) — אין, ולא תתווסף, עריכה/commit/push לריפו GitHub. ה-mirrors בדיסק הם רפליקה חד-כיוונית מ-GitHub (מקור האמת), וה-MCP לעולם לא כותב אליהם.

codekeeper_create_repo_note אינו יוצא מן הכלל הזה. הפתק נכתב לאוסף sticky_notes שב-CodeKeeper, והוא הערה על הקובץ ולא שינוי בו — לא ב-mirror ולא בריפו ב-GitHub. כתוב כאן כדי שאיש לא יסיק אחרת משם הכלי.

תצוגה בתוך Claude — MCP App

מה זה. codekeeper_show_note הוא הכלי הראשון בשרת שיש לו תצוגה: במארח שמציג MCP Apps, הפתק מוצג למשתמש בתוך השיחה, עם הכותרת, הצבע והגוף שלו, במקום שהמשתמש יעבור ללשונית של הוובאפ כדי לראות מה הסוכן כתב. MCP Apps היא הרחבה רשמית של הפרוטוקול (io.modelcontextprotocol/ui, SEP-1865, המפרט היציב 2026-01-26 בריפו modelcontextprotocol/ext-apps). כלי מצביע ב-_meta.ui.resourceUri על משאב ui://, המארח מבקש אותו ב-resources/read, מריץ את ה-HTML ב-iframe מבודד, ומעביר לו את תוצאת הכלי ב-postMessage. השרת לא שולח ולא מקבל אף הודעה שמתחילה ב-ui/ — הן עוברות בין המארח לדף בלבד.

בלי ספרייה חדשה. mcp 1.28.1 אינו מכיר את ההרחבה בשם — התמיכה המובנית (mcp.server.apps) קיימת רק בשורת 2.x, שבה FastMCP נקרא MCPServer — אבל כל מה שההרחבה דורשת מהשרת כבר קיים בו: meta= על כלי ועל משאב, ו-mime_type= שמקבל את text/html;profile=mcp-app. הכול יושב ב-mcp_server/note_view.py, ו-tests/test_mcp_note_view.py מקבע דרך session אמיתי של הפרוטוקול, עם PostHog דלוק כמו בייצור, ששלושתם מגיעים ללקוח: שני מפתחות ה-_meta של הכלי ב-tools/list, וה-mimeType וה-_meta.ui על הפריט שבתשובה של resources/read — שם המארח קורא אותם. שדרוג של הספרייה שישנה אחד מהם יפיל את ה-CI ולא את התצוגה.

  • שני מפתחות על הכלי (tool_meta): _meta.ui.resourceUri של המפרט, וגם "ui/resourceUri" השטוח, שהמפרט מסמן כ-deprecated — כמו registerAppTool ב-SDK הרשמי (src/server/index.ts ב-ext-apps), כדי שמארח שעוד קורא רק את הישן יציג את התצוגה.

  • הכתובת נושאת את הגרסה של הדף — ui://codekeeper/note-view/<hash>.html, כש-<hash> הוא VERSION_HEX_CHARS התווים הראשונים של ה-SHA-256 של הדף כולו (build_note_view). המפרט מתיר למארח לשמור את הדף בקאש לפי הכתובת, וכתובת קבועה הייתה מגישה אחרי דיפלוי את הדף הקודם בלי שום עקבה בשרת. כך כל שינוי בשלד, בסגנון או בסקריפט משנה את הכתובת, בלי שמישהו יצטרך לזכור להעלות מספר.

  • וכל גרסה שפורסמה פעם נשארת קריאה (register_note_view): לצד המשאב של הכתובת הנוכחית, שמופיע ב-resources/list, יש תבנית (URI_TEMPLATE) שעונה על כל גרסה בצורה ש-build_note_view מייצרת — עם הדף הנוכחי. שיחה ישנה שטוענת מחדש את התצוגה שלה עם הכתובת שנרשמה אז לא נופלת על ”לא נמצא“ אחרי דיפלוי. ומכאן כלל למי שישנה את תשובת הכלי: הדף הנוכחי מקבל גם תוצאות שכלי ישן החזיר, ולכן שינוי בצורת התשובה חייב להשאיר את הדף מסוגל לקרוא את הצורה הקודמת.

  • הדף נבנה ברישום, לא בייבוא. build_mcp קורא ל-build_note_view, שקוראת את השלד (mcp_server/apps/note_view.html) ואת החלקים שב-STYLE_PARTS וב-SCRIPT_PARTS, ומכניסה אותם לתוך השלד, כל חלק עם שורת כותרת שנוקבת בשמו. החלקים הם הקבצים של התצוגה עצמה, ומהוובאפ — מנוע התצוגה של הפתק, הקבצים שהוא קורא מ-window והעיצוב שלו — כמו שהם, מ-webapp/static (השרת רץ מהריפו כולו). שלד בלי מקום אחד בדיוק לסגנון ולסקריפט, או חלק שמכיל את התגית שסוגרת את הבלוק שלו (</script / </style), עוצרים את עליית השרת ב-RuntimeError שנוקב בקובץ: אחרת הדפדפן היה סוגר את הבלוק באמצע, ושאר הקוד היה מוצג כטקסט. הסדר של החלקים מהוובאפ הוא הסדר שבו לוח הפתקים טוען אותם, כי בוובאפ אין סדר אחד: base.html טוען את markdown-enhanced.css אחרי הבלוק extra_css, כלומר אחרי העיצוב של הפתק בלוח, ובתצוגת קובץ Markdown העיצוב של הפתק נטען בגוף העמוד, כלומר אחריו. נמדד ב-15.11.2026 שזה לא משנה דבר היום, כי כל כלל ב-sticky-md-render.css תחום ב-.sticky-note וגובר בספציפיות. test_the_page_holds_every_part_in_the_order_the_board_loads_them גוזר את הסדר מהתבניות.

  • בלי מדיניות CSP משלו, בכוונה: אין csp ב-_meta.ui (RESOURCE_META). הדף אינו טוען שום דבר מבחוץ, ולכן הוא רץ תחת מדיניות ברירת המחדל הקשוחה שהמפרט מחייב (connect-src 'none'). דף שיצטרך משהו מבחוץ מצהיר עליו שם, ב-connectDomains או resourceDomains, ולא מרפה בשום מקום אחר. tests/test_mcp_note_view_browser.py מגיש את הדף עם המדיניות הזו בדיוק ובודק בדפדפן שהוא רץ בלי אף הפרה.

הדף (mcp_server/apps/note_view.js). הפרוטוקול כתוב ביד, בלי ה-SDK של ext-apps. המפרט אומר במפורש ש-SDK אינו נדרש, ומדריך ההגירה ל-2.x של ext-apps אומר שההודעות זהות בית-בבית בין הגרסאות. SDK היה מחייב באנדל שנבנה ביד ונשמר בגיט — בדיוק החוליה שנשכחת. כל צעד בקובץ מחקה את App של ה-SDK (src/app.ts, src/message-transport.ts, src/styles.ts), ומי שמשנה אותו בודק קודם מה ה-SDK עושה באותה נקודה.

  • מקור ההודעה נבדק לפני כל דבר (event.source === window.parent), כמו PostMessageTransport. הודעה ממסגרת אחרת נזרקת בלי קריאה בשדות שלה. וגם הדף מתחבר תמיד, בלי לשאול אם הוא בתוך מסגרת, כמו ה-SDK: ב-iOS וב-Android ‏Claude מציג את הדף ב-WebView ולא ב-iframe, ואיך window.parent נראה שם לא מתועד.

  • התוכן אינו מהימן. אין innerHTML בשום מקום: כל צומת נבנה עם createElement ו-textContent, וכל מה שמגיע מהמארח נבדק בצורתו לפני שקוראים בשדות שלו. הצבע של הפתק נכנס ל-CSS רק בצורה #rrggbb שהשרת מייצר (note_color_hex), וקוד שגיאה מוצג רק כשהוא בצורה של קוד.

  • שתי תקרות זמן משלו (INIT_DEADLINE_MS לתשובה ל-ui/initialize, ו-RESULT_DEADLINE_MS לתוצאת הכלי). הן אינן מחזיקות דבר: הן מחליפות את ”טוען…“ בהודעה שאומרת מה לא הגיע, ותשובה שמגיעה אחריהן עדיין מוצגת. פתק, תשובת שגיאה וביטול הם מצבים סופיים, וכל אחד מהם מבטל את התקרה.

  • שורת מקור אחת היא אלמנט אחד, ובלי dir: היא יורשת rtl מהדף, כמו בפתק בוובאפ. נמדד בוובאפ בכרום, עם sticky-notes.js וה-CSS שלו: בתיבת הטקסט ובתצוגת ה-Markdown כל שורה היא direction: rtl בלי תכונת dir, גם שורה שמתחילה באנגלית, והיא מיושרת לימין. unicode-bidi של תיבת הטקסט הוא normal, כלומר כל שורה היא פסקה בכיוון של הדף, בלי הכרעה לפי התוכן. dir="auto" במנוע של הפתק יושב רק על קוד בשורה ועל תאי טבלה (fillInlineCode ו-sticky-md-cell ב-sticky-md-render.js). עד 15.11.2026 כל שורה בתצוגה קיבלה dir="auto", ושורה שמתחילה באנגלית הוצגה משמאל. מאז שהתצוגה מרנדרת דרך המנוע (הסעיף הבא), אותן הכרעות חלות בה מעצמן.

  • ה-Markdown — אותו מנוע ואותו עיצוב כמו בפתק בוובאפ. הגוף מרונדר ב-StickyMdRender.render, מצב הקריאה בלבד של המנוע (המנוע כקובץ משותף: sticky-md-render.js): בלי היסטים, צ’קבוקס מושבת, ובלי כפתור העתקה. סימון של משימה מתוך התצוגה וכפתור ההעתקה מחוץ לתחום. העיצוב הוא sticky-md-render.css ו-markdown-enhanced.css כמו שהם, והנייר נושא את המחלקה sticky-note שהם תחומים בה. note_view.css מוסיף רק את מה ששייך לתצוגה: המכל של התוכן (.ck-body, במקום .sticky-note-tasks), הכותרת, הכפתורים והגובה. הנייר מצהיר color-scheme: light: הדף כולו light dark בשביל המשטח של המארח, ובערכה כהה של Claude הצ’קבוקס המושבת יצא אפור בהיר על הנייר.

  • קישור עובר דרך המארח, והדף לעולם אינו מנווט. כל לחיצה על קישור בפתק מבוטלת (preventDefault). כשהמארח מודיע hostCapabilities.openLinks, הלחיצה שולחת ui/open-link עם הכתובת שבפתק, אחרי בדיקה מול MD_SAFE_LINK של המנוע שבנה את הקישור. זה אותו אובייקט ש-render בדק לפני הרינדור, והבדיקה שם כוללת את כל מה שהתצוגה לוקחת מהמנוע (render ו-MD_SAFE_LINK), כך שבזמן הלחיצה אין קריאה שנייה של window. ב-Claude, בקונקטור מותאם, המשתמש מאשר בחלון לפני שהקישור נפתח (התיעוד של Claude, ”Open external links from MCP Apps“). כשהמארח אינו מודיע, הקישור אינו עושה דבר. בשני המקרים הכתובת מופיעה בריחוף (title). target="_blank" של המנוע לא היה נפתח במסגרת בלי allow-popups, וב-WebView של המובייל ניווט היה מחליף את התצוגה עצמה. בזמן ההמתנה לתשובה שום דבר אינו מוחזק: סירוב, ביטול או שגיאה משאירים את הקישור כמו שהוא.

  • ▲▼ לפי התוכן, ולא רק לפי המסגרת. בגובה הקבוע .ck-body אינו משנה גודל כשהתוכן שבתוכו גדל, למשל בלוק מתקפל שנפתח. ResizeObserver צופה גם ב-.ck-content, שעוטף את התוכן, ולכן הכפתורים מופיעים כשהבלוק נפתח ונעלמים כשהוא נסגר.

  • גודל הטקסט כמו בוובאפ, גם כשאנדרואיד מגדיל טקסט. WebView של אנדרואיד מכפיל כל גופן בגודל הגופן שנבחר במערכת (”By default, scale the text size by the system font scale factor“, AwSettings.java ב-Chromium, נקרא ב-15.11.2026), בזמן שהגובה הקבוע של התצוגה אינו גדל. לכן באפליקציה בטאבלט נכנסו פחות שורות, והטקסט נראה גדול מהפתק בוובאפ. ההכפלה נכנסת לגודל המחושב של הגופן (FontBuilder::GetComputedSizeFromSpecifiedSize), ו-getComputedStyle מחזיר את הגודל המחושב חלקי הזום של העמוד בלבד (ComputedStyleUtils::ValueForFontSize). measureTextScale ב-note_view.js מודד אותה על אלמנט מוסתר שמבקש TEXT_PROBE_PX ומצהיר text-size-adjust: auto, כך שהוא אינו יורש את הפיצוי, ומבטל אותה ב-text-size-adjust של 100% / יחס על html. בדסקטופ ובווב היחס 1, ושום דבר אינו מוצב. למה text-size-adjust ולא חלוקה של הגופנים: em נגזר מהגודל שלפני ההגדלה (CSSToLengthConversionData::FontSizes לוקח את SpecifiedFontSize(), ו-TextZoomFactor נכנס רק לגודל המחושב). חלוקה של font-size, כמו שהייתה עד 15.11.2026, מחזירה את הגופן לגודל של הוובאפ, אבל מקטינה באותו יחס כל ריווח של ה-Markdown, שכולם ב-em. text-size-adjust נכנס לאותה מכפלה כמו TextZoomFactor (באותה פונקציה ב-FontBuilder), ואינו נוגע בגודל המבוקש. WebView מכבד אותו כברירת מחדל (”The modern approach is for CSS to always honor text-size-adjust“, aw_settings.cc; קובצי Chromium נקראו בענף main ב-15.11.2026). WebView ישן, שבו התכונה חלה רק כשהאפליקציה בחרה TEXT_AUTOSIZING, מתגלה בבדיקה שאחרי ההצבה, והדף חוזר אז לחלוקה: היחס עובר כ---ck-text-scale, וכל font-size ב-note_view.css מחולק בו. test_every_font_size_in_the_view_undoes_the_system_text_zoom נכשל על font-size בקובץ שאינו עובר דרך החלוקה. test_the_system_text_zoom_is_measured_and_undone מגדיל בכרום את הטקסט ב-_TEXT_ZOOM דרך TextZoomFactor האמיתי: כש-scaleAllFontsIfNoMetaTextScaleTag דלוק, הוספה והסרה של <meta name="text-scale"> קובעות את הגורם מתוך הדף (Document::SetTextScaleMetaTagPresent). הבדיקה רצה פעם עם textSizeAdjustEnabled, כמו WebView מודרני, ופעם בלעדיו, כמו WebView ישן. עד 15.11.2026 ההגדלה בבדיקות הייתה דרך text-size-adjust עצמו, ומאז שהפיצוי עובר דרכו, אמולציה כזו הייתה מבטלת את עצמה. החלופה שלא נבחרה: <meta name="text-scale" content="scale"> (Chrome 146, לפי Chrome Status) מבטל את ההגדלה ב-WebView בלי מדידה (LocalFrame::SetTextZoomFactor). אבל זה עובד רק בגרסה שתומכת בתגית, ורק כשהדף שלנו הוא המסגרת הראשית של ה-WebView, ושתי העובדות האלה באפליקציה של Claude לא ידועות. המדידה עובדת בשני המקרים.

  • הדף שקוף, והפתק הוא ”נייר“ (mcp_server/apps/note_view.css). התיעוד של Claude מבקש מדף של MCP App לא לצבוע את html/body. הנייר בצבע של הפתק, והטקסט עליו קבוע, כמו בוובאפ: צבע שמגיע מערכת הנושא של המארח היה יוצא בהיר על בהיר בערכה כהה. מה שהמכל של התוכן בוובאפ (.sticky-note-tasks) נותן לתוכן הוא עותק כאן: הדיו של הגוף, ריווח השורות, שבירת השורות (white-space ו-overflow-wrap) וגודל הטקסט — הגודל של ברירת המחדל, NOTE_FONT_SIZE_DEFAULT (”גדול מאוד“), המינימום הקריא לפי החלטת המשתמש. וגם הגודל והמשקל של הכותרת, כמו .sticky-note-title. הדף אינו טוען את sticky-notes.css, ולכן test_the_view_copies_the_ink_spacing_and_default_size_of_a_webapp_note קורא את שני המקורות ומשווה. הדיו של הכותרת ושל פתק ריק אינם עותק: הם הטוקנים --note-ink ו---note-ink-muted מהעיצוב המשותף שבדף. בלי צבע תקין הנייר נשאר בצבעי המארח, ולא בעותק של הפלטה.

  • גובה קבוע, והגוף נגלל בתוכו. בתוך השיחה Claude חותך תצוגה שגבוהה מהתקרה שלו, ובמכשיר מגע גרירה אנכית שמתחילה בתוך התצוגה גוללת את השיחה ולא את התצוגה (עמוד ”Design guidelines“ בתיעוד של Claude, נקרא ב-15.11.2026: ”The host also caps inline height and clips content that exceeds it“, ו-”vertical pan gestures that start inside it go to the conversation scroll instead of to your content“). לכן הדף מגביל את עצמו: הגובה שלו הוא הקטן מבין --ck-cap, עותק של NEW_NOTE_H (הגובה של פתק חדש בוובאפ, החלטת המשתמש), לבין containerDimensions.maxHeight שהמארח מוסר. פתק קצר יותר מתקצר עד השורה האחרונה שלו. הנוסחה כתובה פעם אחת, ב-max-height של #ck-note-root ב-note_view.css, וה-JS רק מעביר אליה את הערך של המארח. test_the_fixed_height_of_the_view_is_the_height_of_a_new_webapp_note משווה את --ck-cap ל-NEW_NOTE_H. הגוף נגלל בגלגלת, ובכפתורים ▲▼ שמופיעים רק כשהפתק ארוך מהגובה. כל לחיצה מזיזה SCROLL_STEP_RATIO מהגובה הגלוי, ולא עמוד שלם, כדי שהשורות האחרונות שנקראו יישארו על המסך, וברכות: scroll-behavior: smooth ב-CSS, עם קפיצה למי שביקש במערכת פחות תנועה (prefers-reduced-motion). safeAreaInsets של המארח נכנסים כריפוד של #ck-note-root, והם פיזיים מטבעם (למעלה, ימין, למטה, שמאל), כי שורת ההודעה של Claude מכסה את התחתית בלי קשר לכיוון הטקסט.

  • מסך מלא, רק כשהמארח מציע אותו. הדף מצהיר על inline ועל fullscreen (APP_CAPABILITIES). כפתור ”מסך מלא“ מופיע רק כש-hostContext.availableDisplayModes כולל fullscreen והדף עוד לא שם, כפי שהמפרט מחייב לבדוק לפני הבקשה, ולחיצה עליו שולחת ui/request-display-mode. Claude מסרב לבקשה בלי לחיצה טרייה בדף, ולכן היא נשלחת רק מתוך הלחיצה. מסגרת בגובה קבוע (containerDimensions.height, כמו ש-Claude מוסר במסך מלא) מקבלת ck-fill: הפתק ממלא אותה, והגוף נגלל. מסך מלא שהמארח משאיר בגובה גמיש (maxHeight, כמו basic-host של ext-apps) מקבל ck-expanded: הגובה הקבוע הוא של התצוגה בתוך השיחה ואינו חל שם, והפתק גדל עד התקרה של המארח. ההקשר שהמארח שולח ב-host-context-changed חלקי, והדף ממזג אותו עם מה שכבר ידוע, כמו ה-SDK.

  • הגודל מדווח גם כשהמסגרת משתנה ולא התוכן. ResizeObserver על html ו-body רואה רק שינוי בתוכן. מסגרת שהמארח הגדיל מעל תוכן שלא השתנה אינה משנה אף אלמנט, והדף שתק. כך נראה ב-Claude, אחרי סגירה ופתיחה מחדש של האפליקציה, שטח ריק בין סוף הפתק להודעה הבאה, שנעלם רק כשהתצוגה נפתחה מחדש. נמדד בכרום על הקוד שלפני התיקון: מסגרת שהמארח הציב ל-700px מעל תוכן של 116px נשארה כך. מאז הדף מדווח את הגודל שלו תמיד בעלייה, בכל resize של החלון שלו (כלומר של המסגרת), ובכל הודעה על המסגרת או על מצב התצוגה, גם כשהמספר זהה לדיווח הקודם. אין כאן לולאה: מסגרת שכבר בגובה שדווח אינה משנה גודל, ולכן אינה יורה resize נוסף. אותו שינוי גם הקדים את ui/notifications/initialized לכל הודעה אחרת שהדף שולח אחרי לחיצת היד, כמו ב-SDK.

התשובה של הכלי (handlers.show_note) עוברת באותו שער של codekeeper_get_note (_readable_note), ואחריו באותה פונקציה שבונה את התשובה (_note_with_target), בלי השרשורים ובלי version. היא טקסט בלבד — JSON, כמו כל כלי בשרת, בלי structuredContent — והכלי מצהיר על תקרת התשובה כמו codekeeper_get_note (תקרת התשובה — מה כלי מצהיר, ומי אוכף), כדי ש-Claude Code יכניס פתק ארוך להקשר ולא ישמור אותו לקובץ. הוא עומד בה בלי חיתוך: גם פתק שכל שדה בו בתקרה ובתווים היקרים ביותר כ-JSON נכנס שלם (test_the_largest_possible_note_fits_the_declared_ceiling_whole). המפרט מחייב תשובה משמעותית גם כשיש תצוגה, כי את הטקסט קורא המודל ולקוח שאינו מציג תצוגה. ועמוד ה-quickstart של MCP Apps בתיעוד של Claude (נקרא ב-15.11.2026) מראה ש-Claude Code, כשהכלי מחזיר structuredContent, מוסר לסוכן את האובייקט הזה כמחרוזת במקום הטקסט — כך בפלט ה-stream-json של claude -p. הדף קורא את הפתק מבלוק הטקסט הראשון.

מה נבדק, ואיפה. tests/test_mcp_note_view.py — החוזה דרך הפרוטוקול, השער, הגרסה שבכתובת, הבנייה, ו-PostHog. האחרון בודק דרך החיווט של הייצור שגוף הפתק והדף אינם בשום אירוע שהיה נשלח. ‏``posthog.mcp`` (7.45.3) אינו עוטף את resources/read בשרת FastMCP 1.x, אבל הבדיקה אינה מניחה את זה. tests/mcp-note-view.test.js — הלוגיקה של הדף, דרך ההודעות בלבד, כמו מארח. tests/test_mcp_note_view_browser.py — הדף בדפדפן אמיתי, תחת ה-CSP של המפרט: הודעה מזויפת ממסגרת אחרת, הכיוון של כל שורה, גודל הטקסט, הרקע השקוף, ותוכן שאינו מריץ דבר. ה-Markdown מול פתק בלוח: test_the_markdown_looks_like_the_same_note_on_the_board מרנדר אוסף של כל סוגי ה-Markdown פעם בתצוגה ופעם בלוח, עם sticky-notes.js וה-blueprint האמיתיים, ומשווה את הסגנון המחושב של כל אלמנט, כולל ::before, ::after ו-::marker. ההשוואה רצה גם בערכה הכהה של המארח, וגם בהגדלת טקסט (_TEXT_ZOOM, דרך TextZoomFactor האמיתי). ההבדלים שמכוונים רשומים ב-_INTENDED עם הסיבה של כל אחד: הסמן, שבלוח מרמז על עריכה, והצ’קבוקס המושבת. כל אחד מהם חייב גם להופיע, אחרת הרשימה התיישנה. מאותה השוואה הגיעו color-scheme: light על הנייר והבסיס של sticky-md-render.css. ולצידה: קישור עם openLinks ובלעדיו, בלי ניווט ובלי ניסיון לפתוח חלון, ובלוק מתקפל שמביא את ▲▼. ומול מארח שמחיל כל דיווח גודל על המסגרת: פתק ארוך בגובה הקבוע ובכל רוחב, תקרה נמוכה של המארח, פתק קצר, הגלילה בגלגלת ובכפתורים, מסגרת ישנה שהמארח מציב, שתי הצורות של מסך מלא, והשוליים הבטוחים. מול המארח הרשמי — examples/basic-host של ext-apps (קומיט ea3e9d0e), מול השרת המקומי עם build_mcp של הייצור — הדף הוצג בערכה בהירה, והמעבר לכהה הוחל עליו. פתק ארוך הוצג שם בגובה הקבוע עם ▲▼, וכפתור ”מסך מלא“ הופיע ועבד. משם נמצא גם שהמארח הזה משאיר את הגובה גמיש במסך מלא, ומכאן ck-expanded. זו הייתה בדיקה ידנית, ולא בדיקה שרצה ב-CI.

איפה זה מוצג (התיעוד של Claude, נקרא ב-15.11.2026): תצוגה בתוך השיחה ב-claude.ai, ב-Claude Desktop ובאפליקציות ל-iOS ול-Android. המשתמש אימת אותה באפליקציה בטאבלט ב-15.11.2026, אחרי הדיפלוי. חלונית הצד קיימת רק בווב ובדסקטופ, ולא לכל החשבונות. על מסך מלא במובייל שני העמודים של Claude אינם מסכימים: עמוד העזרה ”Use interactive connectors in Claude“ אומר ש-”The side panel, full-site views, and opening or pinning interactive connectors from Claude’s navigation“ עוד אינם זמינים במובייל, ועמוד ”Design guidelines“ למפתחים מתאר מסך מלא במובייל (”On mobile, your app fills the entire screen with the chat input and navigation bar overlaid on top“). לכן הדף אינו מנחש לפי פלטפורמה: כפתור ”מסך מלא“ נשען רק על מה שהמארח מונה ב-availableDisplayModes, והגלילה בכפתורים עובדת בכל מקום. קונקטור שמשתמש מוסיף בעצמו, כמו שלנו, מקבל את אותו מסלול ריצה כמו קונקטור מהמדריך. אתר מוטמע — הוובאפ בתוך iframe — נבדק ונדחה בשלב הזה: לקונקטור מותאם הוא זמין רק לחלק מהארגונים, Claude לא מעביר לאתר סשן, וההתחברות דורשת עוגיות Partitioned ושינוי של frame-ancestors בוובאפ.

הקבועים, התקרות ואוצר המילים של התשובה

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

הקבוע

הערך

מה הוא מגביל

MAX_FILE_SIZE_FOR_DISPLAY

512,000

קריאה מלאה של קובץ. יושב ב-services/git_mirror_service.py ומשותף עם הוובאפ. וגם הקובץ השמור הגדול ביותר שנקרא לפי סעיף, בבתים של UTF-8; מעליו too_large_for_sections — ראו קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)

RANGE_READ_MAX_BYTES

10,485,760

קריאת טווח ואאוטליין, ב-mcp_server/repo_backend.py

OUTPUT_BYTE_BUDGET

256,000

תקציב הבתים של תשובה אחת, כפי שהיא נשלחת, ב-mcp_server/answer_size.py. כל כלי שמצהיר על תקרת תשובה עומד בו בעצמו — ראו תקרת התשובה — מה כלי מצהיר, ומי אוכף

DEFAULT_MAX_REQUEST_BYTES

1,048,576

גוף בקשה אחת במתודות שנושאות גוף, ב-mcp_server/limits.py. נגזר מ-MAX_CODE_SIZE (request_bytes_for) ולא מוקלד לצידו; ‏``MCP_MAX_REQUEST_BYTES`` מעלה אותו. ראו ”גבולות הבקשה“

DEFAULT_RATE_LIMIT_PER_MINUTE

40

קריאות כלים לזהות אחת בדקה, ב-mcp_server/limits.py; ‏``MCP_RATE_LIMIT_PER_MINUTE`` מכוון אותו. נבחר כך שהמכפלה בגרוע-לקריאה (WORST_CASE_CPU_SECONDS × _NOT_FOUND_CPU_FACTOR, מסלול ה-not-found) לא תעבור את מכסת המעבד — ראו ”גבולות הבקשה“

MAX_LINES

8,000

שורות בקובץ Markdown, ב-services/md_parser.py. נבדק לפני הפרסור; מעליו too_many_lines — ראו איזה קובץ docs_get_section קורא, ובאיזה ריפו. חל גם על קובץ שמור שנקרא לפי סעיף

MAX_TOKENS

45,000

טוקני בלוק בפרסור Markdown אחד, ב-services/md_parser.py. נבדק ברגע שנוצר כל טוקן; מעליו too_many_tokens — ראו איזה קובץ docs_get_section קורא, ובאיזה ריפו. חל גם על קובץ שמור שנקרא לפי סעיף

MAX_SECTION_CHARS

4,096

אורך section, בתווים, ב-mcp_server/docs_handlers.py. מעליו section_too_long לפני כל התאמה — ב-codekeeper_docs_get_section, ב-codekeeper_read_batch וב-codekeeper_get_file, כי הבדיקה יושבת בפונקציה שבונה את התשובה בשלושתם. המדידה שממנה הוא נגזר — ליד הקבוע; ראו איך docs_get_section מוצא כותרת

MAX_TITLE_CHARS

= MAX_SECTION_CHARS

אורך כותרת בודדת, בתווים, ב-services/doc_sections.py. כותרת ארוכה יותר נחתכת על גבול תו ומסומנת title_truncated בכל מקום שבו היא נפלטת. שווה ל-MAX_SECTION_CHARS ומקובע אליו בטסט, כדי שכותרת מקוצצת תתאים לשאילתה שמדביקה אותה — ראו איך docs_get_section מוצא כותרת

MAX_DEPTH_MIN · MAX_DEPTH_MAX

1 · = MAX_SECTIONS

max_depth של מפת הכותרות, ב-mcp_server/docs_handlers.py. נצמד ולא נדחה, ותשובה שנושאת מפה מהדהדת את הערך שנאכף. התקרה העליונה נגזרת ולא נבחרה: עומק אינו יכול לעבור את מספר הכותרות, ומעל MAX_SECTIONS (services/doc_sections.py) הפרסור מסרב — ולכן ההצמדה מלמעלה אינה מסתירה כותרת בשום קובץ, ורק קובעת את ההד. ראו איך docs_get_section מוצא כותרת

WORST_CASE_CPU_SECONDS

0.66

לא תקרה אלא מדידה: זמן המעבד של הפרסור הגרוע שנמצא תחת MAX_LINES ו- MAX_TOKENS, ב-services/md_parser.py. ממנו נגזרים DEFAULT_RATE_LIMIT_PER_MINUTE ו-DEADLINE_SECONDS, וטסט בודק את שני החשבונות

TREE_PER_PAGE_DEFAULT · TREE_PER_PAGE_MAX

200 · 1000

עמוד בעץ הקבצים

OUTLINE_PER_PAGE_DEFAULT · OUTLINE_PER_PAGE_MAX

100 · 500

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

REPOS_LIMIT_DEFAULT · REPOS_LIMIT_MAX

50 · 200

ריפואים ב-codekeeper_list_repos

SEARCH_RESULTS_DEFAULT · SEARCH_RESULTS_MAX

50 · 100

פגיעות ב-codekeeper_search_repo

CONTEXT_LINES_MAX

10

שורות ההקשר סביב פגיעה בחיפוש

SEARCH_COUNT_CEILING

100,000

התקרה שעד אליה codekeeper_search_repo סופר מופעים. יושב ב-services/git_mirror_service.py, כי הספירה היא של המנוע. מעליה אין total אלא total_at_least — ראו כמה מופעים יש באמת (total מול total_at_least)

GREP_COUNT_MAX_FILES

200,000

קבצים תואמים שמעבר הספירה קורא, ב-services/git_mirror_service.py. הגנה מפני פלט פתולוגי; אינו נגזר מ-max_results

QUERY_RESULTS_DEFAULT · QUERY_RESULTS_MAX · QUERY_CONTEXT_LINES_MAX

50 · 100 · 10

חיפוש בתוך קובץ שמור (codekeeper_get_file עם query). יושבים ב-mcp_server/handlers.py, ו**אותם ערכים בדיוק** כמו שלושת הקבועים המקבילים שמעליהם — repo_handlers מייבא מ-handlers, ולכן ייבוא הפוך היה מעגלי והם משוכפלים. tests/test_mcp_file_query.py משווה את שני העותקים וגם מעגן כל ערך למספר שכתוב בו. תקציב הבתים אינו ביניהם: שני החיפושים מייבאים את OUTPUT_BYTE_BUDGET מ-mcp_server/answer_size.py

QUERY_SNIPPET_MAX_BYTES

500

טקסט של רשומה אחת בתשובת query, בבתים. אותו מספר שחותך codekeeper_search_repo, ביחידה שנאכפת — ראו חיפוש בתוך קובץ שמור (query)

MAX_SYMBOLS

50,000

סימבולים לקובץ באאוטליין. יושב ב-mcp_server/outline_scanners/_ceiling.py

MAX_BATCH_ITEMS

20

פריטים בקריאה אחת של codekeeper_read_batch, ב-mcp_server/read_batch.py. נדחה ולא נצמד (too_many_items), ויורד עם מכסת הקצב כשהיא נמוכה ממנו (item_cap). ראו קריאה קבוצתית — codekeeper_read_batch

DEADLINE_SECONDS

10

שניות קיר לבאץ«, מהכניסה ל-call_tool, ב-mcp_server/read_batch.py. נבדק בין פריטים בלבד, ולמה זה מספיק — ב-קריאה קבוצתית — codekeeper_read_batch

DECLARED_MAX_RESULT_CHARS

256,000

_meta["anthropic/maxResultSizeChars"] של כל כלי שמצהיר על תקרת תשובה, ב-mcp_server/answer_size.py. הוא OUTPUT_BYTE_BUDGET עצמו: בתים כתקרת תווים, ולמה זה בטוח — ב-קריאה קבוצתית — codekeeper_read_batch

MAX_EDIT_PAIRS

50

זוגות בקריאה אחת של codekeeper_multi_edit_file, ב-mcp_server/handlers.py. נדחה ולא נחתך (too_many_edits), כי באץ« שנחתך היה מחיל חלק מהעריכות ומדווח הצלחה. במכסת הקצב הקריאה שוקלת 1, בכל מספר של זוגות. ראו כמה עריכות בגרסה אחת — codekeeper_multi_edit_file

FILE_DESCRIPTION_MAX_CHARS

500

אורך description של קובץ, בתווים ולא בבתים, ב-file_description.py שבשורש. נאכף על תיאור שנמסר מבחוץ, ולעולם לא על תיאור שמועתק לגרסה חדשה: codekeeper_update_file_description דוחה (description_too_long), ו-codekeeper_save_file שומר את הקובץ בלי התיאור (description_saved: false). תיאורי הפרמטר description בשני הכלים נבנים ממנו ברישום. ראו עדכון תיאור בלי גרסה חדשה ו-תיאור ארוך בשמירה — description_saved

UPLOAD_TTL_SECONDS

600

כמה זמן העלאה של PUT /api/agent/upload ממתינה לצריכה, בשניות, ב-mcp_uploads.py. נכתב ל-expires_at של ההעלאה, ואינדקס ה-TTL מוחק בו (expireAfterSeconds=0). התיאור של upload_id נוקב בדקות, ונגזר ממנו. ראו העלאת תוכן בלי לעבור דרך המודל

MAX_PENDING_UPLOADS

5

העלאות חיות למשתמש בו-זמנית, ב-mcp_uploads.py. מעליו too_many_pending_uploads (429) עם הזמן עד שהישנה ביותר פוקעת. ראו העלאת תוכן בלי לעבור דרך המודל

כל קבוע שהטבלה אינה נוקבת במודול שלו יושב ב-mcp_server/repo_handlers.py, ליד ה-handler שאוכף אותו.

אזהרה

ערך מעל התקרה נצמד בשקט, ואינו נדחה. per_page=1000 באאוטליין מקבל 500, ואין בתשובה שדה שמצהיר שזה קרה — מה שכן יש הוא per_page שחוזר בתשובה, והוא הערך שנאכף, ולכן זה מה שכדאי להשוות אליו ולא למה שנשלח. per_page=0 נצמד ל-1 ולא לברירת המחדל.

ומה שאינו מספר שלם אינו מגיע להצמדה בכלל — הוא נדחה בסכימה. נמדד מול הסכימה של הכלי: ערך עם שבר (2.5), null, ומחרוזת שאינה מספר נדחים לפני שהכלי רץ; מחרוזת מספרית ("250") ומספר עשרוני שלם (2.0) עוברים ומומרים. ובוליאני עובר ונעשה 1, בלי שגיאה: per_page=true מחזיר עמוד של רשומה אחת. זו אותה המרה ש-lines חוסם ב-strict — ראו את ההערה ב-קריאת טווח שורות — וכאן היא אינה חסומה. פרמטר שמוצהר StrictInt — context_lines ו-max_depth, למשל — דוחה בסכימה גם את "2", את 2.0 ואת true, ומה שעובר אותה נצמד כרגיל.

ההצמדה היא מדיניות מוצהרת (_clamp ב-mcp_server/handlers.py) ולא מקריות: דחייה על כל ערך מחוץ לטווח הייתה מכשילה קריאה שלמה בגלל פרמטר עימוד. התקרה על הגודל דווקא כן דוחה, וההבדל מכוון — עמוד שאינו נכנס בתקציב הבתים חוזר כ-page_too_large ולא נחתך בשקט. וכך גם מספר הפריטים בבאץ«: codekeeper_read_batch עם יותר מ-MAX_BATCH_ITEMS פריטים נדחה ב-too_many_items ולא נחתך, כי באץ« שנחתך בשקט היה מחזיר פחות ממה שביקשו, בלי לומר אילו פריטים חסרים. ובאותו אופן codekeeper_multi_edit_file עם יותר מ-MAX_EDIT_PAIRS זוגות נדחה ב-too_many_edits: באץ« עריכות שנחתך היה שומר חלק מהעריכות ומדווח הצלחה.

אוצר המילים של התשובה, ושתי המשפחות אינן מתערבבות. status מתאר הצלחה, error מתאר סירוב, וב**תשובת כלי** error מגיע תמיד עם "ok": false. תשובת HTTP של השרת עצמו אינה תשובת כלי ואינה נושאת את השדה — 401 על טוקן פסול, למשל, הוא {"error": "invalid_token"} לבדו, עם הכותרת WWW-Authenticate. ל-status יש בתשובת כלי רשימה סגורה: ok, outline, query, toc, section, binary, too_large ו-no_outline. גם ל-mode בתשובה מוצלחת של codekeeper_docs_get_section יש רשימה סגורה: toc, section ו-document (הקובץ כולו, whole_document=true). ל-error אין רשימה כזאת כאן בכוונה — הערכים נגזרים מהכלי שסירב (path_denied, outline_and_lines, query_and_lines, page_too_large, range_out_of_bounds ועוד רבים), ורשימה חלקית שנראית סגורה גרועה מאין רשימה. ערך status חדש שיתווסף לקוד מתווסף גם כאן. משפחה אחת בכל זאת מתוארת במקום אחד, כי ההבדל בין הקודים שלה הוא כל הערך שלהם: מה כלי הריפו עונים כשהקריאה לא מגיעה לקובץ — invalid_ref, ref_not_mirrored, not_found (שנושא את ref ואת resolved_commit), repo_not_mirrored ו-read_failed. ראו ענף שלא במראה, מול קובץ שלא קיים.

``truncation_reason`` אינו אף אחד מהשניים. הוא אינו מתאר הצלחה ואינו מתאר סירוב, אלא למה תשובה מוצלחת אינה שלמה — ולכן הוא מופיע רק כאשר truncated הוא true, ולעולם לא כ-null בתשובה תקינה. הערכים: max_results (התוצאות נחתכו בתקרה שביקשו), byte_budget (העמוד לא נכנס בתקציב הבתים — בחיפוש, בעמוד של סעיף ב-codekeeper_docs_get_section וב-codekeeper_get_file, ובעמוד של מסמך ב-codekeeper_docs_get_section עם whole_document=true), count_ceiling ו-count_output_limit (הספירה נעצרה בתקרה), count_failed (הספירה לא הסתיימה — קוד יציאה, או error: ב-stderr גם כשהקוד תקין), matches_per_file (התקרה של ההתאמות לכל קובץ), policy_filtered (שורה הוסרה במדיניות הסודות), search_failed (המנוע נפל אחרי שכבר אסף תוצאות — הן מוגשות, ואינן שלמות), timeout, output_limit ו-process_killed. כשהספירה היא זו שנקטעה, הסיבה שלה גוברת — כי היעדר total הוא מה שדורש הסבר, ואילו חיתוך התוצאות כבר משתמע מ-count שקטן מ-total_at_least.

``unread_reason`` אינו ``truncation_reason``, ובכוונה. תשובה של codekeeper_read_batch אינה חתוכה: כל פריט בה שלם, ומה שחסר בה הוא פריטים שלמים שלא נכנסו או שלא הגיעו אליהם בזמן. לכן אין בה truncated, והסיבה נקראת בשם אחר — unread_reason, שמופיע רק לצד unread (האינדקסים שלא נקראו) ולעולם לא בלעדיו. שני הערכים שלו לקוחים מאותו אוצר מילים: byte_budget ו-timeout. ראו קריאה קבוצתית — codekeeper_read_batch.

content_sha256 ו-content_changed אינם status ואינם error. content_sha256 הוא שדה של file, בכל תשובה של codekeeper_get_file, ובתשובה של כלי כתיבה — רק כשהקריאה החוזרת הצליחה; ובפתקים הוא שדה של note (פתקים: note.content_sha256 ו-content_changed). גם הסירוב conflict של כלי העריכה נושא אותו, של הגרסה הנוכחית (עריכה על מה שקראתם — expected_content_sha256). content_changed מופיע רק בתשובת כתיבה מוצלחת, ויש לו שלושה ערכים: false; true, ואז לצידו content_diff; ו-null, כשהקריאה החוזרת לא הצליחה — הכתיבה עצמה כן קרתה, אבל file מינימלי ובלי content_sha256, ובפתק note נושא רק id (וזה קורה רק ביצירה). ראו טביעת אצבע לתוכן — content_sha256 ו-content_changed. מאותה משפחה file.is_latest: שדה של file, רק בקריאה לפי file_id ב-codekeeper_get_file — בכל מצבי הקריאה ובסירובים שנושאים file — עם true, false, null כשאי אפשר לקבוע (השאילתה נכשלה, או תיקו על המספר העליון), ובלי השדה כשהגרסה בסל. ראו האם זו הגרסה האחרונה — is_latest.

description_saved גם הוא לא זה ולא זה: שדה של תשובת codekeeper_save_file מוצלחת שנשלח אליה תיאור, באותם שלושה ערכים: true, false ו-null. מה מגיע לצד כל ערך — ובפרט מתי false נושא את שדות התקרה ומתי לא — בטבלה ב-תיאור ארוך בשמירה — description_saved.

הערה

codekeeper_get_file הוא היחיד שנושא status רק לפעמים, וזה מכוון: הוא מעולם לא נשא את השדה, ולכן קריאה רגילה וקריאת טווח מחזירות היום בדיוק את מה שהחזירו קודם. status: "query" מופיע אך ורק כשהועבר query, ומסמן שהתשובה נושאת מופעים ולא תוכן; status: "toc" ו- status: "section" — אך ורק עם toc=true או section, ומסמנים מפה או סעיף במקום התוכן (קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)).

אימות והרשאות

שני מסלולים, מאוחדים באותו שרת:

  1. OAuth 2.1 — עבור Claude.ai (Custom Connector). זרימה מלאה: רישום לקוח דינמי (DCR) + PKCE + מסך אישור. הזהות נקבעת דרך התחברות הטלגרם בוובאפ. המחבר שייך לחשבון, ולכן מגיע גם ל-Claude Desktop ול-Claude Code שמחובר עם החשבון (חיבור לקוחות).

  2. טוקן אישי (PAT) — עבור Claude Code שלא מחובר עם החשבון ב-claude.ai (Claude Code (טוקן)), ועבור ההוק שטוען את הפריימר. מונפק מהבוט בפקודת /connect_claude (או /connect_claude write לטוקן עם הרשאת כתיבה), נשמר כ-hash בלבד וניתן לביטול.

שכבות ההרשאה:

  • read — ברירת המחדל לכל חיבור.

  • write — נדרש לכל כלי שמשנה נתונים; ניתן רק באישור מפורש (מסך ההרשאה ב-Claude.ai או טוקן write מהבוט).

    הערה

    מה נחשב ”כלי כתיבה“ נקבע במטא-דאטה של הכלי, לא ברשימת שמות. ‏``_declares_write`` ב-mcp_server/server.py קורא את readOnlyHint שהכלי כבר מצהיר עליו, ו-require_write נקרא בשורה הראשונה של גוף הכלי. רשימת שמות הייתה מקום שני לסנכרן, והכלי שנוסף בשבוע הבא הוא בדיוק זה שהיה נשמט ממנה — בלי שגיאה ובלי בדיקה שנופלת. הטבלה שלמעלה מסמנת את כלי הכתיבה ב-כתיבה:, והיא תיעוד של המצב ולא המקור שלו.

  • אדמין — כלי הריפו זמינים רק למשתמשים שב-ADMIN_USER_IDS; לכל אחד אחר הם גם לא מופיעים ברשימת הכלים וגם נחסמים בקריאה ישירה (fail-closed). זה חל גם על שלושת כלי פתקי הריפו, אף שהם אינם נוגעים ב-mirror. codekeeper_create_repo_note הוא הכלי היחיד שעובר שני שערים, ובסדר הזה: אדמין ואז כתיבה. בסדר ההפוך משתמש רגיל היה מקבל ”צריך הרשאת כתיבה“ — רמז שטוקן אחר יפתח לו את הכלי, וזה אינו נכון.

  • codekeeper_search_notes אינו כלי אדמין, אף שהוא מוצא גם פתקי ריפו: הוא מסונן ל-user_id של הקורא ולכן יכול להחזיר רק פתקים שלו, ומשתמש רגיל אינו יכול ליצור פתק ריפו מלכתחילה.

  • codekeeper_get_note גם הוא אינו כלי אדמין — אבל פתק ריפו חסום בו לאדמין בדיוק כמו ב-codekeeper_list_repo_notes, רק שהשער נסגר בשקט: מי שאינו אדמין מקבל not_found, אותה תשובה כמו לפתק של מישהו אחר ולמזהה שאינו קיים, כך שהסירוב אינו מגלה שהמזהה קיים (require_admin היה זורק admin_only ומגלה). הבדיקה נעשית לפי סוג הפתק, לפני שתוכן כלשהו חוזר. ראו קריאת פתק בודד — codekeeper_get_note.

  • codekeeper_comment_note אינו כלי אדמין, ועובר באותו שער — _readable_note ב-mcp_server/handlers.py, פונקציה אחת לשני הכלים — לפני כל כתיבה. כך ”מי שאינו יכול לקרוא פתק אינו יכול להגיב עליו“ נכון מבנית. ראו שרשורי תגובות על פתקים — codekeeper_comment_note.

  • codekeeper_show_note אינו כלי אדמין, ועובר באותו שער — _readable_note — ואחריו באותה פונקציה שבונה את התשובה של codekeeper_get_note (_note_with_target). כך הפתק שהתצוגה בתוך Claude מציגה הוא בדיוק הפתק שהקריאה מחזירה. ראו תצוגה בתוך Claude — MCP App.

ראוטים שמאמתים בעצמם. במצב OAuth ה-SDK עוטף רק את ה-mount של /mcp, וראוט שנרשם ידנית מוגש בלי אימות — ולכן כל ראוט כזה קורא ל-authenticate_bearer בגוף שלו, עם אותו מאמת של הטרנספורט:

tests/test_mcp_uploads.py מחזיק כל ראוט רשום ל-401 בלי טוקן, בשני המצבים, חוץ מרשימה סגורה ומפורשת: /healthz, נקודות ה-OAuth של ה-SDK ועמוד ההסכמה. ראוט חדש ששוכח לאמת מפיל אותו.

תקרת התשובה — מה כלי מצהיר, ומי אוכף

הבעיה (#3460). Claude Code שומר לקובץ תשובת כלי שעוברת את הסף שלו — 25,000 טוקנים כברירת מחדל (MAX_MCP_OUTPUT_TOKENS) — ומכניס להקשר רק הפניה לקובץ. כלי יכול להעלות את הסף של עצמו, עד 500,000 תווים, ב-_meta["anthropic/maxResultSizeChars"] שהוא מצהיר ב-tools/list (code.claude.com/docs/en/mcp.md, ”Raise the limit for a specific tool“, נקרא ב-2026-09-29). עד #3460 רק codekeeper_read_batch הצהיר, ולכן קובץ עברי של 52,158 תווים ב-13 שורות, שנקרא ב-codekeeper_get_repo_file, הגיע לסוכן כקובץ ולא כטקסט — אף שהתשובה עצמה הייתה רחוקה מכל תקרה של השרת.

ההצהרה היא חלק מהרישום של הכלי. כלי שמצהיר מעביר meta=answer_size.declared_size_meta() ל-mcp.tool(...), ו-FastMCP.list_tools שולח ללקוח את אותו meta בדיוק (_meta=info.meta, mcp 1.28.1). אין רשימת שמות בצד: הרשת שלמטה קוראת את התקרה מאותו מקום. מצהירים codekeeper_get_file, codekeeper_get_repo_file, codekeeper_search_repo, codekeeper_list_repo_tree, codekeeper_list_notes, codekeeper_list_board_notes, codekeeper_get_note, codekeeper_show_note, codekeeper_docs_get_section ו-codekeeper_read_batch, וכולם על אותו ערך, DECLARED_MAX_RESULT_CHARS — tests/test_mcp_answer_size.py מקבע את הרשימה ובודק, דרך session אמיתי של הפרוטוקול עם PostHog דלוק, שמה שהלקוח רואה הוא הרישום ולא שום דבר אחר. ``codekeeper_list_repo_notes`` אינו מצהיר, בכוונה: MAX_NOTES_PER_REPO_FILE פתקים של MAX_NOTE_CHARS תווים כל אחד הם 20 × 20,000 = 400,000 תווים, כלומר לפחות 400,000 בתים — יותר מהתקציב — ואין לכלי מצב רזה שאפשר להפנות אליו. להצהיר על תקרה שהכלי אינו יכול לעמוד בה, או לסרב לו בלי דרך אחרת לקרוא, גרוע מלהשאיר אותו כמו שהוא.

למה בתים, ומה נמדד. הערך המוצהר הוא OUTPUT_BYTE_BUDGET (256,000) עצמו, ובכוונה: הלקוח סופר תווים, והתשובה נחסמת ב**בתים** של הטקסט כפי שהוא נשלח. בכל טקסט UTF-8 מספר התווים אינו עולה על מספר הבתים — וגם לא מספר יחידות ה-UTF-16 שבהן JavaScript סופר אורך — ולכן תשובה שחסומה בבתים לעולם אינה עוברת את מה שהוצהר. הפוך זה לא עובד, וגם מדידה דחוסה אינה חסם: _convert_to_content של ה-SDK שולח pydantic_core.to_json(..., indent=2), וההזחה, ה-escaping והמעטפת מתווספים אחרי מדידה של json.dumps או של str(). כל המדידה יושבת ב-mcp_server/answer_size.py — wire_json היא בדיוק הקריאה של ה-SDK — מודול בלי תלויות פנימיות, כך שכל מודול שמודד תשובה מייבא ממנו ולא מחזיק עותק; tests/test_mcp_answer_size.py אוכף את זה על כל מודול בחבילה — בלי מספר מוקלד, בלי שם שני לאותו ערך, ובלי לקרוא אותו דרך מודול אחר שבמקרה מייבא אותו. מה עושים כשתשובה אינה נכנסת יושב במודול אחד מעליו, mcp_server/answer_fit.py: הליבה של כל סירוב answer_too_large (too_large), השגרה האחת ששני כלי קריאת הקובץ ופריט קובץ בבאץ« עוברים בה (fit_read), טווח השורות (fit_line_range), והחיתוך של רשימות ושל מחרוזות בהקשר (fit_lists, fit_refusal). טוקנים אינם נמדדים כאן בכלל.

התקציב הוא הבטחה של השרת, לא של הלקוח. OUTPUT_BYTE_BUDGET הוא מה שהשרת מתחייב לא לעבור, ולכל לקוח יש תקרה משלו על תשובת כלי, שעשויה להיות נמוכה ממנו. ההצהרה ב-anthropic/maxResultSizeChars מתועדת כמנגנון של Claude Code, שקורא אותה ומתאים את עצמו לפיה; לקוח אחר אינו מחויב לה, ולכן תשובה שנכנסת בתקציב שלנו עדיין עלולה להיחתך או להישמר לקובץ אצלו. בקבצים גדולים, ובמיוחד בעברית, הדרך היציבה היא מפת הכותרות ואז סעיף אחד (toc ואז section ב-codekeeper_get_file, או codekeeper_docs_get_section בריפו), או טווח שורות ב-lines — ולא קריאה מלאה.

כל כלי שמצהיר עומד בתקרה בעצמו, במקום שבו הוא יודע מה לקצר ומה לומר:

כלי ומצב

כשהתשובה אינה נכנסת

codekeeper_get_file / codekeeper_get_repo_file, קריאה מלאה

answer_too_large עם bytes (התשובה שהייתה נשלחת, נמדדת), max, file בלי התוכן, ו-hint: lines; בקובץ Markdown שמור גם toc/section; בריפו גם outline, ו-read_with/read_with_arguments כשכלי התיעוד מגיש את הקובץ — עם whole_document: true, כלומר הקובץ כולו שם, מדופדף (איזה קובץ docs_get_section קורא, ובאיזה ריפו)

אותם שני כלים, lines

הטווח נגמר מוקדם על גבול שורה, עם range.truncation_reason: "byte_budget" — ראו קריאת טווח שורות

codekeeper_get_file, query

פחות רשומות, עם truncation_reason: "byte_budget" — ראו חיפוש בתוך קובץ שמור (query)

codekeeper_get_repo_file, outline

page_too_large — ראו מפת סימבולים (outline)

codekeeper_list_repo_tree

page_too_large, והעמוד אינו נחתך, עם hint ל-per_page קטן יותר — ראו גודל וספירת שורות ברשימת הריפו

codekeeper_search_repo

פחות שורות, עם truncation_reason: "byte_budget" — גם כשהמנוע עצמו נעצר ב-max_results, כי מה שקיצר את העמוד הוא התקציב, והגדלת max_results לא הייתה עוזרת. סיבה של הספירה (timeout, count_*) עדיין גוברת, כי היא מסבירה את ה-total החסר

codekeeper_list_notes / codekeeper_list_board_notes

answer_too_large עם hint ל-include_content=false ואז codekeeper_get_note. הקריאה מהמסד נעצרת כשהתקציב עבר, ולכן bytes כאן הוא כמה נצבר עד שם — חסם תחתון, וגדול מ-max. סירוב ולא חיתוך, כי לכלים האלה אין עימוד: פתק שנחתך מהרשימה לא היה נגיש בשום דרך. וגם הרשימה הרזה נמדדת — היא נכנסת כל עוד התקרה הרכה על מספר הפתקים לא נפרצה, ומעבר לזה ה-hint מפנה ל-codekeeper_search_notes

codekeeper_get_note

הפתק תמיד חוזר; מה שאינו נכנס הוא שרשורי התגובות שאחריו. שרשור שאינו נכנס עם תגובותיו מוצג מקופל, עם המזהה שלו, והתשובה נושאת comments_truncated ו-threads_hint שמפנה ל-thread_id — ראו שרשורי תגובות על פתקים — codekeeper_comment_note

codekeeper_docs_get_section, ומצב הסעיפים של codekeeper_get_file

עמוד שנגמר מוקדם, רשימות שנחתכות מהסוף, section_too_large ו-answer_too_large — ראו איך docs_get_section מוצא כותרת

codekeeper_read_batch

unread ו-item_too_large — ראו קריאה קבוצתית — codekeeper_read_batch. פריט קובץ עובר את אותה התאמה של הכלי הבודד, ולכן התשובה שלו זהה לו בית-בית

המטא-דאטה של קובץ שמור אינה חוסמת את הקובץ. כל תשובה על קובץ שמור נושאת את file, ותיאור או תגיות ענקיים מגדילים אותה בלי קשר למה שביקשו. הסירוב עצמו מוותר קודם על התגיות, מהסוף (file.tags_truncated), ואחר כך על התיאור, שלם, ובמקומו file.description_bytes (ראו קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)). וגם תשובה מוצלחת — backend._fit_with_file_meta, בכל צורה של codekeeper_get_file: קריאה מלאה, lines, query, toc ו-section. תשובה שנכנסת כמו שהיא לא משתנה בבית אחד. תשובה שבלי התגיות, ואם צריך גם בלי התיאור, נכנסת שלמה — חוזרת כך. כשהתוכן עצמו גדול מהתקציב, התשובה עם המטא-דאטה נשארת (טווח שנגמר מוקדם, עמוד שנחתך), אלא אם היא סירוב — המטא-דאטה לא השאירה מקום אפילו לשורה אחת — או שהמטא-דאטה גדולה מכל שאר התשובה; אז חוזרת התשובה בלעדיה. תיאור קצר רחוק מאוד משני התנאים, ולכן קריאת המשך רגילה של קובץ גדול אינה משתנה. כל תשובה שהתיאור ירד ממנה — מוצלחת או סירוב — נושאת ב-hint את backend._DESCRIPTION_LEFT_OUT, שמפנה ל-codekeeper_update_file_description: סירוב שמפנה לצורה אחרת של אותו כלי, שנתקלת באותו תיאור, הוא מעגל, וזה מה שקרה עד ריוויו Han על #3492 (תיאור של 200,000 תווים נעל את הקובץ בכל הצורות, ו-lines הפנה ל-query שהפנה ל-lines). השורש, כותבים שאינם אוכפים תקרה על התיאור ועל התגיות, ב-#3489.

לקוח שאינו מכבד את ההצהרה מקבל אותה תשובה בדיוק: קריאה מלאה מעל התקציב היא answer_too_large עם הפניה, ולא התשובה כולה. זה מכוון — תשובה של 400KB לא הייתה שמישה גם אצלו, והסירוב לפחות אומר מה לעשות — ומתאפשר רק כי מטא-דאטה לבדה כבר אינה סיבה לסירוב (הפסקה שלמעלה).

הרשת — ההגנה האחרונה, לא הפתרון. AdminAwareFastMCP.call_tool מעביר כל תשובה של כלי דרך _within_declared_size, בשני הענפים שלו (הרגיל, והענף של codekeeper_read_batch). היא קוראת את התקרה מה-meta של הכלי שנקרא, מודדת את כל מה שיוצא — כל בלוק תוכן ו-structuredContent, ולא רק הבלוק הראשון — ותשובה שעוברת את מה שהוצהר מוחלפת בסירוב: {"ok": false, "error": "answer_too_large", "bytes": ..., "max": ..., "hint": "..."}, עם hint כללי שמבקש פחות. תשובה בצורה שאי אפשר למדוד — סירוב גם היא (fail-closed). כלי שאינו מצהיר אינו נמדד כאן. כשהרשת תופסת משהו בפרודקשן, זה באג בכלי, לא ”המערכת עבדה“: כל כלי שמצהיר מתאים את עצמו, עם הפניה שמתאימה לו, והרשת אינה יודעת לומר דבר מזה. כל תפיסה נרשמת בלוג כ-WARNING עם הסמן הקבוע answer_size_net, שם הכלי והמספרים בלבד — בלי הארגומנטים ובלי התשובה. ב-PostHog היא אינה נראית: $mcp_tool_call נלכד מתחת לרשת (PostHog עוטף את ToolManager.call_tool), ולכן הוא רושם את התשובה של הכלי ולא את הסירוב; הלוג הוא המקום לחפש.

וכל חיתוך או סירוב של תקציב — נרשם. בלי זה לא היה אפשר לדעת אם OUTPUT_BYTE_BUDGET צר מדי לתהליך נפוץ, אלא מתלונות של סוכנים. call_tool פותח answer_fit.recording סביב גוף הכלי; answer_fit.too_large וכל חיתוך ב-byte_budget (answer_fit.cut — טווח, query, חיפוש, עמוד סעיף, עמוד מסמך, מפה, unread בבאץ«) כותבים לתוכו, ובסוף הקריאה נכתבת שורת INFO אחת עם הסמן answer_size_fit: שם הכלי, שמות הארגומנטים, והמספרים; למשל, בטווח שנגמר מוקדם: answer_size_fit: codekeeper_get_file args=[file_name, lines] byte_budget returned=<שורות שחזרו> of=<שורות שביקשו>. לעולם לא ערך של ארגומנט ולא התשובה (K13): ערך יכול להיות שם קובץ, שאילתה או טקסט של פתק. תשובה שנכנסת אינה משאירה שורה. גוף של כלי קריאה רץ בחוט עובד, והפנקס מגיע אליו כי asyncio.to_thread מעתיק את ה-Context — tests/test_mcp_logging_visible.py בודק את זה בתהליך נקי, דרך call_tool ובכלי שרץ בחוט עובד, ולא ב-caplog (שמחבר handler משלו ועובר בלי קשר למה שהתהליך מדפיס). נרשם רק מה שהלקוח קיבל — הכלל כתוב ליד answer_fit.attempt: מי שבונה תשובה שעוד עשויה להיזרק בונה אותה בניסיון משלו, שעובר לפנקס רק כשהיא יוצאת. לכן חיתוך או סירוב בתשובה שנזרקה — ניסיון ש-_fit_with_file_meta זרק, פריט באץ« שהוחלף ב-item_too_large או עבר ל-unread, תשובה שהרשת החליפה — אינו בשורה, והסירוב של הרשת כן, לצד ה-WARNING answer_size_net שלה. tests/conftest.py (answer_fits_match_what_was_sent) אוכף את זה על כל call_tool בטסטים: כל answer_too_large בפנקס הוא סירוב שנשלח, וכל חיתוך בפנקס נושא סימן בתשובה.

והערך המוצהר נבדק ברישום. AdminAwareFastMCP.add_tool מסרב לרשום כלי שמצהיר על משהו שהלקוח לא יכבד — ערך שאינו מספר שלם, בוליאני, אפס או פחות, או מעל 500,000 (CLIENT_CEILING_CHARS) — ב-TypeError שנוקב בשם הכלי, והשרת אינו עולה. כלי שנרשם בדרך שעוקפת את add_tool עדיין מוחזק לתקרה שלו, כי הרשת קוראת אותה בזמן הקריאה ולא בזמן הרישום.

גבולות הבקשה — גודל הגוף והקצב

עד #3431 המידלוור היחיד בשרת היה האימות: כל משתמש מאומת יכול היה לשלוח בקשות בכל גודל ובכל תדירות. תקרת האורך ל-path של codekeeper_docs_get_section (#3428) חסמה הגברה בבקשה בודדת, ולא נגעה לא במספר הבקשות ולא בשאר הכלים. היום יש שני גבולות, כל אחד בשכבה שמתאימה לו, ושניהם חיים ב-mcp_server/limits.py.

גודל גוף הבקשה — במידלוור ASGI, לפני שהטרנספורט מפענח JSON. הטרנספורט של ה-SDK קורא את הגוף כולו ומפענח אותו לפני שאף כלי רואה ארגומנט, ולכן התקרה הזאת היא הגבול היחיד על כל ארגומנט של כל כלי, קיים ועתידי. התקרה נגזרת ולא מוקלדת: הארגומנט הלגיטימי הגדול ביותר הוא code של codekeeper_save_file, שחסום ב-MAX_CODE_SIZE (תווים), ולקוח שמקודד JSON עם ensure_ascii הופך כל תו עברי לשישה בתים; request_bytes_for ב- mcp_server/limits.py מחשב MAX_CODE_SIZE × 6 ועוד מעטפת של 64KiB (שם הכלי, שם הקובץ, שפה, ותיאור בתקרתו) ומעגל כלפי מעלה ל-MiB שלם — על ברירת המחדל של התצורה זה 1MiB. השירות גוזר את הערך בעלייה מהתצורה שהוא באמת רץ איתה (max_code_size()), כך שהעלאת MAX_CODE_SIZE לעולם אינה משאירה את התקרה מאחור, וטסט בונה את בקשת השמירה הגדולה ביותר (קובץ עברי בגודל המקסימלי, בקידוד היקר) ומודד שהיא נכנסת.

מה נקרא ומה לא, ולמה זה חשוב. התקרה מסתכלת רק על מתודות שנושאות גוף (POST, ‏``PUT``, ‏``PATCH``); GET ודומיה עוברות כמות שהן, ולכן Content-Length מזויף על GET /healthz אינו 413 (עד סקירת שבעת ה-PRים הוא כן היה, מול uvicorn אמיתי). Content-Length תקין — ספרות בלבד, כמו ש-h11 מקבל — שמצהיר על יותר מהתקרה נדחה לפני שנקרא בית אחד; תקין ומתחת לתקרה, בלי Transfer-Encoding לצידו, עובר בלי שהמידלוור קורא בית, כי השרת (uvicorn/h11) תוחם את הגוף לאורך המוצהר ואי אפשר להעביר דרכו יותר — נמדד. מה שנשאר לספירה הוא גוף בלי אורך מוצהר (chunked, או Content-Length לצד Transfer-Encoding, ששם h11 תוחם לפי chunked): הוא נקרא עד התקרה, וכל הלולאה תחת דדליין של 30 שניות (DEFAULT_BODY_READ_SECONDS), כי ל-uvicorn אין timeout לגוף בקשה וההמתנה לנתח הבא הייתה אחרת בלתי חסומה. הסירוב נוקב בסיבתו, באותה צורה של ה-401 של האימות, ונושא Connection: close — הוא הגיע לפני שהגוף נגמר, ואין טעם להמשיך לקרוא אותו:

{"error": "body_too_large", "max_bytes": 1048576, "content_length": 20971520}
{"error": "body_read_timeout", "read_timeout_seconds": 30.0, "received_bytes": 4096}

במצב PAT האימות נשאר מחוץ לתקרה (בקשה בלי טוקן היא 401 גם כשהיא ענקית). במצב OAuth התקרה היא השכבה החיצונית ברמת האפליקציה, והאימות של ה-SDK יושב בתוך ה-mount של /mcp: אורך מוצהר מעל התקרה נדחה לפני שנבדק אישור כלשהו, ואורך מוצהר תקין עובר בלי קריאה, כך שה-401 של ה-SDK עדיין מגיע בלי שנקרא בית מהגוף. זו הייתה רגרסיה של #3431 (SEC-001 בסקירת שבעת ה-PRים): הגרסה הראשונה קראה כל גוף אנונימי עד התקרה לפני ה-401 — נמדדו 5 קריאות receive() לפני התשובה על גוף של חמישה נתחים, גם עם אורך מוצהר — ובלי דדליין. היום: 0 קריאות לאורך מוצהר, וגוף chunked אנונימי, המקרה שנשאר, חסום בתקרה ובדדליין.

קצב — לפי זהות, בנקודת השיגור של הכלים. הזהות שאפשר לספור לפיה קיימת במידלוור רק במצב PAT; במצב OAuth (הייצור) ה-SDK מאמת בתוך /mcp, והמקום היחיד שרואה את הזהות בשני המצבים הוא קריאת הכלי עצמה. לכן המגביל יושב ב-call_tool של AdminAwareFastMCP — המתודה שה-SDK רושם כמטפל של tools/call, כלומר נקודה אחת שכל קריאת כלי עוברת בה — ומכריע לפני שגוף סינכרוני נמסר לחוט מהמאגר ולפני שגוף אסינכרוני רץ על הלולאה: קריאה שנדחתה אינה עולה עובד, ומה שאינו קריאת כלי (initialize, ‏``tools/list``) אינו נספר — חוץ מהעלאה: PUT /api/agent/upload נספר מאותה מכסה, דרך אותו מופע של המגביל, ולכן העלאה והשמירה שצורכת אותה הן שתי קריאות (העלאת תוכן בלי לעבור דרך המודל). הוא בנוי מעל rate_limiter.RateLimiter — אותו חלון מתגלגל של דקה שהבוט משתמש בו, בזיכרון ובלי Redis, וזה מספיק כי השירות רץ במופע אחד — הגדרה של השירות ב-Render (numInstances: 1), מחוץ לריפו; מי שמוסיף מופע מאבד את הזיכרון המשותף, וזה המקום להתחיל ממנו. ברירת המחדל היא DEFAULT_RATE_LIMIT_PER_MINUTE קריאות בדקה לזהות, ומאיפה המספר: הטענה שהוא שומר עליה היא שזהות אחת אינה עוברת את מכסת המעבד של השירות, גם כשכל הקריאות שלה הן הקלט היקר ביותר. המכסה היא 0.5 מעבד, כלומר 30 שניות-מעבד בדקה — והיא של כל השירות, לא של זהות: החשבון הזה מגן מפני זהות אחת שממלאת את המכסה לבדה, ולא מפני כמה זהויות במקביל, שכל אחת מוסיפה עומס משלה. מה שמחזיק אותו כטענה על השירות הוא numInstances: 1 (מופע יחיד וחלון מתגלגל בזיכרון). והקלט היקר ביותר אינו הפרסור לבדו: מסלול ה-not-found של toc/section מפרסר, בונה את מפת הכותרות, מריץ suggest (חסום ב- doc_sections.SUGGEST_WORK_BUDGET) ומתאים לתקציב הבתים. נמדד שהוא עולה פי _NOT_FOUND_CPU_FACTOR מהפרסור בלבד (WORST_CASE_CPU_SECONDS ב- services/md_parser.py, שם הקלט, המדידה והתאריך). החשבון: 40 × 0.73 = 29.2 שניות-מעבד בדקה, מתוך 30. ‏``tests/test_md_parse_worst_case_claims.py`` גוזר אותו מהקבועים ונופל כשהוא נשבר, והשורה הזאת נבדקת שם מול אותם קבועים. עד #3391 המגבלה הייתה 60, והיא נגזרה מהמסמך הצפוף האמיתי (0.47 שניות מעבד; שישים קריאות שלו הן 28 שניות) — כי הקלט העוין של אז לא היה חסום בכלל, ושישים קריאות שלו היו פי כמה מהמכסה. עם התקרות הוא חסום, ו-60 היה משאיר אותו מעל המכסה: טענה שצריך להסביר במקום לבדוק. עמוד RST של 500KB עולה 0.24 שניות עם תקרת הסקשנים (נמדד ב-#3431), וקריאה רגילה (10–50ms) הופכת את המגבלה לאחוזים בודדים מהמכסה. הטענה חלה על כל קריאה שמפרסרת, ולא רק על codekeeper_docs_get_section: גם codekeeper_get_file עם toc או section מפרסר קובץ אחד לקריאה, תחת אותן תקרות, ו-section חסום ב-MAX_SECTION_CHARS כדי שההתאמה לא תתווסף על הפרסור (ראו איך docs_get_section מוצא כותרת). הסירוב הוא תשובת כלי רגילה, עם הזמן שנותר עד שהחלון משתחרר:

{"ok": false, "error": "rate_limited", "limit_per_minute": 40, "retry_after_seconds": 17}

באץ« נשקל כמספר הפריטים שלו. codekeeper_read_batch עם N פריטים עולה N קריאות מהמכסה, כי כל פריט הוא קריאה ופרסור בדיוק כמו קריאה בודדת — אחרת באץ« היה דרך לעקוף את המכסה פי MAX_BATCH_ITEMS. שלושה דברים קורים ב-call_tool לפני שדבר נקרא. רגע הכניסה נרשם, והדדליין של הבאץ« נמדד ממנו. רשימה ריקה ורשימה מעל התקרה נדחות לפני השקילה (missing_items, too_many_items), כך שבקשה שלעולם לא תעבור שומעת את הסיבה שלה, ולא rate_limited עם זמן המתנה שלא יעזור. זה נעשה רק לאדמין: מי שאינו אדמין נשקל כקריאה אחת ומסורב בגוף הכלי ב-admin_only, בלי ללמוד את התקרה של כלי שהוא אינו רואה. והשקילה היא הכל או כלום: באץ« שאינו נכנס כולו במכסה נדחה כולו, לפני שפריט אחד נקרא, ו-retry_after_seconds הוא הזמן עד שכל המשקל נכנס. check_rate_limit ו-seconds_until_allowed של RateLimiter מקבלים weight, וברירת המחדל 1 משאירה את הבוט בדיוק כמו שהיה. התקרה של הכלי, MAX_BATCH_ITEMS, קטנה מ-DEFAULT_RATE_LIMIT_PER_MINUTE כדי שבאץ« מלא יוכל לעבור בכלל, וכשהמכסה בפריסה נמוכה ממנה — התקרה יורדת איתה (item_cap). פריטים שלא נקראו אינם מוחזרים למכסה; הנימוק ב-קריאה קבוצתית — codekeeper_read_batch.

באץ« של עריכות נשקל 1, ולא כמספר הזוגות. codekeeper_multi_edit_file קורא את הקובץ פעם אחת מהמסד ושומר פעם אחת, והזוגות הם פעולות על מחרוזת בזיכרון — זו לא עבודה שהמכסה נועדה לספור, בניגוד לפריט של codekeeper_read_batch, שהוא קריאה ופרסור. לכן אין לו ענף ב-call_tool, והגבול על הבאץ« הוא MAX_EDIT_PAIRS בגוף הכלי. ראו כמה עריכות בגרסה אחת — codekeeper_multi_edit_file.

הפטור לנתיב הדופק — שני חצאים, ורק אחד מהם מבני. מהמגביל /healthz פטור במבנה: הוא אינו קריאת כלי ולכן לעולם אינו מגיע למגביל. זו המלכודת שמתוארת ב-blanket-policy-silent-block §7 — מגבלה גורפת שמחזירה 429 למוניטור החיצוני ומכריזה על שירות בריא כמנותק — והיא נסגרת כאן על ידי המבנה. מתקרת הגוף הוא פטור בכלל, לא במבנה: GET אינה מתודה שנושאת גוף, ולכן התקרה אינה מסתכלת עליה — עד סקירת שבעת ה-PRים היא כן הסתכלה, ו-GET /healthz עם Content-Length מזויף מעל התקרה ענה 413. שני החצאים מקובעים בטסטים על האפליקציה האמיתית, בשני מצבי האימות: מאה דגימות של /healthz תחת מגבלה של קריאה אחת בדקה מחזירות מאה 200, ו-GET /healthz עם אורך מזויף מחזיר 200.

מה נרשם בלוג. בעלייה — שורה אחת עם שני הגבולות שנקבעו, ובסופה מכסת ההעלאות הממתינות ומשך החיים שלהן; סירוב על גודל או על הדדליין — WARNING עם הסיבה, המספרים והנתיב (לא הגוף ולא הטוקן); סירוב על קצב — WARNING אחד לזהות לחלון, כדי שסוכן שממשיך לדפוק לא יהפוך את הלוג לתור. וסירובי המכסה אינם נספרים ב-PostHog: המדידה עוטפת את _tool_manager.call_tool של ה-SDK, וההכרעה על המכסה קורית לפניו, ולכן קריאה שסורבה אינה נראית שם כלל; וגם סירוב שכן עובר במדידה (תשובת {"ok": false, ...} מגוף כלי) נרשם כהצלחה, כי is_error מסומן רק על חריגה. האות היחיד על סירובי מכסה הוא ה-WARNING ההוא, שאי אפשר לסכם. ההחלטה מפורטת באישו #3442, ושם גם מה שנשאר לעצב.

כיוון. ‏``MCP_MAX_REQUEST_BYTES`` ו-MCP_RATE_LIMIT_PER_MINUTE (‏``0`` מכבה במפורש, עם WARNING). שניהם נקראים ב-create_app — בכניסה לשירות, לא בזמן ייבוא — וערך שאינו מספר מחזיר את ברירת המחדל עם WARNING; בשום מסלול טעות תצורה אינה הופכת לגבול רחב יותר. ``MCP_MAX_REQUEST_BYTES`` אינו kill switch, וזו החלטה סגורה (YAGNI-002 בסקירת שבעת ה-PRים): 0 אינו מכבה אותו — הרצפה של 65,536 בתים חלה — והוא קיים כדי להעלות את התקרה בלי דיפלוי כשבקשה לגיטימית נדחית ב-body_too_large, למשל אחרי שכלי יקבל ארגומנט גדול מ-MAX_CODE_SIZE. הדדליין על גוף בלי אורך מוצהר (30 שניות) אינו ניתן לכיוון מהסביבה: אין לו קורא שמצדיק זאת.

פריימר לסוכן — GET /api/agent/primer

אנדפוינט HTTP רגיל (לא כלי MCP) שמחזיר טקסט חופשי שהסוכן קורא בפתיחת סשן. הוא חי על שירות ה-MCP, לא על הוובאפ:

https://<MCP-HOST>/api/agent/primer

לדוגמה: https://codekeepermcp.onrender.com/api/agent/primer.

אימות. אותו Authorization: Bearer <token> של שאר השירות — PAT מהבוט (/connect_claude) או טוקן OAuth. בלי טוקן תקין: 401.

תשובה. text/plain; charset=utf-8, לא JSON — הגוף נקרא על ידי המודל כפי שהוא. הוא מורכב מהחלקים הבאים:

  1. שדה ”הוראות לסוכן“ מעמוד ההגדרות בוובאפ (/settings) — עיקר התוכן.

  2. שורת מצב קצרה שנבנית בזמן אמת: שלושת הקבצים האחרונים שנשמרו ומתי.

  3. שורת מצב שנייה, כשיש: הפתקים שמחכה בהם תגובה לסוכן — שרשור פתוח (שרשורי תגובות על פתקים — codekeeper_comment_note) שהתגובה האחרונה בו של המשתמש, כלומר גם תשובה שלו לסוכן וגם שרשור חדש שהוא פתח כדי לבקש משהו. שרשור שסוכן ענה בו אחרון אינו בשורה, כדי שהיא לא תמשיך להציק אחרי שטיפלו בו. לכל פתק: הכותרת (או תחילת הגוף, לפתק בלי כותרת), איפה הוא יושב (לוח, קובץ, קובץ בריפו, או ”בארכיון“), וה-note_id — משם הסוכן ממשיך ל-codekeeper_get_note עם part="threads". עד PENDING_THREADS_COUNT פתקים, החדש ביותר קודם, ואחריהם ”ועוד N“. פתק שנמחק אינו נספר, ופתק ריפו — רק לאדמין, אותו שער של codekeeper_get_note. העברה לארכיון סוגרת את השרשורים הפתוחים של הפתק (ארכיון: היעד הרביעי), ולכן פתק בארכיון מופיע כאן רק אם המשתמש הגיב בו שוב אחרי ההעברה.

התנהגות

פירוט

200

יש הוראות. הגוף = הוראות + שורות המצב (קבצים, אם יש; תגובות שממתינות, אם יש).

204

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

401

אין טוקן, או שהטוקן בוטל/פג.

תקרת 24KB

חריגה גורמת לחיתוך + שורה שמודיעה על כך; לעולם לא שגיאה, כי פריימר חתוך עדיף על פריימר חסר. שורות המצב מקבלות מקום שמור ולא נדחפות החוצה — ולכל אחת תקציב משלה: MAX_STATUS_BYTES לשורת הקבצים ו-MAX_PENDING_STATUS_BYTES לשורת התגובות. כותרות פתקים ושמות לוחות הם קלט משתמש, ותקציב משותף היה נותן לכותרות ארוכות לדחוף את שורת הקבצים החוצה. שורת התגובות נבנית פריט אחרי פריט, כל שם בה מקוצר ל-PENDING_LABEL_CHARS תווים, ולכן note_id לעולם אינו נחתך באמצע ו“ועוד N“ סופר בדיוק את מה שלא הוצג.

כשל בשורת מצב

שורות המצב הן תוספת, וכשל בקריאה שלהן אינו מפיל את ההוראות: הגוף מוגש (200) בלי השורה שנכשלה (_load_primer_sync ב-mcp_server/primer.py). בשורת התגובות שני סוגי הכשל נרשמים אחרת: כשל של המסד — WARNING (וכשל רק בשמות הלוחות או הקבצים מציג את השורה בלעדיהם); כל חריגה אחרת היא באג, ונרשמת ב-ERROR עם traceback מלא, כדי שבאג לא ייראה בלוג כמו תקלת מסד.

Cache

60 שניות לכל משתמש (Cache-Control: private, max-age=60). שינוי בהגדרות מתחיל להשפיע תוך דקה. וכך גם תגובה: תגובה שנכתבה לפני פחות מדקה עלולה לא להופיע בסשן שנפתח מיד אחריה. התגובות שהשורה מציגה הן של המשתמש, והן נכתבות בוובאפ — שירות אחר, שאינו יכול לנקות את ה-cache הזה — וההחלטה היא לקבל את הדקה: אין סשן שנפתח בתוך דקה מתגובה ומפסיד בגלל זה משהו של ממש.

סינון סודות

כל הגוף עובר צנזור של דפוסים שנראים כמו מפתח (ghp_, ckmcp_, sk-, JWT, KEY=... וכו«) לפני ההחזרה — גם אם הודבקו לשדה בטעות. ערכי משתני סביבה של השרת אינם נכנסים לגוף כלל. בשורת התגובות כל שם עובר את הסינון לבדו ולפני שהוא מקוצר: קיצוץ קודם היה יכול לחתוך טוקן באמצעו ולהשאיר את תחילתו קצרה מכדי להיות מזוהה.

התקרה וה-TTL הם קבועים בקוד ולא משתני סביבה, במכוון: התקרה אינה כוונון תפעולי אלא תקציב מול חלון ההקשר של המודל. אילו היה משתנה סביבה, מצב הכשל של העלאתו היה בלתי-נראה — הקשר נאכל בשקט בלי שאף אחד מתריע. שינוי דורש PR.

הערה

הראוט מאמת בגוף שלו, ולא מסתמך על כך שהאפליקציה מוגנת. במצב OAuth ה-PATAuthMiddleware אינו מותקן כלל, וה-SDK עוטף רק את ה-mount של /mcp — ולכן ראוט שנרשם ידנית (כמו /healthz) מוגש ללא אימות. כל ראוט חדש שאסור שיהיה ציבורי חייב לקרוא ל-authenticate_bearer בעצמו. ראו mcp_server/auth.py.

ההוק בפתיחת סשן — בפלאגין. ההוק שמושך את הפריימר יושב בפלאגין codekeeper-memory, בריפו amirbiron/codekeeper-plugin: הסקריפט codekeeper-memory/hooks/session_start.sh, hooks/hooks.json שמריץ אותו, הטסטים שלו וה-CI שמריץ אותם. מי שמוסיף את הפלאגין לחשבון ב-claude.ai מקבל את ההוק בכל סשן של Claude Code, בכל ריפו, גם בסשן שרץ בדפדפן. מי שרוצה את הפריימר רק בריפו אחד יכול להעתיק את ההוק לריפו במקום להתקין את הפלאגין — אבל לא את שניהם (התיבה למטה). ההוראות למשתמש בכרטיס ”הוראות לסוכן“ ב-/settings.

מה ההוק עושה, בקצרה. בהצלחה הוא מדפיס את גוף הפריימר בלבד, וב-204 הוא שותק. בכל כשל אחר הוא מדפיס שורת אבחון אחת שמתחילה ב-[CodeKeeper], ל-stdout: stdout של הוק SessionStart נכנס להקשר של המודל, ו-stderr של הוק שיוצא ב-0 לא מגיע ל-Claude בכלל (התיעוד של hooks ב-Claude Code, נקרא ב-28 באוקטובר 2026). על 502, 503, 504 ועל כשל רשת זמני הוא מנסה שוב בתוך תקציב, כי לשירות ה-MCP מחובר דיסק, ודיפלוי שלו מחזיר 502 לכדקה. על מה עוד הוא מנסה שוב ועל מה לא, המספרים, והחשבון מול ה-timeout של ההוק — ב-README של הפלאגין, ליד הטסטים שמצמידים אותם לסקריפט. כאן אין להם עותק, כי שום טסט בריפו הזה לא היה שומר עליו.

חשוב

הפלאגין נטען גם בסשן שרץ בדפדפן, ולכן ההוק לא יושב בריפו הזה. פלאגין שמופעל בחשבון ב-claude.ai מסונכרן לקונטיינר של הסשן (CLAUDE_CODE_SYNC_PLUGINS=1, תחת ~/.claude/plugins/synced/), וההוק שלו רץ כמו בטרמינל. SKIP_PLUGIN_MARKETPLACE=true עדיין מוגדר שם, אבל הוא חוסם רק התקנה מהמרקטפלייס, ולא את הסנכרון מהחשבון. ב-13 באוגוסט 2026 הפלאגין עוד לא הגיע לסשן כזה, ולכן עד אז ההוק ישב ב-.claude/ של הריפו הזה (codekeeper-plugin#3). ב-27 באוקטובר 2026 הוא כבר הגיע. זו התנהגות של הפלטפורמה ולא חוזה יציב.

עותק נוסף בריפו מכפיל את הפריימר. Claude Code מריץ את ה-hooks של פלאגין לצד אלה של .claude/settings.json ואינו מאחד ביניהם (התיעוד של hooks ב-Claude Code), כך שכל אחד מהם מדפיס את הפריימר בנפרד. כך קרה בריפו הזה ב-27 באוקטובר 2026: בפתיחה מחדש של סשן, שני hooks החזירו את אותו פריימר במלואו. זו הסיבה שההוק הוסר מכאן.

כשהפריימר לא מגיע ואין שום הודעה. כל כשל של ההוק מדפיס שורת [CodeKeeper], ולכן שתיקה היא 204, או הוק שלא רץ בכלל. אם ~/.claude/plugins/synced/*/codekeeper-memory/ חסרה, הפלאגין לא הגיע לסשן: כש-CLAUDE_CODE_SYNC_PLUGINS ריק, הפלטפורמה חזרה להתנהגות הקודמת; אחרת הפלאגין כבוי בחשבון. ListPlugins ו-CLAUDE_PLUGIN_ROOT אינם מדד: שניהם ריקים גם כשהפלאגין נטען. הפירוט: codekeeper-plugin#4.

עריכה מהדפדפן

/settings → הכרטיס ”הוראות לסוכן“. השדה מציג מונה בייטים חי ומתריע כשמתקרבים לתקרה (מ-21KB) וכשחוצים אותה — כדי שחריגה תיתפס בכתיבה, ולא רק דרך שורת חיתוך שמופיעה בגוף שרק הסוכן קורא.

האחסון (48KB תווים) רחב מההגשה (24KB) בכוונה: החיתוך הוא החלטה של ההגשה ולא של האחסון, כדי שלא יימחק טקסט שהמשתמש כתב. הסודות נשמרים כפי שהם ומסוננים רק בהגשה — אחרת המשתמש היה פותח את ההגדרות ומוצא ***REDACTED*** בלי לדעת מה נמחק לו.

אזהרה

הוק שמושך את הפריימר בפתיחת סשן צריך להצביע על ה-MCP host. הצבעה על הוובאפ מחזירה 404, ואם ההוק שותק בכל כשל — הוא ייכשל לנצח בלי לומר מילה. הבחינו בין 204 (אין פריימר — שתיקה נכונה) לבין 404/401 (תקלה — ראוי להשמיע קול פעם אחת).

העלאת תוכן בלי לעבור דרך המודל

הבעיה. codekeeper_save_file ו-codekeeper_append_file מקבלים את התוכן בתוך קריאת הכלי. כשהתוכן כבר קיים כקובץ שהסוכן עצמו יצר — דוח, ניתוח, handoff — הסוכן קורא את כל הקובץ להקשר ואז כותב את כולו שוב בתוך הקריאה: משלם פעמיים על אותם בתים, ובמסמך ארוך מסתכן בקיטוע או בסחיפה בהעתקה. פרמטר של נתיב מקומי אינו פתרון: השרת רץ על Render, והקובץ יושב בקונטיינר של הסוכן.

הזרימה — שלושה צעדים, ואף אחד מהם אינו מעביר את התוכן דרך המודל:

  1. הסוכן מעלה את הקובץ בקריאת curl אחת, עם ה-PAT שכבר נמצא בסביבה שלו — אותו CODEKEEPER_PAT שהוק הפריימר משתמש בו (פריימר לסוכן — GET /api/agent/primer):

    curl -sS -T report.md -H "Authorization: Bearer $CODEKEEPER_PAT" https://<MCP-HOST>/api/agent/upload
    
  2. השרת מאמת, בודק, שומר את הטקסט לזמן קצוב, ומחזיר JSON קטן:

    {"upload_id": "…", "bytes": 28213, "chars": 16540, "content_sha256": "…", "expires_in_seconds": 600}
    
  3. הסוכן קורא ל-codekeeper_save_file(file_name=..., upload_id=..., description=..., language=...) בלי code — או ל-codekeeper_append_file(file_name=..., upload_id=...) בלי content. הכלי מוחק את ההעלאה, ורק אז שומר.

ה-hash-ים — בשמירה ובהוספה זה לא אותו דבר. ב-codekeeper_save_file הקובץ הוא ההעלאה, ולכן ה-sha256sum המקומי של הסוכן, content_sha256 בתשובת ההעלאה ו-file.content_sha256 אחרי השמירה הם hash אחד (טביעת אצבע לתוכן — content_sha256 ו-content_changed). ב-codekeeper_append_file רק שני הראשונים שווים: file.content_sha256 הוא של הקובץ כולו אחרי ההוספה, ומה שמראה שהטקסט נכנס בשלמותו הוא content_changed: false. תיאור הפרמטר upload_id נותן לכל כלי את המשפט שלו (_UPLOAD_HASH_AFTER_SAVE ו-_UPLOAD_HASH_AFTER_APPEND ב-mcp_server/server.py); בגרסה הראשונה המשפט היה משותף, והבטיח גם בהוספה את מה שנכון רק בשמירה. ההעלאה מחשבת את ה-hash באותה פונקציה של file.content_sha256 (_content_sha256 ב-mcp_server/backend.py), והתוכן נשמר בדיוק כמו שנשלח: שום נרמול בראוט ושום נרמול בצריכה — ‏BOM נשאר תו, כמו שהוא נשאר ב-code.

מה זה נותן, ומה לא. ההעלאה חוסכת את הבתים בהקשר ואת ההעתקה. היא אינה מעלה את תקרת התוכן: max_code_size() חל על תוכן שהגיע ב-upload_id בדיוק כמו על code — גם בראוט, שדוחה מוקדם, וגם בכלי. ב-codekeeper_append_file התקרה חלה על הקובץ כולו אחרי ההוספה, ולכן גם פיצול להוספות אינו עוקף אותה. לתוכן ארוך מהתקרה יש שתי דרכים: לפצל לכמה קבצים, או לשלוח אותו לבוט כמסמך — הוא יישמר כקובץ גדול (large_files), שכלי ה-MCP אינם קוראים.

מתי לא. בלי bash, בלי רשת או בלי CODEKEEPER_PAT — Claude.ai, למשל — שולחים code כרגיל. תיאור הפרמטר upload_id אומר זאת לסוכן, ונוקב בפקודה עם ה-host של השירות כשהוא ידוע מ-MCP_SERVER_URL (ו-<mcp-host> כשלא, וגם כשהערך שהוגדר נדחה — ואז עם WARNING בעלייה; ראו פתרון תקלות); הדקות בתיאור נגזרות מ-UPLOAD_TTL_SECONDS, והתקרה בתיאור code — מ-max_code_size() ברישום, כלומר מהתצורה שהשירות רץ איתה.

למה הראוט אינו דורש ``write``. ה-PAT שבסביבת Claude Code משרת את הפריימר ומונפק כ-read (/connect_claude בלי ארגומנט). דרישת write בראוט הייתה מחייבת PAT של כתיבה במשתני הסביבה של כל סשן — נגיש לכל הוק, סוכן-משנה וסקריפט בקונטיינר, וממנו אפשר לשלוח tools/call ישר ל-/mcp. הראוט רק מחזיק טקסט לזמן קצוב; שום דבר לא מגיע לקבצים של המשתמש בלי codekeeper_save_file או codekeeper_append_file, שדורשים write מטוקן הקונקטור, ובלי שה-user_id של ההעלאה שווה לזה של מי שצורך אותה. זה נבדק בצריכה, ולא מונח.

הראוט — PUT /api/agent/upload

אחיו התאום של הפריימר, ב-mcp_server/uploads.py. הסדר קבוע, וכל מה שאינו צריך את הגוף בא לפני קריאתו: אימות ← מגבלת הקצב ← מכסת ההעלאות הממתינות ← מוכנות האחסון ← הגוף, תחת דדליין ← פענוח ← שמירה. הגוף הוא בתים ותו לא: Content-Type אינו נקרא ואינו נדרש.

תשובה

מתי

201

נשמר. {"upload_id", "bytes", "chars", "content_sha256", "expires_in_seconds"}

401 invalid_token

בלי טוקן, או טוקן פסול. בשני מצבי האימות זה ה-401 של הראוט עצמו

429 rate_limited

המכסה של הזהות נגמרה. אותה מכסה של קריאות הכלים: המגביל נבנה פעם אחת ב-build_app ועובר גם ל-call_tool וגם לראוט, ולכן העלאה והשמירה שצורכת אותה הן שתי קריאות מתוך DEFAULT_RATE_LIMIT_PER_MINUTE. נושא limit_per_minute ו-retry_after_seconds

429 too_many_pending_uploads

למשתמש כבר MAX_PENDING_UPLOADS העלאות שעוד לא נצרכו ולא פקעו. נושא max ו-retry_after_seconds — הזמן עד שהישנה ביותר פוקעת

503 upload_storage_unavailable

אינדקס ה-TTL לא אומת, או שהמסד לא ענה. בלי TTL מאומת ”חמש העלאות“ הוא חסם על הנייר והתוכן נשאר לצמיתות, ולכן fail-closed — ראו האחסון למטה

408 body_read_timeout

הגוף לא הגיע בתוך DEFAULT_BODY_READ_SECONDS. גוף עם אורך מוצהר תקין עובר את BodySizeLimitMiddleware בלי שנקרא — השרת תוחם אותו — ולכן אין לו שום תקרת זמן מלבד זו של הראוט. אותה מילה ואותם שדות של המידלוור

413 body_too_large

אורך מוצהר מעל תקרת הגוף. של המידלוור, והראוט אינו רץ בכלל — ראו ”גבולות הבקשה“

400 empty_upload

גוף ריק

400 invalid_utf8

הבתים אינם UTF-8 תקין. פענוח קפדני — utf-8 ולא utf-8-sig

413 code_too_large

יותר תווים מ-max_code_size(), עם max. אותה פונקציה ואותה מילה של codekeeper_save_file, רק מוקדם יותר

כל סירוב נושא ``Connection: close``. נמדד על uvicorn 0.38.0: אחרי סירוב שנשלח לפני קריאת הגוף השרת ממשיך לקרוא ולזרוק את מה שהלקוח שולח, והחיבור נשאר פתוח שניות; עם close הוא נסגר מיד. אוצר המילים הוא של תשובות HTTP של השירות — {"error": ...} בלי ok, כמו ה-401 של האימות ו-body_too_large — וכל מילה שיש לה מקבילה בתשובות הכלים היא אותה מילה.

upload_id בכלים

code: str = "" ו-content: str = "" — ולא str | None — לצד upload_id. לתוכן ריק כבר יש סירוב, ולכן ”לא נשלח“ ו“נשלח ריק“ מקבלים אותה תשובה, וקריאה עם code בלבד מתנהגת בדיוק כמו קודם. בדיוק אחד מהשניים:

תשובה

מתי

code_and_upload_id · content_and_upload_id

נשלחו גם תוכן וגם upload_id. שם הקוד הוא שם הפרמטר של הכלי, כמו empty_code ו-empty_content

empty_code · empty_content

לא נשלח אף אחד מהשניים. ה-hint מזכיר את upload_id

invalid_upload_id

המזהה אינו בצורה שהראוט מייצר. הערך אינו מוחזר

upload_not_found

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

upload_storage_unavailable

אחסון ההעלאות לא ענה. שום דבר לא נכתב

upload_corrupted

הטקסט שנשלף אינו מה שהגיע: ה-hash שלו שונה מ-content_sha256 שנשמר עם ההעלאה, או שמה שנשמר אינו hash. נבדק מיד עם השליפה, ולכן זו התשובה גם כשבדיקה אחרת של הכלי הייתה נכשלת. שום דבר לא נכתב, וההעלאה נמחקת — ואם האחסון לא ענה למחיקה, היא פוקעת ב-TTL. ראו ”בדיקת השלמות“

upload_consumed: true

לא קוד שגיאה אלא שדה שמתווסף לסירוב של השמירה עצמה (save_failed, למשל), כשהיא נכשלה אחרי שההעלאה נמחקה — ראו ”המחיקה היא השער“

תיאור הפרמטר upload_id אינו מונה את הסירובים האלה, בכוונה: הוא נקרא בכל שיחה שבה הכלים נטענים — גם ב-Claude.ai, שאינו יכול להעלות — והם רלוונטיים רק אחרי כשל. ואז כל אחד מהם נושא hint משלו (_both_sent, _invalid_upload_id ו-_upload_not_found ב-mcp_server/handlers.py), שנוקב בפרמטר בשמו — ”the content parameter“ ולא ”content“ לבד, כי content הוא גם שם עצם.

codekeeper_edit_file אינו מקבל העלאה: הוא מצא-והחלף, ולא הזרמת תוכן. codekeeper_multi_edit_file מקבל העלאה מסוג אחר, בפרמטר בשם משלו: edits_upload_id נושא את רשימת הזוגות כקובץ JSON, ולא תוכן של קובץ. היא עוברת באותם עוזרים — _load_upload עם בדיקת השלמות, והשער _consume_upload — ולכן upload_not_found, upload_storage_unavailable, upload_corrupted ו-upload_consumed שבטבלה הקודמת חלים גם עליה. הקודים שנקראים על שם פרמטר נושאים שם את השם שלו:

תשובה

מתי

edits_and_edits_upload_id

נשלחו גם edits שאינו ריק וגם edits_upload_id

missing_edits

לא נשלח אף אחד מהשניים — אותה תשובה של רשימה ריקה

invalid_edits_upload_id

המזהה אינו בצורה שהראוט מייצר. הערך אינו מוחזר

invalid_edits_upload

הקובץ שהועלה אינו מערך JSON. עם line, column ו-position כשהפענוח נעצר במקום מסוים — מספרים בלבד. שום דבר לא נכתב, וההעלאה נשארת עד שהיא פוקעת

ה-hint-ים של הכלי הזה נוקבים בשמות שלו — edits_upload_id ו-”the edits parameter“ — ואינם אומרים ”send the content inline“: מי שהעלה זוגות עשה זאת כי המחרוזות שלהם אינן עוברות בבטחה בתוך edits. הם גם אינם שולחים לכלי אחר: מה שעושים בלי העלאה תלוי בטקסט, והכלל הזה כתוב פעם אחת, בתיאור הפרמטר, ולכן ה-hint מפנה לשם. השמות מגיעים לעוזרים ב-_UploadParam (mcp_server/handlers.py), אחד לכל כלי. למה הפרמטר קיים, מה ה-JSON שבקובץ צריך, ומה נשאר אחרי כל סירוב — ב-הזוגות כקובץ — edits_upload_id.

המחיקה היא השער. הסדר בגוף הכלי: שם הקובץ ← בדיוק אחד מהשניים ← צורת המזהה ← שליפה לפי מזהה, משתמש ו-expires_at > now, ו**בדיקת השלמות** מיד אחריה (למטה) ← המסלול הקיים כמו שהוא על הטקסט (תוכן ריק, התקרה, זיהוי שפה, file_exists) ← ``delete_one`` באותו מסנן, ו-``deleted_count == 1`` הוא השער ← ורק אז השמירה. השליפה אינה צורכת, ולכן file_exists ו-existence_check_unavailable אינם שורפים את ההעלאה: שמירה חוזרת בשם אחר מצליחה. ומכיוון ש-delete_one אטומי במסד, משתי צריכות של אותו מזהה — גם מקבילות, גם מחוץ לתור הכתיבה — רק אחת שומרת; השנייה מקבלת upload_not_found.

המחיר, בכוונה: כשל של השמירה עצמה אחרי המחיקה שורף את ההעלאה, והתשובה אומרת זאת (upload_consumed); הסוכן מעלה שוב. החלופה — למחוק אחרי השמירה — הייתה משאירה העלאה חיה אחרי שמירה שהצליחה, ו-codekeeper_append_file שנשלח שוב כי התשובה אבדה בדרך היה מוסיף את התוכן פעמיים, בשקט. tests/test_mcp_uploads.py מקבע את שני המקרים: שני חוטים שצורכים את אותו מזהה, והוספה שנשלחה שוב.

בדיקת השלמות — הרגל שאף hash אחר אינו רואה. content_changed משווה את הטקסט שהכלי קיבל — כאן, הטקסט שנשלף מ-mcp_uploads — למה שנכתב לקובץ. הוא מכסה את הדרך מהכלי לאחסון הקבצים, ולא את הדרך מההעלאה לכלי: טקסט שהשתבש באחסון הזמני היה נשמר בשקט, עם content_changed: false, כי מה שנכתב שווה למה שנשלף. את הרגל הזו סוגרת בדיקת השלמות ב-_load_upload (mcp_server/handlers.py), העוזר שכל כלי שמקבל upload_id שולף דרכו: מיד אחרי השליפה, ה-hash של הטקסט שנשלף מושווה ל-content_sha256 שנשמר עם ההעלאה כשהגיעה. שונים, או שמה שנשמר אינו 64 ספרות הקס — upload_corrupted: שום דבר לא נכתב, ההעלאה נמחקת (ProductionBackend.discard_upload, דרך אותה מחיקה של השער), והסוכן מעלה שוב. למה עם השליפה, ולא רק לפני המחיקה: כל ההחלטות שבאות אחריה — תוכן ריק, התקרה, file_exists, conflict — נעשות על הטקסט. טקסט משובש היה מקבל מהן תשובה על טקסט שלא נשלח, למשל code_too_large על אורך שאינו של ההעלאה, וההעלאה הייתה נשארת חיה, בלי שורת לוג, עד שפקעה. התשובה אינה תלויה בתוצאת המחיקה: גם כשצורך מקביל מחק את ההעלאה בינתיים, וגם כשהאחסון לא ענה והיא תפקע ב-TTL, היא upload_corrupted. test_every_upload_is_checked_as_it_is_read_and_consumed_at_one_gate ב-tests/test_mcp_uploads.py מוודא על המקור שאין דרך שליפה או צריכה אחרת — לא בכלי ולא ב-backend.

אותו מסלול שמירה, בלי מסלול מקביל. הטקסט שנשלף עובר את ProductionBackend.save_file כמו code: הקריאה החוזרת לפי _id עם content_sha256 ו-content_changed, חותמת התיאור, והתראת ה-Push.

האחסון

אוסף mcp_uploads: upload_id (secrets.token_urlsafe, 43 תווים), user_id, text, bytes, chars, content_sha256, created_at, expires_at. המפרט — שם האוסף, הקבועים והאינדקסים — יושב במקום אחד, mcp_uploads.py בשורש, כי גם database/manager.py וגם שירות ה-MCP צריכים אותו.

  • TTL על ``expires_at`` עם ``expireAfterSeconds=0`` — השדה נושא את מועד המחיקה עצמו, ולכן UPLOAD_TTL_SECONDS מוגדר רק בכתיבה. לצידו אינדקס ייחודי על upload_id ואינדקס (user_id, expires_at) לספירת הממתינות ולמסנן הצריכה. ההצהרה ב-DatabaseManager._create_indexes, שרץ בכל עלייה — גם של שירות ה-MCP, הכותב היחיד — ובודקת את התוצאה של safe_create_index: כשל של ה-TTL או של הייחודי יוצא כאירוע db_mcp_uploads_index_missing ברמת error (אינדקסים שהם התנהגות, לא אופטימיזציה).

  • מונגו מוחק TTL בעצלות (המוניטור רץ בערך פעם בדקה), ולכן השליפה, המחיקה והספירה מסננות expires_at > now בעצמן. העלאה שפקעה ועוד לא נמחקה היא upload_not_found, ואינה תופסת מקום במכסה.

  • שער המוכנות נפתח על קריאה חוזרת, לא על הצהרה. לפני שהראוט מקבל העלאה, ProductionBackend.upload_storage_ready מריץ את אותה הצהרה ואז קורא את list_indexes ומחפש TTL במפרט — הדגל נדלק רק כשהמסד עצמו מראה אותו, כמו דגלי המוכנות של הפתקים (docs/performance-sticky-notes.rst). עד אז 503, עם ניסיון בנייה חוזר אחרי השהיה, באותו מנוע של צילומי הפתקים (snapshot_failed). בלי נעילה, ובכוונה: בקשה שמגיעה בזמן שחוט אחר בונה מקבלת ”לא מאומת“ מיד ואינה ממתינה — הלקח של התקלה שבה בקשות הצטברו מאחורי בניית אינדקסים תחת מנעול משותף. אחרי שאומת פעם אחת בתהליך, זו בדיקת דגל בלבד.

  • החסם על אחסון של משתמש אחד: MAX_PENDING_UPLOADS העלאות, כל אחת עד max_code_size() תווים — ובמקרה הגרוע תו הוא ארבעה בתים. הספירה וההכנסה אינן אטומיות: שתי העלאות מקבילות של אותו משתמש יכולות לעבור את החסם באחת. זה מעקה ולא נעילה, כמו file_exists, וכל העלאה פוקעת בכל מקרה.

מה נרשם בלוג. שורת INFO אחת על העלאה שנשמרה (mcp upload: stored ... bytes, ... chars for user ...) ואחת על צריכה (mcp upload: consumed by <tool> ...), בלי המזהה ובלי התוכן; ERROR אחת על העלאה משובשת (mcp upload: <tool> refused a corrupted upload (<reason>; ...) ... — deleted: ...), גם היא בלי המזהה ובלי התוכן — הסיבות הן של _upload_integrity_problem ב-handlers.py, ו-deleted אומר מה המחיקה עשתה, כולל unknown כשהאחסון לא ענה (discard_upload ב-backend.py). העלאה משובשת אינה רושמת consumed: היא לא נצרכה לשמירה; ERROR בעלייה כשאינדקס התנהגות לא נבנה, ו-ERROR מהשער כשה-TTL לא אומת; ה-WARNING של מגבלת הקצב מגיע מ-admit, אחד לזהות לחלון. סירובים של הראוט אינם נרשמים, ו-PostHog אינו רואה ראוטים: הכשל נראה למי שצריך לראות אותו — הסוכן, בקוד ה-HTTP ובגוף. שורת הגבולות בעלייה (mcp request limits: ...) נוקבת גם במכסת הממתינות ובמשך החיים.

הורדת קובץ לדיסק בלי לעבור דרך המודל

הבעיה. סוכן שצריך להריץ בקונטיינר שלו סקריפט ששמור ב-CodeKeeper קורא אותו ב-codekeeper_get_file, ואז מעתיק את כל התוכן לכלי הכתיבה שלו: משלם פעמיים על אותם בתים, וההעתקה עצמה היא מקום לטעות שרק השוואת hash תופסת. זה המראה של העלאת תוכן בלי לעבור דרך המודל: שם הבתים עולים בלי לעבור בהקשר, וכאן הם יורדים.

הזרימה — קריאת ``curl`` אחת, עם אותו CODEKEEPER_PAT של הפריימר ושל ההעלאה:

curl -fsS -H "Authorization: Bearer $CODEKEEPER_PAT" -o script.py 'https://<MCP-HOST>/api/agent/download?file_id=<id>' && sha256sum script.py

file_id הוא מזהה של גרסה — file.id מכל תשובה שמתארת קובץ, או id מ-codekeeper_list_versions. ה-hash ש-sha256sum מדפיס שווה ל-file.content_sha256 של אותה גרסה (טביעת אצבע לתוכן — content_sha256 ו-content_changed), וגם ל-X-Content-SHA256 שבתשובה.

למה ``-f``. בלעדיו curl -sS כותב את גוף ה-404 או ה-401 ({"error":"not_found"}) לתוך קובץ היעד ויוצא בקוד 0; ה-&& ממשיך, ו-sha256sum מחשב טביעת אצבע של הודעת השגיאה — וסוכן שלא משווה בקפידה היה מריץ JSON כאילו היה סקריפט. עם -f curl יוצא בקוד 22, קובץ היעד אינו נוצר ו-sha256sum אינו רץ. נמדד ב-16.10.2026, ב-curl 8.5.0 מול uvicorn 0.38.0, גם על 401: האזהרה ב-man של curl ש-401 יכול לחמוק עוסקת באימות של curl עצמו, ולא בכותרת Authorization שנשלחת כאן.

הורדה לפי שם — רק בצורה המקודדת. שמות קבצים כוללים עברית ורווחים, ו-?file_name=... שמוקלד ישירות בכתובת נשבר. תיאורי הכלים מפנים ל-file_id; כשבכל זאת מורידים לפי שם — הגרסה האחרונה, או version לגרסה מסוימת:

curl -fsS -G -H "Authorization: Bearer $CODEKEEPER_PAT" --data-urlencode 'file_name=<שם>' -o out.md 'https://<MCP-HOST>/api/agent/download'

למה לא קישור חתום. מאותו נימוק של ההעלאה: ה-PAT מאמת את הבקשה עצמה, ולכן אין מה להטביע, אין סוד בכתובת ואין אחסון זמני. וכאן גם ה-scope אינו שאלה — הורדה היא קריאה, וטוקן read מספיק.

מתי לא. בלי bash, בלי רשת או בלי CODEKEEPER_PAT — Claude.ai, למשל — קוראים ב-codekeeper_get_file כרגיל. הפקודה מופיעה בתיאור הפרמטר file_id של codekeeper_get_file ובתיאור codekeeper_list_versions, עם ה-host מ-MCP_SERVER_URL (או <mcp-host>, באותה בדיקה של פקודת ההעלאה — public_base_for ב-mcp_server/public_url.py). בתיאור codekeeper_get_file עצמו יש רק הפניה לפרמטר: הוא קרוב לתקרת תיאור כלי, והפקודה אינה נכנסת בה (_DOWNLOAD_TOOL_DOC ו-_download_command ב-mcp_server/server.py).

הכתובת בפקודה מצוטטת ל-shell. הסוכן מריץ את הפקודה מהתיאור כמו שהיא, והכתובת נגזרת מ-MCP_SERVER_URL. public_base_for בודק שהיא שמישה ושאין בה סוד — לא שהיא בטוחה ל-shell, ונתיב כמו /$(id) עובר אותו. לכן שתי הפקודות, ההורדה וההעלאה, מצטטות את הכתובת בנקודת ההרכבה (_shell_word, מעל shlex.quote): גרשיים בודדים, כי בתוך גרשיים כפולים bash עדיין מרחיב $(...), backticks ו-$, ו-" בכתובת סוגר אותם. כתובת רגילה בפקודת ההעלאה נשארת בלי גרשיים — shlex.quote מחזיר ערך שכולו תווים בטוחים כמו שהוא — והכתובת בפקודת ההורדה תמיד מצוטטת, בגלל ה-? שבה. עד התיקון הזה פקודת ההעלאה הכניסה את הכתובת בלי ציטוט בכלל.

הראוט — GET /api/agent/download

ב-mcp_server/downloads.py, התאום של הפריימר ושל ההעלאה. הסדר: אימות ← מגבלת הקצב ← צורת הבקשה ← השליפה ← התשובה. אין גוף בבקשה, ולכן אין דדליין לגוף.

  • הזיהוי הוא של ``codekeeper_get_file``, דרך אותה שליפה (handlers.get_file): file_id, או file_name ו-version אופציונלי, לפי ה-user_id של הטוקן. השליפה רצה ב-asyncio.to_thread, כמו גוף הכלי — במאגר הקריאה שגודלו נגזר ממכסת הזיכרון, ולא במאגר של anyio. ולכן הורדה לפי file_id משלמת גם את השאילתה של file.is_latest (האם זו הגרסה האחרונה — is_latest), אף שהשדה לא מגיע לכותרות.

  • הגוף הוא ``code.encode(”utf-8“)`` ותו לא: BOM, ‏CRLF וירידת שורה בסוף נשארים. הכותרות: Content-Type: text/plain; charset=utf-8, Content-Length, X-Content-SHA256 (מ-_full ב-mcp_server/backend.py — אותו ערך של file.content_sha256) ו-X-File-Version. שם הקובץ אינו בכותרת: הסוכן בוחר את שם היעד ב--o.

  • אין תקרה חדשה: קובץ שמור חסום ב-max_code_size() כבר בשמירה, ומוחזר שלם. large_files מחוץ להישג, כמו בכל ה-MCP, וקבצים מהמראות אינם בראוט הזה.

  • ``HEAD`` — Starlette מוסיף אותה לכל ראוט GET: היא עוברת את כל הראוט ונספרת במכסה, ו-uvicorn שולח לה את הכותרות בלי הגוף.

תשובה

מתי

200

הבתים, עם הכותרות שלמעלה

401 invalid_token

בלי טוקן, או טוקן פסול. בשני מצבי האימות זה ה-401 של הראוט עצמו: במצב PAT הנתיב פטור מ-PATAuthMiddleware

429 rate_limited

המכסה של הזהות נגמרה. אותה מכסה של קריאות הכלים ושל ההעלאה — המגביל נבנה פעם אחת ב-build_app — והורדה היא קריאה אחת מתוכה. נושא limit_per_minute ו-retry_after_seconds

404 not_found

אין קובץ כזה שלך: מזהה של משתמש אחר, מזהה שאינו קיים, מזהה פגום, או שם שאין לך — תשובה אחת, בלי לגלות איזו, כמו found: false של הכלי

400 missing_target

לא נשלח file_id ולא file_name

400 unknown_parameter

פרמטר שאינו file_id, file_name או version. allowed מונה את המותרים, והשם שנשלח אינו מוחזר. סירוב ולא התעלמות: verison=3 שהיה נבלע היה מחזיר בשקט את הגרסה האחרונה, עם 200

400 repeated_parameter

אותו פרמטר פעמיים, עם parameter

400 empty_parameter

פרמטר עם ערך ריק, עם parameter

400 ambiguous_target

file_id לצד file_name או version. הכלי מתעלם מ-version לצד file_id; הראוט מסרב, כי מי ששלח את שניהם התכוון למשהו

400 invalid_version

version שאינו ספרות ASCII, או ארוך ממה ש-_VERSION ב-mcp_server/downloads.py מתיר

כל סירוב נושא ``Connection: close``, כמו בהעלאה — כאן אין גוף שהשרת היה ממשיך לקרוא, וזה חוזה אחד לכל סירוב של ראוט. כל תשובה שהראוט עצמו מחזיר נושאת ``Cache-Control: no-store``, גם הצלחה וגם סירוב: זה תוכן פרטי שעבר אימות, ואין סיבה שמטמון בדרך ישמור אותו. מה שהראוט אינו בונה — 405 על מתודה אחרת מ-Starlette, או 500 מחריגה שלא נתפסה, שגופו אינו נושא תוכן — יוצא בלעדיה.

מה נרשם בלוג. שורת INFO אחת על כל הורדה (mcp download: <bytes> bytes of file <id> (version <n>) for user <user_id>), בלי התוכן ובלי שם הקובץ. סירובים אינם נרשמים, ו-PostHog אינו רואה ראוטים. שורת הגבולות בעלייה (mcp request limits: ...) נוקבת גם בהורדה.

ידוע, ואינו מתוקן כאן. הראוט יורש מהכלי שלוש התנהגויות של השליפה, והן אותו דבר בדיוק ב-codekeeper_get_file: מזהה פגום נרשם כאירוע שגיאה (db_get_file_by_id_error), כשל של המסד נענה כ-404 ולא כשגיאה, ו-get_version בוחר בלי מיון כששני מסמכים חולקים מספר גרסה.

הפעלה — צעד אחר צעד

שלב 1 — שירות חדש

שירות web נפרד (ASGI) ב-Render, שמתחבר לאותו MongoDB של הבוט והוובאפ:

Start command:  uvicorn mcp_server.app:app --host 0.0.0.0 --port $PORT
Health check:   /healthz

שלב 2 — מצב בסיס (PAT בלבד)

מספיק כדי לעבוד מול Claude Code דרך טוקן אישי, וכדי להגיש את הפריימר. מחבר ב-Claude.ai, ואיתו Claude Desktop ו-Claude Code שמחובר עם החשבון, דורש גם את שלב 3:

משתנה

הערה

MONGODB_URL + DATABASE_NAME

זהים לבוט/וובאפ

BOT_TOKEN

נדרש רק לטעינת מודול ה-config המשותף

שלב 3 — מצב OAuth (מוסיף את Claude.ai)

נדלק אוטומטית כשמוגדרים בשירות ה-MCP:

משתנה

הערה

MCP_SERVER_URL

ה-URL הציבורי (https) של שירות ה-MCP

WEBAPP_URL

ה-URL הציבורי של הוובאפ (למסך התחברות הטלגרם). בלעדיו, או כשהוא פגום (webapp_url.py), השירות רץ במצב PAT בלבד, ונרשמת שורת ERROR בעלייה. המצב מוצג ב-/healthz (webapp_url).

SECRET_KEY

זהה לוובאפ, ערך אקראי חזק (≥16 תווים) — חותם את זהות המשתמש בין השירותים

בנוסף: על הוובאפ להגדיר MCP_SERVER_URL (+אותו SECRET_KEY), ועל הבוט MCP_SERVER_URL (לפקודת /connect_claude).

שלב 4 — דפדפן הריפו (אדמין, אופציונלי)

משתנה

הערה

ADMIN_USER_IDS

מזהה הטלגרם של האדמין (CSV). ריק = הכלים כבויים לכולם

REPO_MIRROR_PATH + דיסק מצורף

ב-Render דיסק הוא פר-שירות; בלי דיסק ה-mirrors משוכפלים מחדש אחרי כל deploy

GITHUB_TOKENS / GITHUB_TOKEN

רק לריפואים פרטיים (אימות ל-clone/fetch)

אין צורך ב-GITHUB_WEBHOOK_SECRET בשירות ה-MCP — ה-webhook ממשיך להגיע לוובאפ בלבד, וה-MCP מתעדכן לבד (ראו ”רענון אוטומטי“ למטה).

הרשימה המלאה של המשתנים: משתני סביבה - רפרנס.

חיבור לקוחות

למשתמש, ההוראות נמצאות גם בוובאפ: בהגדרות, בסעיף ”חיבור סוכן AI“ (העוגן /settings#ai-connect), עם לשונית ל-Claude.ai (שם כתוב גם שאותו מחבר עובד ב-Claude Code בווב, באפליקציית הדסקטופ וב-Claude Code בטרמינל שמחובר עם החשבון), ל-Gemini (בגרסת הרשת בלבד) ול-Claude Code בטרמינל (שם כתוב מתי מספיק החשבון ומתי צריך טוקן), וכפתור שמעתיק את הכתובת. הכתובת שם היא MCP_SERVER_URL של הוובאפ ואחריו MCP_ENDPOINT_PATH (_mcp_connect_url ב-webapp/routes/settings_routes.py); כשהמשתנה חסר או נדחה, הסעיף מוצג בלי שורת הכתובת. מתחת ללשוניות יש בלוק מתקפל, ”מה אפשר לבקש מהסוכן“, עם דוגמאות לבקשה ראשונה, כדי שמי שחיבר עכשיו לא יישאר מול חלון צ’אט ריק.

Claude.ai (Custom Connector)

Settings → Connectors → Add custom connector → הזינו את הכתובת:

https://<mcp-host>/mcp

זהו — Claude מבצע DCR + OAuth לבד, מפנה להתחברות טלגרם ולמסך אישור. אין צורך ב-Client ID/Secret. כדי לקבל write, ה-connector צריך להירשם עם ההרשאה — אם כבר חיברתם לקריאה בלבד, הסירו והוסיפו מחדש ואשרו ”קריאה וכתיבה“.

Claude Code (טוקן)

קודם — ייתכן שלא צריך טוקן. כש-Claude Code מחובר עם חשבון claude.ai, המחברים של החשבון נטענים בו לבד, ובהם זה של Claude.ai (Custom Connector); /mcp מסמן אותם כמחברים מ-claude.ai. הם לא נטענים כשהאימות הפעיל הוא אחר: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN או apiKeyHelper; ספק צד שלישי כמו Amazon Bedrock; פרופיל Anthropic או משתני federation שמספקים את ההרשאה; או CLAUDE_CODE_OAUTH_TOKEN שנוצר ב-claude setup-token. הם גם לא נטענים כשהמחברים כובו במפורש, בהגדרה disableClaudeAiConnectors או ב-ENABLE_CLAUDEAI_MCP_SERVERS=false, ובתוכניות Team ו-Enterprise רק אדמין מוסיף מחבר. בכל המקרים האלה — הטוקן שבהמשך הסעיף. (code.claude.com/docs/en/mcp, הסעיפים ”Use MCP servers from claude.ai“ ו-”Disable claude.ai connectors“, נקרא ב-2026-10-29. בוובאפ, הלשונית ”Claude Code בטרמינל“ נוקבת רק בחלק מהמקרים, כדוגמאות.)

שלחו לבוט בצ’אט פרטי /connect_claude (או /connect_claude write), ואז:

claude mcp add --transport http codekeeper --scope user https://<mcp-host>/mcp \
  --header "Authorization: Bearer <token>"

איפה הפקודה שומרת, והמקבילה הידנית. הבוט מחזיר את הפקודה הזו (connect_claude_command ב-main.py), ו-tests/test_connect_claude_command.py מקבע שיש בה --scope user. הדגל כותב את הרשומה ל-mcpServers שבראש ~/.claude.json, ולכן CodeKeeper זמין בכל הפרויקטים. בלי הדגל, claude mcp add שומר ב-scope ברירת המחדל, local: תחת הרשומה של הפרויקט שממנו הורצה הפקודה (projects ← נתיב הפרויקט ← mcpServers), ו-CodeKeeper היה זמין רק שם (code.claude.com/docs/en/mcp, ה-Tips של --scope, נקרא ב-2026-10-29; ונמדד באותו יום ב-Claude Code 2.1.312, בתיקיית הגדרות מבודדת). מי שמעדיף לערוך את הקובץ ביד מוסיף את הרשומה הזו ל-mcpServers הקיים, ולא מחליף את הקובץ, שיש בו עוד הגדרות רבות של Claude Code:

{
  "mcpServers": {
    "codekeeper": {
      "type": "http",
      "url": "https://<mcp-host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

כמה מהבלוק ומהתיאורים מגיע לסוכן. Claude Code חותך כברירת מחדל בשתי תקרות: את ה-instructions של כל שרת, ואת התיאור של כלי שנטען מראש, ב-4,096 תווים; ואת התיאור של כלי שנטען דרך tool search — שדלוק כברירת מחדל — ב-16,384 תווים. כלי נטען מראש, ונשאר בתקרה הקצרה, כש-tool search כבוי, או כשהכלי או השרת שלו הוחרגו מהדחייה (code.claude.com/docs/en/mcp, הסעיף ”Tool search for MCP server authors“, נקרא ב-2026-10-29). התקרה הקצרה הייתה 2,048 תווים לפני גרסה 2.1.296, ולפני 2.1.295 היא חלה על כל תיאור כלי, גם כזה שנטען דרך tool search (אותו סעיף; וה-changelog של Claude Code, code.claude.com/docs/en/changelog, הרשומה של 2026-10-09, נקרא ב-2026-10-13). CLIENT_INSTRUCTIONS_MAX_CHARS עוקב אחרי התקרה של ה-instructions, וההערה שלידו נוקבת בשני המקורות. לקוח ישן מ-2.1.296 עדיין חותך ב-2,048, ובלוק ארוך מזה מגיע אליו בלי סופו — ולכן החלק האחרון בבלוק הוא כלי הריפו של האדמין, ומה שנחתך שם חסר רק לאדמין שעובד מלקוח ישן. המשתנה CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH בסביבה של Claude Code קובע מספר תווים אחד לשתי התקרות — לכל שרתי ה-MCP בסשן יחד, ומגרסה v2.1.280 ומעלה — ולכן ערך כמו 8,192 מגדיל את התקרה הקצרה ומקטין את הארוכה (אותו עמוד, אותו יום). השרת הזה אינו נשען עליו: הבלוק נשמר בתוך CLIENT_INSTRUCTIONS_MAX_CHARS, והתיאורים בתוך התקרה של tests/test_mcp_server_build.py (_TOOL_DESCRIPTION_MAX_CHARS), שנמוכה משתיהן — כך שבלקוח עדכני שום דבר אינו נחתך בברירת המחדל, בין שהכלי נטען מראש ובין שדרך tool search. להגדיל אותו כדאי רק אם שורת ה-WARNING של הבלוק מופיעה בעליית השרת (ראו הכלים), וגם אז זה פותר רק את הסביבה שבה הוגדר — סוכן בסביבה אחרת, או משתמש אחר, עדיין רואה את התקרה הרגילה. ב-claude.ai, לפי אישו פתוח (anthropics/claude-ai-mcp#93, לא תיעוד רשמי), שדה ה-instructions כנראה אינו מגיע לסוכן כלל.

Claude Desktop

המחבר מ-Claude.ai (Custom Connector) שייך לחשבון, ולכן הוא זמין לבד גם באפליקציית הדסקטופ, בלי JSON ובלי טוקן: בצ’אט, ובסשנים המקומיים וה-SSH של טאב ה-Code כשמחוברים בה עם חשבון Claude. לסשנים של WSL ב-Windows המחברים עדיין בהטמעה. הקובץ claude_desktop_config.json מתועד לשרתים מקומיים, ולא נדרש כאן. מי שמעדיף רשומה ידנית: טאב ה-Code קורא גם את ~/.claude.json, והרשומה היא זו שב-Claude Code (טוקן). (נקראו ב-2026-10-29: code.claude.com/docs/en/mcp, הסעיף ”How connectors reach Claude Code“; code.claude.com/docs/en/desktop, הסעיף ”MCP servers from the Claude Desktop chat app“; support.claude.com, ”Get started with custom connectors using remote MCP“.)

דפדפן הריפו — איך זה עובד

רענון אוטומטי (autosync)

שירות ה-MCP מריץ thread רקע (אותו דפוס כמו ה-worker בוובאפ) ששומר על ה-mirrors המקומיים טריים — בלי cron ובלי שירות נוסף:

merge ל-main → GitHub webhook → הוובאפ מסנכרן את הדיסק שלו וכותב SHA ל-Mongo
            → ה-autosync ב-MCP מזהה שה-SHA המקומי שונה → git fetch מקומי
  • ריפו שקיים ב-repo_metadata אך חסר בדיסק המקומי — משוכפל אוטומטית (אין צורך ב-import ידני בצד ה-MCP). הקריאה של הרשומות והשכפול נמצאים ב-services/repo_mirror_fill.py, ומשותפים למילוי שהוובאפ עושה לדיסק שלו בעלייה (דיסק בלי mirrors: המילוי בעלייה).

  • מראה בדיסק המקומי שאין לה רשומה ב-repo_metadata — נמחקת בסוף אותו מעבר (_prune_orphans ב-mcp_server/repo_autosync.py). הסרת ריפו בוובאפ (unmirror_repo ב-services/repo_sync_service.py) מוחקת את המראה שבדיסק של הוובאפ ואת הרשומות, ולדיסק של שירות ה-MCP היא לא מגיעה — ולכן ההסרה מגיעה לכאן במעבר הראשון שאחריה. מאותו רגע כלי הריפו עונים על הריפו repo_not_mirrored (ענף שלא במראה, מול קובץ שלא קיים), כולל codekeeper_docs_get_section.

  • מה לא נמחק: שום דבר, כשהקריאה של repo_metadata נכשלה, או כשאף שם בה אינו שם של מראה שבדיסק. זה כולל קריאה ריקה, רשומות שהשמות בהן אינם שמות של מראה, ומסד עם ריפואים אחרים. מצב כזה מעיד יותר על חיבור למסד הלא נכון מאשר על הסרה של כל הריפואים, וכשיש בדיסק מראות שנחסכו נרשמת עליו אזהרה. גם לא נמחקים תיקייה שאינה מראה שהשירות יוצר (שם ש-_validate_repo_name דוחה, או קישור סמלי — list_managed_mirror_names ב-GitMirrorService), וריפו שנמצא באמצע clone או fetch (is_refreshing). הקריאה של repo_metadata נעשית מה-primary במפורש, כי ההתאמה סומכת עליה שתמנה כל ריפו.

  • המחיקה עצמה עוברת ב-delete_mirror, ומראה נספרת כמחוקה רק אחרי שבדיקה חוזרת מראה שהתיקייה אכן איננה. מחיקה שנכשלה, או תיקיית מראות שאי אפשר לקרוא, נספרות ב-errors ונרשמות כאזהרה. במקרה כזה המראה נשארת, והמעבר הבא מנסה שוב.

  • שורת הלוג repo autosync pass: נכתבת כשהמעבר שכפל, משך, מחק או נכשל במשהו. pruned בה הוא מספר המראות שנמחקו, ולכל מראה שנמחקה יש גם שורה pruned the local mirror of <repo>.

  • שליטה: MCP_REPO_AUTOSYNC (ברירת מחדל פעיל), MCP_REPO_AUTOSYNC_INTERVAL (ברירת מחדל 300 שניות).

מה המראה מחזיקה. המראה נוצרת ב-git clone --mirror ומתעדכנת ב-git fetch --all --prune (init_mirror ו-fetch_updates ב-services/git_mirror_service.py). ה-refspec ש---mirror קובע הוא +refs/*:refs/* (התיעוד של git clone ב-git v2.43.0), ולכן היא מחזיקה כל ref שהיה ב-GitHub ברגע המשיכה האחרונה שלה: הענפים, התגיות, ו-refs/pull/* של GitHub.

מתי היא נמשכת — לא על כל push. ה-webhook מגיע לוובאפ על כל push, אבל handle_push_event (webapp/routes/webhooks.py) מסנכרן רק push לענף הראשי, ועל כל ענף אחר עונה Ignoring branch. ה-autosync של שירות ה-MCP (refresh_once ב-mcp_server/repo_autosync.py) מושך רק כשה-SHA של הענף הראשי שהוובאפ כתב למונגו שונה מזה שבמראה המקומית. לכן ענף שנדחף בלי שינוי בענף הראשי אינו מגיע למראה עד השינוי הבא בענף הראשי — ואז הוא מגיע יחד עם כל השאר. המשפט שהסוכן קורא על זה, בתיאור הפרמטר ref ובהודעה של ref_not_mirrored, הוא MIRROR_REFRESH_NOTE ב-mcp_server/repo_handlers.py; ליד הקבוע כתוב אילו טסטים מקבעים את המדיניות שהוא מתאר.

אימות מול GitHub — הטוקן לא נשמר במראה

מראה חדשה נוצרת עם URL נקי, ומראה ישנה מנוקה. עד #3480 הטוקן הוזרק ל-URL של ה-clone, ו-git שמר אותו בטקסט גלוי ב-remote.origin.url שבקובץ config של המראה — על הדיסק של הוובאפ, על הדיסק של שירות ה-MCP, ובצילומי הדיסק של Render. היום ה-clone נעשה מה-URL הנקי, והטוקן עובר לכל clone/fetch בנפרד ככותרת Authorization, דרך משתני הסביבה GIT_CONFIG_COUNT/GIT_CONFIG_KEY_<n>/GIT_CONFIG_VALUE_<n> ולא בשורת הפקודה (network_env ב-services/mirror_credentials.py). הכותרת ממוקדת ל-GITHUB_HTTPS_ORIGIN בלבד. מראה ישנה נשארת עם הטוקן בדיסק עד שהניקוי שלה מצליח — ראו למטה; עד אז ה-fetch שלה חסום.

איזה טוקן, ולמי. הטוקן נבחר לפי בעלי הריפו: מהמפה ב-GITHUB_TOKENS, ובעלים שאינו במפה מקבל את GITHUB_TOKEN (_token_and_source_for_url). כל פקודת רשת נשלחת קודם בלי טוקן, ורק כש-GitHub עונה שהריפו דורש הזדהות היא נשלחת שוב עם הכותרת — כך שריפו ציבורי לא מקבל טוקן אף פעם (_run_network_git). שורות הלוג Mirror clone/Mirror fetch מציינות auth_used: none, map, global או explicit.

ניקוי מראות ישנות. ensure_clean_remote מוציא credentials מה-URL השמור ב-git remote set-url, ומאמת בקריאה חוזרת של ה-URL — לא לפי קוד היציאה. הוא רץ לפני כל fetch_updates (אם הניקוי לא אומת, ה-fetch לא רץ ומוחזר mirror_url_not_clean), וגם על כל המראות בעליית כל שירות: בשירות ה-MCP מה-lifespan של האפליקציה (attach_credential_sweep ב-mcp_server/repo_autosync.py — לא בייבוא של mcp_server.app), ובוובאפ מתוך scripts/start_webapp.sh. שורת הלוג של המעבר הזה היא האימות:

mirror credential sweep: checked=<n> had_credentials=<n> cleaned=<n> failed=<n> sources={"<repo>": "map", ...}

המראות נקיות רק כש-``failed=0``. מראה שנספרה ב-failed עלולה עדיין להחזיק את הטוקן ב-config; לכל אחת מהן יש שורת mirror credential sweep: <repo> failed (<reason>) עם הסיבה, והניסיון חוזר לפני ה-fetch הבא שלה ובעלייה הבאה. sources אומר לכל מראה מאיפה יגיע הטוקן שלה אם הריפו ידרוש הזדהות, בלי הטוקן עצמו — כך רואים אילו מראות נשענות על GITHUB_TOKEN. שורה שלא מופיעה בלוג של אחד השירותים פירושה שהמעבר לא רץ שם, או שנכשל: תיקיית מראות שאי אפשר לקרוא אינה נספרת כ-checked=0, כי שורה כזו הייתה נראית כמו ”הכול נקי“. במקומה מופיעה שורת mirror credential sweep failed עם החריגה בשירות ה-MCP (start_credential_sweep), ושורת Mirror credential sweep reported failures בוובאפ (scripts/start_webapp.sh).

שומר. כל פקודת רשת רצה עם transfer.credentialsInUrl=die: מראה שעדיין נושאת credentials ב-URL נכשלת לפני בקשת רשת, ו-git עצמו מסתיר את הסיסמה בהודעה. git remote מותר ב-_run_git_command רק בשתי הצורות get-url origin ו-set-url origin <url>, וה-URL חייב לעבור את _validate_repo_url.

מדיניות סינון סודות

נתיבים רגישים (.env*, *.pem, *.key, id_rsa*, secrets.*, credentials* ועוד) נחסמים בקריאת קובץ, מושמטים מרשימות ו**מדולגים** בחיפוש — בכל הריפואים, תמיד. ההתאמה case-insensitive על הנתיב המלא ועל כל רכיב בו, ולכן שם רגיש נתפס גם כשהוא תיקייה ולא קובץ: config/.env נחסם, וגם config/.env/README.md שבתוכה. הרחבת הרשימה: MCP_REPO_DENYLIST_EXTRA (CSV של תבניות glob). על שגיאה פנימית המדיניות נכשלת סגור (חוסמת).

בחיפוש ההחרגה נכנסת ל-git grep עצמו, ולכן קובץ חסום אינו נסרק ואינו נספר — ולא רק מסונן מהתוצאות. התבניות הן אותן תבניות; הסינון על התוצאות נשאר כשכבה אחרונה.

קוד חיצוני וקבצים מקומפלים הם רשימה אחרת לגמרי, ולא להתבלבל. סוד חסום גם בקריאה; node_modules ובאנדלים רק אינם נכללים בחיפוש כברירת מחדל, וממשיכים להיקרא דרך codekeeper_get_repo_file. ראו כמה מופעים יש באמת (total מול total_at_least).

והכלי הציבורי אינו יוצא מן הכלל. codekeeper_docs_get_section הוא הכלי היחיד כאן שאינו דורש אדמין, והוא קורא דרך אותה פונקציה — ולכן המדיניות חלה עליו במלואה. path="secrets" מחזיר path_denied ולא not_found, ובריפו שהתיעוד שלו יושב בשורש גם secrets.md ו-credentials.md חסומים. ההבדל בין שני הקודים אינו סגנוני: not_found אומר ”אין קובץ כזה“ ומזמין לנסות שם אחר, ו-path_denied אומר ”יש, ולא תקבל“.

התנהגות בזמן sync

אין נעילת קריאה מול ה-sync, ולכן קריאה שנכשלת בזמן ש-sync רץ מחזירה:

{"ok": false, "error": "sync_in_progress", "retry_after": 30}

זה סימן לנסות שוב אחרי המתנה קצרה — לא להסיק שהקובץ או הריפו לא קיימים.

מדידת שימוש (PostHog MCP Analytics)

השרת מדווח ל-PostHog אירוע על כל קריאת כלי, על כל tools/list ועל כל לחיצת יד — כדי לדעת באילו כלים באמת משתמשים, כמה זמן הם לוקחים וכמה מהם נכשלים. הקוד: mcp_server/analytics.py.

הסעיף הזה מתאר את צד ה**כתיבה**: מה השרת שולח, ומה נחסם בשער הפרטיות שלפניו. לקריאת הנתונים חזרה יש מסך אדמין ייעודי בוובאפ — /admin/mcp — עם משתני הסביבה שהוא דורש ומצבי הכשל שלו: MCP Analytics (מדידת השימוש בכלי ה-MCP). שימו לב ש-POSTHOG_HOST נושא שם משותף וערך שונה בין שני השירותים, והפרטים שם.

מה לא יוצא מהשרת. בשרת הזה הארגומנטים של הכלי והתוצאה שלו הם התוכן של המשתמש: codekeeper_get_file מחזיר גוף של קובץ, codekeeper_save_file מקבל אחד, ואותם מסלולים משרתים גם פתקים ומסמכים משוקפים. לכן הוק before_send על לקוח ה-PostHog מחזיק רשימת היתר של מאפייני $mcp_*, וכל מאפיין שאינו בה נזרק:

מאפיין

מה קורה איתו

$mcp_parameters

נזרק, בכל אירוע ובלי חריג. הארגומנטים של הקריאה — בכלי הכתיבה זה הקובץ עצמו

$mcp_response

נזרק, בכל אירוע ובלי חריג. תוצאת הכלי — גוף קובץ, פתק, מסמך

$mcp_error_message

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

$mcp_intent

נשלח, כשהערך מחרוזת, ואחרי סינון סודות. המשפט שהסוכן כותב כשהוא קורא ל-get_more_tools כדי לדווח על יכולת חסרה. על קריאת כלי רגילה הוא לא נוצר, כי context כבוי — ראו לכידת הכוונה (context) — כבויה

$mcp_intent_source

נשלח, כשהערך הוא בדיוק context_parameter או inferred. זו תווית סגורה שה-SDK כותב, לא טקסט — ולכן היא נאכפת מול שני הערכים ולא מתקבלת כמחרוזת חופשית

$exception_list[*].value

מוחלף בטקסט קבוע, בכל אירוע. לא אותו מידע כמו $mcp_error_message: זה נושא את שרשרת ה-__cause__ המלאה ובלי תקרה, בעוד המאפיין נושא את הרשומה הראשית בלבד, מקוצצת ל-2,048 תווים בידי ה-SDK. וזה לא נעצר בכלים: enable_exception_autocapture תופס גם threading.excepthook, כך שחריגה שלא נתפסה ב-thread כלשהו בתהליך (למשל ה-autosync) מגיעה כאירוע $exception בלי שום מפתח $mcp_ להיאחז בו. סוג החריגה והמסגרות נשמרים, ולכן קיבוץ השגיאות עובד

ck_read_mode

נשלח, כשהערך אחד מארבעה: outline, query, range או full. מאפיין שהשרת מחשב בעצמו — ראו ”מצב הקריאה“ למטה

$mcp_tool_name · $mcp_duration_ms · $mcp_is_error · $mcp_error_type · $mcp_client_name · $session_id · $mcp_listed_tool_names

נשלחים. מטא-דאטה של השרת ושל הפרוטוקול בלבד

הלקוח הזה משרת רק את שרת ה-MCP, וכל מה שהשרת נוגע בו הוא תוכן של המשתמש. לכן הכלל חל על כל אירוע שהלקוח שולח, ולא רק על אירועי $mcp_.

שני שדות של טקסט חופשי, ובדיקה אחת שחלה על שניהם. $mcp_error_message ו-$mcp_intent הם היחידים שיוצאים ואינם נכתבו על ידי השרת. שניהם מוצדקים כ“משפט שאדם קורא“, ולכן שניהם עוברים רק כשהערך הוא מחרוזת: מילון או רשימה תחת אותו שם אינם המשפט הזה אלא מבנה שלם — ומבנה אי אפשר לחטא חלקית, ולכן הוא נזרק. זה נמדד ולא נוסח: מילון תחת $mcp_error_message עבר גרסה קודמת של השער, שבדקה מי מבקש ולא מה עובר, עם גוף קובץ בתוכו.

ואז שניהם עוברים סינון סודות. אותה רשימת דפוסים שמסננת את הפריימר, ב-mcp_server/redaction.py — מודול טהור ששני הצרכנים מייבאים, ולא עותק שני. זה לא סגנון: כשלכל צרכן הייתה רשימה משלו, דפוס נוסף לאחד ולא לשני, וזה כבר קרה בפרויקט הזה.

מה נמדד שהמסנן תופס, ומה לא

נתפס

לא נתפס

כל צורת סוד מוכרת, בכל מקום במחרוזת: מפתח AWS בזנב של input_value, ghp_, ckmcp_, sk-, JWT, Bearer, ו-scheme://user:pass@host

הכלל לפי שם (API_KEY=…) כשההשמה יושבת באמצע שורה — וזו בדיוק הצורה של הודעת Pydantic. הכלל מעוגן ל-^, וזה מכוון: בלי העיגון key=value בתוך פרוזה היה נמחק מהפריימר

—

נתיבי קבצים ושמות. הם אינם סודות, והמסנן אינו מתיימר להיות מנקה PII

המסנן מצמצם חשיפה; הוא אינו הופך את השדות לבטוחים. האזהרה שמתחת נשארת תקפה במלואה.

אזהרה

הודעת השגיאה עלולה לשאת קטע מתוכן המשתמש, וזה התקבל במודע.

ההודעה של Pydantic מכילה את input_value — הערך שנדחה. הוא מקוצץ ל-50 תווים, אבל הקיצוץ שומר ראש וזנב, ולכן ערך רגיש בתחילת הקלט או בסופו עובר שלם. נמדד על pydantic 2.12.3: קלט בן 500+ תווים שהסתיים ב-AWS_KEY=... החזיר את הזנב במלואו. והמקרה הרחב יותר הוא שדה חובה חסר (type=missing), שבו Pydantic מדווח כ-input_value את אובייקט הארגומנטים כולו — כלומר codekeeper_save_file בלי file_name שם קטע מגוף הקובץ בהודעה.

וזה כבר לא מוגבל ל-Pydantic. בגרסה קודמת ההודעה נשלחה רק כאשר $mcp_error_type היה בדיוק ValidationError; הגידור הזה הוסר, ולכן הודעה של חריגה מכל סוג יוצאת — כולל חריגה שספרייה זרקה. חריגת pymongo יכולה לנקוב בכותרת שחיפשנו, ושגיאת מערכת יכולה לנקוב בנתיב. מה שמצמצם את זה בפועל אינו השער אלא הקוד: repo_backend.py תופס רחב ומחזיר {"ok": false, "error": ...} במקום לזרוק, ולכן רוב הכשלים לעולם אינם מגיעים לכאן כחריגה. זו תכונה של הקוד היום, לא הבטחה של השער — מסלול חדש שנותן לחריגה לעלות מרחיב את מה שיוצא, בלי לגעת ב-analytics.py.

הגידור הוא בהיקף ולא בניקוי: אין כאן ניסיון לחטא את המחרוזת, כי סניטציה מומצאת על טקסט חופשי נכשלת בשקט. האורך מגודר על ידי ה-SDK, שמקצץ את $mcp_error_message ל-2,048 תווים.

למה רשימת היתר ולא מחיקה של שני השמות. מחיקה לפי שם היא רשימה שחורה: ה-SDK של MCP הוא טרום-1.0, ומאפיין נושא-תוכן שייכנס במהדורה עתידית היה יוצא לרשת לפני שמישהו הספיק להוסיף אותו לרשימה. רשימת היתר זורקת דווקא את מה שלא מכירים. ההוק גם נכשל סגור: תקלה בתוכו מפילה את האירוע במקום להעביר אותו כמות שהוא.

לכידת הכוונה (context) — כבויה

כש-context דלוק, posthog.mcp מוסיף לסכימה של כל כלי פרמטר context, שבו הסוכן כותב מה הקריאה באה לעשות, והמשפט יוצא ל-PostHog כ-$mcp_intent על כל קריאת כלי. זה משפט על מה שהשיחה של המשתמש מנסה להשיג. האופציה הייתה דלוקה עד נובמבר 2026, וכובתה לפני ההגשה לספריית המחברים של Anthropic: מדיניות הספרייה אומרת שתוכנה ”must not collect extraneous conversation data, even for logging purposes“ (סעיף 1E ב-Anthropic Software Directory Policy), ומדיניות הפרטיות של האתר אומרת למשתמשים שהשרת לא שומר אותו (מדיניות הפרטיות של המחבר (/privacy#mcp)).

הכיבוי כתוב במפורש, כי ברירת המחדל של ה-SDK היא דלוק. MCPAnalyticsOptions.context מתחיל ב-True, ו-is_context_enabled בודק context is not False (posthog/mcp/types.py, posthog/mcp/_context_parameters.py, posthog 7.45.3). מי שמוחק את השורה context=False ב-instrument_mcp_server מדליק את האיסוף מחדש. test_a_real_instrumented_tool_call_reaches_posthog_with_no_content (tests/test_mcp_analytics_privacy.py) נכשל אז, כי הוא בודק שאין context בסכימה ואין $mcp_intent על קריאת כלי.

לקוח שעדיין שולח context. לקוח ששמר את רשימת הכלים מהתקופה שבה האופציה הייתה דלוקה ממשיך לשלוח את הפרמטר. הקריאה לא נדחית, הפרמטר לא מגיע לגוף הכלי, והמשפט לא יוצא ל-PostHog. שני הטסטים שנוקבים בזה: זה שלמעלה, ו-test_with_posthog_on_every_string_still_arrives_as_sent (tests/test_mcp_pre_parse_json.py), שעובר על כל פרמטר מחרוזת בכל כלי רשום.

מה נשאר. $mcp_intent נוצר עכשיו רק על אירוע $mcp_missing_capability: ה-SDK לוקח אותו מהארגומנט context של get_more_tools עצמו (record_missing_capability ב-posthog/mcp/_instrumentation.py), בלי קשר לאופציה. שם המשפט הוא הדיווח עצמו. לכן הטבלה ”יכולות שסוכנים ביקשו“ ב-/admin/mcp ממשיכה לעבוד, וטור הכוונה בטבלת הסשנים כבר לא מקבל משפט מקריאת כלי רגילה.

מצב הקריאה (ck_read_mode)

outline=true ו-lines=[5, 80] הן אותו כלי, ולכן דשבורד שסופר לפי שם הכלי סופר אותן באותה עמודה — בזמן שהן הפוכות במשמעות: אאוטליין הוא מפה זולה, וקריאת תוכן היא הניווט היקר שהמפה באה להחליף.

ההבחנה חיה ב-$mcp_parameters, והוא חסום ונשאר חסום. לכן במקום לפתוח את הארגומנטים, השרת מחשב בעצמו תווית אחת מתוך קבוצה סגורה ושולח אותה:

ערך

מתי

outline

מפה במקום תוכן: outline אמיתי ב-codekeeper_get_repo_file, או toc אמיתי ב-codekeeper_get_file — כל אחד רק לכלי שמצהיר עליו. ערך אחד לשניהם, כי זו אותה קריאה במשמעות; שם הכלי נמצא ממילא ב-$mcp_tool_name. גם קריאה שמעבירה גם lines (ונדחית כ-outline_and_lines או toc_and_lines) נספרת כאן — היא לא קראה תוכן. ”אמיתי“ הוא כפי שהכלי קורא את הדגל — ראו ”דגל נקרא כמו שהכלי קורא אותו“ מתחת לטבלה

section

הועבר section ל-codekeeper_get_file — סעיף אחד במקום הקובץ (קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)). נבדק אחרי המפה ולפני query ו-lines, ולכן קריאה שמעבירה גם אחד מהם (ונדחית כ-section_and_query או section_and_lines) נספרת כאן

query

הועבר query לכלי שמצהיר עליו — מופעים במקום תוכן, כלומר קריאה זולה מאותה משפחה כמו outline. נבדק לפני lines, ולכן גם קריאה שמעבירה את שניהם (ונדחית כ-query_and_lines) נספרת כאן, מאותו נימוק

range

הועבר lines

full

לא הועבר אף אחד מהם — קריאת הקובץ המלא, היקרה מכולן

הסדר הוא הסדר של קודי הסירוב. קריאה שנדחתה כזוג מצבים מתויגת לפי המצב הראשון בשם הקוד שלה — toc_and_section כמפה, section_and_query כסעיף. הסדר כתוב במקום אחד, FILE_READ_MODES ב-mcp_server/handlers.py: הכלי גוזר ממנו את הזוגות שהוא דוחה (_EXCLUSIVE_READ_MODES), ו-read_mode_properties ב-mcp_server/analytics.py מקבל אותו כמו שהוא — מפה, סעיף, מופעים, טווח. עד #3472 הסדר היה כתוב פעמיים, וטסט הוא שסיכם בין שני העותקים. לכלי הריפו יש זוג אחד, outline_and_lines, והסדר שלו כתוב באנליטיקס. קריאה שנדחתה כזוג לא קראה תוכן בכל מקרה, ולכן כל אחת מהתוויות הזולות ישרה לגביה.

דגל נקרא כמו שהכלי קורא אותו (#3472). outline ו-toc הם bool רגיל בסכימה, והוולידציה ממירה מחרוזות: outline="false" קורא את הקובץ המלא. עד #3472 הקולבק בדק אמת-שקר של פייתון, שבה כל מחרוזת לא ריקה היא אמת — ולכן קריאה כזו תויגה outline, מפה, על קריאה של קובץ מלא. הבאג היה קיים ב-outline של codekeeper_get_repo_file, ו-toc הצטרף אליו כשהפסיק להיות strict (קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)). עכשיו הקולבק מריץ על הדגל את אותה ולידציה של pydantic (TypeAdapter(bool)): מה שהכלי קורא true — outline; מה שהוא קורא false — לפי שאר הפרמטרים; ומה שהוא דוחה — null, 2, "maybe" — outline, כמו זוג שנדחה: הקריאה לא קראה תוכן. דגל שלא נשלח בכלל אינו בקשה. ב-query, section ו-lines null הוא ברירת המחדל, כלומר ”לא נשלח“ — ולכן שם הוא אינו בקשה גם כשנשלח.

הנגזרת נשענת על נוכחות הפרמטר — ובדגל, על הערך כפי שהכלי קורא אותו — ולעולם אינה מהדהדת ערך שהגיע מהקורא: מה שיוצא הוא אחת מחמש המילים האלה. query ו-section הם בדיוק המקום שבו זה נדרש, כי הערך שלהם הוא טקסט חופשי שהקורא כתב. השער אוכף את הקבוצה הסגורה — מאפיין משלנו אינו נושא את התחילית $mcp_, ולכן רשימת ההיתר אינה חלה עליו, ובלי האכיפה הזו היה כאן שם שדרכו אפשר לשלוח כל מחרוזת.

הערה

כל פרמטר נקרא רק עבור הכלי שמצהיר עליו. outline קיים ב- codekeeper_get_repo_file בלבד, ו-toc, section ו-query ב-codekeeper_get_file בלבד (בין שני כלי הקבצים — codekeeper_docs_get_section נושא section משלו, ואינו כלי קריאת קובץ במובן של העמודה: אין לו lines, והוא אינו במפה). הקולבק מקבל את מילון הארגומנטים הגולמי — לפני ש-pydantic מסלק ממנו מפתחות שאינם בסכימה של הכלי — ולכן מפתח תועה של הכלי האחר מגיע אליו ונקרא. בלי השיוך, קריאה כזו נספרת בעמודה הלא נכונה ושתי העמודות האחרות יוצאות חסרות באותה מידה, בלי שגיאה ובלי סימן. השיוך יושב ב-_TOOL_READ_MODES ב-mcp_server/analytics.py, ו-_TOOL_READ_MODE_PARAMS ו-FILE_READ_TOOLS נגזרים ממנו ואינם נכתבים פעמיים.

מאותה סיבה codekeeper_search_code, שנושא פרמטר בשם query ואינו קריאת קובץ, אינו נכנס לעמודה הזו כלל: הוא אינו במפה.

גם ``codekeeper_read_batch`` אינו במפה, בהחלטה. lines ושאר הפרמטרים שהקולבק מחפש יושבים אצלו בתוך הפריטים ולא ברמה העליונה, ובאץ« אחד מערב קריאה מלאה, טווח וסעיף — אין לו מצב קריאה אחד לתייג. תווית לכל פריט הייתה מחייבת לפתוח את items לקולבק, כלומר לקרוא את הארגומנטים ש-$mcp_parameters חוסם בכוונה. מה שנשלח עליו הוא שם הכלי והמשך בלבד, ולכן באץ« הוא אירוע אחד בדשבורד, ולא אירוע לכל פריט (ראו קריאה קבוצתית — codekeeper_read_batch).

התווית נוספת רק לקריאת כלי מבין הכלים שמקבלים lines. ה-SDK מריץ את הקולבק על כל אירוע, וגרסה שנפלה ל-full בברירת מחדל תייגה גם את לחיצת היד ואת tools/list — אירועים שלא קראו שום קובץ, שהיו נושאים תווית של קריאת קובץ מלא.

מה הדשבורד סופר מהתווית, ומה לא. נקודת הקצה ck_mcp_navigation_cost_v2 סופרת את outline_reads ואת content_reads רק על אירועי $mcp_tool_call של codekeeper_get_repo_file (countIf על שם הכלי; נקרא מהגדרת נקודת הקצה ב-PostHog, 2026-09-28). כלומר התוויות של codekeeper_get_file — outline מ-toc, section, query — אינן נכנסות לאף עמודה בדשבורד היום, ותווית שגויה על לחיצת יד לא הייתה מגדילה אותן. הן קיימות כדי שהאירוע עצמו יגיד את האמת: כל שאילתה על ck_read_mode — בנקודת קצה עתידית, או ישירות על האירועים — קוראת את התווית כפי שהיא.

מה כבוי בכוונה. enable_conversation_id מזריקה ארגומנט נוסף וגם מוסיפה הנחיה לתוצאת הכלי, כלומר עורכת את מה שהכלי מחזיר לקורא שלו — וזה החוזה של הכלי, לא של האנליטיקס. גם capture_exception_code_variables כבוי במפורש: הוא לוכד משתנים מקומיים, ובשרת הזה המשתנים המקומיים מחזיקים תוכן קבצים.

מה כן דלוק: ``report_missing``. היא מוסיפה כלי וירטואלי אחד, get_more_tools, שהסוכן קורא לו כדי לומר איזו יכולת חסרה לו. היא אינה נוגעת באף כלי קיים, וגם הסינון של כלי האדמין ממשיך לעבוד (get_more_tools מתווסף אחרי הסינון ולכן גלוי לכולם, כפי שהוא אמור להיות). המשפט שהסוכן כותב שם מגיע כ-$mcp_intent על אירוע $mcp_missing_capability, וזה המקום היחיד שבו המאפיין נוצר (לכידת הכוונה (context) — כבויה).

בלוק ה-``instructions`` נוקב ב-``get_more_tools`` רק כשהוא באמת ברשימה. instrument() של posthog.mcp אינו זורק כשהוא נכשל אלא מחזיר ידית ריקה, ולכן instrument_mcp_server אינו מסתמך על כך שהקריאה עברה: הוא בודק אם ה-handler של tools/list הוחלף בעטיפה שמוסיפה את הכלי, ומחזיר את התשובה. כשלא — המשפט אינו נכנס לבלוק, ושורת WARNING אומרת זאת. השם עצמו הוא MISSING_CAPABILITY_TOOL_NAME ב-mcp_server/analytics.py, ומועבר ל-SDK במפורש, כך שהבלוק וה-SDK אינם יכולים לנקוב בשני שמות.

קונפיגורציה. שני משתני סביבה בשירות ה-MCP: POSTHOG_PROJECT_TOKEN ו-POSTHOG_HOST. חסר אחד מהם — בפרודקשן השרת עולה רגיל והמדידה פשוט לא פועלת (עם אזהרה בלוג), ובסביבת פיתוח העלייה נכשלת ברעש, כדי ש“אין אירועים“ לא ייראה כמו ”הכל תקין“. ”פרודקשן“ הוא ENVIRONMENT/ENV ששווה production או prod, וכן המצב שבו אף אחד מהם אינו מוגדר; כל ערך אחר נחשב פיתוח. הטוקן לעולם אינו בקוד ואינו בריפו.

הערה

כשהמדידה כבויה (אין טוקן, אין host) האינסטרומנטציה אינה רצה כלל — ולכן גם get_more_tools אינו ברשימת הכלים. סוויטת הבדיקות רצה בלי קונפיגורציה של PostHog, והטסטים שבודקים את המצב הדלוק מגדירים לקוח בעצמם.

ניקוז. posthog.shutdown רשום ב-atexit, ובנוסף ה-lifespan של אפליקציית ה-ASGI מנקז את האירועים שעדיין באוויר לפני שהלולאה של uvicorn נסגרת. atexit לבדו אינו מספיק: הלכידה האוטומטית היא asyncio.Task על אותה לולאה, ומשימה שנשארה תלויה כשהלולאה נסגרת לא מגיעה בכלל לתור השליחה.

מדיניות הפרטיות של המחבר (/privacy#mcp)

עמוד מדיניות הפרטיות של הוובאפ (webapp/templates/privacy.html) כולל סעיף על המחבר, עם העוגן mcp. הכתובת /privacy נמסרת בהגשה לספריית המחברים של Anthropic: הטופס דורש כתובת של מדיניות פרטיות, והמדיניות של הספרייה דורשת שהיא תסביר איזה מידע נאסף, איך משתמשים בו וכמה זמן שומרים אותו (Anthropic Software Directory Policy, סעיף 3A). העמוד עצמו, והסיבה שהנתיב שלו לא משתנה, מתוארים ב-עמוד מדיניות הפרטיות (/privacy). הסעיף כתוב באנגלית, כמו שאר העמוד.

העובדות שהסעיף נשען עליהן, ומי מצמיד כל אחת. מי שמשנה אחת מהן מפיל טסט, ומגיע מהטסט לעמוד. בכל המקרים הטסט ב-tests/test_privacy_page.py, אלא אם כתוב אחרת:

  • אורך החיים של טוקנים והעלאות. הסעיף נוקב בשעה, ב-30 יום וב-10 דקות. test_the_lifetimes_the_mcp_section_states_are_the_ones_in_the_code גוזר את המספרים מ-ACCESS_TTL_SECONDS, ‏``REFRESH_TTL_SECONDS`` (mcp_server/oauth_store.py) ו-UPLOAD_TTL_SECONDS (mcp_uploads.py), ונכשל גם על משך אחר שמופיע בסעיף בלי קבוע מאחוריו.

  • רק hash נשמר, ורשומות שפג תוקפן נמחקות לבד. test_connector_tokens_are_stored_only_as_a_hash_and_expire_out_of_the_database כותב קוד, טוקן גישה וטוקן רענון דרך OAuthStore, וטוקן אישי דרך MCPTokenStore, ובודק שהערך הגולמי לא מופיע במסמך שנכתב. הוא גם בודק שקיים אינדקס ה-TTL על expires_at באוסף הטוקנים, ש-OAuthStore מצהיר עליו בבנאי. כל כתיבה לארבעת האוספים של OAuth היא מתודה של המחלקה הזו — הוספה (save_client, ‏``create_txn``, ‏``save_code``, ‏``save_token``), עדכון (revoke_token) ומחיקה (delete_txn, ‏``delete_code``) — ולכן כל אחת רצה על מופע שהבנאי שלו כבר ביקש את האינדקסים. אף מודול אחר לא נוקב בשמות האוספים (test_nothing_outside_the_store_names_its_collections ב-tests/test_mcp_oauth_store.py). _ensure_indexes יוצר כל אינדקס לבד, ומשאיר את השרת עולה גם כשאינדקס נכשל. כשהשרת של המסד ענה וסירב לאינדקס, הלולאה ממשיכה לאינדקס הבא: כשל של unique או של TTL נרשם כ-ERROR, עם הסמן oauth_index_failed והאוסף, המפתח והאפשרויות, ואינדקס הביצועים subject נרשם כ-WARNING. כשהמסד לא ענה (ConnectionFailure), הלולאה עוצרת, כי כל קריאה נוספת הייתה מחכה שוב את serverSelectionTimeoutMS. נרשמת שורת ERROR אחת שנוקבת בכל האינדקסים שלא נוסו, והם מתבקשים שוב בעלייה הבאה (tests/test_mcp_oauth_store.py). לא נבדק שהאינדקס קיים במסד של הפרודקשן, ולכן שורת oauth_index_failed ברמת ERROR בלוג של שירות ה-MCP פירושה שהמשפט על המחיקה האוטומטית במדיניות כבר לא נכון.

  • אין מזהה משתמש ב-PostHog, ואין פרמטר מוזרק שמבקש לתאר את הקריאה. test_posthog_gets_no_user_identity_and_no_intent_option לוכד את האופציות ש-instrument_mcp_server מעביר ל-posthog.mcp: אין identify, ‏``context`` הוא False, ואין intent_fallback.

  • המקום היחיד שבו המחבר מבקש מהסוכן לתאר את המשימה הוא working_on של תגובה על פתק. הפרמטר הוא חובה ב-codekeeper_comment_note, עד MAX_WORKING_ON_CHARS תווים (note_threads.py), והמשפט נשמר עם התגובה ומוצג ליד שם הסוכן. test_the_only_task_description_the_connector_asks_for_is_working_on_on_a_comment עובר על הסכימות של כל הכלים הרשומים: working_on רק בכלי הזה, ו-context באף כלי. הבדיקה היא לפי שם הפרמטר, ולכן פרמטר חדש בשם אחר שמבקש תיאור משימה לא ייתפס בה. שהאירוע בפועל לא נושא כוונה, לא נושא תוכן ולא בונה פרופיל, נבדק בזרימה אמיתית ב-test_a_real_instrumented_tool_call_reaches_posthog_with_no_content (tests/test_mcp_analytics_privacy.py), ואיך זה קורה מתואר ב-מדידת שימוש (PostHog MCP Analytics) וב-לכידת הכוונה (context) — כבויה.

  • אין כלי מחיקה. test_the_connector_has_no_tool_that_deletes בונה את השרת האמיתי (build_mcp), כולל כלי האדמין, ובודק שאף שם של כלי רשום לא מכיל מילה של מחיקה.

מה הסעיף אומר בלי טסט שמצמיד אותו לעמוד, ולמה.

  • הלוגים: כמה זמן Render שומר אותם תלוי בתוכנית של החשבון ולא בקוד, ולכן הסעיף אומר ”according to its log retention“ ולא נוקב במספר.

  • ההתראות: ההתראה כששומרים קובץ או מגיבים על פתק נבדקת בטסטים של מסלול השמירה (התראה כשסוכן שומר קובץ), אבל אף טסט לא קושר אותם לעמוד.

  • השיתוף: רשימת הספקים (MongoDB Atlas, ‏Render, ‏PostHog) היא תצורת הפריסה ולא ערך בקוד.

  • הניתוק: ביטול טוקן על ידי האפליקציה עובר בנקודת /revoke של ה-SDK (RevocationOptions ב-mcp_server/app.py), והסעיף לא מבטיח שהאפליקציה קוראת לה.

  • פרטי הרישום: פרטי הרישום של האפליקציה נשמרים כמו שהיא שולחת אותם (register_client ב-mcp_server/oauth_provider.py).

שינוי שמחייב עדכון של הסעיף, וגם הודעה ל-Anthropic: מדיניות הספרייה דורשת לעדכן אותם על שינוי מהותי ב-”data practices“ (סעיף 3H). למשל: הדלקה מחדש של context, ‏``identify`` שמעביר מזהה משתמש, שדה חדש ש-PostHog מקבל, או כלי שמוחק.

אבטחה — עקרונות

  • זהות תמיד מהטוקן; טוקנים נשמרים כ-hash בלבד ומוצגים פעם אחת.

  • ראוט שנרשם ידנית (לא /mcp) אינו מוגן במצב OAuth — הוא חייב לקרוא ל-authenticate_bearer בגוף שלו. ראו פריימר לסוכן — GET /api/agent/primer.

  • קוד הרשאה ו-refresh token חד-פעמיים (זיהוי replay); refresh לא מרחיב הרשאות.

  • SECRET_KEY חלש/ריק/ברירת-מחדל — מצב OAuth מסרב לעלות (fail-closed).

  • מסך האישור מציג במדויק קריאה בלבד לעומת קריאה וכתיבה.

  • כלי האדמין: הסתרה מ-tools/list היא נוחות בלבד — האכיפה האמיתית היא בגוף כל כלי.

פתרון תקלות

סימפטום

כיוון

401 invalid_token

הטוקן בוטל/פג או ששירות ה-MCP מחובר ל-MongoDB אחר מזה שהנפיק אותו

404 על /api/agent/primer

ה-URL מצביע על הוובאפ במקום על ה-MCP host — האנדפוינט חי רק על ה-MCP

204 על /api/agent/primer

תקין, לא תקלה: שדה ”הוראות לסוכן“ ריק. מלאו אותו ב-/settings

הפריימר לא נטען, בלי שום הודעה

כל כשל של ההוק מדפיס שורה, ולכן זה 204 או הוק שלא רץ בכלל — למשל פלאגין שכבוי בחשבון. הבדיקות שמבדילות בין השניים בתיבה שבסעיף פריימר לסוכן — GET /api/agent/primer

הפריימר לא מתעדכן

ה-cache הוא 60 שניות — המתינו דקה אחרי השמירה

שורת ההוראות לסוכן לא נטענו שמסתיימת ב-(כנראה דיפלוי)

שירות ה-MCP היה בדיפלוי כשהסשן נפתח: ההוק שבפלאגין ניסה שוב לאורך כל התקציב שלו וקיבל 502, 503 או 504 בכל פעם. פתחו סשן מחדש בעוד דקה. אם השורה חוזרת בכל פתיחה, זה כבר לא דיפלוי — הבעיה היא הכתובת (CODEKEEPER_PRIMER_URL) או השירות עצמו. ראו פריימר לסוכן — GET /api/agent/primer

שורת לא הצלחתי להגיע לשרת (curl …)

לא חזרה תשובה בכלל, ולכן זה לא דיפלוי — Render עונה 502 גם באמצע דיפלוי. בדקו את הרשת של הסביבה (למשל מדיניות רשת שחוסמת את ה-host) ואת הכתובת. המספר שבשורה הוא קוד היציאה של curl, והמשמעות שלו בפרק EXIT CODES ב-curl --manual

421 Invalid Host header

MCP_ALLOWED_HOSTS מגדיר host שלא תואם; ריק = הבדיקה כבויה

bad_assertion במסך האישור

SECRET_KEY לא זהה בין הוובאפ לשירות ה-MCP

insufficient_scope בשמירה

חיבור בקריאה בלבד — חברו מחדש עם write (או /connect_claude write)

file_exists בשמירה

כבר קיים קובץ בשם הזה, ו-codekeeper_save_file אינו דורס: שמירה כזו הייתה יוצרת גרסה חדשה, והתוכן הקודם היה נעלם מהחיפוש ומעמוד הקובץ. לעריכה — codekeeper_edit_file / codekeeper_multi_edit_file / codekeeper_append_file, או שמרו בשם אחר. ואם רק התיאור הוא מה שהתיישן — codekeeper_update_file_description

description_too_long בעדכון תיאור

התיאור ארוך מ-FILE_DESCRIPTION_MAX_CHARS. max_chars הוא התקרה ו-actual_chars האורך שנשלח — שניהם בתווים, לא בבתים: טקסט עברי הוא בערך פי שניים בבתים, ונמדד בתווים. קצרו עד max_chars ושלחו שוב; שום דבר לא נכתב. הוא נדחה ולא נחתך בכוונה, וטקסט שזהה לתיאור השמור עובר בכל אורך — ראו עדכון תיאור בלי גרסה חדשה

description_saved: false בשמירה

הקובץ נשמר, והתיאור לא: הוא ארוך מ-FILE_DESCRIPTION_MAX_CHARS תווים (max_chars, actual_chars — תווים, לא בתים). אל תשמרו שוב — זו תהיה file_exists. קצרו את התיאור וקבעו אותו ב- codekeeper_update_file_description. ראו תיאור ארוך בשמירה — description_saved

not_found בעדכון תיאור

אין קובץ פעיל בשם הזה אצל המשתמש המאומת. השם נלקח כפי שהוא מופיע ב-codekeeper_list_files

existence_check_unavailable בשמירה

בדיקת הקיום נכשלה — זה אינו ”הקובץ אינו קיים“. שום דבר לא נשמר; נסו שוב בעוד רגע. אותה הבחנה כמו ב-repo_list_unavailable

upload_not_found בשמירה או בהוספה

אין העלאה חיה במזהה הזה למשתמש המאומת: היא פקעה (UPLOAD_TTL_SECONDS), כבר נצרכה — כל העלאה נצרכת פעם אחת — או שהועלתה בטוקן של משתמש אחר. התשובה אינה מגלה איזה מהשלושה. שום דבר לא נכתב; העלו שוב, או שלחו את התוכן inline. ראו העלאת תוכן בלי לעבור דרך המודל

upload_corrupted בשמירה או בהוספה

ההעלאה שנשמרה אינה תואמת את ה-hash שחושב כשהגיעה, ולכן לא נכתב כלום והיא נמחקה — ואם האחסון לא ענה למחיקה, היא תפקע ב-TTL. זו התשובה גם כשהכלי היה נכשל מסיבה אחרת, כמו התקרה או file_exists: השלמות נבדקת ראשונה, עם השליפה. העלו שוב. בלוג השירות — שורת ERROR refused a corrupted upload עם הסיבה. אם השורה חוזרת, האחסון הזמני (mcp_uploads) משבש טקסט: זו תקלה לחקור, ולא משהו שהסוכן יכול לפתור. ראו העלאת תוכן בלי לעבור דרך המודל

429 too_many_pending_uploads מ-PUT /api/agent/upload

יש כבר MAX_PENDING_UPLOADS העלאות שלא נצרכו ולא פקעו. צרכו אותן (upload_id בשמירה), או המתינו retry_after_seconds עד שהישנה ביותר פוקעת

503 upload_storage_unavailable מ-PUT /api/agent/upload, או upload_storage_unavailable בשמירה

אינדקס ה-TTL של mcp_uploads לא אומת, או שהמסד לא ענה. בלוג השירות — db_mcp_uploads_index_missing בעלייה, או שורת uploads_expire_on_time index not confirmed. השער מנסה לבנות שוב אחרי השהיה; עד אז שלחו את התוכן inline

הפקודה בתיאור upload_id, בתיאור file_id או בתיאור codekeeper_list_versions מציגה <mcp-host>

השירות לא יודע את הכתובת הציבורית שלו: MCP_SERVER_URL לא הוגדר (מצב PAT מקומי), או שהוגדר ונדחה כי אינו כתובת http/https נקייה (public_base_for ב-mcp_server/public_url.py, בדיקה אחת לשתי הפקודות). במקרה השני בלוג העלייה שורת WARNING אחת, MCP_SERVER_URL not used for the commands in the tool descriptions, עם הסיבה ובלי הכתובת עצמה — מה שנדחה עלול להיות סיסמה בכתובת. הראוטים עצמם עובדים: החליפו את <mcp-host> בכתובת השירות

curl: (22) The requested URL returned error: 404 בפקודת ההורדה

אין גרסה כזו שלך: המזהה שגוי, של משתמש אחר, או שהשם לא קיים. מזהים תקינים — id ב-codekeeper_list_versions או file.id ב- codekeeper_get_file. 400 אומר שהבקשה עצמה לא בצורה הנכונה, והקוד בגוף נוקב בסיבה (ראו הורדת קובץ לדיסק בלי לעבור דרך המודל); כדי לראות אותו, הריצו שוב בלי -f ובלי -o

admin_only בכלי ריפו

ה-user_id אינו ב-ADMIN_USER_IDS בשירות ה-MCP. חל גם על codekeeper_list_repo_notes / codekeeper_create_repo_note

repo_not_found ביצירת פתק ריפו

שם הריפו אינו ברשימת המשוקפים. codekeeper_list_repos מציג את השמות המדויקים

repo_file_not_found ביצירת פתק ריפו

הנתיב אינו בעץ המשוקף. הנתיב נלקח כפי שהוא מופיע ב-list_repo_tree

repo_list_unavailable / repo_file_unavailable

השאילתה על המניפסט נכשלה — זה אינו ”לא קיים“. אל תתקנו את הנתיב; נסו שוב

collection_not_found בשיוך לאוסף

ה-collection_id אינו קיים או אינו שלך. codekeeper_list_collections מציג את המזהים

file_not_found בשיוך לאוסף

השם אינו של קובץ שמור. השיוך אינו יוצר קובץ — שמרו קודם ב-save_file

snapshot_failed בעדכון פתק

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

version_not_found

מספר הגרסה אינו בטווח שנשמר (20 האחרונות). codekeeper_list_note_versions מציג מה קיים

ambiguous_match ב-note_str_replace

old_string מופיע יותר מפעם אחת. הארוכו, או העבירו replace_all

conflict ב-note_str_replace

הפתק השתנה בין הקריאה לכתיבה (עריכה מקבילה). קראו אותו מחדש ונסו שוב — שום דבר לא נדרס

duplicate_title בפתק

השם כבר תפוס — על אותו לוח, או על אותו קובץ בריפו

invalid_line_range בקריאת קובץ

lines אינו [start, end] תקין: אורך שונה משניים, ערך אפס או שלילי, או start גדול מ-end

range_out_of_bounds בקריאת קובץ

start מעבר לסוף הקובץ. range.total_lines בקריאה רגילה יגיד כמה שורות יש בפועל

not_markdown ב-codekeeper_get_file עם toc או section

הקובץ אינו Markdown לפי הכלל של הוובאפ — שפה markdown/md או סיומת .md/.markdown. קראו אותו ב-lines או ב-query, כמו שה-hint אומר — ראו קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section)

too_large_for_sections

הקובץ השמור גדול מ-MAX_FILE_SIZE_FOR_DISPLAY בבתים של UTF-8 (bytes ו-max בתשובה) — קובץ עברי מגיע לשם בחצי מהתווים. הקובץ קריא ב-lines וב-query

empty_section

section ריק או רווחים בלבד. המפה היא toc=true — ומשם מעתיקים את הכותרת. (רווחים בלבד שארוכים מ-MAX_SECTION_CHARS הם section_too_long.)

toc_and_section / section_and_query וקודי הזוגות האחרים

ארבעת מצבי הקריאה של codekeeper_get_file — toc, section, query ו-lines — אינם מצטברים. בחרו אחד; הקוד אומר איזה שניים התנגשו

max_chars_without_section / offset_without_section

העימוד הוא של סעיף, ולכן בלי section הוא נדחה — גם עם toc=true

max_depth_without_toc

max_depth מגביל מפה, וב-codekeeper_get_file מפה יש רק עם toc=true — או בתוך section_not_found של section. בלי שניהם הוא נדחה, ולא נבלע

במפה חסרות כותרות, ו-toc_truncated כבוי

נשלח max_depth, והמפה מוגבלת בכוונה. hidden_subsections על הכותרות שבגבול אומר כמה הוסתר תחת כל אחת, ובתשובת המפה (mode: toc) section_count הוא מספר הכותרות כולן. קראו פרק בשמו — הוא כולל את תת-הסעיפים שלו — או בקשו את המפה עם max_depth גדול יותר. ראו איך docs_get_section מוצא כותרת

section_too_long

section ארוך מ-MAX_SECTION_CHARS (max_chars ו-actual_chars בתשובה). אין כותרת אמיתית באורך כזה: השאילתה כנראה הכילה משהו אחר מכותרת — העתיקו את השם מהמפה

סעיף חזר עם פחות מ-max_chars תווים, ו-truncation_reason: "byte_budget"

העמוד לא נכנס ב-OUTPUT_BYTE_BUDGET בתים ונגמר מוקדם, על גבול תו — זו לא שגיאה. המשיכו מ-next_offset, כמו בכל עמוד. ראו איך docs_get_section מוצא כותרת

section_too_large

הכותרות שהתשובה נושאת גדולות מהתקציב לבדן, כך שגם עמוד ריק אינו נכנס. קראו את הסעיף ב-lines לפי line_range שבתשובה. בקובץ שמור הסיבה יכולה להיות גם המטא-דאטה שלו — ראו answer_too_large

toc_truncated, suggestions_truncated או candidates_truncated דלוקים, והרשימה קצרה מהתקרה שלה

הרשימה נחתכה מהסוף כדי שהתשובה תיכנס ב-OUTPUT_BYTE_BUDGET — זו הסיבה השנייה של אותו דגל, ולא שגיאה. כותרת שחסרה במפה נקראת בשמה כשאין עוד כותרת באותו שם; מועמד שחסר מופיע במפה, עם line_range; ומה שחסר גם במפה וגם במועמדים — query מוצא את השורות שלו, ו-lines קורא משם. ראו איך docs_get_section מוצא כותרת

ambiguous_section גם כשביקשתם בשם הכותרת המלא

השם חוזר בקובץ, והכלי אינו מנחש. קראו לפי line_range של המועמד — ב-codekeeper_get_file עם lines — או את ההורה מה-breadcrumb בשמו. ראו איך docs_get_section מוצא כותרת

answer_too_large

התשובה אינה נכנסת בתקציב, ואין בה מה לקצר בלי לאבד משהו בשקט. ה-hint אומר מה לבקש במקום: בקריאה מלאה — lines (ובקובץ Markdown גם toc/section, ובריפו גם outline, ו-read_with עם whole_document: true כשכלי התיעוד מגיש את הקובץ — הקובץ כולו שם, מדופדף); ברשימת פתקים — include_content=false ואז codekeeper_get_note. במפה ובסעיף: גם בלי אף פריט ברשימות התשובה גדולה, ומה שנשאר בה הוא המטא-דאטה של הקובץ — תיאור ארוך או תגיות ענקיות — שנוסעת על כל תשובה על הקובץ. הסירוב עצמו מוותר על התגיות ועל התיאור כדי להיכנס (file.tags_truncated, file.description_bytes). השורש — כותבים שאינם אוכפים תקרה — ב-#3489. ראו תקרת התשובה — מה כלי מצהיר, ומי אוכף

file.tags_truncated: true

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

file.description_bytes, ו-file.description חסר

התיאור של הקובץ גדול מדי לתשובה הזו, ולכן ירד שלם; description_bytes הוא גודלו בבתים, וה-hint מפנה ל-codekeeper_update_file_description, שמחליף אותו בקצר יותר. התיאור שמור כמו שהוא — רק התשובה הזו לא נשאה אותו. ראו תקרת התשובה — מה כלי מצהיר, ומי אוכף

טווח שחזר עם range.truncation_reason: "byte_budget"

הטווח לא נכנס ב-OUTPUT_BYTE_BUDGET בתים ונגמר מוקדם, על גבול שורה — זו לא שגיאה. המשיכו ב-lines=[end + 1, ...]. ראו קריאת טווח שורות

page_too_large ב-codekeeper_list_repo_tree

העמוד אינו נכנס בתקציב, והוא נדחה כולו ולא נחתך, וה-hint אומר את זה. בקשו per_page קטן יותר — include_stats מכביד כל רשומה. ראו גודל וספירת שורות ברשימת הריפו

answer_too_large עם hint כללי (”Ask for less“), ושורת answer_size_net בלוג

באג בכלי, לא התנהגות צפויה. הרשת שב-AdminAwareFastMCP.call_tool תפסה תשובה שהכלי היה צריך להתאים בעצמו. בקשו פחות כדי להמשיך, ודווחו על הכלי ועל הארגומנטים. ראו תקרת התשובה — מה כלי מצהיר, ומי אוכף

שורות answer_size_fit בלוג, ברמת INFO

התנהגות צפויה: כלי חתך או סירב כדי להיכנס בתקציב, והשורה אומרת איזה כלי, עם אילו שמות ארגומנטים וכמה. היא מתארת רק את התשובה שהלקוח קיבל. הרבה שורות מאותו כלי ואותה צורה הן הסימן ש-OUTPUT_BYTE_BUDGET צר לתהליך הזה. answer_too_large בשורה שיש לצידה גם answer_size_net הוא הסירוב של הרשת — באג בכלי, כמו בשורה שלמעלה. ראו תקרת התשובה — מה כלי מצהיר, ומי אוכף

query="null" או section="null" מחזירים את הקובץ המלא, או שקובץ ששמו null אינו נמצא לפי file_name

הלקוח שלח null של JSON ולא את המילה: claude.ai ו-Claude Code ממירים את המילה null בפרמטר שהסכימה שלו מתירה null (נמדד ב-2026-09-29). ראו מצבי הקצה ב-קריאה לפי סעיף בקובץ Markdown שמור (toc ו-section). קובץ ששמו null נקרא לפי file_id

query_too_long בחיפוש פתקים

שאילתה ארוכה משם פתק אפשרי לא תתפוס דבר. קצרו אותה

invalid_query בחיפוש פתקים

יש בשאילתה תו NUL, ומונגו דוחה $regex כזה. הסירו אותו. הבדיקה היא note_search_needle_error ב-sticky_notes_target.py, אותה בדיקה של החיפוש בוובאפ — ראו את ההערה על codekeeper_search_notes ב-איך מחפשים קובץ ופתק — codekeeper_search_code ו-codekeeper_search_notes

sync_in_progress

רענון רץ ברגע זה — נסו שוב לפי retry_after

אין שום לוג מהשרת, גם כשהכול תקין

מאז #3393 ‏``mcp_server/app.py`` מגדיר לוגים בייבוא (‏``LOG_LEVEL``, ברירת מחדל INFO), ובעליית השירות אמורה להופיע שורת mcp dispatch capacity. אם גם היא חסרה — הרמה שבתוקף גבוהה מ-INFO, או שהתהליך לא הגיע ל-lifespan של ה-ASGI והכשל יופיע לפניה. היעדר שורה של כלי אינו סימן שהכלי לא נקרא: קריאות אינן רושמות שורה לכל קריאה — רק כתיבות (זמן ההמתנה בתור וזמן הריצה) — ומדידת השימוש עוברת ב-PostHog וגם סירוב אינו רושם שורה, וזו החלטה ולא פער (#3432, SUGG-022): תשובת {"ok": false, "error": ...} היא תשובה תקינה של הפרוטוקול — הקורא ביקש משהו שאין, או שאסור — ולא תקרית של השרת; מסלולי הסירוב בשכבת המטפלים אינם רושמים דבר, בכל הקבצים באותה מידה. השורה היחידה שנרשמת היא על תקלת תצורה שרק המפעיל יכול לתקן (repo_not_configured), וזה הקו: לוג למה שהמפעיל צריך לדעת, תשובה למה שהקורא צריך לדעת. ואין היום מקום שסופר סירובים לפי סוג: PostHog מודד כל קריאה שהגיעה לגוף כלי, אבל סירוב מגוף כלי נרשם שם כהצלחה (is_error מסומן רק על חריגה), וסירוב מכסה (rate_limited) אינו מגיע למדידה כלל — הוא מוכרע לפני התפר שהיא עוטפת. הפער מתועד באישו #3442; ראו גם ”מה נרשם בלוג“ ב-גבולות הבקשה — גודל הגוף והקצב

repo_or_ref_not_found

כבר אינו מוחזר. codekeeper_list_repo_tree איחד בו ריפו בלי מראה, שם פגום, ענף שלא במראה ומראה שבורה; היום כל אחד מהם נקרא בשמו — repo_not_mirrored, invalid_ref, ref_not_mirrored או read_failed. ראו ענף שלא במראה, מול קובץ שלא קיים

repo_not_mirrored

למארח אין עותק של הריפו. זה אינו שם קובץ שגוי — אל תנסו נתיב אחר; בדקו את המראה (REPO_MIRROR_PATH, autosync — ריפו חסר משוכפל במעבר הבא). ריפו שאין לו רשומה ב-repo_metadata הוסר, והמראה שלו נמחקת במעבר הראשון שאחרי ההסרה (רענון אוטומטי (autosync)). בזמן sync התשובה היא sync_in_progress

ref_not_mirrored

המראה של המארח הזה לא מכירה את הענף או את ה-SHA — מה שאינו אומר שהם אינם קיימים ב-GitHub. ענף שנדחף בלי שינוי בענף הראשי יגיע למראה רק עם השינוי הבא בענף הראשי, והבקשה עצמה לעולם אינה מושכת אותו. ראו ענף שלא במראה, מול קובץ שלא קיים

invalid_ref

שם ה-ref פגום (לא עבר את BASIC_REF_PATTERN), ו-git לא נשאל עליו בכלל. תקנו את השם

read_failed בכלי ריפו

הריפו נמצא והקריאה נכשלה — למשל מראה שבורה, ששירות המראה רושם עליה WARNING עם ה-stderr של git. אם זה חוזר, בדקו את המראה בדיסק

path_outside_root ב-codekeeper_docs_get_section

הנתיב פותר אל מחוץ לשורש התיעוד של הריפו (root בתשובה). נתיב מלא נלקח כמות שהוא; slug בלי / מעוגן לשורש

הסוכן שמר קובץ ולא הגיעה התראה

לפי הסדר: ‏(1) יש מנוי Push פעיל בדפדפן? נרשמים ב-/settings, ובלי מנוי האירועים נפסלים מיד. ‏(2) MCP_PUSH_NOTIFICATIONS_ENABLED כבוי על שירות ה-MCP? ‏(3) האם הוובאפ בכלל רץ — הוא ששולח, לא ה-MCP. ‏(4) עברה פחות מדקה? יש עיכוב של סבב. ‏(5) אם כל אלה תקינים, ייתכן שהמסירה נחתכת בתקרת הזמן — ראו תקרת זמן למסירה מקומית. לאבחון: /settings/push-debug

missing_items ב-codekeeper_read_batch

items היא רשימה ריקה. אין מה לקרוא, ולכן זה סירוב של הקריאה כולה ולא באץ« ריק שהצליח

too_many_items ב-codekeeper_read_batch

יותר פריטים ממה שבאץ« אחד נושא. max בתשובה הוא התקרה שבתוקף — MAX_BATCH_ITEMS, או מכסת הקצב לדקה כשהיא נמוכה ממנו. הבאץ« נדחה ולא נחתך; פצלו אותו לכמה קריאות

item_too_large בפריט של באץ«

הפריט לבדו גדול מכל מה שתשובה יכולה להכיל. read_with הוא הכלי הבודד שיקרא אותו, ופריט קובץ יכול גם לצמצם את עצמו ב-lines

invalid_item בפריט של באץ«

הפריט אינו תואם לסכימה, ו-problems אומר איפה ומה, בלי להדהד את הערך. השכיח: ref בפריט (פריטים אינם מקבלים ref), outline בפריט קובץ, או lines שאינו רשימה של מספרים שלמים. רק הפריט הזה נכשל. רשימה באורך שגוי, כמו [5], דווקא עוברת את הסכימה, וחוזרת מהכלי כ-invalid_line_range — בדיוק כמו בכלי הבודד

פריטים ב-unread של באץ«

הם לא נקראו, וכל מה שלפניהם שלם. unread_reason אומר למה: byte_budget — התשובה התמלאה, או timeout — עברו DEADLINE_SECONDS. בשני המקרים שולחים שוב את מה שב-unread, בקריאה חדשה

rate_limited על באץ«, כשנראה שנשארה מכסה

באץ« נשקל כמספר הפריטים שלו, והמכסה נגבית כולה או לא בכלל: באץ« של 20 פריטים כשנשארו 15 יחידות נדחה כולו, ו-retry_after_seconds הוא עד שכל העשרים נכנסים. באץ« קטן יותר עובר מיד

conflict בעריכת קובץ

הקובץ השתנה מאז שקראתם אותו, וביקשתם בדיקה (expected_content_sha256). שום דבר לא נכתב. file בתשובה הוא הגרסה הנוכחית, בלי התוכן. קראו שוב ב-codekeeper_get_file, בנו את העריכה על התוכן הנוכחי, ושלחו שוב — ראו עריכה על מה שקראתם — expected_content_sha256

invalid_utf8 בכלי הכתיבה של קבצים

הטקסט נושא surrogate בודד — חצי של זוג, ש-UTF-8 אינו יכול לקודד והמסד אינו שומר. הוא נוצר מ-escape של JSON שהחצי השני שלו חסר. שום דבר לא נכתב, והעלאה שהייתה בקריאה נשארת. שלחו את התו עצמו, או את שני חצאי הזוג. ב-codekeeper_multi_edit_file זוג כזה נענה invalid_edit, עם index והשדה. ראו ”טקסט ש-UTF-8 אינו יכול לקודד“ ב-טביעת אצבע לתוכן — content_sha256 ו-content_changed

invalid_expected_content_sha256

הערך אינו hash: צריך 64 ספרות הקס, בדיוק file.content_sha256 כפי שחזר מ-codekeeper_get_file. שום דבר לא נקרא ולא נכתב

unicode_escapes_mismatch בעריכת קובץ

הצהרתם ב-expected_unicode_escapes כמה escapes של יוניקוד יש ב-old_string וב-new_string יחד, והמחרוזות הגיעו לכלי עם סכום אחר: expected הוא מה שהוצהר, received הוא הסכום שנספר במה שהגיע, received_in_old_string ו-received_in_new_string אומרים כמה הגיע בכל מחרוזת — כלומר איזו מהן הומרה — ובזוג של codekeeper_multi_edit_file יש גם index. שום דבר לא נקרא ולא נכתב. השכיח: הלקוח הפך escape לתו לפני שהקריאה יצאה. ודאו שהמספר שהצהרתם נכון — כל escape שכתבתם בקריאה נספר, ומי שרוצה את התו עצמו שולח את התו — ושלחו את אותה קריאה פעם אחת נוספת — ההמרה משתנה מקריאה לקריאה. סורבה שוב: אמרו למשתמש שמהלקוח הזה אי אפשר לכתוב את הטקסט הזה. כשהזוגות באו מ-edits_upload_id אין טעם לשלוח שוב את אותו מזהה: בקובץ, לוכסן שנועד להיות טקסט נכתב כשני לוכסנים — תקנו את הקובץ והעלו אותו שוב. ראו escape של יוניקוד שהגיע כטקסט — expected_unicode_escapes

invalid_expected_unicode_escapes

הערך אינו מספר שלם, 0 ומעלה. שום דבר לא נקרא ולא נכתב. ראו escape של יוניקוד שהגיע כטקסט — expected_unicode_escapes

סירוב עם index ב-codekeeper_multi_edit_file

הזוג במקום הזה (מאפס) נכשל, בקוד של codekeeper_edit_file — או code_too_large עם max, כשהתוצאה שלו הייתה חוצה את התקרה. שום דבר לא נכתב, גם לא הזוגות שלפניו. תקנו אותו ושלחו שוב את כל הבאץ« — וכשהזוגות באו מ-edits_upload_id, תקנו את הקובץ, העלו אותו שוב והעבירו את המזהה החדש. כש-occurrences שונה מ-occurrences_in_stored_version, זוג קודם בבאץ« שינה את הטקסט שהזוג הזה מחפש — ראו כמה עריכות בגרסה אחת — codekeeper_multi_edit_file

invalid_edits_upload ב-codekeeper_multi_edit_file

הקובץ שהועלה ל-edits_upload_id אינו מערך JSON של זוגות. line ו-column (מ-1) אומרים איפה הפענוח נעצר; בלעדיהם הקובץ הוא JSON תקין שאינו מערך, או שהוא מקונן עמוק מדי או מכיל מספר ארוך מדי. השכיח: לוכסן יחיד לפני תו שאינו escape של JSON (ב-JSON לוכסן שנועד להיות טקסט נכתב כשניים), או קובץ שנפתח ב-BOM. העלאה אי אפשר לתקן: תקנו את הקובץ, העלו שוב והעבירו את המזהה החדש — ראו הזוגות כקובץ — edits_upload_id

invalid_edit ב-codekeeper_multi_edit_file

זוג אינו בצורה הנכונה, ו-problems אומר איפה ומה, בלי להדהד את הערך. השכיח: מפתח שאינו אחד מארבעת שדות הזוג (old_string, new_string, replace_all, expected_unicode_escapes), replace_all כמחרוזת ("true") במקום בוליאני, expected_unicode_escapes שאינו מספר שלם של JSON, 0 ומעלה, או new_string חסר. index הוא הזוג הראשון שנכשל, ושום דבר לא נקרא ולא נכתב

missing_edits ב-codekeeper_multi_edit_file

edits היא רשימה ריקה. אין מה לערוך, ולכן זה סירוב ולא עריכה שהצליחה

too_many_edits ב-codekeeper_multi_edit_file

יותר זוגות ממה שקריאה אחת נושאת; max בתשובה הוא MAX_EDIT_PAIRS. הבאץ« נדחה ולא נחתך, ושום זוג לא הוחל. פצלו לכמה קריאות — כל אחת תהיה גרסה משלה

סעיפים שעברו לעמודים אחרים

העמוד הזה פוצל לשלושה (What’s New), וחלק מהסעיפים שלו עברו, עם התוויות שלהם, ל-עמוד הקבצים והפתקים ול-עמוד הקריאה והחיפוש. :ref: לתווית כזו ממשיך להגיע לסעיף שלה, אבל כתובת ישנה מהצורה mcp-server.html#<תווית> נפתחת עכשיו בראש העמוד הזה, כי התווית כבר אינה בו. אלה כל התוויות שעברו, בסדר אלפביתי, וכל אחת היא קישור למקום שבו היא נמצאת היום. כתובת שבסופה מספר רץ, כמו #id12, אינה תווית, ולכן אינה ברשימה.

ראו גם