trustgraph/docs/tech-specs/mcp-tool-bearer-token.ar.md

---
layout: default
title: "مواصفات مصادقة رمز الحامل لأدوات MCP"
parent: "Arabic (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
**المؤلف**: مساعد كود كلود
**التاريخ**: 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. **مشكلات النشر في بيئة الإنتاج:** لا يمكن اتباع أفضل الممارسات الأمنية لنقاط نهاية واجهة برمجة التطبيقات.

**قيود هذا الحل:**
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 حيث يحتاج كل من المستأجر A والمستأجر B إلى الوصول إلى خوادم MCP الخاصة بهم المعزولة ببيانات اعتماد منفصلة. لا يدعم هذا الميزة إدارة الرموز الخاصة بالمستأجر.

### المكونات ذات الصلة
**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.
**مجموعة تطوير البرامج (SDK) لـ MCP بلغة Python**: `streamablehttp_client` من `mcp.client.streamable_http`

## المتطلبات

### المتطلبات الوظيفية

1. **رمز مصادقة تكوين MCP:** يجب أن تدعم تكوينات أداة MCP حقل `auth-token` اختياري.
2. **استخدام رمز مميز:** يجب أن ترسل خدمة أداة 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**، أريد تكوين رموز مميزة لأدوات MCP حتى أتمكن من تأمين نقاط نهاية خادم MCP.
2. بصفتي **مستخدم سطر أوامر**، أريد تعيين رموز مميزة عند إنشاء أدوات MCP حتى أتمكن من الاتصال بالخوادم المحمية.
3. بصفتي **مسؤول النظام**، أريد أن أرى أي أدوات MCP تم تكوين مصادقة لها حتى أتمكن من تدقيق إعدادات الأمان.

## التصميم

### البنية عالية المستوى
قم بتوسيع تكوين وخدمة أداة MCP لدعم مصادقة الرمز المميز:
1. أضف حقل `auth-token` اختياري إلى مخطط تكوين أداة MCP.
2. قم بتعديل خدمة أداة MCP لقراءة الرمز المميز وتمريره إلى عميل HTTP.
3. قم بتحديث أدوات سطر الأوامر لدعم تعيين وعرض الرموز المميزة.
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 token) للمصادقة

### تدفق البيانات

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)
لا توجد تغييرات في واجهة برمجة التطبيقات الخارجية - فقط توسيع مخطط التكوين.

### تفاصيل المكون

#### المكون 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 لواجهة برمجة تطبيقات TrustGraph

**وسيطة جديدة**:
`--auth-token` (اختياري): رمز مميز للمصادقة

