MCP لمساعدي الذكاء الاصطناعي

يوصل خادم HAM MCP (Model Context Protocol) مساعد ذكاء اصطناعي بأجهزتك. يستطيع المساعد رؤية قائمة الأجهزة والقراءات الحالية والسجل. يعمل كل استدعاء بحسابك وبأذوناتك على كل جهاز.

بيانات الاتصال

العنصر	القيمة
العنوان	https://api.hamsystems.eu/mcp/index.php
النقل	HTTP، JSON-RPC 2.0
إصدار البروتوكول	2024-11-05
المصادقة	الترويسة Authorization: Bearer-API YOUR_API_KEY

تنشئ مفتاح API في صفحة الحساب. انظر REST API.

إعداد المساعد

1. أنشئ مفتاح API.

2. أضف الخادم إلى إعدادات MCP في مساعدك. في Claude Code، الملف هو .mcp.json:

   {
     "mcpServers": {
       "ham": {
         "type": "http",
         "url": "https://api.hamsystems.eu/mcp/index.php",
         "headers": {
           "Authorization": "Bearer-API YOUR_API_KEY"
         }
       }
     }
   }

3. أعد تشغيل المساعد.

4. اسأل مثلًا “اعرض أجهزتي”. يستدعي المساعد الأداة list_devices.

تنبيه

للمساعد الوصول نفسه الذي لديك. يستطيع التحكم في المخرجات على الأجهزة التي لديك عليها إذن الكتابة. لا تشارك ملف الإعدادات، لأنه يحتوي على مفتاحك.

الأدوات

الأداة	المعاملات	النتيجة
list_devices	compact (الافتراضي true)	أجهزتك. مع compact: true: serialno وname وicon وgroups وfloorplans وcount. مع compact: false: كل التفاصيل، مع الإعدادات.
get_device_state	serialno (رقم واحد أو قائمة)	الحالة الحالية. التنسيق نفسه لـ get_device_state.php. انظر REST API.
get_device_history	serialno، level، bin	صفوف السجل. المستويات والـ bins نفسها الموجودة في تنزيل البيانات التاريخية.
get_definitions	family_id (اختياري)، include_readings (الافتراضي true)	تعريفات العائلة: القراءات والمخرجات والإعدادات
get_docs	لا يوجد	تعليمات الأدوات
send_command	serialno، command	يرسل أمرًا إلى جهاز أو مجموعة. يحصل المساعد على الأوامر من get_docs.

ترتيب الاستدعاء المعتاد: list_devices، ثم get_definitions للعائلة، ثم get_device_state أو get_device_history.

الاختبار بـ curl

curl -X POST https://api.hamsystems.eu/mcp/index.php \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'

النتيجة موجودة في result.content[0].text، كنص JSON:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"devices\":[{\"serialno\":\"e11:123\",\"name\":\"Fridge 1\",\"icon\":\"\",\"groups\":[],\"floorplans\":[]}],\"count\":1}" }
    ]
  }
}

الطرق المدعومة: initialize وnotifications/initialized وtools/list وtools/call.

الأخطاء

الرمز	المعنى
-32000	خطأ في المصادقة (HTTP 401) أو خطأ في الأداة
-32700	المحتوى ليس JSON صالحًا
-32600	طلب JSON-RPC غير صالح
-32601	طريقة غير معروفة
-32602	اسم الأداة مفقود
-32603	خطأ داخلي

انظر أيضًا

• REST API
• الأمان