#3491 feat(mcp): בלוק instructions שנכנס בתקרה של הלקוח, ושומר שמשווה אותו ל-tools/list

✨ תיאור קצר

בלוק ה-instructions שהשרת מחזיר ב-initialize לא הזכיר 17 מתוך 32 הכלים. עם טעינת כלים מושהית, כלי שלא מוזכר בבלוק כמעט לא מתגלה לסוכן. הבלוק נכתב מחדש: הוא מקובץ לפי משימות, נוקב בכל 32 הכלים, ונכנס כולו בתקרה של 2,048 תווים ש-Claude Code מעביר לסוכן. נוסף גם שומר (טסט) שמשווה את הבלוק ל-tools/list של אדמין.

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

• קוד (Backend)

• תיעוד (docs/)

• הבלוק: build_instructions ב-mcp_server/server.py, בנוסח שאושר בשיחה. שלושה חלקים בו נבנים ולא מוקלדים:

  • רשימת הריפואים שכלי התיעוד מגיש. היא נגזרת מ-MCP_DOCS_REPO ומטבלת המדיניות, דרך served_docs_repos ב-docs_handlers.
  • תקרת הבאץ' של השרת (batch_item_cap).
  • המשפט על get_more_tools, שנכנס רק כשהכלי באמת מופיע ב-tools/list.

• תקרת הלקוח: הקבוע CLIENT_INSTRUCTIONS_MAX_CHARS = 2_048. ההערה לידו נוקבת בלקוח, במקור ובתאריך, ואומרת במפורש שהערך לא נמדד בלקוח עצמו. אם בלוק בפריסה מסוימת ארוך מהתקרה, השרת כותב בעלייה שורת WARNING שנוקבת בשמות הכלים שנפלו מעבר לה.

• analytics.instrument_mcp_server מחזיר עכשיו האם העטיפה של PostHog על tools/list באמת הותקנה, לפי המצב בפועל ולא לפי זה שהקריאה עברה. הסיבה: instrument() אינו זורק בכשל אלא מחזיר ידית ריקה (K11). שם הכלי הווירטואלי הוא הקבוע MISSING_CAPABILITY_TOOL_NAME, ומועבר ל-SDK במפורש.

• המשפט הראשון בתיאורים של get_file, search_code, get_repo_file ו-list_repo_tree נוסח מחדש. מה שהיה במשפט הישן ולא נכנס לחדש עבר למשפט שאחריו.

• תיעוד: ב-docs/mcp-server.rst נוסף משפט על השומר ועל התקרה בסעיף "הכלים", משפט על כך שהבלוק נגזר מ-MCP_DOCS_REPO, ומשפט על התנאי של get_more_tools. נוספה גם רשומה ב-whats-new.

🧪 בדיקות

• Unit
• Integration
• Manual
• טסט חדש, tests/test_mcp_instructions.py (10 טסטים). כולם עוברים דרך session אמיתי של הפרוטוקול, בתצורת הייצור: PostHog דלוק עם send=False, רשימת הריפואים של הייצור, ומראה. מה הם בודקים:
  • הכיסוי: השמות מתוך instructions[:2048] מול tools/list של אדמין.
  • שהבלוק נכנס בתקרה.
  • שהכלי הווירטואלי מוזכר אם ורק אם הוא ברשימה, כולל המקרה שבו instrument() נכשל בשקט.
  • שקבוצת "admins only" תואמת בדיוק את מה שהשרת מסתיר ממי שאינו אדמין (גזור מהממשק, ולא מרשימת שמות).
  • שמשפט הריפואים וה-"20" נגזרים.
  • שהאזהרה נוקבת בשמות שנפלו.
• מוטציות, ב-git worktree נפרד:
  • כלי שנרשם בלי עדכון הבלוק ← נופל עם ['codekeeper_mutation_probe'].
  • שם שנמחק מהבלוק ← נופל עם ['codekeeper_list_repos'].
  • זיהוי שסומך על הקריאה ולא על המצב ← נופל.
  • על הבלוק הישן ← נופל עם 17 כלים חסרים.
• טסטי MCP ו-docs: 1,869 עוברים, 36 מדולגים.
• אימות HTTP אמיתי, דרך build_app עם PAT ו-ADMIN_USER_IDS: אדמין רואה 33 כלים, ומשתמש רגיל רואה 25. ההפרש הסימטרי בתוך התקרה ריק. הבלוק: 2,008 תווים, 2,008 בתים ב-UTF-8, 211 מילים, ו-2,036 בתים כמחרוזת JSON על החוט. לפני השינוי הבלוק היה 1,491 תווים, 1,503 בתים ו-225 מילים.

📝 סוג שינוי

• feat: פיצ'ר חדש

✅ צ'קליסט

• בדיקות רצות ועוברות
• תיעוד עודכן (README/Docs)
• אין סודות/מפתחות בקוד
• עיינתי במסמכי אתר התיעוד — נתיב: AI-MAP.md, docs/doc-authoring.rst, docs/versioning-stable-anchors.rst, docs/mcp-server.rst (סעיפי "הכלים", "איזה קובץ docs_get_section קורא", "מדידת שימוש") | המשפט: "ערך שנאכף — כן תעדו"

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

• מה שכל לקוח MCP מקבל ב-initialize משתנה. לא נגעתי בסכימות, ולא בתיאורי כלים מלבד ארבעת המשפטים הראשונים ואיחוד של משפט הפניה אחד ב-get_file.
• לפי אישו פתוח, anthropics/claude-ai-mcp#93, claude.ai כנראה לא מעביר את השדה instructions בכלל (זה לא תיעוד רשמי).

🔗 קישורים

• מקור התקרה: https://code.claude.com/docs/en/mcp ("For MCP server authors")

🧯 סיכון / החזרה לאחור (Rollback)

• revert של שני הקומיטים.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HDpMsgN52cR1EHJCj5fNms

---

Generated by Claude Code

Summary by Sourcery

Ensure MCP clients receive accurate, complete, and size-bounded tool discovery guidance that stays synchronized with the server’s actual tool listing.

New Features:

• Generate a task-oriented MCP instructions block that covers the server’s available tools within the client-visible 2,048-character limit.
• Derive instruction content from the configured documentation repositories, batch-size limit, and actual PostHog virtual-tool availability.

Bug Fixes:

• Prevent MCP instructions from advertising tools that are not present in tools/list, including when analytics instrumentation fails silently.
• Warn at startup when instruction content exceeds the client limit and identify tool names truncated from the client-visible portion.

Enhancements:

• Improve discovery guidance in file and mirrored-repository tool descriptions.
• Make PostHog instrumentation report whether tools/list was actually wrapped rather than relying on call success.

Documentation:

• Document the instructions coverage guard, client character limit, dynamic repository content, and conditional get_more_tools guidance.
• Add a whats-new entry for the MCP instructions improvements.

Tests:

• Add protocol-level tests comparing client-visible instructions with admin and regular tools/list results, including coverage, length limits, permissions, dynamic content, instrumentation failure, and truncation warnings.