इस प्रोजेक्ट के बारे में

ccu-mcp एक Model Context Protocol (MCP) सर्वर है जो AI असिस्टेंट (जैसे Claude, Cursor, या कोई भी MCP क्लाइंट) को HomeMatic स्मार्ट होम सिस्टम से जोड़ता है। यह सीधे CCU के बिल्ट-इन JSON-RPC API (via `/api/homematic.cgi`) से जुड़ता है, जिससे ऐडऑन, XML-API, या क्लाउड सेवाओं की आवश्यकता समाप्त हो जाती है। यह किसी भी HomeMatic CCU के साथ काम करता है, जिसमें debmatic, CCU3, और OpenCCU (पूर्व में RaspberryMatic) शामिल हैं। सर्वर डिवाइस डिस्कवरी, टाइप रिज़ॉल्यूशन, सत्र प्रबंधन, और मान रूपांतरण को संभालता है, और ऐसे टूल उजागर करता है जो उपयोगकर्ताओं को प्राकृतिक भाषा में प्रश्न पूछने की अनुमति देते हैं जैसे "बाथरूम में तापमान क्या है?", "क्या कोई खिड़की खुली है?", "लिविंग रूम का हीटिंग 21 डिग्री पर सेट करें", या "मुझे कम बैटरी वाले सभी डिवाइस दिखाएं"। यह उन्नत संचालन भी समर्थन करता है जैसे नामकरण परंपराओं का पालन करने के लिए डिवाइस का नाम बदलना, मेल न खाते चैनल नाम ढूंढना, और डिवाइस स्वास्थ्य की जांच करना। **मुख्य विशेषताएं:** - **सीधा CCU कनेक्शन**: कोई ऐडऑन या क्लाउड नहीं; मानक JSON-RPC एंडपॉइंट का उपयोग करता है। - **कई ट्रांसपोर्ट**: सबप्रोसेस (stdio) या स्टैंडअलोन HTTP सर्वर (Docker) के रूप में चलाएं। - **Docker समर्थन**: linux/amd64 और linux/arm64 के लिए प्रकाशित इमेज, सप्लाई-चेन सुरक्षा के लिए अटेस्टेशन के साथ। - **कई CCU प्रोफाइल**: एक सर्वर से कई CCU (जैसे prod और dev) कॉन्फ़िगर और स्विच करें। - **सुरक्षा**: Bearer टोकन प्रमाणीकरण (स्वतः-जनरेटेड या स्पष्ट), 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 और bearer टोकन के साथ कॉन्फ़िगर करें। - **कॉन्फ़िगरेशन**: सभी सेटिंग्स पर्यावरण चर के माध्यम से (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 Best Practices और Scorecard के लिए बैज शामिल हैं, जो सुरक्षा और गुणवत्ता पर ध्यान केंद्रित करने का संकेत देते हैं।