asher-cli 0.0.4__tar.gz → 0.0.5__tar.gz

{asher_cli-0.0.4 → asher_cli-0.0.5}/CLAUDE.md

@@ -41,6 +41,8 @@ asher/
   login_flow.py     LoginFlow state machine — inline email/password prompt in command bar
   robot_protocol.py RobotProtocol structural Protocol for pylitterbot robot objects
   robot_adapters.py RobotAdapter ABC + LR3/LR4/LR5 subclasses + make_adapter() factory
+  mcp_config.py     Claude Desktop config read/write for the /mcp slash command
+  mcp_bridge.py     asher-mcp-launch console script — keyring-backed pylitterbot MCP launcher
   __main__.py       main() entry point
   commands/
     base.py         Command ABC, SlashCommand, CommandRegistry
@@ -61,6 +63,9 @@ tests/
   test_connection_mixin.py ConnectionMixin structure
   test_monitoring.py      MonitoringMixin async methods
   test_ui.py              UIMixin constants, CSS, helper existence
+  test_mcp_config.py      Claude Desktop config read/write
+  test_mcp_bridge.py      mcp_bridge launcher credential/subprocess handling
+  test_mcp_command.py     /mcp slash command dispatch
 
 .github/workflows/
   ci.yml            ruff + mypy + pytest on every push/PR
@@ -83,13 +88,23 @@ LITTER_ROBOT_PASSWORD=...
 Keyring service name: `asher-cli`, keys `email` and `password`.
 Helper functions in `asher/connection/__init__.py`: `_keyring_load()`, `_keyring_save()`, `_keyring_delete()`.
 
