MCP לעוזרי AI

שרת ה-MCP ‏(Model Context Protocol) של HAM מחבר עוזר AI למכשירים שלכם. העוזר יכול לראות את רשימת המכשירים, את המדידות הנוכחיות ואת ההיסטוריה. כל קריאה פועלת עם החשבון שלכם ועם ההרשאות שלכם על כל מכשיר.

פרטי החיבור

פריט	ערך
כתובת	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.

Caution

לעוזר יש אותה גישה כמו לכם. הוא יכול לשלוט בפלטים של המכשירים שבהם יש לכם הרשאת כתיבה. אל תשתפו את קובץ ההגדרות, כי המפתח שלכם נמצא בו.

כלים

כלי	פרמטרים	תוצאה
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
• אבטחה