#3388 fix: תיאור codekeeper_get_repo_file נחתך אצל הלקוח — פיצול לתיאורי פרמטרים + טסט תקרה

✨ תיאור קצר

התיאור של codekeeper_get_repo_file הגיע ל-2,482 תווים — פי 3.8 מהכלי השני בגודלו (652) ופי שמונה מהחציון (303) — ונמדד שהוא מגיע לסוכן חתוך באמצע המשפט על RST ועל symbol=. כלומר שני פיצ'רים עבדו ואף לקוח לא קרא עליהם, בדיוק מחלקת הכשל שהמשפטים האלה נכתבו כדי למנוע.

הפתרון הוא העברה ולא מחיקה: הפירוט על השפות עבר ל-Field(description=...) של הפרמטר outline, והפירוט על הסינון לזה של symbol. סך שלושת השדות גדל (2,711 מול 2,482) — אף לקח לא נמחק — ותיאור הכלי ירד ל-1,125.

📦 שינויים עיקריים

• קוד (Backend)
• בוט טלגרם
• מסד נתונים/מיגרציות
• תיעוד (docs/)
• DevOps/CI/CD

פירוט:

• mcp_server/server.py — שני קבועים חדשים, _OUTLINE_PARAM_DOC ו-_SYMBOL_PARAM_DOC, מחוברים לפרמטרים דרך Annotated[..., Field(description=...)]. תיאור הכלי מקוצר ל-1,125 ומפנה לשני הפרמטרים. _RANGE_DOC לא נגעתי בו — הוא משותף ל-codekeeper_get_file ו-docs/mcp-server.rst מחייב שהשניים יישארו סימטריים.
• mcp_server/outline.py — הערת "מקור האמת" מעל _SCANNERS נוקבת עכשיו בתיאור הפרמטר outline ולא בתיאור הכלי.
• tests/test_mcp_server_build.py — עשר assertions הועברו לשדה שבו הטקסט יושב עכשיו; שני טסטים חדשים; שלוש הרחבות כיסוי.
• docs/ — הערה ב-mcp-server.rst שאומרת איפה הפירוט גר בקוד, וערך ב-whats-new.rst.

page/per_page — פיצ'ר בלי שומר

"and page/per_page walk long files" היה המשפט היחיד בתיאור שלא היה עליו אף טסט, ולכן הוא נשמט בטיוטה הראשונה של הפיצול בלי שאף בדיקה שמה לב. הוחזר עם assertion. זה לא שולי: OUTLINE_PER_PAGE_DEFAULT הוא 100, ולכן 486 הסימבולים שנמדדו על הקובץ הצפוף בקורפוס מתפרסים על חמישה עמודים — סוכן שלא יודע על page רואה עמוד אחד וחושב שראה הכול.

assertion הסדר

assert description.index('symbol="@media"') < description.index("500KB") הגנה על כך שהפילטר לא ייקרא כמדיניות גודל. אחרי הפיצול השניים אינם באותה מחרוזת כלל — הסכנה נמנעת מבנית והטענה לא הייתה יכולה לרוץ. הוחלפה בטסט שאוכף את שרשרת הגילוי: שתיאור הכלי מפנה לפרמטרים, ושהם באמת נושאים את הפירוט. הכשל המקורי ("פיצ'ר שאף אחד לא קורא לו הוא פיצ'ר שאינו קיים") חוזר אחרת אחרי הפיצול — סוכן שקורא רק את תיאור הכלי לא יֵדע ש-symbol= קיים.

שלוש הרחבות כיסוי

• ה-escape ב-services.backup\_service נבדק עכשיו ישירות. עד כה הוא נבדק רק דרך symbol="backup_service" — טענה שעוברת גם על טקסט שאיבד את הלוכסן, כלומר בדיוק מה שקורה בהעתקה דרך שכבת escaping. הדוגמה הייתה הופכת לשקר שקט.
• האיסור על "only the RST label targets" חל עכשיו על שלושת השדות ולא על אחד.
• סריקת lines=[...] כוללת את תיאורי הפרמטרים, אחרת דוגמה שתיכתב שם לא הייתה נבדקת.

🧪 בדיקות

• Unit
• Integration
• Manual

435 טסטים עוברים, אפס כשלים: test_mcp_server_build · test_mcp_analytics_privacy · test_mcp_outline · test_mcp_docs_handlers · test_mcp_repo_handlers. ruff ו-flake8 נקיים.

ארבע מוטציות — כל אחת מפילה את הטסט שאמור לתפוס אותה (הרצה ראשונה של אחת מהן החזירה ERROR ולא FAILED, כלומר ה-sed שבר תחביר במקום שהטסט יתפוס; חזרתי עליה נקי עם אימות ast.parse):

