প্রকল্প সম্পর্কে

ccu-mcp হলো একটি মডেল কনটেক্সট প্রোটোকল (MCP) সার্ভার যা AI সহায়কদের (যেমন Claude, Cursor, বা যেকোনো MCP ক্লায়েন্ট) HomeMatic স্মার্ট হোম সিস্টেমের সাথে সংযুক্ত করে। এটি CCU-এর অন্তর্নির্মিত JSON-RPC API-এর সাথে সরাসরি সংযোগ স্থাপন করে (`/api/homematic.cgi` এর মাধ্যমে), ফলে অ্যাডন, XML-API বা ক্লাউড পরিষেবার প্রয়োজন হয় না। এটি যেকোনো HomeMatic CCU-এর সাথে কাজ করে, যার মধ্যে debmatic, CCU3 এবং OpenCCU (পূর্বে RaspberryMatic) অন্তর্ভুক্ত। সার্ভারটি ডিভাইস আবিষ্কার, টাইপ রেজোলিউশন, সেশন ম্যানেজমেন্ট এবং মান রূপান্তর পরিচালনা করে, এবং এমন টুল প্রকাশ করে যা ব্যবহারকারীদের প্রাকৃতিক ভাষায় প্রশ্ন করতে দেয়, যেমন "বাথরুমের তাপমাত্রা কত?", "কোনো জানালা খোলা আছে?", "বসার ঘরের হিটিং ২১ ডিগ্রিতে সেট করুন", বা "কম ব্যাটারি সহ সব ডিভাইস দেখান"। এটি নামকরণের নিয়ম অনুসরণ করতে ডিভাইসের নাম পরিবর্তন, মিলহীন চ্যানেল নাম খুঁজে বের করা এবং ডিভাইসের স্বাস্থ্য পরীক্ষা করার মতো উন্নত অপারেশনও সমর্থন করে। **মূল বৈশিষ্ট্য:** - **সরাসরি CCU সংযোগ**: কোনো অ্যাডন বা ক্লাউড নেই; স্ট্যান্ডার্ড JSON-RPC এন্ডপয়েন্ট ব্যবহার করে। - **একাধিক ট্রান্সপোর্ট**: সাবপ্রসেস (stdio) হিসেবে বা স্বতন্ত্র HTTP সার্ভার (Docker) হিসেবে চালান। - **Docker সমর্থন**: linux/amd64 এবং linux/arm64-এর জন্য প্রকাশিত ইমেজ, সাপ্লাই-চেইন নিরাপত্তার জন্য অ্যাটেস্টেশন সহ। - **একাধিক CCU প্রোফাইল**: একটি সার্ভার থেকে একাধিক CCU (যেমন prod এবং dev) কনফিগার ও স্যুইচ করুন। - **নিরাপত্তা**: বিয়ারার টোকেন প্রমাণীকরণ (স্বয়ংক্রিয়-জেনারেট বা স্পষ্ট), 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 বেস্ট প্র্যাকটিস এবং স্কোরকার্ডের জন্য ব্যাজ অন্তর্ভুক্ত রয়েছে, যা নিরাপত্তা এবং মানের উপর ফোকাস নির্দেশ করে।