عن المشروع

ccu-mcp هو خادم Model Context Protocol (MCP) يربط مساعدي الذكاء الاصطناعي (مثل Claude أو Cursor أو أي عميل MCP) بأنظمة HomeMatic المنزلية الذكية. يتصل مباشرة بواجهة JSON-RPC المدمجة في CCU (عبر `/api/homematic.cgi`)، مما يلغي الحاجة إلى إضافات أو XML-API أو خدمات سحابية. يعمل مع أي HomeMatic CCU، بما في ذلك debmatic وCCU3 وOpenCCU (المعروف سابقًا باسم RaspberryMatic). يتولى الخادم اكتشاف الأجهزة وتحليل الأنواع وإدارة الجلسات وتحويل القيم، ويعرض أدوات تتيح للمستخدمين طرح أسئلة بلغة طبيعية مثل "ما درجة الحرارة في الحمام؟" أو "هل هناك أي نوافذ مفتوحة؟" أو "اضبط تدفئة غرفة المعيشة على 21 درجة" أو "أرني جميع الأجهزة ذات البطارية المنخفضة". كما يدعم عمليات متقدمة مثل إعادة تسمية الأجهزة لتتبع اصطلاحات التسمية، والعثور على أسماء قنوات غير متطابقة، وفحص صحة الأجهزة. **الميزات الرئيسية:** - **اتصال مباشر بـ CCU**: لا إضافات أو سحابة؛ يستخدم نقطة نهاية JSON-RPC القياسية. - **وسائل نقل متعددة**: يعمل كعملية فرعية (stdio) أو كخادم HTTP مستقل (Docker). - **دعم Docker**: صور منشورة لـ linux/amd64 وlinux/arm64، مع attestation لأمان سلسلة التوريد. - **ملفات تعريف CCU متعددة**: تكوين والتبديل بين عدة CCU (مثل prod وdev) من خادم واحد. - **الأمان**: مصادقة رمز Bearer (يتم إنشاؤه تلقائيًا أو صريحًا)، وحماية من إعادة ربط DNS، وقائمة CORS المسموح بها، ودعم TLS (بما في ذلك تثبيت الشهادات ذاتية التوقيع)، وتكامل اختياري مع fail2ban. - **معالج الإعداد**: أمر `init` التفاعلي يفحص CCU، ويثبت شهادات TLS، ويختبر تسجيل الدخول، ويكتب ملف `.env` جاهزًا للاستخدام. وضع إعداد حواري يتيح لنموذج لغوي كبير إرشاد العملية عبر الدردشة. - **التشخيص**: أمر `doctor` يتحقق من التكوين من البداية إلى النهاية. - **تحديد المعدل**: حدود معدل مدمجة للانفجار والمعدل المستدام لحماية CCU. - **استقصاء الموارد**: استقصاء اختياري لإشعارات تغيير موارد MCP. **التثبيت والاستخدام:** - **البدء السريع (stdio)**: عيّن متغيرات البيئة `CCU_HOST` و`CCU_PASSWORD`، ثم شغّل `npx ccu-mcp --stdio`. قم بتكوين عميل MCP (مثل Claude Code) باستخدام ملف `.mcp.json`. - **Docker (HTTP)**: اسحب الصورة، وشغّلها مع متغيرات البيئة، واحصل على رمز المصادقة من وحدة تخزين بيانات الحاوية. قم بتكوين العميل باستخدام عنوان URL للخادم ورمز Bearer. - **التكوين**: جميع الإعدادات عبر متغيرات البيئة (انظر الجدول في README). يدعم env المضمّن، أو ملفات `.env`، أو تصدير shell. - **أعلام CLI**: `init`، `doctor`، `secret`، `--stdio`، `--http`، `--env`، `--version`، `--help`. **اعتبارات الأمان:** - يعمل الخادم افتراضيًا عبر HTTP عادي لكنه يحذر عند تقديم الرموز عبر واجهات غير loopback؛ عيّن `MCP_ALLOW_PLAINTEXT=true` للإقرار بذلك. - للوصول عن بُعد، استخدم TLS (وكيل عكسي أو HTTPS أصلي) وعيّن `MCP_ALLOWED_HOSTS` لتجنب أخطاء 403. - يتم دعم تدوير الرموز مع فترات سماح لتجنب تعطيل العميل. - CORS مرفوض افتراضيًا؛ اسمح بأصول محددة للعملاء المستندين إلى المتصفح. **المتطلبات:** Node.js 24+ (للمصدر/stdio) أو Docker. HomeMatic CCU قيد التشغيل مع بيانات اعتماد المسؤول. **مثال تكوين العميل (stdio):** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "your-ccu-hostname-or-ip", "CCU_PASSWORD": "your-ccu-admin-password" } } } } ``` **مثال تكوين العميل (HTTP):** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` المشروع مفتوح المصدر ويرحب بالمساهمات. يتضمن شارات OpenSSF Best Practices وScorecard، مما يشير إلى التركيز على الأمان والجودة.