mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
562
docs/tech-specs/mcp-tool-bearer-token.he.md
Normal file
562
docs/tech-specs/mcp-tool-bearer-token.he.md
Normal file
|
|
@ -0,0 +1,562 @@
|
|||
---
|
||||
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. זה **אינו** פתרון אימות שלם ו**אינו מתאים** עבור:
|
||||
> - סביבות מרובות משתמשים
|
||||
> - פריסות מרובות דיירים
|
||||
> - אימות פדרטיבי
|
||||
> - העברת הקשר משתמש
|
||||
> - הרשאה ברמת המשתמש
|
||||
>
|
||||
> תכונה זו מספקת **טוקן סטטי אחד לכל כלי MCP**, המשותף לכל המשתמשים והסשנים. אם אתם זקוקים לאימות ברמת המשתמש או הדייר, זו אינה הפתרון הנכון.
|
||||
|
||||
## סקירה כללית
|
||||
**שם התכונה**: תמיכה באימות טוקן עבור כלי MCP
|
||||
**כותב**: Claude Code Assistant
|
||||
**תאריך**: 2025-11-11
|
||||
**סטטוס**: בפיתוח
|
||||
|
||||
### תקציר
|
||||
|
||||
אפשר תצורות של כלי MCP לציין טוקנים סטטיים אופציונליים לאימות עם שרתי MCP מוגנים. זה מאפשר ל-TrustGraph להפעיל כלי MCP המאוחסנים בשרתים הדורשים אימות, מבלי לשנות את סוכן או ממשקי הפעלה של הכלי.
|
||||
|
||||
**חשוב**: זוהי מנגנון אימות בסיסי המיועדת לתסריטי אימות בין שירותים בסביבות עם משתמש יחיד. זה **אינו** מתאים עבור:
|
||||
סביבות מרובות משתמשים שבהן משתמשים שונים צריכים אישורים שונים
|
||||
פריסות מרובות דיירים הדורשות בידוד לדייר
|
||||
תרחישי אימות פדרטיביים
|
||||
אימות או הרשאה ברמת המשתמש
|
||||
ניהול או רענון אישורים דינמיים
|
||||
|
||||
תכונה זו מספקת טוקן סטטי, ברמת המערכת, עבור כל תצורת כלי MCP, המשותף לכל המשתמשים וההפעלה של כלי זה.
|
||||
|
||||
### הצגת הבעיה
|
||||
|
||||
כיום, כלי MCP יכולים להתחבר רק לשרתי MCP נגישים לציבור. פריסות MCP רבות בייצור דורשות אימות באמצעות טוקנים עבור אבטחה. ללא תמיכה באימות:
|
||||
כלי MCP לא יכולים להתחבר לשרתי MCP מאובטחים
|
||||
משתמשים חייבים או לחשוף שרתי MCP לציבור או ליישם שרתי הפוך
|
||||
אין דרך סטנדרטית להעביר אישורים לחיבורי MCP
|
||||
לא ניתן לאכוף שיטות עבודה מומלצות לאבטחה בקצוות MCP
|
||||
|
||||
### מטרות
|
||||
|
||||
[ ] לאפשר לתצורות של כלי MCP לציין פרמטר אופציונלי `auth-token`
|
||||
[ ] לעדכן את שירות כלי MCP כדי להשתמש בטוקנים בעת חיבור לשרתי MCP
|
||||
[ ] לעדכן כלים בשורת הפקודה לתמיכה בהגדרת/הצגת טוקני אימות
|
||||
[ ] לשמור על תאימות לאחור עם תצורות MCP ללא אימות
|
||||
[ ] לתעד שיקולים אבטחתיים עבור אחסון טוקנים
|
||||
|
||||
### לא מטרות
|
||||
רענון טוקנים דינמי או זרימות OAuth (רק טוקנים סטטיים)
|
||||
הצפנה של טוקנים המאוחסנים (אבטחת מערכת התצורה אינה בתחום)
|
||||
שיטות אימות חלופיות (אימות בסיסי, מפתחות API, וכו')
|
||||
אימות או בדיקת תפוגה של טוקנים
|
||||
**אימות ברמת המשתמש**: תכונה זו **אינה** תומכת באישורים ספציפיים למשתמש
|
||||
**בידוד מרובה דיירים**: תכונה זו **אינה** מספקת ניהול טוקנים ברמת הדייר
|
||||
**אימות פדרטיבי**: תכונה זו **אינה** משתלבת עם ספקי זהות (SSO, OAuth, SAML, וכו')
|
||||
**אימות מודע הקשר**: טוקנים אינם מועברים בהתבסס על הקשר משתמש או סשן
|
||||
|
||||
## רקע והקשר
|
||||
|
||||
### מצב נוכחי
|
||||
תצורות של כלי MCP מאוחסנות בקבוצת התצורה `mcp` עם המבנה הבא:
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
שירות הכלי MCP מתחבר לשרתים באמצעות `streamablehttp_client(url)` ללא כותרות אימות.
|
||||
|
||||
### מגבלות
|
||||
|
||||
**מגבלות מערכת נוכחיות:**
|
||||
1. **ללא תמיכה באימות:** לא ניתן להתחבר לשרתי MCP מאובטחים.
|
||||
2. **חשיפה אבטחתיות:** שרתי MCP חייבים להיות נגישים לציבור או להשתמש באבטחה ברמת הרשת בלבד.
|
||||
3. **בעיות פריסה בסביבת ייצור:** לא ניתן לעקוב אחר שיטות עבודה מומלצות לאבטחת נקודות קצה של API.
|
||||
|
||||
**מגבלות של פתרון זה:**
|
||||
1. **מתאים רק למערכת משתמש יחיד:** טוקן סטטי אחד לכל כלי MCP, משותף לכל המשתמשים.
|
||||
2. **ללא אישורים מבוססי משתמש:** לא ניתן לאמת כמשתמשים שונים או להעביר הקשר משתמש.
|
||||
3. **ללא תמיכה בריבוי משתמשים:** לא ניתן לבודד אישורים לפי משתמש או ארגון.
|
||||
4. **טוקנים סטטיים בלבד:** ללא תמיכה בחידוש טוקנים, רוטציה או טיפול בתפוגה.
|
||||
5. **אימות ברמת השירות:** מאמת את שירות TrustGraph, ולא משתמשים בודדים.
|
||||
6. **הקשר אבטחה משותף:** כל שימוש בכלי MCP משתמש באותו אישור.
|
||||
|
||||
### התאמת מקרי שימוש
|
||||
|
||||
**✅ מקרי שימוש מתאימים:**
|
||||
פריסות TrustGraph עם משתמש יחיד.
|
||||
אימות בין שירותים (TrustGraph → שרת MCP).
|
||||
סביבות פיתוח ובדיקה.
|
||||
כלי MCP פנימיים שאליהם ניגש מערכת TrustGraph.
|
||||
תרחישים שבהם כל המשתמשים חולקים את אותו רמת גישה לכלי MCP.
|
||||
אישורים שירותיים סטטיים, בעלי אורך חיים ארוך.
|
||||
|
||||
**❌ מקרי שימוש לא מתאימים:**
|
||||
מערכות מרובות משתמשים הדורשות אימות מבוסס משתמש.
|
||||
פריסות SaaS מרובות משתמשים עם דרישות בידוד משתמשים.
|
||||
תרחישי אימות מאוחדים (SSO, OAuth, SAML).
|
||||
מערכות הדורשות העברת הקשר משתמש לשרתי MCP.
|
||||
סביבות הזקוקות לחידוש טוקנים דינמי או טוקנים בעלי אורך חיים קצר.
|
||||
יישומים שבהם משתמשים שונים צריכים רמות הרשאות שונות.
|
||||
דרישות תאימות לרישומי ביקורת ברמת המשתמש.
|
||||
|
||||
**תרחיש מתאים לדוגמה:**
|
||||
פריסה של TrustGraph עבור ארגון יחיד שבהם כל העובדים משתמשים באותו כלי MCP פנימי (לדוגמה, שאילתת מסד נתונים של החברה). שרת ה-MCP דורש אימות כדי למנוע גישה חיצונית, אך לכל המשתמשים הפנימיים יש את אותו רמת גישה.
|
||||
|
||||
**תרחיש לא מתאים לדוגמה:**
|
||||
פלטפורמת SaaS מרובת משתמשים של TrustGraph שבה כל אחד מ-Tenant A ו-Tenant B צריך לגשת לשרתי MCP מבודדים משלהם עם אישורים נפרדים. תכונה זו אינה תומכת בניהול טוקנים ברמת ה-Tenant.
|
||||
|
||||
### רכיבים קשורים
|
||||
**trustgraph-flow/trustgraph/agent/mcp_tool/service.py**: שירות הפעלת כלי MCP.
|
||||
**trustgraph-cli/trustgraph/cli/set_mcp_tool.py**: כלי שורת פקודה ליצירת/עדכון תצורות MCP.
|
||||
**trustgraph-cli/trustgraph/cli/show_mcp_tools.py**: כלי שורת פקודה להצגת תצורות MCP.
|
||||
**MCP Python SDK**: `streamablehttp_client` מ- `mcp.client.streamable_http`
|
||||
|
||||
## דרישות
|
||||
|
||||
### דרישות פונקציונליות
|
||||
|
||||
1. **טוקן אימות לתצורה של MCP:** תצורות כלי MCP חייבות לתמוך בשדה אופציונלי `auth-token`.
|
||||
2. **שימוש בטוקן Bearer:** שירות כלי MCP חייב לשלוח כותרת `Authorization: Bearer {token}` כאשר טוקן אימות מוגדר.
|
||||
3. **תמיכה בשורת הפקודה:** `tg-set-mcp-tool` חייב לקבל פרמטר אופציונלי `--auth-token`.
|
||||
4. **הצגת טוקן:** `tg-show-mcp-tools` חייב לציין מתי טוקן אימות מוגדר (מוסתר מטעמי אבטחה).
|
||||
5. **תאימות לאחור:** תצורות כלי MCP קיימות ללא טוקן אימות חייבות להמשיך לעבוד.
|
||||
|
||||
### דרישות לא פונקציונליות
|
||||
1. **תאימות לאחור:** ללא שינויים משמעותיים עבור תצורות כלי MCP קיימות.
|
||||
2. **ביצועים:** ללא השפעה משמעותית על ביצועי הפעלת כלי MCP.
|
||||
3. **אבטחה:** טוקנים המאוחסנים בתצורה (יש להבין את השלכות האבטחה).
|
||||
|
||||
### סיפורי משתמש
|
||||
|
||||
1. כ-**מהנדס DevOps**, אני רוצה להגדיר טוקני Bearer עבור כלי MCP כך שאוכל לאבטח נקודות קצה של שרתי MCP.
|
||||
2. כ-**משתמש שורת פקודה**, אני רוצה להגדיר טוקני אימות בעת יצירת כלי MCP כך שאוכל להתחבר לשרתים מוגנים.
|
||||
3. כ-**מנהל מערכת**, אני רוצה לראות אילו כלי MCP מוגדרים עם אימות כך שאוכל לבדוק הגדרות אבטחה.
|
||||
|
||||
## עיצוב
|
||||
|
||||
### ארכיטקטורה ברמה גבוהה
|
||||
הרחבת תצורת כלי MCP ושירות כדי לתמוך באימות טוקן Bearer:
|
||||
1. הוספת שדה אופציונלי `auth-token` לתבנית תצורה של כלי MCP.
|
||||
2. שנה את שירות הכלי MCP כדי לקרוא את הטוקן האימות ולהעביר אותו ללקוח HTTP.
|
||||
3. עדכן את כלי שורת הפקודה (CLI) כדי לתמוך בהגדרת והצגת טוקני אימות.
|
||||
4. תעד שיקולי אבטחה ושיטות עבודה מומלצות.
|
||||
|
||||
### סכימת תצורה
|
||||
|
||||
**הסכימה הנוכחית**:
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
**סכימה חדשה** (עם טוקן אימות אופציונלי):
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api",
|
||||
"auth-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
**תיאורי שדות**:
|
||||
`remote-name` (אופציונלי): שם המשמש את שרת ה-MCP (ברירת מחדל היא מפתח התצורה)
|
||||
`url` (חובה): כתובת URL של נקודת הקצה של שרת ה-MCP
|
||||
`auth-token` (אופציונלי): טוקן Bearer לאימות
|
||||
|
||||
### זרימת נתונים
|
||||
|
||||
1. **אחסון תצורה**: המשתמש מריץ את `tg-set-mcp-tool --id my-tool --tool-url http://server/api --auth-token xyz123`
|
||||
2. **טעינת תצורה**: שירות הכלי ה-MCP מקבל עדכון תצורה באמצעות קריאה חוזרת (callback) של `on_mcp_config()`
|
||||
3. **הפעלת כלי**: כאשר הכלי מופעל:
|
||||
השירות קורא את `auth-token` מהתצורה (אם קיים)
|
||||
יוצר מילון כותרות: `{"Authorization": "Bearer {token}"}`
|
||||
מעביר את הכותרות ל-`streamablehttp_client(url, headers=headers)`
|
||||
שרת ה-MCP מאמת את הטוקן ומעבד את הבקשה
|
||||
|
||||
### שינויי API
|
||||
אין שינויי API חיצוניים - רק הרחבת סכימת התצורה.
|
||||
|
||||
### פרטי רכיב
|
||||
|
||||
#### רכיב 1: service.py (שירות כלי MCP)
|
||||
**קובץ**: `trustgraph-flow/trustgraph/agent/mcp_tool/service.py`
|
||||
|
||||
**מטרה**: הפעלת כלי MCP על שרתים מרוחקים
|
||||
|
||||
**שינויים נדרשים** (בשיטה `invoke_tool()`):
|
||||
1. בדוק אם קיים `auth-token` בתצורת `self.mcp_services[name]`
|
||||
2. בנה מילון כותרות עם כותרת Authorization אם קיים טוקן
|
||||
3. העבר את הכותרות ל-`streamablehttp_client(url, headers=headers)`
|
||||
|
||||
**קוד נוכחי** (שורות 42-89):
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server
|
||||
async with streamablehttp_client(url) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method
|
||||
```
|
||||
|
||||
**קוד שעבר שינוי:**
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
# Build headers with optional bearer token
|
||||
headers = {}
|
||||
if "auth-token" in self.mcp_services[name]:
|
||||
token = self.mcp_services[name]["auth-token"]
|
||||
headers["Authorization"] = f"Bearer {token}"
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server with headers
|
||||
async with streamablehttp_client(url, headers=headers) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method (unchanged)
|
||||
```
|
||||
|
||||
#### רכיב 2: set_mcp_tool.py (כלי תצורה דרך שורת הפקודה)
|
||||
**קובץ**: `trustgraph-cli/trustgraph/cli/set_mcp_tool.py`
|
||||
|
||||
**מטרה**: יצירת/עדכון תצורות לכלי MCP
|
||||
|
||||
**שינויים נדרשים**:
|
||||
1. הוספת ארגומנט אופציונלי `--auth-token` ל-argparse
|
||||
2. הכללת `auth-token` בקובץ JSON של התצורה כאשר הוא מסופק
|
||||
|
||||
**ארגומנטים נוכחיים**:
|
||||
`--id` (חובה): מזהה של כלי MCP
|
||||
`--remote-name` (אופציונלי): שם של כלי MCP מרוחק
|
||||
`--tool-url` (חובה): נקודת קצה של כתובת URL של כלי MCP
|
||||
`-u, --api-url` (אופציונלי): כתובת URL של ממשק API של TrustGraph
|
||||
|
||||
**ארגומנט חדש**:
|
||||
`--auth-token` (אופציונלי): טוקן bearer לאימות
|
||||
|
||||
**שינוי בבניית התצורה**:
|
||||
```python
|
||||
# Build configuration object
|
||||
config = {
|
||||
"url": args.tool_url,
|
||||
}
|
||||
|
||||
if args.remote_name:
|
||||
config["remote-name"] = args.remote_name
|
||||
|
||||
if args.auth_token:
|
||||
config["auth-token"] = args.auth_token
|
||||
|
||||
# Store configuration
|
||||
api.config().put([
|
||||
ConfigValue(type="mcp", key=args.id, value=json.dumps(config))
|
||||
])
|
||||
```
|
||||
|
||||
#### רכיב 3: show_mcp_tools.py (כלי תצוגה בשורת הפקודה)
|
||||
**קובץ**: `trustgraph-cli/trustgraph/cli/show_mcp_tools.py`
|
||||
|
||||
**מטרה**: הצגת תצורות של כלי MCP
|
||||
|
||||
**שינויים נדרשים**:
|
||||
1. הוספת עמודה "אימות" (Auth) לטבלת הפלט
|
||||
2. הצגת "כן" או "לא" בהתאם לנוכחות של טוקן אימות
|
||||
3. אין להציג את ערך הטוקן בפועל (אבטחה)
|
||||
|
||||
**פלט נוכחי**:
|
||||
```
|
||||
ID Remote Name URL
|
||||
---------- ------------- ------------------------
|
||||
my-tool my-tool http://server:3000/api
|
||||
```
|
||||
|
||||
**פלט חדש**:
|
||||
```
|
||||
ID Remote Name URL Auth
|
||||
---------- ------------- ------------------------ ------
|
||||
my-tool my-tool http://server:3000/api Yes
|
||||
other-tool other-tool http://other:3000/api No
|
||||
```
|
||||
|
||||
#### רכיב 4: תיעוד
|
||||
**קובץ**: `docs/cli/tg-set-mcp-tool.md`
|
||||
|
||||
**שינויים נדרשים**:
|
||||
1. לתעד את הפרמטר החדש `--auth-token`
|
||||
2. לספק דוגמה לשימוש עם אימות
|
||||
3. לתעד שיקולי אבטחה
|
||||
|
||||
## תוכנית יישום
|
||||
|
||||
### שלב 1: יצירת מפרט טכני
|
||||
[x] לכתוב מפרט טכני מקיף המתעד את כל השינויים
|
||||
|
||||
### שלב 2: עדכון שירות כלי MCP
|
||||
[ ] לשנות את `invoke_tool()` ב-`service.py` כדי לקרוא את auth-token מקובץ התצורה
|
||||
[ ] לבנות מילון כותרות ולהעביר ל-`streamablehttp_client`
|
||||
[ ] לבדוק עם שרת MCP מאומת
|
||||
|
||||
### שלב 3: עדכון כלי שורת הפקודה
|
||||
[ ] להוסיף את הארגומנט `--auth-token` ל-`set_mcp_tool.py`
|
||||
[ ] לכלול את auth-token בקובץ JSON של התצורה
|
||||
[ ] להוסיף עמודה "אימות" לפלט של `show_mcp_tools.py`
|
||||
[ ] לבדוק את השינויים בכלי שורת הפקודה
|
||||
|
||||
### שלב 4: עדכון תיעוד
|
||||
[ ] לתעד את הפרמטר `--auth-token` ב-`tg-set-mcp-tool.md`
|
||||
[ ] להוסיף סעיף של שיקולי אבטחה
|
||||
[ ] לספק דוגמה לשימוש
|
||||
|
||||
### שלב 5: בדיקות
|
||||
[ ] לבדוק שכלי ה-MCP מתחבר בהצלחה עם auth-token
|
||||
[ ] לבדוק תאימות לאחור (כלים ללא auth-token עדיין עובדים)
|
||||
[ ] לבדוק שכלי שורת הפקודה מקבלים ושומרים את auth-token כראוי
|
||||
[ ] לבדוק שפקודת ה-show מציגה את סטטוס האימות כראוי
|
||||
|
||||
### סיכום שינויים בקוד
|
||||
| קובץ | סוג שינוי | שורות | תיאור |
|
||||
|------|------------|-------|-------------|
|
||||
| `service.py` | שינוי | ~52-66 | הוספת קריאת auth-token ובניית כותרות |
|
||||
| `set_mcp_tool.py` | שינוי | ~30-60 | הוספת ארגומנט --auth-token ואחסון בתצורה |
|
||||
| `show_mcp_tools.py` | שינוי | ~40-70 | הוספת עמודה "אימות" לתצוגה |
|
||||
| `tg-set-mcp-tool.md` | שינוי | שונות | תיעוד פרמטר חדש |
|
||||
|
||||
## אסטרטגיית בדיקות
|
||||
|
||||
### בדיקות יחידה
|
||||
**קריאת סיסמת אימות**: לבדוק ש-`invoke_tool()` קורא כראוי את סיסמת האימות מקובץ התצורה
|
||||
**בניית כותרות**: לבדוק שכותרת ה-Authorization נבנית כראוי עם הקידומת Bearer
|
||||
**תאימות לאחור**: לבדוק שכלי ללא סיסמת אימות עובדים ללא שינוי
|
||||
**ניתוח ארגומנטים בשורת הפקודה**: לבדוק שהארגומנט `--auth-token` מנותח כראוי
|
||||
|
||||
### בדיקות אינטגרציה
|
||||
**חיבור מאומת**: בדיקת חיבור שירות כלי MCP לשרת מאומת
|
||||
**מקיף (End-to-End)**: בדיקת CLI → אחסון תצורה → הפעלת שירות עם טוקן אימות
|
||||
**טוקן לא נדרש**: בדיקת חיבור לשרת לא מאומת עדיין עובד
|
||||
|
||||
### בדיקות ידניות
|
||||
**שרת MCP אמיתי**: בדיקה עם שרת MCP אמיתי הדורש אימות באמצעות טוקן
|
||||
**זרימת עבודה של CLI**: בדיקת זרימת עבודה מלאה: הגדרת כלי עם אימות → הפעלת כלי → אימות הצלחה
|
||||
**הסתרת תצוגה**: ודאו שמצב האימות מוצג אך ערך הטוקן אינו נחשף
|
||||
|
||||
## מעבר ושילוב
|
||||
|
||||
### אסטרטגיית מעבר
|
||||
אין צורך במעבר - זו פונקציונליות נוספת בלבד:
|
||||
תצורות כלי MCP קיימות ללא `auth-token` ממשיכות לעבוד ללא שינוי
|
||||
ניתן לכלול את השדה `auth-token` בתצורות חדשות, אופציונלית
|
||||
כלי CLI מקבלים אך אינם דורשים את הפרמטר `--auth-token`
|
||||
|
||||
### תוכנית שילוב
|
||||
1. **שלב 1**: פריסת שינויים בסיסיים בשירות לסביבות פיתוח/בדיקות
|
||||
2. **שלב 2**: פריסת עדכוני כלי CLI
|
||||
3. **שלב 3**: עדכון תיעוד
|
||||
4. **שלב 4**: שילוב בסביבת ייצור עם ניטור
|
||||
|
||||
### תוכנית חזרה אחורה
|
||||
השינויים הבסיסיים תואמים לאחור - כלים קיימים אינם מושפעים
|
||||
אם מתעוררות בעיות, ניתן להשבית את הטיפול בטוקן אימות על ידי הסרת הלוגיקה לבניית כותרות
|
||||
שינויים ב-CLI הם עצמאיים וניתן לבטל אותם בנפרד
|
||||
|
||||
## שיקולי אבטחה
|
||||
|
||||
### ⚠️ מגבלה קריטית: אימות רק עבור לקוח יחיד
|
||||
|
||||
**מנגנון אימות זה אינו מתאים לסביבות מרובות משתמשים או מרובות לקוחות.**
|
||||
|
||||
**אישורים משותפים**: כל המשתמשים וההפעלה חולקים את אותו טוקן עבור כל כלי MCP
|
||||
**ללא הקשר משתמש**: שרת ה-MCP אינו יכול להבחין בין משתמשי TrustGraph שונים
|
||||
**ללא בידוד לקוחות**: כל הלקוחות חולקים את אותו אישור עבור כל כלי MCP
|
||||
**מגבלת מעקב**: שרת ה-MCP רושם את כל הבקשות מאותו אישור
|
||||
**היקף הרשאות**: לא ניתן לאכוף רמות הרשאות שונות עבור משתמשים שונים
|
||||
|
||||
**אל תשתמשו בתכונה זו אם:**
|
||||
הפריסה של TrustGraph שלכם משרתת מספר ארגונים (מרובת לקוחות)
|
||||
אתם צריכים לעקוב אילו משתמשים גשו לאילו כלי MCP
|
||||
משתמשים שונים דורשים רמות הרשאות שונות
|
||||
אתם צריכים לעמוד בדרישות מעקב ברמת המשתמש
|
||||
שרת ה-MCP שלכם מאכף מגבלות קצב או מכסות ברמת המשתמש
|
||||
|
||||
**פתרונות חלופיים עבור תרחישי משתמשים/לקוחות מרובים:**
|
||||
הטמעת העברת הקשר משתמש באמצעות כותרות מותאמות אישית
|
||||
פריסת מופעי TrustGraph נפרדים עבור כל לקוח
|
||||
שימוש בבידוד ברמת הרשת (VPCs, רשתות שירות)
|
||||
הטמעת שכבת פרוקסי המטפלת באימות מבוסס משתמש
|
||||
|
||||
### אחסון טוקנים
|
||||
**סיכון**: טוקנים של אימות מאוחסנים בטקסט רגיל במערכת התצורה
|
||||
|
||||
**הפחתה**:
|
||||
תיעוד העובדה שטוקנים מאוחסנים ללא הצפנה
|
||||
המלצה על שימוש בטוקנים קצרי טווח במידת האפשר
|
||||
המלצה על בקרת גישה מתאימה לאחסון התצורה
|
||||
שקילת שיפור עתידי לאחסון מוצפן של טוקנים
|
||||
|
||||
### חשיפת טוקנים
|
||||
**סיכון**: טוקנים עלולים להיחשף ביומני רישום או בפלט של שורת הפקודה
|
||||
|
||||
**הפחתה**:
|
||||
אין לרשום ערכי טוקנים (לרשום רק "אימות מוגדר: כן/לא")
|
||||
פקודת ה-CLI להצגה מציגה סטטוס מוסתר בלבד, ולא את הטוקן בפועל
|
||||
אין לכלול טוקנים בהודעות שגיאה
|
||||
|
||||
### אבטחת רשת
|
||||
**סיכון**: טוקנים מועברים על גבי חיבורים לא מוצפנים
|
||||
|
||||
**הפחתה**:
|
||||
המלצה לשימוש בכתובות URL של HTTPS עבור שרתי MCP
|
||||
אזהרת משתמשים לגבי סיכון השידור בטקסט רגיל עם HTTP
|
||||
|
||||
### גישה לתצורה
|
||||
**סיכון**: גישה לא מורשית למערכת התצורה חושפת טוקנים
|
||||
|
||||
**הפחתה**:
|
||||
תיעוד החשיבות של אבטחת גישה למערכת התצורה
|
||||
המלצה על עקרון ההרשאה המינימלית לגישה לתצורה
|
||||
שקילת רישום ביקורת עבור שינויים בתצורה (שיפור עתידי)
|
||||
|
||||
### סביבות מרובות משתמשים
|
||||
**סיכון**: בסביבות מרובות משתמשים, כל המשתמשים חולקים את אותם פרטי כניסה של MCP
|
||||
|
||||
**הבנת הסיכון**:
|
||||
משתמש א' ומשתמש ב' משתמשים באותו טוקן בעת גישה לכלי MCP
|
||||
שרת ה-MCP אינו יכול להבחין בין משתמשי TrustGraph שונים
|
||||
אין דרך לאכוף הרשאות או מגבלות קצב מבוססות משתמש
|
||||
יומני רישום בשרת ה-MCP מציגים את כל הבקשות מאותה פרטי כניסה
|
||||
אם הסשן של משתמש אחד נפגע, לתוקף יש את אותה גישה ל-MCP כמו לכל המשתמשים
|
||||
|
||||
**זהו לא באג - זהו מגבלה יסודית של עיצוב זה.**
|
||||
|
||||
## השפעה על ביצועים
|
||||
**תקורה מינימלית**: בניית כותרת מוסיפה זמן עיבוד זניח
|
||||
**השפעה על הרשת**: כותרת HTTP נוספת מוסיפה ~50-200 בתים לכל בקשה
|
||||
**שימוש בזיכרון**: עלייה זניחה עבור אחסון מחרוזת הטוקן בתצורה
|
||||
|
||||
## תיעוד
|
||||
|
||||
### תיעוד למשתמש
|
||||
[ ] עדכון `tg-set-mcp-tool.md` עם פרמטר `--auth-token`
|
||||
[ ] הוספת סעיף שיקולי אבטחה
|
||||
[ ] מתן דוגמה לשימוש עם טוקן bearer
|
||||
[ ] תיעוד השלכות אחסון טוקנים
|
||||
|
||||
### תיעוד למפתחים
|
||||
[ ] הוספת הערות שורה לטיפול בטוקן אימות ב-`service.py`
|
||||
[ ] תיעוד לוגיקת בניית כותרות
|
||||
[ ] עדכון תיעוד סכימת התצורה של כלי MCP
|
||||
|
||||
## שאלות פתוחות
|
||||
1. **הצפנת טוקנים**: האם עלינו ליישם אחסון מוצפן של טוקנים במערכת התצורה?
|
||||
2. **רענון טוקנים**: תמיכה עתידית בזרמי רענון OAuth או סיבוב טוקנים?
|
||||
3. **שיטות אימות חלופיות**: האם עלינו לתמוך באימות בסיסי, מפתחות API או שיטות אחרות?
|
||||
|
||||
## חלופות שנשקלו
|
||||
|
||||
1. **משתני סביבה עבור טוקנים**: אחסון טוקנים במשתני סביבה במקום בתצורה
|
||||
**נדחה**: מסבך פריסה וניהול תצורה
|
||||
|
||||
2. **מאגר סודות נפרד**: שימוש במערכת ניהול סודות ייעודית
|
||||
**נדחה**: מחוץ להיקף היישום הראשוני, לשקול שיפור עתידי
|
||||
|
||||
3. **שיטות אימות מרובות**: תמיכה בסיסי, מפתח API, OAuth וכו'.
|
||||
**נדחה**: טוקני bearer מכסים את רוב מקרי השימוש, לשמור על יישום ראשוני פשוט
|
||||
|
||||
4. **אחסון מוצפן של טוקנים**: הצפנת טוקנים במערכת התצורה
|
||||
**נדחה**: אבטחת מערכת התצורה היא דאגה רחבה יותר, לדחות לעבודה עתידית
|
||||
|
||||
5. **טוקנים לכל קריאה**: לאפשר העברת טוקנים בזמן ההפעלה
|
||||
**נדחה**: מפר את הפרדת האחריות, סוכן לא צריך לטפל באישורים
|
||||
|
||||
## הפניות
|
||||
[מפרט פרוטוקול MCP](https://github.com/modelcontextprotocol/spec)
|
||||
[אימות Bearer HTTP (RFC 6750)](https://tools.ietf.org/html/rfc6750)
|
||||
[כלי שירות MCP נוכחי](../trustgraph-flow/trustgraph/agent/mcp_tool/service.py)
|
||||
[מפרט ארגומנטים של כלי MCP](./mcp-tool-arguments.md)
|
||||
|
||||
## נספח
|
||||
|
||||
### שימוש לדוגמה
|
||||
פלט חוזה (יש לעקוב בדיוק אחר הפורמט הבא).
|
||||
**הגדרת כלי MCP עם אימות:**
|
||||
```bash
|
||||
tg-set-mcp-tool \
|
||||
--id secure-tool \
|
||||
--tool-url https://secure-server.example.com/mcp \
|
||||
--auth-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**הצגת כלי MCP:**
|
||||
```bash
|
||||
tg-show-mcp-tools
|
||||
|
||||
ID Remote Name URL Auth
|
||||
----------- ----------- ------------------------------------ ------
|
||||
secure-tool secure-tool https://secure-server.example.com/mcp Yes
|
||||
public-tool public-tool http://localhost:3000/mcp No
|
||||
```
|
||||
|
||||
### דוגמה לתצורה
|
||||
|
||||
**מאוחסן במערכת התצורה:**
|
||||
```json
|
||||
{
|
||||
"type": "mcp",
|
||||
"key": "secure-tool",
|
||||
"value": "{\"url\": \"https://secure-server.example.com/mcp\", \"auth-token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### שיטות עבודה מומלצות לאבטחה
|
||||
|
||||
1. **שימוש ב-HTTPS**: השתמשו תמיד בכתובות HTTPS עבור שרתי MCP עם אימות.
|
||||
2. **אסימונים קצרי טווח**: השתמשו באסימונים עם תאריך תפוגה כאשר אפשר.
|
||||
3. **הרשאות מינימליות**: העניקו לאסימונים את ההרשאות המינימליות הנדרשות.
|
||||
4. **בקרת גישה**: הגבילו את הגישה למערכת התצורה.
|
||||
5. **החלפת אסימונים**: החליפו אסימונים באופן קבוע.
|
||||
6. **רישום ביקורת**: עקבו אחר שינויים בתצורה לאירועי אבטחה.
|
||||
Loading…
Add table
Add a link
Reference in a new issue