trustgraph/docs/tech-specs/mcp-tool-arguments.he.md

---
layout: default
title: "מפרט ארגומנטים של כלי MCP"
parent: "Hebrew (Beta)"
---

# מפרט ארגומנטים של כלי MCP

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## סקירה כללית
**שם פיצ'ר**: תמיכה בארגומנטים של כלי MCP
**מחבר**: עוזר קוד של Claude
**תאריך**: 2025-08-21
**סטטוס**: סופי

### סיכום מנהלים

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

### הצגת הבעיה

כרגע, כלי MCP בתוך מסגרת ה-ReACT אינם יכולים לציין את
הארגומנטים הצפויים שלהם. מתודת `McpToolImpl.get_arguments()`
מחזירה רשימה ריקה, ולכן LLMs חייבים לנחש את המבנה של הפרמטרים
רק על סמך שמות וכותרות כלים. זה גורם ל:
- קריאות כלים לא אמינות עקב ניחוש פרמטרים
- חוויית משתמש גרועה כאשר כלים נכשלים עקב ארגומנטים שגויים
- אי אימות של פרמטרי כלים לפני ביצוע
- אי עליית תיעוד פרמטרים בהנחיית הסוכן

### מטרות

- [ ] לאפשר להגדרות כלי MCP לציין ארגומנטים צפויים (שם, סוג, תיאור)
- [ ] לעדכן את מנהל הסוכן כדי לחשוף ארגומנטי כלי MCP ל-LLMs באמצעות הנחיה
- [ ] לשמור על תאימות לאחור להגדרות כלי MCP קיימות
- [ ] לתמוך באימות ארגומנטים בדומה לכלי תבנית הנחיה

### מטרות לא
- גילוי דינמי של ארגומנטים מהשרתים של MCP (שיפור עתידי)
- אימות סוגי ארגומנט מעבר למבנה בסיסי
- סכימות ארגומנטים מורכבות (אובייקטים מקובצים, מערכים)

## רקע והקשר

### מצב נוכחי
כלי MCP מוגדרים במערכת ה-ReACT עם מידע מינימלי:
```json
{
  "type": "mcp-tool",
  "name": "get_bank_balance",
  "description": "Get bank account balance",
  "mcp-tool": "get_bank_balance"
}
```

המתודת `McpToolImpl.get_arguments()` מחזירה `[]`, ולכן LLMs לא מקבלים הדרכה לגבי ארגומנטים בהנחייתם.

### מגבלות
1. **אין מפרט ארגומנטים**: כלי MCP אינם יכולים להגדיר פרמטרים צפויים
2. **ניחוש פרמטרים על ידי LLM**: הסוכן חייב להסיק פרמטרים משמות/תיאורים של כלים
3. **מידע הנחיה חסר**: הנחיות הסוכן אינן מציגות פרטים לגבי ארגומנטים של כלי MCP
4. **אין אימות**: פרמטרים לא חוקיים מתגלים רק בזמן ביצוע כלי MCP

### רכיבים קשורים
- **trustgraph-flow/agent/react/service.py**: טעינת הגדרות כלי וליצירת מנהל סוכן
- **trustgraph-flow/agent/react/tools.py**: יישום של McpToolImpl
- **trustgraph-flow/agent/react/agent_manager.py**: יצירת הנחיה עם ארגומנטי כלי
- **trustgraph-cli**: כלים של שורת פקודה לניהול כלי MCP
- **Workbench**: ממשק משתמש חיצוני להגדרת כלי סוכן

## דרישות

### דרישות פונקציונליות
1. **הגדרות ארגומנטים של כלי MCP**: הגדרות כלי MCP חייבות לתמוך במערך אופציונלי של `arguments` עם שדות שם, סוג ותיאור
2. **חשיפת ארגומנטים**: `McpToolImpl.get_arguments()` חייב להחזיר את הארגומנטים המוגדרים במקום רשימה ריקה
3. **אינטגרציה עם הנחיה**: הנחיית הסוכן חייבת לכלול פרטים של ארגומנטי כלי MCP כאשר הם מוגדרים
4. **תאימות לאחור**: הגדרות כלי MCP קיימות ללא ארגומנטים חייבות להמשיך לעבוד
5. **תמיכה ב-CLI**: כלי ה-CLI הקיים `tg-invoke-mcp-tool` תומך בארגומנטים (כבר מיושם)

### דרישות לא פונקציונליות
1. **תאימות לאחור**: ללא שינויים שמשבשים בהגדרות כלי MCP קיימות
2. **ביצועים**: ללא השפעה משמעותית על יצירת הנחיות סוכן
3. **עקביות**: טיפול בארגומנטים חייב להתאים לתבניות של כלי תבנית הנחיה

### סיפורי משתמש
1. כ**מפתח סוכן**, אני רוצה לציין ארגומנטים של כלי MCP בהגדרות, כך ש-LLMs יוכלו להפעיל כלים עם פרמטרים נכונים
2. כ**משתמש ב-Workbench**, אני רוצה להגדיר ארגומנטים של כלי MCP בממשק ה-UI, כך שהסוכן ישתמש בכלים כראוי
3. כ**LLM בסוכן ReACT**, אני רוצה לראות את המפרט של ארגומנטי כלי בהנחיות, כך שאוכל לספק פרמטרים נכונים

## עיצוב

### ארכיטקטורה ברמה גבוהה
להרחיב את הגדרת כלי MCP כך שתתאים לתבנית כלי תבנית הנחיה על ידי:
1. הוספת מערך אופציונלי של `arguments` להגדרות כלי MCP
2. שינוי המחלקה `McpToolImpl` כדי לקבל את הארגומנטים
3. לשמור על התאמה לאחור להגדרות כלי MCP קיימות

### דוגמה
```python
class McpToolImpl:
    def get_arguments(self):
        # ... קוד לקבלת ארגומנטים ...
        return arguments
```

## שאלות פתוחות
1. **אימות ארגומנטים**: האם אמור להיות אימות סוגים/פורמטים של ארגומנט מעבר לבדיקות מבני בסיסיות?
2. **גילוי דינמי**: האם עדיף לשאול את שרתי ה-MCP עבור סכימות כלי באופן אוטומטי?
3. **מבנה ארגומנטים**: האם הארגומנטים צריכים להיות בפורמט מובנה (לדוגמה, JSON)?

## אפשרויות שנשקלו
1. **גילוי דינמי של סכימת MCP**: לשאול את שרתי ה-MCP עבור סכימות של כלי בזמן ריצה - נדחה עקב מורכבות וחששות לגבי אמינות
2. **רשום ארגומנטים נפרד**: לאחסן את ארגומנטי הכלי בפרטי הגדרה נפרדים - נדחה עקב עקביות עם הגישה של תבנית הנחיה
3. **אימות סוג**: אימות JSON מלא של ארגומנטים - מוחזר כשיפור עתידי כדי לשמור על היישום הראשוני פשוט

## מקורות
- [מפרט פרוטוקול MCP](https://github.com/modelcontextprotocol/spec)
- [יישום כלי תבנית הנחיה](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
- [יישום כלי MCP נוכחי](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)

## נספחים
[כל מידע, דיאגרמות או דוגמאות נוספות]