mijiaAPI 4.0.0__tar.gz → 4.1.1__tar.gz

{mijiaapi-4.0.0 → mijiaapi-4.1.1}/.gitignore

@@ -20,4 +20,4 @@ wheels/
 
 # VitePress
 node_modules/
-.vitepress/
+/.vitepress/

{mijiaapi-4.0.0/mijiaAPI.egg-info → mijiaapi-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mijiaAPI
-Version: 4.0.0
+Version: 4.1.1
 Summary: A Python API for Xiaomi Mijia
 Author-email: Do1e <i@do1e.cn>
 License-Expression: GPL-3.0-or-later
@@ -21,7 +21,10 @@ Dynamic: license-file
 
 # mijiaAPI
 
-小米米家设备的 API，可以使用代码直接控制米家设备。
+米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
+
+> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
+> 🎉 **v4.1.0 版本已支持 Agent Skill**，详见 [Agent Skill 使用文档](https://mijia-api.do1e.com/usage/skill)
 
 [![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/)
@@ -29,6 +32,8 @@ Dynamic: license-file
 
 📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
 
+[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
+
 ## 安装
 
 > 要求 Python >= 3.10
@@ -38,7 +43,7 @@ pip install mijiaAPI
 # Or `uv add mijiaAPI` for uv users
 ```
 
-其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com)。
+其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
 
 ## 快速开始
 
@@ -66,6 +71,21 @@ 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)。
 
 ## 致谢

{mijiaapi-4.0.0 → mijiaapi-4.1.1}/README.md

@@ -1,6 +1,9 @@
 # mijiaAPI
 
-小米米家设备的 API，可以使用代码直接控制米家设备。
+米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
+
+> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
+> 🎉 **v4.1.0 版本已支持 Agent Skill**，详见 [Agent Skill 使用文档](https://mijia-api.do1e.com/usage/skill)
 
 [![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/)
@@ -8,6 +11,8 @@
 
 📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
 
+[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
+
 ## 安装
 
 > 要求 Python >= 3.10
@@ -17,7 +22,7 @@ pip install mijiaAPI
 # Or `uv add mijiaAPI` for uv users
 ```
 
-其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com)。
+其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
 
 ## 快速开始
 
@@ -45,6 +50,21 @@ 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)。
 
 ## 致谢

{mijiaapi-4.0.0 → mijiaapi-4.1.1}/mijiaAPI/__main__.py

@@ -193,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:
@@ -245,14 +246,24 @@ def get_homes_list(api: mijiaAPI, verbose: bool = True, device_mapping: Optional
     home_mapping = {home['id']: home for home in homes}
     return home_mapping
 
-def get_devices_list(api: mijiaAPI, verbose: bool = True) -> dict:
+def get_devices_list(api: mijiaAPI, verbose: bool = True, home_mapping: Optional[dict] = None) -> dict:
     devices = api.get_devices_list() + api.get_shared_devices_list()
     if verbose:
+        if home_mapping is None:
+            home_mapping = get_homes_list(api, verbose=False)
+        did_location = {}
+        for home in home_mapping.values():
+            for room in home.get('roomlist', []):
+                for did in room.get('dids', []) or []:
+                    did_location[did] = (home['name'], room['name'])
         print("设备列表:")
         for device in devices:
+            home_name, room_name = did_location.get(device['did'], ("未知", "未知"))
             print(f"  - {device['name']}\n"
                     f"    did: {device['did']}\n"
                     f"    model: {device['model']}\n"
+                    f"    home: {home_name}\n"
+                    f"    room: {room_name}\n"
                     f"    online: {device['isOnline']}")
     device_mapping = {device['did']: device for device in devices}
     return device_mapping
@@ -345,7 +356,13 @@ def main(args):
         run_mcp(args.auth_path)
         return
     if hasattr(args, 'func') and args.func == 'login':
-        api = init_api(args.auth_path)
+        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
@@ -356,7 +373,9 @@ def main(args):
     scenes_mapping = None
 
     if args.list_devices:
-        device_mapping = get_devices_list(api)
+        if home_mapping is None:
+            home_mapping = get_homes_list(api, verbose=False)
+        device_mapping = get_devices_list(api, home_mapping=home_mapping)
     if args.list_homes:
         home_mapping = get_homes_list(api, device_mapping=device_mapping)
     if args.list_scenes:

{mijiaapi-4.0.0 → mijiaapi-4.1.1}/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]

{mijiaapi-4.0.0 → mijiaapi-4.1.1}/mijiaAPI/mcp_server.py

@@ -1,6 +1,7 @@
 import json
 import logging
 import sys
+import threading
 from pathlib import Path
 from typing import Optional
 
@@ -10,19 +11,25 @@ from .apis import mijiaAPI
 from .devices import get_device_info, mijiaDevice
 from .errors import LoginError
 from .logger import logger
+from .version import version
 
 
-mcp = FastMCP("mijia-api")
+mcp = FastMCP("mijia-api", version=version)
 
 _api: Optional[mijiaAPI] = None
 _auth_path: Optional[Path] = None
 
+_login_api: Optional[mijiaAPI] = None
+_login_data: Optional[dict] = None
+_login_thread: Optional[threading.Thread] = None
+_login_status: dict = {"status": "idle"}
+
 
 def _get_api() -> mijiaAPI:
     global _api
     if _api is not None:
         return _api
-    raise RuntimeError("mijiaAPI 未初始化，请先登录后重启 MCP server")
+    raise RuntimeError("mijiaAPI 未初始化，请先调用 login 工具完成登录")
 
 
 def _refresh_if_needed(api: mijiaAPI) -> None:
@@ -31,8 +38,7 @@ def _refresh_if_needed(api: mijiaAPI) -> None:
             api._refresh_token()
         except LoginError:
             raise RuntimeError(
-                "认证已失效且无法自动刷新，请运行 "
-                f"`mijiaAPI login -p {_auth_path}` 重新登录后重启 MCP server"
+                "认证已失效且无法自动刷新，请调用 login 工具重新登录"
             )
 
 
@@ -40,30 +46,28 @@ def run(auth_path: Path) -> None:
     global _api, _auth_path
     _auth_path = auth_path if not auth_path.is_dir() else auth_path / "auth.json"
 
-    if not _auth_path.exists():
-        print(
-            f"认证文件不存在: {_auth_path}\n"
-            f"请先运行 `mijiaAPI login -p {_auth_path}` 登录后再启动 MCP server",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
     logger.handlers = [h for h in logger.handlers if not isinstance(h, logging.StreamHandler) or h.stream is sys.stderr]
-    try:
-        _api = mijiaAPI(auth_data_path=_auth_path)
-        if not _api.available:
-            _api._refresh_token()
-        if not _api.available:
-            raise LoginError(-1, "认证不可用")
-    except Exception as e:
-        print(
-            f"认证不可用且无法自动刷新: {e}\n"
-            f"请运行 `mijiaAPI login -p {_auth_path}` 重新登录后再启动 MCP server",
-            file=sys.stderr,
+
+    if not _auth_path.exists():
+        _api = None
+        logger.warning(
+            f"认证文件不存在: {_auth_path}，请调用 login 工具完成登录后再使用其他工具"
         )
-        sys.exit(1)
+    else:
+        try:
+            _api = mijiaAPI(auth_data_path=_auth_path)
+            if not _api.available:
+                _api._refresh_token()
+            if not _api.available:
+                raise LoginError(-1, "认证不可用")
+            logger.info(f"MCP server 启动，认证文件: {_auth_path}")
+        except Exception as e:
+            _api = None
+            logger.warning(
+                f"认证不可用且无法自动刷新: {e}\n"
+                f"请调用 login 工具重新登录后再使用其他工具"
+            )
 
-    logger.info(f"MCP server 启动，认证文件: {_auth_path}")
     mcp.run()
 
 
@@ -318,3 +322,84 @@ def run_speaker_command(
     speaker = mijiaDevice(api, did=match["did"])
     speaker.run_action("execute-text-directive", _in=[prompt, 1 if quiet else 0])
     return f"已通过 {match['name']} 执行: {prompt}"
+
+
+def _login_worker(api: mijiaAPI, login_data: dict) -> None:
+    try:
+        api._complete_qr_login(login_data)
+        _login_status.update({"status": "success", "message": "登录成功"})
+    except LoginError as e:
+        _login_status.update({"status": "error", "message": f"登录失败: {e}"})
+    except Exception as e:
+        _login_status.update({"status": "error", "message": f"登录失败: {e}"})
+
+
+@mcp.tool
+def login() -> str:
+    """发起米家二维码登录。
+
+    当 API 调用失败或凭证过期且自动刷新失败时使用。先尝试刷新 token，
+    失败则生成二维码并在后台长轮询等待扫码。返回二维码图片链接，请用
+    米家APP在2分钟内扫码，然后调用 login_status 查询结果。
+    """
+    global _api, _login_api, _login_data, _login_thread, _login_status
+    if _auth_path is None:
+        return "认证路径未初始化，请检查 MCP server 启动配置"
+    if _login_thread is not None and _login_thread.is_alive():
+        return "已有登录正在进行中，请调用 login_status 查询结果"
+
+    if _api is not None:
+        try:
+            if _api.available:
+                return "凭证仍然有效，无需重新登录"
+            _api._refresh_token()
+            if _api.available:
+                return "Token 刷新成功，无需重新登录"
+        except LoginError:
+            pass
+
+    new_api = mijiaAPI(auth_data_path=_auth_path)
+    login_data = new_api._get_qr_login_data()
+    if login_data.get("refreshed"):
+        _api = new_api
+        return "Token 刷新成功，无需重新登录"
+
+    _login_api = new_api
+    _login_data = login_data
+    _login_status = {"status": "pending", "message": "等待扫码"}
+    _login_thread = threading.Thread(target=_login_worker, args=(new_api, login_data), daemon=True)
+    _login_thread.start()
+    return (
+        "二维码已生成，请在2分钟内用米家APP扫码完成登录。\n"
+        f"二维码图片链接: {login_data['qr']}\n"
+        "扫码后请调用 login_status 查询登录结果。"
+    )
+
+
+@mcp.tool
+def login_status() -> str:
+    """查询 login 发起的二维码登录结果。
+
+    返回 pending（等待扫码）/ success（登录成功，已切换为新凭证）/ error（失败）。
+    成功后后续工具调用将使用新登录的凭证。
+    """
+    global _api, _login_api, _login_data, _login_thread, _login_status
+    if _login_thread is None:
+        return "没有正在进行的登录，请先调用 login"
+
+    status = _login_status.get("status", "idle")
+    if status == "success":
+        _api = _login_api
+        _login_thread = None
+        _login_api = None
+        _login_data = None
+        _login_status = {"status": "idle"}
+        return "登录成功，已切换为新凭证，可继续调用其他工具"
+    if status == "error":
+        message = _login_status.get("message", "登录失败")
+        _login_thread = None
+        _login_api = None
+        _login_data = None
+        _login_status = {"status": "idle"}
+        return message
+    return "等待扫码中，请用米家APP扫描 login 返回的二维码后再次查询"

mijiaapi-4.1.1/mijiaAPI/version.py

@@ -0,0 +1 @@
+version = "4.1.1"

{mijiaapi-4.0.0 → mijiaapi-4.1.1/mijiaAPI.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mijiaAPI
-Version: 4.0.0
+Version: 4.1.1
 Summary: A Python API for Xiaomi Mijia
 Author-email: Do1e <i@do1e.cn>
 License-Expression: GPL-3.0-or-later
@@ -21,7 +21,10 @@ Dynamic: license-file
 
 # mijiaAPI
 
-小米米家设备的 API，可以使用代码直接控制米家设备。
+米家 API，可以使用代码、CLI、MCP 直接控制米家设备。
+
+> 🎉 **v4.0.0 版本已支持 MCP**，详见 [MCP 使用文档](https://mijia-api.do1e.com/usage/mcp)
+> 🎉 **v4.1.0 版本已支持 Agent Skill**，详见 [Agent Skill 使用文档](https://mijia-api.do1e.com/usage/skill)
 
 [![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/)
@@ -29,6 +32,8 @@ Dynamic: license-file
 
 📖 **完整文档请见 [mijia-api.do1e.com](https://mijia-api.do1e.com)**
 
+[常见问题](https://mijia-api.do1e.com/faq) | [更新日志](https://mijia-api.do1e.com/changelog)
+
 ## 安装
 
 > 要求 Python >= 3.10
@@ -38,7 +43,7 @@ pip install mijiaAPI
 # Or `uv add mijiaAPI` for uv users
 ```
 
-其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com)。
+其他安装方式（源码安装、AUR）请参考[文档](https://mijia-api.do1e.com/guide/installation)。
 
 ## 快速开始
 
@@ -66,6 +71,21 @@ 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)。
 
 ## 致谢

mijiaapi-4.0.0/mijiaAPI/version.py

@@ -1 +0,0 @@
-version = "4.0.0"