mijiaAPI 3.2.0__tar.gz → 4.1.0__tar.gz

{mijiaapi-3.2.0 → mijiaapi-4.1.0}/.gitignore

@@ -17,3 +17,7 @@ wheels/
 
 # har files
 *.har
+
+# VitePress
+node_modules/
+/.vitepress/

mijiaapi-4.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: mijiaAPI
+Version: 4.1.0
+Summary: A Python API for Xiaomi Mijia
+Author-email: Do1e <i@do1e.cn>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Do1e/mijia-api
+Project-URL: Repository, https://github.com/Do1e/mijia-api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pycryptodome>=3.23.0
+Requires-Dist: qrcode>=8.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: tzlocal>=5.3.1
+Dynamic: license-file
+
+# mijiaAPI
+
+米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
+
+> 🎉 **v4 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
+
+[![GitHub](https://img.shields.io/badge/GitHub-Do1e%2Fmijia--api-blue)](https://github.com/Do1e/mijia-api)
+[![PyPI](https://img.shields.io/badge/PyPI-mijiaAPI-blue)](https://pypi.org/project/mijiaAPI/)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-green.svg)](https://opensource.org/licenses/GPL-3.0)
+
+📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
+
+[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
+
+## 安装
+
+> 要求 Python >= 3.10
+
+```bash
+pip install mijiaAPI
+# Or `uv add mijiaAPI` for uv users
+```
+
+其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
+
+## 快速开始
+
+```python
+from mijiaAPI import mijiaAPI, mijiaDevice
+
+# 初始化并扫码登录（认证文件默认保存在 ~/.config/mijia-api/auth.json）
+api = mijiaAPI()
+api.login()
+
+# 通过设备名称控制设备（推荐）
+device = mijiaDevice(api, dev_name="我的台灯")
+device.on = True              # 打开设备
+device.brightness = 60        # 设置亮度为 60%
+
+# 查看设备支持的所有属性和动作
+print(device)
+```
+
+CLI 用法：
+
+```bash
+mijiaAPI login                          # 扫码登录
+mijiaAPI -l                             # 列出所有设备
+mijiaAPI set --dev_name "台灯" --prop_name "brightness" --value 60
+```
+
+MCP 用法：
+
+执行 `uvx mijiaAPI login -p /path/to/auth.json` 登录后，在 MCP 客户端配置中添加以下内容即可接入米家：
+
+```json
+{
+  "mcpServers": {
+    "mijia-api": {
+      "command": "uvx",
+      "args": ["mijiaAPI", "mcp", "-p", "/path/to/auth.json"]
+    }
+  }
+}
+```
+
+更多用法（API 基础调用、MCP Server、CLI 完整参数、最佳实践等）请查阅[完整文档](https://mijia-api.do1e.com)。
+
+## 致谢
+
+* [janzlan/mijia-api](https://gitee.com/janzlan/mijia-api/tree/master)
+* [米家 APP 网络请求的抓包、加解密与构造的代码笔记](https://imkero.net/posts/mihome-app-api/)
+* [al-one/hass-xiaomi-miot](https://github.com/al-one/hass-xiaomi-miot)
+
+## 开源许可
+
+本项目采用 [GPL-3.0](LICENSE) 开源许可证。
+
+**请注意：GPL-3.0 是具有“强传染性”的开源许可证。**  
+如果您在您的项目中使用、修改或分发本项目的代码（包括作为库依赖），您的整个项目也**必须**以 GPL-3.0 或兼容许可证开源发布。
+
+## 免责声明
+
+* 本项目仅供学习交流使用，不得用于商业用途，如有侵权请联系删除
+* 用户使用本项目所产生的任何后果，需自行承担风险
+* 开发者不对使用本项目产生的任何直接或间接损失负责

mijiaapi-4.1.0/README.md

@@ -0,0 +1,86 @@
+# mijiaAPI
+
+米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
+
+> 🎉 **v4 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
+
+[![GitHub](https://img.shields.io/badge/GitHub-Do1e%2Fmijia--api-blue)](https://github.com/Do1e/mijia-api)
+[![PyPI](https://img.shields.io/badge/PyPI-mijiaAPI-blue)](https://pypi.org/project/mijiaAPI/)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-green.svg)](https://opensource.org/licenses/GPL-3.0)
+
+📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
+
+[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
+
+## 安装
+
+> 要求 Python >= 3.10
+
+```bash
+pip install mijiaAPI
+# Or `uv add mijiaAPI` for uv users
+```
+
+其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
+
+## 快速开始
+
+```python
+from mijiaAPI import mijiaAPI, mijiaDevice
+
+# 初始化并扫码登录（认证文件默认保存在 ~/.config/mijia-api/auth.json）
+api = mijiaAPI()
+api.login()
+
+# 通过设备名称控制设备（推荐）
+device = mijiaDevice(api, dev_name="我的台灯")
+device.on = True              # 打开设备
+device.brightness = 60        # 设置亮度为 60%
+
+# 查看设备支持的所有属性和动作
+print(device)
+```
+
+CLI 用法：
+
+```bash
+mijiaAPI login                          # 扫码登录
+mijiaAPI -l                             # 列出所有设备
+mijiaAPI set --dev_name "台灯" --prop_name "brightness" --value 60
+```
+
+MCP 用法：
+
+执行 `uvx mijiaAPI login -p /path/to/auth.json` 登录后，在 MCP 客户端配置中添加以下内容即可接入米家：
+
+```json
+{
+  "mcpServers": {
+    "mijia-api": {
+      "command": "uvx",
+      "args": ["mijiaAPI", "mcp", "-p", "/path/to/auth.json"]
+    }
+  }
+}
+```
+
+更多用法（API 基础调用、MCP Server、CLI 完整参数、最佳实践等）请查阅[完整文档](https://mijia-api.do1e.com)。
+
+## 致谢
+
+* [janzlan/mijia-api](https://gitee.com/janzlan/mijia-api/tree/master)
+* [米家 APP 网络请求的抓包、加解密与构造的代码笔记](https://imkero.net/posts/mihome-app-api/)
+* [al-one/hass-xiaomi-miot](https://github.com/al-one/hass-xiaomi-miot)
+
+## 开源许可
+
+本项目采用 [GPL-3.0](LICENSE) 开源许可证。
+
+**请注意：GPL-3.0 是具有“强传染性”的开源许可证。**  
+如果您在您的项目中使用、修改或分发本项目的代码（包括作为库依赖），您的整个项目也**必须**以 GPL-3.0 或兼容许可证开源发布。
+
+## 免责声明
+
+* 本项目仅供学习交流使用，不得用于商业用途，如有侵权请联系删除
+* 用户使用本项目所产生的任何后果，需自行承担风险
+* 开发者不对使用本项目产生的任何直接或间接损失负责

{mijiaapi-3.2.0 → mijiaapi-4.1.0}/mijiaAPI/__main__.py

@@ -9,6 +9,7 @@ from typing import Optional
 
 from .apis import mijiaAPI
 from .devices import get_device_info, mijiaDevice
+from .mcp_server import run as run_mcp
 from .version import version
 
 
@@ -104,6 +105,30 @@ def parse_args(args):
         help="小爱音箱静默执行",
     )
 
+    mcp_cmd = subparsers.add_parser(
+        'mcp',
+        help="启动 MCP server（stdio 传输）",
+    )
+    mcp_cmd.set_defaults(func='mcp')
+    mcp_cmd.add_argument(
+        '-p', '--auth_path',
+        type=Path,
+        default=Path.home() / ".config" / "mijia-api" / "auth.json",
+        help="认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json",
+    )
+
+    login_cmd = subparsers.add_parser(
+        'login',
+        help="二维码登录米家账号",
+    )
+    login_cmd.set_defaults(func='login')
+    login_cmd.add_argument(
+        '-p', '--auth_path',
+        type=Path,
+        default=Path.home() / ".config" / "mijia-api" / "auth.json",
+        help="认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json",
+    )
+
     get = subparsers.add_parser(
         'get',
         help="获取设备属性",
@@ -168,26 +193,27 @@ def parse_args(args):
     return parser.parse_args(args)
 
 def init_api(auth_path: Path) -> mijiaAPI:
-    class APIUnavailableError(Exception):
-        pass
-
     if Path(auth_path).is_dir():
         auth_path = auth_path / "auth.json"
-    if auth_path.exists():
-        try:
-            api = mijiaAPI(auth_data_path=auth_path)
-            if not api.available:
-                api._refresh_token()
-            if not api.available:
-                raise APIUnavailableError()
-            return api
-        except (json.JSONDecodeError, APIUnavailableError):
-            auth_path.unlink(missing_ok=True)
-            api = mijiaAPI(auth_data_path=auth_path)
-            api.login()
-    else:
+    if not auth_path.exists():
+        print(f"认证文件不存在: {auth_path}")
+        print("请调用 'mijiaAPI login' 进行扫描登录")
+        sys.exit(1)
+    try:
         api = mijiaAPI(auth_data_path=auth_path)
-        api.login()
+    except json.JSONDecodeError:
+        print(f"认证文件已损坏: {auth_path}")
+        print("请调用 'mijiaAPI login' 进行扫描登录")
+        sys.exit(1)
+    if not api.available:
+        try:
+            api._refresh_token()
+        except Exception:
+            pass
+        if not api.available:
+            print(f"认证已失效且刷新失败: {auth_path}")
+            print("请调用 'mijiaAPI login' 进行扫描登录")
+            sys.exit(1)
     return api
 
 def get_homes_list(api: mijiaAPI, verbose: bool = True, device_mapping: Optional[dict] = None) -> dict:
@@ -316,6 +342,21 @@ def main(args):
             hasattr(args, 'func') and args.func is not None):
         return
 
+    if hasattr(args, 'func') and args.func == 'mcp':
+        run_mcp(args.auth_path)
+        return
+    if hasattr(args, 'func') and args.func == 'login':
+        auth_path = args.auth_path
+        file_path = Path(auth_path) / "auth.json" if Path(auth_path).is_dir() else Path(auth_path)
+        try:
+            api = mijiaAPI(auth_data_path=auth_path)
+        except json.JSONDecodeError:
+            file_path.unlink(missing_ok=True)
+            api = mijiaAPI(auth_data_path=auth_path)
+        if not api.available:
+            api.login()
+        return
+
     api = init_api(args.auth_path)
     device_mapping = None
     home_mapping = None

{mijiaapi-3.2.0 → mijiaapi-4.1.0}/mijiaAPI/apis.py

@@ -226,15 +226,30 @@ class mijiaAPI():
         异常:
             LoginError: 当登录超时或服务器返回错误时抛出
         """
-        # Step 1: 从 serviceLogin 获取登录链接参数
+        login_data = self._get_qr_login_data()
+        if login_data.get("refreshed"):
+            return self.auth_data
+        self._print_qr(login_data["loginUrl"])
+        print(f"也可以访问链接查看二维码图片: {login_data['qr']}")
+        return self._complete_qr_login(login_data)
+
+    def _get_qr_login_data(self) -> dict:
+        """获取二维码登录数据（含 loginUrl/qr/lp），不阻塞等待扫码。
+
+        先尝试刷新 token，若成功返回 {"refreshed": True}；否则请求二维码并返回
+        登录数据，供 _complete_qr_login 长轮询完成登录。
+
+        返回值:
+            dict: 刷新成功时为 {"refreshed": True}；否则包含 loginUrl（二维码原始
+                  链接）、qr（二维码图片链接）、lp（长轮询地址）等字段。
+        """
         location_data = self._get_location()
         if location_data.get("code", -1) == 0 and location_data.get("message", "") == "刷新Token成功":
             self._save_auth_data()
             self._init_session()
             logger.info("刷新Token成功，无需登录")
-            return self.auth_data
+            return {"refreshed": True}
 
-        # Step 2: 获取并打印二维码
         location_data.update({
             "theme": "",
             "bizDeviceType": "",
@@ -251,10 +266,26 @@ class mijiaAPI():
         }
         login_ret = requests.get(url, headers=headers)
         login_data = self._handle_ret(login_ret)
-        self._print_qr(login_data["loginUrl"])
-        print(f"也可以访问链接查看二维码图片: {login_data['qr']}")
+        return login_data
+
+    def _complete_qr_login(self, login_data: dict) -> dict:
+        """长轮询等待扫码并完成登录，保存认证数据。
 
-        # Step 3: 轮询等待扫码登录
+        参数:
+            login_data: _get_qr_login_data 返回的登录数据（含 lp 等字段）。
+
+        返回值:
+            dict: 包含认证信息的字典。
+
+        异常:
+            LoginError: 当扫码超时或服务器返回错误时抛出。
+        """
+        headers = {
+            "User-Agent": self.user_agent,
+            "Accept-Encoding": "gzip",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Connection": "keep-alive",
+        }
         session = requests.Session()
         try:
             lp_ret = session.get(login_data["lp"], headers=headers, timeout=120)
@@ -262,7 +293,6 @@ class mijiaAPI():
         except requests.exceptions.Timeout:
             raise LoginError(-1, "超时，请重试")
 
-        # Step 4: 处理登录结果
         auth_keys = ["psecurity", "nonce", "ssecurity", "passToken", "userId", "cUserId"]
         for key in auth_keys:
             self.auth_data[key] = lp_data[key]