xAgent · للمطورين
اربط أدواتك الخاصة (MCP)
امنح xAgent أدواتك الخاصة: تشغيل أضواء المكتب، أو البحث عن طلب، أو قراءة مواعيد الغد. تشغّل برنامجًا صغيرًا، يُسمى خادم MCP، على أي جهاز كمبيوتر تختاره. يتصل هو بـ XIOT، فلا تحتاج إلى فتح منافذ أو امتلاك عنوان عام.
قبل أن تبدأ
- مساعد في xConsole.
- جهاز كمبيوتر يبقى يعمل طوال الوقت الذي تريد فيه أن تعمل الأدوات، وعليه Python 3.10 أو أحدث.
- أن يكون إعداد التعرّف على النية للمساعد على استدعاء الوظائف (المساعد ← النماذج والذاكرة ← التعرّف على النية). وهو الإعداد الافتراضي.
١. انسخ عنوان MCP الخاص بمساعدك
- في xConsole، افتح الوكلاء واختر إعداد الوكيل لمساعدك.
- افتح تبويب الأدوات. في بطاقة أدواتك الخاصة (MCP)، اضغط نسخ.
يبدو العنوان هكذا: wss://console.xiot.io/mcp_endpoint/mcp/?token=…. لكل مساعد عنوانه الخاص.
تعامل معه ككلمة مرور. من يملكه يستطيع تقديم أدوات لمساعدك. لا تضعه في كود تشاركه أو ترفعه؛ احفظه في متغير بيئة.
٢. شغّل مثال الآلة الحاسبة
أسرع طريقة لترى ذلك يعمل هي مثال الآلة الحاسبة مفتوح المصدر. يمنح مساعدك أداة واحدة: calculator.
git clone https://github.com/78/mcp-calculator
cd mcp-calculator
pip install -r requirements.txt
اضبط العنوان الذي نسخته، ثم شغّله. على macOS أو Linux:
export MCP_ENDPOINT='wss://console.xiot.io/mcp_endpoint/mcp/?token=…'
python mcp_pipe.py calculator.py
على Windows (PowerShell):
$env:MCP_ENDPOINT = 'wss://console.xiot.io/mcp_endpoint/mcp/?token=…'
python mcp_pipe.py calculator.py
اتركه يعمل. يُبقي mcp_pipe.py الاتصال مفتوحًا ويعيد الاتصال تلقائيًا إذا انقطعت الشبكة.
٣. تحقق منه في xConsole وجرّبه
- عد إلى تبويب الأدوات واضغط زر التحديث بجانب الحالة. ستظهر متصل · 1 أدوات مع
calculator. - ابدأ محادثة جديدة مع xAgent واسأل: «كم يساوي ١٨ بالمئة من ٢٤٥٠؟»
تُحمَّل الأدوات الجديدة في بداية كل محادثة، لذا تحتفظ المحادثة الجارية بالأدوات التي بدأت بها.
اكتب أداتك الخاصة
الأداة دالة Python لها اسم ووصف واضحان. يقرأ المساعد الوصف ليقرر متى يستخدمها. احفظ هذا باسم office.py بجانب mcp_pipe.py:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Office")
@mcp.tool()
def meeting_room_status(room: str) -> dict:
"""Tells whether a meeting room is free now. room: the room's name, e.g. "Palm"."""
busy = room.lower() in {"palm"} # replace with your booking system
return {"success": True, "result": f"{room} is {'busy' if busy else 'free'} right now"}
if __name__ == "__main__":
mcp.run(transport="stdio")
python mcp_pipe.py office.py
يمكن لعدة خوادم MCP الاتصال بالمساعد نفسه، وتُضاف أدواتها معًا.
نصائح
- اكتب متى تُستخدم الأداة. «يشغّل أضواء المكتب أو يطفئها» أفضل من «أضواء». الأوصاف بالإنجليزية تعمل في المحادثات العربية أيضًا.
- أعد نتائج قصيرة. يحوّلها المساعد إلى كلام، فالجملة أفضل من الجدول.
- أجب خلال ثوانٍ. الشخص ينتظر الرد.
- احذر مع الإجراءات. تحقق من المدخلات، ولكل ما لا يمكن التراجع عنه (الدفع، الحذف) اجعل الأداة تطلب التأكيد أولًا.
حل المشكلات
غير متصل
- انسخ العنوان مجددًا: يجب أن يشمل كل ما بعد
token=. - تأكد أن البرنامج ما زال يعمل وأن سجله يخلو من الأخطاء.
- يحتاج الكمبيوتر إلى اتصال HTTPS صادر (المنفذ 443) إلى
console.xiot.io.
متصل، لكن المساعد لا يستخدم الأداة
- ابدأ محادثة جديدة: تُحمَّل الأدوات عند بدايتها.
- اجعل الوصف يقول بوضوح ماذا تفعل الأداة ومتى تُستخدم.
- تأكد أن التعرّف على النية مضبوط على استدعاء الوظائف.
MCP أم البيانات الحية أم الأدوات المدمجة؟
| استخدم | عندما |
|---|---|
| أدواتك الخاصة (MCP) | تريد أن يفعل المساعد شيئًا أو يبحث عن شيء عندما يُطلب منه. |
| البيانات الحية (مصادر السياق) | تريد أن يعرف المساعد شيئًا مسبقًا في بداية كل محادثة. |
| الأدوات المدمجة | الطقس ومواقيت الصلاة والتذكيرات والملاحظات وأزرار الجهاز نفسه. فعّلها من المساعد ← الأدوات ← تعديل الوظائف. |