منصوبے کے بارے میں

ccu-mcp ایک ماڈل کانٹیکسٹ پروٹوکول (MCP) سرور ہے جو AI اسسٹنٹس (جیسے Claude، Cursor، یا کوئی بھی MCP کلائنٹ) کو HomeMatic سمارٹ ہوم سسٹمز سے جوڑتا ہے۔ یہ براہ راست CCU کے بلٹ ان JSON-RPC API (بذریعہ `/api/homematic.cgi`) سے منسلک ہوتا ہے، جس سے ایڈونز، XML-API، یا کلاؤڈ سروسز کی ضرورت ختم ہو جاتی ہے۔ یہ کسی بھی HomeMatic CCU کے ساتھ کام کرتا ہے، بشمول debmatic، CCU3، اور OpenCCU (پہلے RaspberryMatic)۔ سرور ڈیوائس کی دریافت، قسم کی شناخت، سیشن مینجمنٹ، اور ویلیو کنورژن کو سنبھالتا ہے، اور صارفین کو قدرتی زبان کے سوالات پوچھنے کے قابل بناتا ہے جیسے "باتھ روم میں درجہ حرارت کیا ہے؟"، "کیا کوئی کھڑکی کھلی ہے؟"، "لونگ روم کی ہیٹنگ 21 ڈگری پر سیٹ کریں"، یا "مجھے کم بیٹری والے تمام ڈیوائسز دکھائیں"۔ یہ اعلی درجے کی کارروائیوں کو بھی سپورٹ کرتا ہے جیسے ڈیوائسز کا نام تبدیل کرنا تاکہ نام دینے کے کنونشنز پر عمل ہو، مماثل نہ ہونے والے چینل ناموں کی تلاش، اور ڈیوائس کی صحت کی جانچ۔ **کلیدی خصوصیات:** - **براہ راست CCU کنکشن**: کوئی ایڈونز یا کلاؤڈ نہیں؛ معیاری JSON-RPC اینڈ پوائنٹ استعمال کرتا ہے۔ - **متعدد ٹرانسپورٹس**: سب پروسیس (stdio) یا اسٹینڈ اکیلا HTTP سرور (Docker) کے طور پر چلائیں۔ - **Docker سپورٹ**: linux/amd64 اور linux/arm64 کے لیے شائع شدہ امیجز، سپلائی چین سیکیورٹی کے لیے تصدیق کے ساتھ۔ - **متعدد CCU پروفائلز**: ایک سرور سے کئی CCUs (مثلاً پروڈ اور ڈیو) کنفیگر اور سوئچ کریں۔ - **سیکیورٹی**: بیئرر ٹوکن تصدیق (خودکار یا واضح)، DNS-ری بائنڈنگ تحفظ، CORS الاؤنسٹ، TLS سپورٹ (سیلف سائنڈ سرٹ پننگ سمیت)، اور اختیاری fail2ban انٹیگریشن۔ - **سیٹ اپ وزرڈ**: انٹرایکٹو `init` کمانڈ CCU کی جانچ کرتا ہے، TLS سرٹیفکیٹس پن کرتا ہے، لاگ ان ٹیسٹ کرتا ہے، اور ایک تیار `.env` فائل لکھتا ہے۔ ایک گفتگو پر مبنی سیٹ اپ موڈ LLM کو چیٹ کے ذریعے عمل کی رہنمائی کرنے دیتا ہے۔ - **تشخیص**: `doctor` کمانڈ کنفیگریشن کی مکمل تصدیق کرتا ہے۔ - **ریٹ لمیٹنگ**: CCU کی حفاظت کے لیے بلٹ ان برسٹ اور مسلسل ریٹ کی حدیں۔ - **ریسورس پولنگ**: MCP ریسورس تبدیلی کے نوٹیفیکیشنز کے لیے اختیاری پولنگ۔ **انسٹالیشن اور استعمال:** - **فوری آغاز (stdio)**: `CCU_HOST` اور `CCU_PASSWORD` ماحولیاتی متغیرات سیٹ کریں، پھر `npx ccu-mcp --stdio` چلائیں۔ اپنے MCP کلائنٹ (مثلاً Claude Code) کو `.mcp.json` فائل کے ساتھ کنفیگر کریں۔ - **Docker (HTTP)**: امیج پل کریں، ماحولیاتی متغیرات کے ساتھ چلائیں، اور کنٹینر کے ڈیٹا والیوم سے آتھ ٹوکن حاصل کریں۔ کلائنٹ کو سرور URL اور بیئرر ٹوکن کے ساتھ کنفیگر کریں۔ - **کنفیگریشن**: تمام سیٹنگز ماحولیاتی متغیرات کے ذریعے (README میں جدول دیکھیں)۔ ان لائن env، `.env` فائلیں، یا شیل ایکسپورٹس سپورٹ کرتا ہے۔ - **CLI فلیگز**: `init`، `doctor`، `secret`، `--stdio`، `--http`، `--env`، `--version`، `--help`۔ **سیکیورٹی تحفظات:** - سرور ڈیفالٹ طور پر سادہ HTTP استعمال کرتا ہے لیکن نان لوپ بیک انٹرفیس پر ٹوکن بھیجنے پر انتباہ کرتا ہے؛ تسلیم کرنے کے لیے `MCP_ALLOW_PLAINTEXT=true` سیٹ کریں۔ - ریموٹ رسائی کے لیے، TLS استعمال کریں (ریورس پراکسی یا نیٹیو HTTPS) اور 403 غلطیوں سے بچنے کے لیے `MCP_ALLOWED_HOSTS` سیٹ کریں۔ - ٹوکن گردش گریس پیریڈز کے ساتھ سپورٹ کی جاتی ہے تاکہ کلائنٹ میں خلل نہ پڑے۔ - 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 بیسٹ پریکٹسز اور اسکور کارڈ کے بیجز شامل ہیں، جو سیکیورٹی اور معیار پر توجہ کی نشاندہی کرتے ہیں۔