mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
8954fa3ad7
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.
163 lines
10 KiB
Markdown
163 lines
10 KiB
Markdown
---
|
|
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
|
|
**المؤلف**: مساعد كود كلوود
|
|
**التاريخ**: 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**: تحميل تكوين الأداة وإنشاء AgentManager
|
|
- **trustgraph-flow/agent/react/tools.py**: تنفيذ McpToolImpl
|
|
- **trustgraph-flow/agent/react/agent_manager.py**: إنشاء المطالبات بمعاملات الأداة
|
|
- **CLI tools**: أدوات سطر الأوامر لإدارة أدوات 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 في التكوين حتى تتمكن نماذج اللغة الكبيرة من استدعاء الأدوات بمعلمات صحيحة
|
|
2. بصفتي **مستخدم واجهة Workbench**: أرغب في تكوين معاملات أداة MCP في واجهة المستخدم حتى تستخدم الوكلاء الأدوات بشكل صحيح
|
|
3. بصفتي **نموذج لغة كبيرة في وكيل ReACT**: أرغب في رؤية مواصفات معامل الأداة في المطالبات حتى أتمكن من توفير المعلمات الصحيحة
|
|
|
|
## التصميم
|
|
|
|
### الهندسة المعمارية عالية المستوى
|
|
لتحقيق التوافق مع أنماط أدوات القالب، قم بتوسيع تكوين أداة MCP عن طريق:
|
|
1. إضافة مصفوفة اختيارية "arguments" إلى تكوينات أدوات MCP
|
|
2. تعديل `McpToolImpl` لقبول وإرجاع المعاملات المحددة
|
|
3. تحديث تحميل تكوين الأداة للتعامل مع معاملات أدوات MCP
|
|
4. التأكد من تضمين معلومات معامل أداة MCP في المطالبات
|
|
|
|
### مخطط التكوين
|
|
```json
|
|
{
|
|
"type": "mcp-tool",
|
|
"name": "get_bank_balance",
|
|
"description": "Get bank account balance",
|
|
"mcp-tool": "get_bank_balance",
|
|
"arguments": [
|
|
{
|
|
"name": "account_id",
|
|
"type": "string",
|
|
"description": "Bank account identifier"
|
|
},
|
|
{
|
|
"name": "date",
|
|
"type": "string",
|
|
"description": "Date for balance query (optional, format: YYYY-MM-DD)"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### تدفق البيانات
|
|
1. **تحميل التكوين**: يتم تحميل تكوين أداة MCP مع المعاملات بواسطة `on_tools_config()`
|
|
2. **إنشاء الأداة**: يتم تحليل المعاملات وتمريرها إلى `McpToolImpl` من خلال المُنشئ
|
|
3. **توليد المطالبة**: تتلقى LLMs معلومات المعاملات من الأداة، مما يسمح لها بإنشاء مطالبات مناسبة.
|
|
4. **تنفيذ الأداة**: يتم تنفيذ أداة MCP باستخدام المعاملات التي تم تمريرها.
|
|
|
|
### تأثير الأداء
|
|
- **وقت تشغيل ضئيل**: يحدث تحليل المعاملات فقط أثناء تحميل التكوين، وليس لكل طلب
|
|
- **حجم المطالبة**: قد تزيد المطالبات الخاصة بالوكيل قليلاً بسبب تضمين تفاصيل معامل أداة MCP.
|
|
- **استخدام الذاكرة**: زيادة ضئيلة لتخزين مواصفات المعاملات في كائنات الأداة.
|
|
|
|
## الوثائق
|
|
|
|
### وثائق المستخدم
|
|
- [ ] تحديث دليل تكوين أداة MCP مع أمثلة للمعاملات
|
|
- [ ] إضافة مواصفات المعامل إلى نص مساعد أدوات سطر الأوامر
|
|
- [ ] إنشاء أمثلة لأنماط معلمات أداة MCP الشائعة
|
|
|
|
### وثائق المطور
|
|
- [ ] تحديث وثائق فئة `McpToolImpl`
|
|
- [ ] إضافة تعليقات توضيحية حول منطق تحليل المعاملات
|
|
- [ ] توثيق تدفق المعامل في الهندسة المعمارية للنظام
|
|
|
|
## الأسئلة المفتوحة
|
|
1. **التحقق من صحة المعاملات**: هل يجب علينا التحقق من أنواع المعاملات/تنسيقاتها بالإضافة إلى التحقق الأساسي من الهيكل؟
|
|
2. **اكتشاف ديناميكي**: هل نريد الاستعلام عن خوادم MCP عن مخططات أدوات بشكل تلقائي؟
|
|
|
|
## البدائل التي تم النظر فيها
|
|
1. **اكتشاف مخططات MCP الديناميكية**: الاستعلام عن خوادم MCP عن مخططات أدوات المعامل في وقت التشغيل - تم رفضها بسبب التعقيد ومخاوف الموثوقية
|
|
2. **سجل المعاملات المنفصل**: تخزين معاملات أداة MCP في قسم تكوين منفصل - تم رفضه للحفاظ على التوافق مع نهج أدوات القالب
|
|
3. **التحقق من نوع المعامل**: التحقق الكامل من مخطط JSON للمعاملات - تم تأجيله للحفاظ على البساطة في التنفيذ الأولي
|
|
|
|
## المراجع
|
|
- [المواصفات الخاصة ببروتوكول MCP](https://github.com/modelcontextprotocol/spec)
|
|
- [تنفيذ أداة MCP](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
|
|
- [تنفيذ أداة MCP الحالي](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)
|
|
|
|
## الملحق
|
|
[أي معلومات إضافية، أو مخططات، أو أمثلة]
|