שרת ה-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) השורות על כלי המראה ועל כלי התיעוד יורדות, כי הכלים האלה אינם נרשמים אז, ופתקי הריפו נשארים.
כלי משתמש (לכל משתמש מחובר):
כלי |
תיאור |
|---|---|
|
רשימת קבצים (מטא-דאטה, עם עימוד) |
|
חיפוש טקסט מלא ( |
|
תוכן מלא של קובץ (לפי שם/מזהה, אופציונלית גרסה). |
|
כתיבה: יצירת קובץ חדש. שם שכבר תפוס נדחה ב- |
|
כתיבה: מצא-והחלף מדויק בקובץ קיים ( |
|
כתיבה: כמה עריכות מדויקות בקובץ קיים, בגרסה אחת: רשימת זוגות |
|
כתיבה: הוספת טקסט לסוף קובץ קיים (גרסה חדשה). |
|
כתיבה: החלפת ה- |
|
היסטוריית גרסאות של קובץ. |
|
פתקים דביקים של קובץ (לפי |
|
פתק בודד לפי |
|
פתק בודד לפי |
|
כתיבה: יצירת פתק דביק על קובץ קיים; |
|
כתיבה: עדכון חלקי של פתק לפי |
|
כתיבה: מצא-והחלף מדויק בתוך פתק ( |
|
כתיבה: תגובה בשרשור שעל פתק — בלי לגעת בפתק עצמו. בלי |
|
הגרסאות הקודמות של פתק (מטא-דאטה בלבד: מספר, זמן, ואורך בתווים —
לא בבתים כמו |
|
תוכן של גרסה קודמת אחת. הגוף הנוכחי הוא |
|
הלוחות של המשתמש — משטחים שנושאים פתקים שאינם שייכים לשום קובץ. מייצר את לוח ברירת המחדל בקריאה הראשונה |
|
הפתקים שעל לוח יחיד (לפי |
|
כתיבה: פתק חדש על לוח — בלי קובץ. |
|
חיפוש פתק במקומות שפתק יכול לשבת בהם — קובץ, לוח, או קובץ בריפו משוקף. לפי שם כברירת מחדל; |
|
האוספים והקבצים שבתוכם |
|
כתיבה: שיוך קובץ שמור קיים לאוסף קיים. |
|
סקשן בודד מקובץ תיעוד — RST או Markdown, לפי הריפו — במקום קובץ שלם.
בלי |
כלי אדמין (דפדפן הריפו — מוסתרים וחסומים לכל משתמש אחר):
כלי |
תיאור |
|---|---|
|
הריפואים המשוקפים (מטא-דאטה) |
|
נתיבי קבצים בריפו (עימוד, סינון תיקייה/ref; בלי תוכן).
|
|
תוכן קובץ בודד (עד 500KB לקובץ מלא, עד 10MB עם |
|
חיפוש טקסט בריפו (קטעים קצרים עם path+line, עם תקרות).
|
|
כמה סעיפי תיעוד וקבצים מהמראות בקריאת כלי אחת, במקום קריאה לכל אחד — למשל כל הדפוסים שסבב ריוויו חייב לקרוא. כל פריט עובר דרך ה-handler של הכלי שהוא משקף ( |
|
פתקים דביקים על קובץ בריפו משוקף ( |
|
מפת גילוי: אילו קבצים בריפו נושאים פתקים, וכמה על כל אחד.
|
|
כתיבה: פתק חדש על קובץ בריפו משוקף. |
הערה
דפדפן הריפו הוא קריאה בלבד לצמיתות (החלטת עיצוב) — אין, ולא תתווסף,
עריכה/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 בוובאפ.
הקבועים, התקרות ואוצר המילים של התשובה
המספרים כאן חיים בקוד ונאכפים בו. ההפניה היא לשם המודול ולשם הקבוע ולא למספר שורה, כדי שהטבלה לא תצביע למקום אחר אחרי הריפקטור הבא.
הקבוע |
הערך |
מה הוא מגביל |
|---|---|---|
|
512,000 |
קריאה מלאה של קובץ. יושב ב- |
|
10,485,760 |
קריאת טווח ואאוטליין, ב- |
|
256,000 |
תקציב הבתים של תשובה אחת, כפי שהיא נשלחת, ב- |
|
1,048,576 |
גוף בקשה אחת במתודות שנושאות גוף, ב- |
|
40 |
קריאות כלים לזהות אחת בדקה, ב- |
|
8,000 |
שורות בקובץ Markdown, ב- |
|
45,000 |
טוקני בלוק בפרסור Markdown אחד, ב- |
|
4,096 |
אורך |
|
= |
אורך כותרת בודדת, בתווים, ב- |
|
1 · = |
|
|
0.66 |
לא תקרה אלא מדידה: זמן המעבד של הפרסור הגרוע שנמצא תחת |
|
200 · 1000 |
עמוד בעץ הקבצים |
|
100 · 500 |
סימבולים בעמוד באאוטליין. קבועים משלו ולא מיחזור של |
|
50 · 200 |
ריפואים ב- |
|
50 · 100 |
פגיעות ב- |
|
10 |
שורות ההקשר סביב פגיעה בחיפוש |
|
100,000 |
התקרה שעד אליה |
|
200,000 |
קבצים תואמים שמעבר הספירה קורא, ב- |
|
50 · 100 · 10 |
חיפוש בתוך קובץ שמור ( |
|
500 |
טקסט של רשומה אחת בתשובת |
|
50,000 |
סימבולים לקובץ באאוטליין. יושב ב- |
|
20 |
פריטים בקריאה אחת של |
|
10 |
שניות קיר לבאץ«, מהכניסה ל- |
|
256,000 |
|
|
50 |
זוגות בקריאה אחת של |
|
500 |
אורך |
|
600 |
כמה זמן העלאה של |
|
5 |
העלאות חיות למשתמש בו-זמנית, ב- |
כל קבוע שהטבלה אינה נוקבת במודול שלו יושב ב-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)).
אימות והרשאות
שני מסלולים, מאוחדים באותו שרת:
OAuth 2.1 — עבור Claude.ai (Custom Connector). זרימה מלאה: רישום לקוח דינמי (DCR) + PKCE + מסך אישור. הזהות נקבעת דרך התחברות הטלגרם בוובאפ. המחבר שייך לחשבון, ולכן מגיע גם ל-Claude Desktop ול-Claude Code שמחובר עם החשבון (חיבור לקוחות).
טוקן אישי (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 בגוף שלו, עם אותו מאמת של הטרנספורט:
GET /api/agent/primer— טוקן תקין, בכל scope. במצב PATPATAuthMiddlewareעונה לפניו. ראו פריימר לסוכן — GET /api/agent/primer.PUT /api/agent/upload— טוקן תקין, ולאwrite: הראוט רק מחזיק טקסט לזמן קצוב, והכתיבה לקובץ נשארת קריאת כלי שדורשתwrite(הנימוק ב-העלאת תוכן בלי לעבור דרך המודל). במצב PAT הנתיב פטור מ-PATAuthMiddleware, כדי שה-401 יהיה של הראוט — עםConnection: close— בשני המצבים.GET /api/agent/download— טוקן תקין, בכל scope: הורדה היא קריאה. במצב PAT הנתיב פטור מ-PATAuthMiddleware, מאותה סיבה של ההעלאה. ראו הורדת קובץ לדיסק בלי לעבור דרך המודל.
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 — ולא קריאה מלאה.
כל כלי שמצהיר עומד בתקרה בעצמו, במקום שבו הוא יודע מה לקצר ומה לומר:
כלי ומצב |
כשהתשובה אינה נכנסת |
|---|---|
|
|
אותם שני כלים, |
הטווח נגמר מוקדם על גבול שורה, עם |
|
פחות רשומות, עם |
|
|
|
|
|
פחות שורות, עם |
|
|
|
הפתק תמיד חוזר; מה שאינו נכנס הוא שרשורי התגובות שאחריו. שרשור שאינו נכנס עם תגובותיו מוצג מקופל, עם המזהה שלו, והתשובה נושאת |
|
עמוד שנגמר מוקדם, רשימות שנחתכות מהסוף, |
|
|
המטא-דאטה של קובץ שמור אינה חוסמת את הקובץ. כל תשובה על קובץ שמור נושאת את 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 — הגוף נקרא על ידי המודל
כפי שהוא. הוא מורכב מהחלקים הבאים:
שדה ”הוראות לסוכן“ מעמוד ההגדרות בוובאפ (
/settings) — עיקר התוכן.שורת מצב קצרה שנבנית בזמן אמת: שלושת הקבצים האחרונים שנשמרו ומתי.
שורת מצב שנייה, כשיש: הפתקים שמחכה בהם תגובה לסוכן — שרשור פתוח (שרשורי תגובות על פתקים — codekeeper_comment_note) שהתגובה האחרונה בו של המשתמש, כלומר גם תשובה שלו לסוכן וגם שרשור חדש שהוא פתח כדי לבקש משהו. שרשור שסוכן ענה בו אחרון אינו בשורה, כדי שהיא לא תמשיך להציק אחרי שטיפלו בו. לכל פתק: הכותרת (או תחילת הגוף, לפתק בלי כותרת), איפה הוא יושב (לוח, קובץ, קובץ בריפו, או ”בארכיון“), וה-
note_id— משם הסוכן ממשיך ל-codekeeper_get_noteעםpart="threads". עדPENDING_THREADS_COUNTפתקים, החדש ביותר קודם, ואחריהם ”ועוד N“. פתק שנמחק אינו נספר, ופתק ריפו — רק לאדמין, אותו שער שלcodekeeper_get_note. העברה לארכיון סוגרת את השרשורים הפתוחים של הפתק (ארכיון: היעד הרביעי), ולכן פתק בארכיון מופיע כאן רק אם המשתמש הגיב בו שוב אחרי ההעברה.
התנהגות |
פירוט |
|---|---|
|
יש הוראות. הגוף = הוראות + שורות המצב (קבצים, אם יש; תגובות שממתינות, אם יש). |
|
שדה ההוראות ריק. גוף ריק לחלוטין — הפריימר קיים כדי לשאת את ההוראות, ושמות קבצים בלי מסגור הם רעש ולא פריימר. ולכן גם אין שורת תגובות, והשאילתה שלה אינה רצה: משתמש בלי הוראות לא יראה בפריימר תגובות שממתינות לסוכן. |
|
אין טוקן, או שהטוקן בוטל/פג. |
תקרת 24KB |
חריגה גורמת לחיתוך + שורה שמודיעה על כך; לעולם לא שגיאה, כי פריימר
חתוך עדיף על פריימר חסר. שורות המצב מקבלות מקום שמור ולא נדחפות החוצה —
ולכל אחת תקציב משלה: |
כשל בשורת מצב |
שורות המצב הן תוספת, וכשל בקריאה שלהן אינו מפיל את ההוראות: הגוף מוגש
( |
Cache |
60 שניות לכל משתמש ( |
סינון סודות |
כל הגוף עובר צנזור של דפוסים שנראים כמו מפתח ( |
התקרה וה-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, והקובץ יושב בקונטיינר של הסוכן.
הזרימה — שלושה צעדים, ואף אחד מהם אינו מעביר את התוכן דרך המודל:
הסוכן מעלה את הקובץ בקריאת
curlאחת, עם ה-PAT שכבר נמצא בסביבה שלו — אותוCODEKEEPER_PATשהוק הפריימר משתמש בו (פריימר לסוכן — GET /api/agent/primer):curl -sS -T report.md -H "Authorization: Bearer $CODEKEEPER_PAT" https://<MCP-HOST>/api/agent/upload
השרת מאמת, בודק, שומר את הטקסט לזמן קצוב, ומחזיר JSON קטן:
{"upload_id": "…", "bytes": 28213, "chars": 16540, "content_sha256": "…", "expires_in_seconds": 600}
הסוכן קורא ל-
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 אינו נקרא ואינו נדרש.
תשובה |
מתי |
|---|---|
|
נשמר. |
|
בלי טוקן, או טוקן פסול. בשני מצבי האימות זה ה-401 של הראוט עצמו |
|
המכסה של הזהות נגמרה. אותה מכסה של קריאות הכלים: המגביל נבנה פעם אחת ב- |
|
למשתמש כבר |
|
אינדקס ה-TTL לא אומת, או שהמסד לא ענה. בלי TTL מאומת ”חמש העלאות“ הוא חסם על הנייר והתוכן נשאר לצמיתות, ולכן fail-closed — ראו האחסון למטה |
|
הגוף לא הגיע בתוך |
|
אורך מוצהר מעל תקרת הגוף. של המידלוור, והראוט אינו רץ בכלל — ראו ”גבולות הבקשה“ |
|
גוף ריק |
|
הבתים אינם UTF-8 תקין. פענוח קפדני — |
|
יותר תווים מ- |
כל סירוב נושא ``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 בלבד מתנהגת בדיוק כמו קודם. בדיוק אחד מהשניים:
תשובה |
מתי |
|---|---|
|
נשלחו גם תוכן וגם |
|
לא נשלח אף אחד מהשניים. ה- |
|
המזהה אינו בצורה שהראוט מייצר. הערך אינו מוחזר |
|
אין העלאה חיה במזהה הזה שלך: פקעה, נצרכה, או של משתמש אחר — תשובה אחת, בלי לגלות איזו, כמו |
|
אחסון ההעלאות לא ענה. שום דבר לא נכתב |
|
הטקסט שנשלף אינו מה שהגיע: ה-hash שלו שונה מ- |
|
לא קוד שגיאה אלא שדה שמתווסף לסירוב של השמירה עצמה ( |
תיאור הפרמטר 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 שבטבלה הקודמת חלים גם עליה. הקודים שנקראים על שם פרמטר נושאים שם את השם שלו:
תשובה |
מתי |
|---|---|
|
נשלחו גם |
|
לא נשלח אף אחד מהשניים — אותה תשובה של רשימה ריקה |
|
המזהה אינו בצורה שהראוט מייצר. הערך אינו מוחזר |
|
הקובץ שהועלה אינו מערך JSON. עם |
ה-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 שולח לה את הכותרות בלי הגוף.
תשובה |
מתי |
|---|---|
|
הבתים, עם הכותרות שלמעלה |
|
בלי טוקן, או טוקן פסול. בשני מצבי האימות זה ה-401 של הראוט עצמו: במצב PAT הנתיב פטור מ- |
|
המכסה של הזהות נגמרה. אותה מכסה של קריאות הכלים ושל ההעלאה — המגביל נבנה פעם אחת ב- |
|
אין קובץ כזה שלך: מזהה של משתמש אחר, מזהה שאינו קיים, מזהה פגום, או שם שאין לך — תשובה אחת, בלי לגלות איזו, כמו |
|
לא נשלח |
|
פרמטר שאינו |
|
אותו פרמטר פעמיים, עם |
|
פרמטר עם ערך ריק, עם |
|
|
|
|
כל סירוב נושא ``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:
משתנה |
הערה |
|---|---|
|
זהים לבוט/וובאפ |
|
נדרש רק לטעינת מודול ה-config המשותף |
שלב 3 — מצב OAuth (מוסיף את Claude.ai)
נדלק אוטומטית כשמוגדרים בשירות ה-MCP:
משתנה |
הערה |
|---|---|
|
ה-URL הציבורי (https) של שירות ה-MCP |
|
ה-URL הציבורי של הוובאפ (למסך התחברות הטלגרם). בלעדיו, או כשהוא פגום ( |
|
זהה לוובאפ, ערך אקראי חזק (≥16 תווים) — חותם את זהות המשתמש בין השירותים |
בנוסף: על הוובאפ להגדיר MCP_SERVER_URL (+אותו SECRET_KEY), ועל
הבוט MCP_SERVER_URL (לפקודת /connect_claude).
שלב 4 — דפדפן הריפו (אדמין, אופציונלי)
משתנה |
הערה |
|---|---|
|
מזהה הטלגרם של האדמין (CSV). ריק = הכלים כבויים לכולם |
|
ב-Render דיסק הוא פר-שירות; בלי דיסק ה-mirrors משוכפלים מחדש אחרי כל deploy |
|
רק לריפואים פרטיים (אימות ל-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, וכל מה שהשרת נוגע בו הוא תוכן של המשתמש.
לכן הכלל חל על כל אירוע שהלקוח שולח, ולא רק על אירועי $mcp_.
שני שדות של טקסט חופשי, ובדיקה אחת שחלה על שניהם. $mcp_error_message
ו-$mcp_intent הם היחידים שיוצאים ואינם נכתבו על ידי השרת. שניהם מוצדקים
כ“משפט שאדם קורא“, ולכן שניהם עוברים רק כשהערך הוא מחרוזת: מילון או רשימה
תחת אותו שם אינם המשפט הזה אלא מבנה שלם — ומבנה אי אפשר לחטא חלקית, ולכן
הוא נזרק. זה נמדד ולא נוסח: מילון תחת $mcp_error_message עבר גרסה
קודמת של השער, שבדקה מי מבקש ולא מה עובר, עם גוף קובץ בתוכו.
ואז שניהם עוברים סינון סודות. אותה רשימת דפוסים שמסננת את
הפריימר, ב-mcp_server/redaction.py — מודול טהור
ששני הצרכנים מייבאים, ולא עותק שני. זה לא סגנון: כשלכל צרכן הייתה רשימה
משלו, דפוס נוסף לאחד ולא לשני, וזה כבר קרה בפרויקט הזה.
נתפס |
לא נתפס |
|---|---|
כל צורת סוד מוכרת, בכל מקום במחרוזת: מפתח AWS בזנב של
|
הכלל לפי שם ( |
— |
נתיבי קבצים ושמות. הם אינם סודות, והמסנן אינו מתיימר להיות מנקה 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, והוא חסום ונשאר חסום. לכן במקום לפתוח את
הארגומנטים, השרת מחשב בעצמו תווית אחת מתוך קבוצה סגורה ושולח אותה:
ערך |
מתי |
|---|---|
|
מפה במקום תוכן: |
|
הועבר |
|
הועבר |
|
הועבר |
|
לא הועבר אף אחד מהם — קריאת הקובץ המלא, היקרה מכולן |
הסדר הוא הסדר של קודי הסירוב. קריאה שנדחתה כזוג מצבים מתויגת לפי המצב
הראשון בשם הקוד שלה — 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 היא נוחות בלבד — האכיפה האמיתית היא בגוף כל כלי.
פתרון תקלות
סימפטום |
כיוון |
|---|---|
|
הטוקן בוטל/פג או ששירות ה-MCP מחובר ל-MongoDB אחר מזה שהנפיק אותו |
|
ה-URL מצביע על הוובאפ במקום על ה-MCP host — האנדפוינט חי רק על ה-MCP |
|
תקין, לא תקלה: שדה ”הוראות לסוכן“ ריק. מלאו אותו ב- |
הפריימר לא נטען, בלי שום הודעה |
כל כשל של ההוק מדפיס שורה, ולכן זה |
הפריימר לא מתעדכן |
ה-cache הוא 60 שניות — המתינו דקה אחרי השמירה |
שורת |
שירות ה-MCP היה בדיפלוי כשהסשן נפתח: ההוק שבפלאגין ניסה שוב לאורך כל התקציב שלו וקיבל |
שורת |
לא חזרה תשובה בכלל, ולכן זה לא דיפלוי — Render עונה |
|
|
|
|
|
חיבור בקריאה בלבד — חברו מחדש עם write (או |
|
כבר קיים קובץ בשם הזה, ו- |
|
התיאור ארוך מ- |
|
הקובץ נשמר, והתיאור לא: הוא ארוך מ- |
|
אין קובץ פעיל בשם הזה אצל המשתמש המאומת. השם נלקח כפי שהוא מופיע
ב- |
|
בדיקת הקיום נכשלה — זה אינו ”הקובץ אינו קיים“. שום דבר לא נשמר;
נסו שוב בעוד רגע. אותה הבחנה כמו ב- |
|
אין העלאה חיה במזהה הזה למשתמש המאומת: היא פקעה ( |
|
ההעלאה שנשמרה אינה תואמת את ה-hash שחושב כשהגיעה, ולכן לא נכתב כלום
והיא נמחקה — ואם האחסון לא ענה למחיקה, היא תפקע ב-TTL. זו התשובה גם
כשהכלי היה נכשל מסיבה אחרת, כמו התקרה או |
|
יש כבר |
|
אינדקס ה-TTL של |
הפקודה בתיאור |
השירות לא יודע את הכתובת הציבורית שלו: |
|
אין גרסה כזו שלך: המזהה שגוי, של משתמש אחר, או שהשם לא קיים. מזהים
תקינים — |
|
ה-user_id אינו ב- |
|
שם הריפו אינו ברשימת המשוקפים. |
|
הנתיב אינו בעץ המשוקף. הנתיב נלקח כפי שהוא מופיע ב- |
|
השאילתה על המניפסט נכשלה — זה אינו ”לא קיים“. אל תתקנו את הנתיב; נסו שוב |
|
ה- |
|
השם אינו של קובץ שמור. השיוך אינו יוצר קובץ — שמרו קודם ב- |
|
צילום הגרסה הקודמת נכשל, ולכן העדכון לא בוצע. הפתק שלם; נסו שוב |
|
מספר הגרסה אינו בטווח שנשמר (20 האחרונות).
|
|
|
|
הפתק השתנה בין הקריאה לכתיבה (עריכה מקבילה). קראו אותו מחדש ונסו שוב — שום דבר לא נדרס |
|
השם כבר תפוס — על אותו לוח, או על אותו קובץ בריפו |
|
|
|
|
|
הקובץ אינו Markdown לפי הכלל של הוובאפ — שפה |
|
הקובץ השמור גדול מ- |
|
|
|
ארבעת מצבי הקריאה של |
|
העימוד הוא של סעיף, ולכן בלי |
|
|
במפה חסרות כותרות, ו- |
נשלח |
|
|
סעיף חזר עם פחות מ- |
העמוד לא נכנס ב- |
|
הכותרות שהתשובה נושאת גדולות מהתקציב לבדן, כך שגם עמוד ריק אינו נכנס.
קראו את הסעיף ב- |
|
הרשימה נחתכה מהסוף כדי שהתשובה תיכנס ב- |
|
השם חוזר בקובץ, והכלי אינו מנחש. קראו לפי |
|
התשובה אינה נכנסת בתקציב, ואין בה מה לקצר בלי לאבד משהו בשקט. ה- |
|
התשובה לא נכנסה בתקציב עם התגיות של הקובץ, ולכן ויתרה עליהן — בסירוב מהסוף, ובתשובה מוצלחת כולן. התגיות שמורות כמו שהן; רק התשובה הזו לא נשאה אותן. תשובה מוצלחת מוותרת עליהן רק כשהן מה שעומד בינה לבין התקציב, או כשהמטא-דאטה גדולה מכל שאר תשובה שנחתכה. ראו תקרת התשובה — מה כלי מצהיר, ומי אוכף |
|
התיאור של הקובץ גדול מדי לתשובה הזו, ולכן ירד שלם; |
טווח שחזר עם |
הטווח לא נכנס ב- |
|
העמוד אינו נכנס בתקציב, והוא נדחה כולו ולא נחתך, וה- |
|
באג בכלי, לא התנהגות צפויה. הרשת שב- |
שורות |
התנהגות צפויה: כלי חתך או סירב כדי להיכנס בתקציב, והשורה אומרת איזה כלי, עם אילו שמות ארגומנטים וכמה. היא מתארת רק את התשובה שהלקוח קיבל. הרבה שורות מאותו כלי ואותה צורה הן הסימן ש- |
|
הלקוח שלח |
|
שאילתה ארוכה משם פתק אפשרי לא תתפוס דבר. קצרו אותה |
|
יש בשאילתה תו NUL, ומונגו דוחה |
|
רענון רץ ברגע זה — נסו שוב לפי |
אין שום לוג מהשרת, גם כשהכול תקין |
מאז #3393 ``mcp_server/app.py`` מגדיר לוגים בייבוא (``LOG_LEVEL``,
ברירת מחדל |
|
כבר אינו מוחזר. |
|
למארח אין עותק של הריפו. זה אינו שם קובץ שגוי — אל תנסו נתיב אחר; בדקו
את המראה ( |
|
המראה של המארח הזה לא מכירה את הענף או את ה-SHA — מה שאינו אומר שהם אינם קיימים ב-GitHub. ענף שנדחף בלי שינוי בענף הראשי יגיע למראה רק עם השינוי הבא בענף הראשי, והבקשה עצמה לעולם אינה מושכת אותו. ראו ענף שלא במראה, מול קובץ שלא קיים |
|
שם ה-ref פגום (לא עבר את |
|
הריפו נמצא והקריאה נכשלה — למשל מראה שבורה, ששירות המראה רושם עליה WARNING עם ה-stderr של git. אם זה חוזר, בדקו את המראה בדיסק |
|
הנתיב פותר אל מחוץ לשורש התיעוד של הריפו ( |
הסוכן שמר קובץ ולא הגיעה התראה |
לפי הסדר: (1) יש מנוי Push פעיל בדפדפן? נרשמים ב- |
|
|
|
יותר פריטים ממה שבאץ« אחד נושא. |
|
הפריט לבדו גדול מכל מה שתשובה יכולה להכיל. |
|
הפריט אינו תואם לסכימה, ו- |
פריטים ב- |
הם לא נקראו, וכל מה שלפניהם שלם. |
|
באץ« נשקל כמספר הפריטים שלו, והמכסה נגבית כולה או לא בכלל: באץ« של 20 פריטים כשנשארו 15 יחידות נדחה כולו, ו- |
|
הקובץ השתנה מאז שקראתם אותו, וביקשתם בדיקה ( |
|
הטקסט נושא surrogate בודד — חצי של זוג, ש-UTF-8 אינו יכול לקודד והמסד אינו שומר. הוא נוצר מ-escape של JSON שהחצי השני שלו חסר. שום דבר לא נכתב, והעלאה שהייתה בקריאה נשארת. שלחו את התו עצמו, או את שני חצאי הזוג. ב- |
|
הערך אינו hash: צריך 64 ספרות הקס, בדיוק |
|
הצהרתם ב- |
|
הערך אינו מספר שלם, 0 ומעלה. שום דבר לא נקרא ולא נכתב. ראו escape של יוניקוד שהגיע כטקסט — expected_unicode_escapes |
סירוב עם |
הזוג במקום הזה (מאפס) נכשל, בקוד של |
|
הקובץ שהועלה ל- |
|
זוג אינו בצורה הנכונה, ו- |
|
|
|
יותר זוגות ממה שקריאה אחת נושאת; |
סעיפים שעברו לעמודים אחרים
העמוד הזה פוצל לשלושה (What’s New), וחלק מהסעיפים שלו עברו, עם התוויות שלהם, ל-עמוד הקבצים והפתקים ול-עמוד הקריאה והחיפוש. :ref: לתווית כזו ממשיך להגיע לסעיף שלה, אבל כתובת ישנה מהצורה mcp-server.html#<תווית> נפתחת עכשיו בראש העמוד הזה, כי התווית כבר אינה בו. אלה כל התוויות שעברו, בסדר אלפביתי, וכל אחת היא קישור למקום שבו היא נמצאת היום. כתובת שבסופה מספר רץ, כמו #id12, אינה תווית, ולכן אינה ברשימה.
ראו גם
MCP Analytics (מדידת השימוש בכלי ה-MCP) — מסך האדמין שקורא את הנתונים האלה חזרה
משתני סביבה - רפרנס — כל משתני הסביבה (כולל קטגוריית MCP)
mcp_server/README.md— תיעוד תפעולי קצר בתוך הריפוFEATURE_SUGGESTIONS/FEATURE_MCP_CLAUDE_INTEGRATION.md— מסמך התכנון המלאSecurity Guide — מדיניות האבטחה הכללית