+## MCP bridge (`/mcp`)
+
+pylitterbot ships an optional MCP server (`pip install pylitterbot[mcp]`, run via `python -m pylitterbot.mcp`) that lets an MCP client like Claude Desktop monitor/control the robot directly. Its own docs configure it with plaintext credentials in the client's JSON config — asher-cli avoids that:
+
+- `/mcp on|off|status` (in `asher/commands/__init__.py`, logic in `asher/mcp_config.py`) adds/removes an entry (named by `mcp_config._SERVER_NAME`) in every `claude_desktop_config.json` this OS's Claude Desktop might read (`mcp_config.config_paths()` — on Windows this includes both the standard installer path and any MSIX/Microsoft Store virtualized path). The entry's `command` is `sys.executable -m asher.mcp_bridge` — never the credentials themselves.
+- `/mcp on` also auto-installs pylitterbot's `mcp` extra via `sys.executable -m pip install "pylitterbot[mcp]==<installed version>"` if the `mcp` package isn't importable yet.
+- `asher/mcp_bridge.py` (console script `asher-mcp-launch`) is what Claude Desktop actually spawns. It reads email/password from the OS keyring at process start, sets them as `LITTER_ROBOT_USERNAME`/`LITTER_ROBOT_PASSWORD` (pylitterbot's expected names — note these differ from asher-cli's own `.env` var `LITTER_ROBOT_USER`) in that process's environment only, then execs `python -m pylitterbot.mcp`. No credentials ever touch the on-disk MCP config.
+- `/mcp on` requires keyring credentials. If none are found but `.env` fallback credentials are set, it copies them into the keyring automatically (since the bridge process can't reliably discover a project-relative `.env` — Claude Desktop controls its working directory, not asher-cli).
+- Requires the `mcp` extra: `uv sync --extra mcp` / `pip install asher-cli[mcp]`. Restart Claude Desktop after toggling for the change to take effect.
+
 ## Command convention
 
 **Normal commands** (no prefix) — robot actions only:
 `clean`, `status`, `lock`, `unlock`, `sleep`, `wake`, `night-light on|off|auto`, `night-light-brightness <level>`, `history`, `clear`, `help`
 
 **Slash commands** (`/` prefix) — app management only:
-`/login`, `/logout`, `/exit`, `/robots`, `/robot <index|name>`
+`/login`, `/logout`, `/exit`, `/robots`, `/robot <index|name>`, `/pets`, `/pet <index|name>`, `/cat on|off|color <hex>`, `/refresh <seconds|off>`, `/config`, `/mcp on|off|status`
 
 **Special cases** (accepted both with and without `/`):
 `exit`, `quit`, `q` — exit the app

{asher_cli-0.0.4 → asher_cli-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asher-cli
-Version: 0.0.4
+Version: 0.0.5
 Summary: Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API
 License: MIT License
         
@@ -40,6 +40,8 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: textual>=0.47.0
 Requires-Dist: tzlocal>=5.4
+Provides-Extra: mcp
+Requires-Dist: pylitterbot[mcp]==2025.5.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Asher CLI
@@ -154,12 +156,14 @@ LITTER_ROBOT_PASSWORD=yourpassword
 ## Releasing
 
 ```bash
-# bump version, commit, and tag in one step
+# bump version, commit, and tag in one step, then push with tags
 uv run bump-my-version bump patch    # 0.0.1 → 0.0.2
 uv run bump-my-version bump minor    # 0.0.2 → 0.1.0
 uv run bump-my-version bump major    # 0.1.0 → 1.0.0
 
-# then push the release branch to trigger PyPI publish
+git push && git push --tags
+
+# then push the release branch to trigger PyPI publish with the new semver
 git checkout -b release/0.0.2
 git push origin release/0.0.2
 ```

{asher_cli-0.0.4 → asher_cli-0.0.5}/README.md

@@ -110,12 +110,14 @@ LITTER_ROBOT_PASSWORD=yourpassword
 ## Releasing
 
 ```bash
-# bump version, commit, and tag in one step
+# bump version, commit, and tag in one step, then push with tags
 uv run bump-my-version bump patch    # 0.0.1 → 0.0.2
 uv run bump-my-version bump minor    # 0.0.2 → 0.1.0
 uv run bump-my-version bump major    # 0.1.0 → 1.0.0
 
-# then push the release branch to trigger PyPI publish
+git push && git push --tags
+
+# then push the release branch to trigger PyPI publish with the new semver
 git checkout -b release/0.0.2
 git push origin release/0.0.2
 ```

{asher_cli-0.0.4 → asher_cli-0.0.5}/ROADMAP.md

@@ -15,7 +15,8 @@ Current state, missing functionality, and suggested additions — grounded in wh
 | Status bar second row — drawer %, litter %, cat weight (with pet name), last visit | ✅ |
 | Pet name from Whisker account profile | ✅ |
 | Commands: clean, status, lock, unlock, sleep, wake, night-light on/off/auto, night-light-brightness, history, export [days\|month], help, clear, quit | ✅ |
-| Slash commands: `/login`, `/logout`, `/exit`, `/help`, `/robots`, `/robot <index\|name>`, `/pets`, `/pet <index\|name>`, `/cat on\|off\|color <hex>`, `/refresh [seconds\|off]`, `/config` | ✅ |
+| Slash commands: `/login`, `/logout`, `/exit`, `/help`, `/robots`, `/robot <index\|name>`, `/pets`, `/pet <index\|name>`, `/cat on\|off\|color <hex>`, `/refresh [seconds\|off]`, `/config`, `/mcp on\|off\|status` | ✅ |
+| MCP bridge — keyring-backed `pylitterbot[mcp]` launcher, auto-installs the extra, writes/removes the Claude Desktop config entry (incl. Windows MSIX path) | ✅ |
 | Inline login flow (email → password in command bar, no restart) | ✅ |
 | `LoginScreen` modal (`auth.py`) — available for future use | ✅ |
 | Activity history (`get_activity_history`) | ✅ |
@@ -2065,6 +2066,109 @@ Implemented via `robot_model(r)` in `asher/helpers.py`, called from `_refresh_st
 
 ---
 
+## 25. Headless CLI export — automate history without the TUI or MCP
+
+`export [days|month]` (§2) already writes activity history to CSV, but only
+from *inside* the running interactive TUI — a human has to launch `asher`,
+wait for it to connect, and type the command. That's unusable from cron,
+Windows Task Scheduler, or a systemd timer. The MCP bridge (`/mcp`, shipped)
+solves automation for an AI assistant talking to the robot, but it doesn't
+help someone who just wants `asher --export 7` in a nightly script with no
+Claude Desktop involved at all.
+
+### Command syntax
+
+```
+asher --export 7                        export last 7 days to the default path
+asher --export 7 --output ~/hist.csv    explicit output path
+asher --export month --robot "Asher 2"  export 30 days for a specific robot
+```
+
+No flags → today's behavior unchanged: launches the interactive TUI. Any
+recognized flag → run headlessly and exit; the Textual `App` is never
+constructed, so this works over SSH, in a container, or from Task Scheduler
+with no terminal attached.
+
+### Entry point changes
+
+`asher/__main__.py` parses `sys.argv` with `argparse` *before* deciding
+whether to build `AsherApp`:
+
+```python
+def main() -> None:
+    args = _parse_args()
+    if args.export is not None:
+        sys.exit(asyncio.run(_run_headless_export(args)))
+    AsherApp().run()
+```
+
+### Decouple `_run_export` from Textual
+
+`_run_export(app, days)` in `asher/commands/__init__.py` currently logs via
+`app._log_info` / `_log_err` / `_log_ok` (RichLog writes) and always opens
+the output folder in the OS file explorer — neither makes sense headlessly
+(no widget tree, no desktop session on a server). Split the CSV-writing core
+out into a plain function both paths share:
+
+```python
+async def build_history_csv(
+    robot: RobotProtocol, pets: list, days: int, dest: Path,
+) -> None:
+    """Pure logic: fetch, filter, write. No Textual, no I/O side effects beyond dest."""
+    ...
+
+async def _run_export(app: AsherApp, days: int) -> None:
+    # existing TUI path: resolve dest via app, call build_history_csv,
+    # log via app._log_*, then _open_folder(dest)
+
+async def _run_headless_export(args: argparse.Namespace) -> int:
+    # connect via keyring -> .env (same priority as _connect_worker), no
+    # interactive login possible - print a clear error and exit 1 if missing
+    # resolve robot by --robot or keyring preferred_robot or robots[0]
+    # call build_history_csv, print plain text to stdout/stderr, no folder-open
+```
+
+### Credentials — same priority, no interactive fallback
+
+Headless mode can't prompt for a password. Priority stays keyring → `.env`,
+but if neither has credentials, print an actionable error and exit non-zero
+rather than starting the inline login flow (there's no command bar to type
+into). This mirrors the constraint already documented for the MCP bridge:
+a scheduled task's environment can't be assumed to match the project's
+working directory, so `.env` discovery should not rely on `find_dotenv()`'s
+upward directory search — same caveat as `asher/mcp_bridge.py`.
+
+### Exit codes (for shell scripting)
+
+| Code | Meaning |
+|---|---|
+| `0` | Export succeeded |
+| `1` | No credentials found (keyring or `.env`) |
+| `2` | Connection or API failure |
+| `3` | Failed to write the CSV (permissions, disk full) |
+| `4` | `--robot` selector matched no robot on the account |
+
+### Example automation
+
+```bash
+# crontab -e — nightly export at 03:00
+0 3 * * * /usr/bin/env asher --export 7 --output /home/me/litter-history.csv >> /var/log/asher-export.log 2>&1
+```
+
+```powershell
+# Windows Task Scheduler action
+asher.exe --export 7 --output C:\Users\me\litter-history.csv
+```
+
+### Testing
+
+No Textual `Pilot` needed — `build_history_csv` and `_run_headless_export`
+are plain async functions, testable the same way as `mcp_bridge.main()`
+(§ MCP bridge): mock `Account.connect`, mock `robot.get_activity_history`,
+assert on the written CSV content and the returned exit code.
+
+---
+
 ## Priority suggestion
 
 Ranked by user-visible impact vs. implementation effort:
@@ -2103,6 +2207,7 @@ Ranked by user-visible impact vs. implementation effort:
 6. **`/version` slash command** (§24) — print Python/package versions to log; model badge in status bar is already done
 7. **`wait-time`, `power`, `rename`, `insight` commands** (§3) — each is a two-line wiring job
 8. **Sleep schedule viewer** (§8) — read-only first, config wizard later
+9. **Headless CLI export** (§25) — `asher --export 7` for cron/Task Scheduler automation, no TUI or Claude Desktop needed
 
 ### Release pipeline
 

{asher_cli-0.0.4 → asher_cli-0.0.5}/asher/commands/__init__.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import csv
+import os
 import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
@@ -628,6 +629,102 @@ class RobotCommand(SlashCommand):
             _keyring_save_robot(serial)
 
 
+async def _ensure_mcp_extra(app: AsherApp) -> bool:
+    """Install pylitterbot's mcp extra if it isn't already available. Returns success."""
+    from importlib.metadata import version as pkg_version  # noqa: PLC0415
+
+    from ..mcp_config import mcp_extra_installed  # noqa: PLC0415
+
+    if mcp_extra_installed():
+        return True
+
+    pin = f"pylitterbot[mcp]=={pkg_version('pylitterbot')}"
+    app._log_info(f"Installing {pin}…")
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        pin,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+    )
+    output = (await proc.communicate())[0].decode(errors="replace")
+    if proc.returncode == 0:
+        app._log_ok("Installed pylitterbot[mcp].")
+        return True
+
+    app._log_err("Failed to install pylitterbot[mcp]:")
+    for line in output.splitlines()[-10:]:
+        app._log_err(f"  {line}")
+    app._log_info(f"Try manually: {sys.executable} -m pip install '{pin}'")
+    return False
+
+
+class McpCommand(SlashCommand):
+    name = "mcp"
+    description = "on|off|status  Litter-Robot MCP server for Claude Desktop"
+
+    async def run(self, app: AsherApp, args: list[str]) -> None:
+        from ..mcp_config import mcp_status, set_mcp_enabled  # noqa: PLC0415
+
+        sub = args[0].lower() if args else "status"
+        if sub not in ("on", "off", "status"):
+            app._log_warn("Usage: /mcp on|off|status")
+            return
+
+        if sub == "status":
+            from ..connection import _keyring_load  # noqa: PLC0415
+
+            email, password = _keyring_load()
+            has_keyring_creds = bool(email and password)
+            has_env_creds = bool(
+                os.getenv("LITTER_ROBOT_USER") and os.getenv("LITTER_ROBOT_PASSWORD")
+            )
+            if has_keyring_creds:
+                app._log_info("Credentials: present in keyring")
+            elif has_env_creds:
+                app._log_info("Credentials: present in .env (will be copied to keyring on /mcp on)")
+            else:
+                app._log_info("Credentials: missing - use /login first")
+            for path, enabled in mcp_status():
+                state = "enabled " if enabled else "disabled"
+                found = "found" if path.exists() else "not found"
+                app._log_info(f"  [{state}, {found}]  {path}")
+            return
+
+        if sub == "on":
+            from ..connection import _keyring_load, _keyring_save  # noqa: PLC0415
+
+            email, password = _keyring_load()
+            if not email or not password:
+                env_email = os.getenv("LITTER_ROBOT_USER") or ""
+                env_password = os.getenv("LITTER_ROBOT_PASSWORD") or ""
+                if env_email and env_password and _keyring_save(env_email, env_password):
+                    app._log_info("Copied .env credentials into the OS keyring for MCP use.")
+                    email, password = env_email, env_password
+
+            if not email or not password:
+                app._log_err(
+                    "No credentials in keyring or .env - use /login first, "
+                    "or set LITTER_ROBOT_USER/LITTER_ROBOT_PASSWORD."
+                )
+                return
+            if not await _ensure_mcp_extra(app):
+                return
+            touched = set_mcp_enabled(True)
+        else:
+            touched = set_mcp_enabled(False)
+
+        verb = "enabled" if sub == "on" else "disabled"
+        if touched:
+            for path in touched:
+                app._log_ok(f"MCP server '{verb}' in {path}")
+            app._log_info("Restart Claude Desktop to apply this change.")
+        else:
+            app._log_info(f"MCP server was already {verb}")
+
+
 _ACTION_LABELS: dict[str, tuple[str, str]] = {
     "ready": ("Ready", "#484f58"),
     "litter robot is ready.": ("Ready", "#484f58"),
@@ -778,6 +875,7 @@ _registry.register(PetCommand())
 _registry.register(CatCommand())
 _registry.register(RefreshCommand())
 _registry.register(ConfigCommand())
+_registry.register(McpCommand())
 
 
 # ── mixin ───────────────────────────────────────────────────────────────────

asher_cli-0.0.5/asher/mcp_bridge.py

@@ -0,0 +1,41 @@
+"""Launcher for pylitterbot's MCP server, run by an MCP client (e.g. Claude Desktop).
+
+Reads credentials from the OS keyring — the same store asher-cli itself uses — and
+passes them to pylitterbot's MCP server as environment variables held only in this
+process's memory. The MCP client's on-disk config never contains a plaintext
+username or password; it just points here.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+_SERVICE = "asher-cli"
+
+
+def main() -> None:
+    import keyring
+
+    email = keyring.get_password(_SERVICE, "email") or ""
+    password = keyring.get_password(_SERVICE, "password") or ""
+
+    if not email or not password:
+        print(
+            "asher-mcp-launch: no credentials found in the OS keyring. "
+            "Run asher-cli and sign in with /login at least once, then retry.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    env = os.environ.copy()
+    env["LITTER_ROBOT_USERNAME"] = email
+    env["LITTER_ROBOT_PASSWORD"] = password
+
+    result = subprocess.run([sys.executable, "-m", "pylitterbot.mcp"], env=env, check=False)
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

asher_cli-0.0.5/asher/mcp_config.py

@@ -0,0 +1,107 @@
+"""Manage the Litter-Robot MCP server entry in Claude Desktop's config file(s)."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+_SERVER_NAME = "Asher CLI MCP Bridge"
+
+
+def mcp_extra_installed() -> bool:
+    """Whether pylitterbot's mcp extra (the third-party `mcp` SDK) is importable."""
+    return importlib.util.find_spec("mcp") is not None
+
+
+def config_paths() -> list[Path]:
+    """Return every claude_desktop_config.json path this OS's Claude Desktop might read.
+
+    On Windows, a standard installer and an MSIX/Microsoft Store install use different,
+    unrelated directories (the Store version is redirected by Windows to a virtualized
+    per-package path) - write to both so the entry is picked up regardless of install type.
+
+    On Linux, Anthropic's official apt package (beta as of mid-2026) is expected to use
+    ~/.config/Claude/, matching macOS/Windows naming, but older community-built wrappers
+    used ~/.config/claude-desktop/ - include that one too if it's already present.
+    """
+    if sys.platform == "win32":
+        paths = []
+        appdata = Path(os.environ.get("APPDATA", str(Path.home() / "AppData" / "Roaming")))
+        paths.append(appdata / "Claude" / "claude_desktop_config.json")
+
+        local_appdata = Path(os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local")))
+        packages_dir = local_appdata / "Packages"
+        if packages_dir.is_dir():
+            for entry in sorted(packages_dir.glob("Claude_*")):
+                paths.append(
+                    entry / "LocalCache" / "Roaming" / "Claude" / "claude_desktop_config.json"
+                )
+        return paths
+    if sys.platform == "darwin":
+        return [
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "Claude"
+            / "claude_desktop_config.json"
+        ]
+
+    paths = [Path.home() / ".config" / "Claude" / "claude_desktop_config.json"]
+    alt_dir = Path.home() / ".config" / "claude-desktop"
+    if alt_dir.is_dir():
+        paths.append(alt_dir / "claude_desktop_config.json")
+    return paths
+
+
+def _load(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        data: dict = json.loads(path.read_text(encoding="utf-8"))
+        return data
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def set_mcp_enabled(enabled: bool) -> list[Path]:
+    """Add or remove the MCP server entry in every known config location.
+
+    Returns the list of config paths actually written.
+    """
+    touched: list[Path] = []
+
+    for path in config_paths():
+        data = _load(path)
+        servers = data.setdefault("mcpServers", {})
+
+        if enabled:
+            servers[_SERVER_NAME] = {
+                "command": sys.executable,
+                "args": ["-m", "asher.mcp_bridge"],
+            }
+            _save(path, data)
+            touched.append(path)
+        elif _SERVER_NAME in servers:
+            del servers[_SERVER_NAME]
+            _save(path, data)
+            touched.append(path)
+
+    return touched
+
+
+def mcp_status() -> list[tuple[Path, bool]]:
+    """Return (path, enabled) for every known Claude Desktop config location."""
+    result = []
+    for path in config_paths():
+        data = _load(path)
+        enabled = _SERVER_NAME in data.get("mcpServers", {})
+        result.append((path, enabled))
+    return result

{asher_cli-0.0.4 → asher_cli-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asher-cli"
-version = "0.0.4"
+version = "0.0.5"
 description = "Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -25,8 +25,12 @@ dependencies = [
     "tzlocal>=5.4",
 ]
 
+[project.optional-dependencies]
+mcp = ["pylitterbot[mcp]==2025.5.0"]
+
 [project.scripts]
 asher = "asher.__main__:main"
+asher-mcp-launch = "asher.mcp_bridge:main"
 
 [dependency-groups]
 dev = [
@@ -87,7 +91,7 @@ exclude = ["asher/slash-commands"]
 # ── bump-my-version ───────────────────────────────────────────────────────────
 
 [tool.bumpversion]
-current_version = "0.0.4"
+current_version = "0.0.5"
 commit = true
 tag = true
 tag_name = "v{new_version}"

asher_cli-0.0.5/tests/test_mcp_bridge.py

@@ -0,0 +1,43 @@
+"""Tests for asher.mcp_bridge module."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from asher.mcp_bridge import main
+
+
+class TestMain:
+    def test_exits_nonzero_when_no_credentials(self):
+        with (
+            patch("keyring.get_password", return_value=None),
+            pytest.raises(SystemExit) as exc,
+        ):
+            main()
+        assert exc.value.code == 1
+
+    def test_launches_pylitterbot_mcp_with_env_credentials(self):
+        mock_result = MagicMock(returncode=0)
+        with (
+            patch("keyring.get_password", side_effect=["test@example.com", "secret123"]),
+            patch("asher.mcp_bridge.subprocess.run", return_value=mock_result) as mock_run,
+            pytest.raises(SystemExit) as exc,
+        ):
+            main()
+        assert exc.value.code == 0
+        args, kwargs = mock_run.call_args
+        assert args[0][1:] == ["-m", "pylitterbot.mcp"]
+        assert kwargs["env"]["LITTER_ROBOT_USERNAME"] == "test@example.com"
+        assert kwargs["env"]["LITTER_ROBOT_PASSWORD"] == "secret123"
+
+    def test_propagates_child_exit_code(self):
+        mock_result = MagicMock(returncode=3)
+        with (
+            patch("keyring.get_password", side_effect=["a@b.com", "pw"]),
+            patch("asher.mcp_bridge.subprocess.run", return_value=mock_result),
+            pytest.raises(SystemExit) as exc,
+        ):
+            main()
+        assert exc.value.code == 3