**تعديل بناء التكوين**:
```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. توثيق الاعتبارات الأمنية

## خطة التنفيذ

### المرحلة الأولى: إنشاء المواصفات الفنية
[x] كتابة مواصفات فنية شاملة توثق جميع التغييرات

### المرحلة الثانية: تحديث خدمة MCP
[ ] تعديل `invoke_tool()` في `service.py` لقراءة رمز المصادقة من التكوين
[ ] إنشاء قاموس الرؤوس وتمريره إلى `streamablehttp_client`
[ ] الاختبار مع خادم MCP مصادق عليه

### المرحلة الثالثة: تحديث أدوات سطر الأوامر
[ ] إضافة المعامل `--auth-token` إلى `set_mcp_tool.py`
[ ] تضمين رمز المصادقة في ملف تكوين JSON
[ ] إضافة عمود "المصادقة" إلى إخراج `show_mcp_tools.py`
[ ] اختبار تغييرات أداة سطر الأوامر

### المرحلة الرابعة: تحديث التوثيق
[ ] توثيق المعامل `--auth-token` في `tg-set-mcp-tool.md`
[ ] إضافة قسم للاعتبارات الأمنية
[ ] تقديم مثال للاستخدام

### المرحلة الخامسة: الاختبار
[ ] اختبار أن خدمة MCP تقرأ رمز المصادقة وتتصل بنجاح
[ ] اختبار التوافق مع الإصدارات السابقة (الأدوات بدون رمز مصادقة لا تزال تعمل)
[ ] اختبار أن أدوات سطر الأوامر تقبل وتخزن رمز المصادقة بشكل صحيح
[ ] اختبار أن الأمر "عرض" يعرض حالة المصادقة بشكل صحيح

### ملخص التغييرات في التعليمات البرمجية
| الملف | نوع التغيير | الأسطر | الوصف |
|------|------------|-------|-------------|
| `service.py` | تم التعديل | ~52-66 | إضافة قراءة رمز المصادقة وإنشاء الرؤوس |
| `set_mcp_tool.py` | تم التعديل | ~30-60 | إضافة وسيطة --auth-token وتخزين التكوين |
| `show_mcp_tools.py` | تم التعديل | ~40-70 | إضافة عمود المصادقة للعرض |
| `tg-set-mcp-tool.md` | تم التعديل | متنوع | توثيق المعامل الجديد |

## استراتيجية الاختبار

### اختبارات الوحدة
**قراءة رمز المصادقة**: اختبار ما إذا كانت `invoke_tool()` تقرأ رمز المصادقة بشكل صحيح من التكوين
**إنشاء الرؤوس**: اختبار ما إذا كان يتم إنشاء رأس التفويض بشكل صحيح مع البادئة "Bearer"
**التوافق مع الإصدارات السابقة**: اختبار ما إذا كانت الأدوات بدون رمز مصادقة تعمل دون تغيير
**تحليل وسيطات سطر الأوامر**: اختبار ما إذا كانت المعامل `--auth-token` يتم تحليلها بشكل صحيح

### اختبارات التكامل
**الاتصال المصادق**: اختبار ما إذا كانت خدمة MCP تتصل بخادم مصادق عليه
**نهاية إلى نهاية**: اختبار تدفق سطر الأوامر → تخزين التكوين → استدعاء الخدمة باستخدام رمز المصادقة
**غير مطلوب رمز المصادقة**: اختبار الاتصال بخادم غير مصادق عليه لا يزال يعمل

### الاختبار اليدوي
**خادم MCP حقيقي**: اختبار مع خادم MCP فعلي يتطلب مصادقة باستخدام رمز "Bearer"
**تدفق سطر الأوامر**: اختبار التدفق الكامل: تعيين الأداة باستخدام رمز مصادقة → استدعاء الأداة → التحقق من النجاح
**إخفاء العرض**: التحقق من أن حالة المصادقة معروضة ولكن قيمة الرمز غير معروضة

## الترحيل والنشر

### استراتيجية الترحيل
لا يلزم الترحيل - هذه وظيفة إضافية بحتة:
تكوينات أدوات MCP الحالية بدون `auth-token` تستمر في العمل دون تغيير
يمكن أن تتضمن التكوينات الجديدة اختياريًا حقل `auth-token`
تقبل أدوات سطر الأوامر ولكن لا تتطلب المعامل `--auth-token`

### خطة النشر
1. **المرحلة 1**: نشر تغييرات الخدمة الأساسية إلى التطوير/التجريب
2. **المرحلة 2**: نشر تحديثات أدوات سطر الأوامر
3. **المرحلة 3**: تحديث التوثيق
4. **المرحلة 4**: النشر في بيئة الإنتاج مع المراقبة

### خطة التراجع
التغييرات الأساسية متوافقة مع الإصدارات السابقة - لا تتأثر الأدوات الحالية
في حالة ظهور مشكلات، يمكن تعطيل معالجة رمز المصادقة عن طريق إزالة منطق إنشاء الرأس
يمكن التراجع عن تغييرات سطر الأوامر بشكل مستقل

## اعتبارات الأمان

### ⚠️ قيد حاسم: مصادقة المستأجر الواحد فقط

**هذه آلية المصادقة غير مناسبة للبيئات متعددة المستخدمين أو متعددة المستأجرين.**

**بيانات اعتماد مشتركة**: جميع المستخدمين والاستدعاءات يشاركون نفس الرمز لكل أداة MCP
**لا يوجد سياق مستخدم**: لا يمكن لخادم MCP التمييز بين مستخدمي TrustGraph المختلفين
**عزل المستأجر**: تشارك جميع المستأجرين نفس الاعتماد لكل أداة MCP
**قيود سجل التدقيق**: يسجل خادم MCP جميع الطلبات من نفس الاعتماد
**نطاق الأذونات**: لا يمكن فرض مستويات أذونات مختلفة لمستخدمين مختلفين

**لا تستخدم هذه الميزة إذا:**
يخدم توزيعة TrustGraph الخاصة بك مؤسسات متعددة (متعددة المستأجرين)
تحتاج إلى تتبع المستخدم الذي قام بالوصول إلى أداة MCP
تتطلب مستخدمون مختلفون مستويات أذونات مختلفة
تحتاج إلى الامتثال لمتطلبات التدقيق على مستوى المستخدم
خادم MCP الخاص بك يفرض حدود معدل أو حصص لكل مستخدم

**حلول بديلة لسيناريوهات المستخدمين المتعددين/العملاء المتعددين:**
تنفيذ نشر سياق المستخدم من خلال رؤوس مخصصة
نشر مثيلات TrustGraph منفصلة لكل عميل
استخدام عزل على مستوى الشبكة (VPCs، شبكات الخدمات)
تنفيذ طبقة وكيل تتعامل مع المصادقة لكل مستخدم

### تخزين الرموز المميزة
**مخاطر**: يتم تخزين الرموز المميزة للمصادقة كنص عادي في نظام التكوين

**تدابير تخفيفية**:
توثيق أن الرموز المميزة مخزنة بدون تشفير
يوصى باستخدام الرموز المميزة قصيرة الأجل كلما أمكن ذلك
يوصى بتطبيق ضوابط وصول مناسبة على تخزين التكوين
ضع في اعتبارك تحسينًا مستقبليًا لتخزين الرموز المميزة المشفرة

### كشف الرموز المميزة
**مخاطر**: يمكن الكشف عن الرموز المميزة في سجلات أو مخرجات سطر الأوامر

**تدابير تخفيفية**:
لا تقم بتسجيل قيم الرموز المميزة (قم بتسجيل "تم تكوين المصادقة: نعم/لا" فقط)
يعرض أمر "show" الخاص بسطر الأوامر الحالة "مخفية" فقط، وليس الرمز المميز الفعلي
لا تقم بتضمين الرموز المميزة في رسائل الخطأ

### أمان الشبكة
**مخاطر**: يتم نقل الرموز المميزة عبر اتصالات غير مشفرة

**تدابير تخفيفية**:
يوصى بتوثيق استخدام عناوين URL لبروتوكول HTTPS لخوادم MCP
تحذير المستخدمين بشأن مخاطر النقل النصي باستخدام HTTP

### الوصول إلى التكوين
**مخاطر**: يؤدي الوصول غير المصرح به إلى نظام التكوين إلى كشف الرموز المميزة

**تدابير تخفيفية**:
قم بتوثيق أهمية تأمين الوصول إلى نظام التكوين
يوصى بمبدأ الامتياز الأقل للوصول إلى التكوين
ضع في اعتبارك تسجيل التدقيق للتغييرات في التكوين (تحسين مستقبلي)

### بيئات المستخدمين المتعددين
**مخاطر**: في عمليات النشر متعددة المستخدمين، يشارك جميع المستخدمين نفس بيانات اعتماد MCP

**فهم المخاطر**:
يستخدم كل من المستخدم أ والمستخدم ب نفس الرمز المميز عند الوصول إلى أداة MCP
لا يمكن لخادم MCP التمييز بين مستخدمي TrustGraph المختلفين
لا توجد طريقة لفرض أذونات أو حدود معدل لكل مستخدم
تُظهر سجلات التدقيق على خادم MCP جميع الطلبات من نفس الاعتماد
إذا تم اختراق جلسة مستخدم واحد، يتمتع المهاجم بنفس وصول MCP مثل جميع المستخدمين

**هذا ليس خطأ - إنه قيد أساسي لهذا التصميم.**

## التأثير على الأداء
**نفقات عامة ضئيلة**: يضيف بناء الرأس وقت معالجة ضئيل
**تأثير الشبكة**: يضيف رأس HTTP إضافي ~ 50-200 بايت لكل طلب
**استخدام الذاكرة**: زيادة طفيفة لتخزين سلسلة الرمز المميز في التكوين

## التوثيق

### وثائق المستخدم
[ ] قم بتحديث `tg-set-mcp-tool.md` باستخدام معلمة `--auth-token`
[ ] أضف قسمًا للاعتبارات الأمنية
[ ] قدم مثالًا للاستخدام باستخدام رمز مميز
[ ] قم بتوثيق آثار تخزين الرمز المميز

### وثائق المطور
[ ] أضف تعليقات مضمنة للتعامل مع الرمز المميز للمصادقة في `service.py`
[ ] وثق منطق بناء الرأس
[ ] قم بتحديث وثائق مخطط تكوين أداة MCP

## أسئلة مفتوحة
1. **تشفير الرمز المميز**: هل يجب علينا تنفيذ تخزين مشفر للرموز المميزة في نظام التكوين؟
2. **تحديث الرمز المميز**: دعم مستقبلي لتدفقات تحديث OAuth أو تدوير الرموز المميزة؟
3. **طرق مصادقة بديلة**: هل يجب أن ندعم المصادقة الأساسية أو مفاتيح API أو طرق أخرى؟

## بدائل تم أخذها في الاعتبار

1. **متغيرات البيئة للرموز المميزة**: قم بتخزين الرموز المميزة في متغيرات البيئة بدلاً من التكوين
   **مرفوض**: يعقد النشر وإدارة التكوين

2. **مخزن أسرار منفصل**: استخدم نظام إدارة أسرار مخصص
   **مؤجل**: خارج نطاق التنفيذ الأولي، ضع في اعتبارك تحسينًا مستقبليًا

3. **طرق مصادقة متعددة**: دعم الأساسي و API key و OAuth وما إلى ذلك
   **مرفوض**: تغطي الرموز المميزة الخاصة بالحامل معظم حالات الاستخدام، حافظ على بساطة التنفيذ الأولي

4. **تخزين مشفر للرموز المميزة**: قم بتشفير الرموز المميزة في نظام التكوين
   **مؤجل**: يعد أمان نظام التكوين مصدر قلق أوسع، وتأجيله إلى عمل مستقبلي

5. **الرموز المميزة لكل استدعاء**: اسمح بتمرير الرموز المميزة في وقت الاستدعاء
   **مرفوض**: ينتهك فصل الاهتمامات، لا ينبغي للوكيل التعامل مع بيانات الاعتماد

## المراجع
[مواصفات بروتوكول MCP](https://github.com/modelcontextprotocol/spec)
[مصادقة حامل 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**: استخدم دائمًا عناوين URL لبروتوكول HTTPS لخوادم MCP التي تتطلب مصادقة.
2. **الرموز قصيرة الأجل**: استخدم الرموز التي لها تاريخ انتهاء صلاحية كلما أمكن ذلك.
3. **أقل الامتيازات**: امنح الرموز الحد الأدنى من الأذونات المطلوبة.
4. **التحكم في الوصول**: قم بتقييد الوصول إلى نظام التكوين.
5. **تغيير الرموز بشكل دوري**: قم بتغيير الرموز بانتظام.
6. **تسجيل التدقيق**: راقب تغييرات التكوين بحثًا عن أحداث أمنية.