מוטציה	הטסט שנפל
page/per_page ← pagination	test_the_description_tells_the_agent_which_languages_have_a_map
Field של symbol ← מחרוזת ריקה	test_the_description_says_symbol_works_on_the_non_python_names
אובדן ה-escape ב-backup\_service	test_the_description_says_symbol_works_on_the_non_python_names
תיאור מעל 1,400 תווים	test_no_tool_description_exceeds_the_truncation_budget

אומת מול הגרסאות המוצמדות ב-requirements/base.txt — mcp==1.28.1, pydantic==2.12.3, posthog==7.45.3. (התקנה ראשונה הביאה mcp 2.2.0; אימות מול גרסה שגויה היה חסר ערך, והוחלף.) דרך request_handlers[ListToolsRequest] עם ההזרקה האמיתית של PostHog פעילה: context הוזרק, get_more_tools נוסף, שני תיאורי הפרמטרים שרדו במלואם, והסכמה עוברת round-trip של JSON בית-בית — כולל {% block %}, <script>, @media וה-escape.

🧩 השפעות/סיכונים

⚠️ סיכון פתוח שצריך להכריע אחרי הדיפלוי. מה שנמדד הוא שהשרת שולח את תיאורי הפרמטרים במלואם — לא מה שלקוח מציג מהם. יש שתי תצפיות סותרות: בסביבה אחת תיאור הכלי נחתך סביב 2,000 תווים, ובסביבה אחרת כל 2,482 התווים הגיעו שלמים בזמן שתיאור פרמטר קוצר לכ-120 תווים בשורת סיכום. אם ההתנהגות השנייה היא הרווחת, הפיצול הזה אינו הפתרון והחלופה היא כלי אאוטליין נפרד, שם הטקסט חוזר להיות תיאור כלי. האזהרה הזאת כתובה במפורש מעל _TOOL_DESCRIPTION_MAX_CHARS ובהערה שמעל שני הקבועים, כדי שלא תיקרא כאן יותר ממה שנמדד.

האימות שחסר: לבקש מסוכן ב-Claude Code להדפיס מילולית את מה שהוא רואה עבור outline ו-symbol.

תופעת לוואי מוצהרת: $mcp_tool_description נמצא ברשימת ההיתר ב-analytics.py:133, ולכן המאפיין שנשלח ל-PostHog יתקצר — תיאורי הפרמטרים לא ייכללו בו. אין assert על תוכנו.

טסט התקרה — ממצא ששווה לשים לב אליו בריוויו: הוא רץ על _tool_manager.list_tools() ולא על mcp.list_tools(). AdminAwareFastMCP מסנן את כלי האדמין כשאין request context, ומחזיר 22 כלים מול 29 — ושבעת החסרים כוללים את codekeeper_get_repo_file עצמו. טסט על התצוגה המסוננת היה ירוק בלי לכסות את המקרה היחיד שהפיל אותנו.

📝 סוג שינוי

• fix: תיקון באג

✅ צ'קליסט

• הקוד עוקב אחרי הסגנון (ruff + flake8 נקיים)
• בדיקות רצות ועוברות
• תיעוד עודכן
• אין סודות/מפתחות בקוד
• אין מחיקות מסוכנות
• הודעת הקומיט תואמת Conventional Commits
• עיינתי במסמכי אתר התיעוד — נתיב: docs/mcp-server.rst | המשפט: "הסיומות הנתמכות הן .py ו-.pyi לפייתון…"

סטיות מהתוכנית, לשקיפות: התוכנית ציינה ארבעה מקומות לעדכון ב-docs/mcp-server.rst ואת mcp_server/README.md שורות 50 ו-84. בפועל בדקתי ומצאתי שאין שם אף טענה על מבנה התיאור — רק על התנהגות, וההתנהגות לא זזה. לכן הוספתי שם רק הערה אחת שאומרת איפה הפירוט גר בקוד, ולא נגעתי ב-README.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TbDVRRR8NxB8FtttvLpc1M

---

Generated by Claude Code

Summary by Sourcery

Keep MCP tool guidance discoverable by moving detailed file, outline, symbol, and query documentation into parameter descriptions while enforcing a safe tool-description length.

Bug Fixes:

• Prevent MCP clients from losing repository-file outline and symbol-filter guidance by moving the detailed documentation into the corresponding parameter descriptions.
• Move the file-query details into the query parameter description to keep the tool description within the client truncation budget.

Enhancements:

• Add a tool-description size budget and verify that tool descriptions point to parameters carrying detailed guidance.
• Expand documentation assertions to cover pagination, supported suffixes, symbol matching and escaping, cross-field content rules, and parameter discovery.

Documentation:

• Document where outline and symbol parameter details are defined and record the change in the release notes.

Tests:

• Update MCP schema and description tests for parameter-level documentation and add coverage for description size limits and parameter-detail discoverability.