letitpeek-mcp 0.2.0__tar.gz

letitpeek_mcp-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+# Android
+android/.gradle/
+android/build/
+android/app/build/
+android/local.properties
+android/.idea/
+*.iml
+*.apk
+*.keystore
+# Python
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+android/.kotlin/

letitpeek_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: letitpeek-mcp
+Version: 0.2.0
+Summary: MCP stdio bridge and CLI for the LetItPeek Android camera server
+Project-URL: Homepage, https://gitlab.com/n-group4622738/letitpeek
+Project-URL: Repository, https://gitlab.com/n-group4622738/letitpeek
+Author: nickzam
+License: MIT
+Keywords: ai-agent,android,camera,mcp
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Digital Camera
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: zeroconf>=0.130
+Description-Content-Type: text/markdown
+
+# letitpeek-mcp
+
+MCP (stdio) bridge and CLI for the [LetItPeek](..) Android camera server.
+
+```bash
+# MCP server (stdio) — add to Claude Desktop / Cursor / any MCP client
+uvx letitpeek-mcp \
+    --url http://192.168.1.23:8420 --token <token>
+
+# CLI
+export LETITPEEK_URL=http://192.168.1.23:8420 LETITPEEK_TOKEN=<token>
+uvx --from letitpeek-mcp letitpeek capture -o shot.jpg
+```
+
+Both accept `--discover` / `letitpeek discover` to find the phone via mDNS.

letitpeek_mcp-0.2.0/README.md

@@ -0,0 +1,15 @@
+# letitpeek-mcp
+
+MCP (stdio) bridge and CLI for the [LetItPeek](..) Android camera server.
+
+```bash
+# MCP server (stdio) — add to Claude Desktop / Cursor / any MCP client
+uvx letitpeek-mcp \
+    --url http://192.168.1.23:8420 --token <token>
+
+# CLI
+export LETITPEEK_URL=http://192.168.1.23:8420 LETITPEEK_TOKEN=<token>
+uvx --from letitpeek-mcp letitpeek capture -o shot.jpg
+```
+
+Both accept `--discover` / `letitpeek discover` to find the phone via mDNS.

letitpeek_mcp-0.2.0/letitpeek_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""LetItPeek MCP bridge."""
+
+__version__ = "0.1.0"

letitpeek_mcp-0.2.0/letitpeek_mcp/cli.py

@@ -0,0 +1,90 @@
+"""`letitpeek` command-line client for shell-driven agents."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import LetItPeekClient, LetItPeekError
+from .discovery import discover
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="letitpeek", description="Control a LetItPeek phone camera")
+    p.add_argument("--url", help="Phone base URL (or $LETITPEEK_URL)")
+    p.add_argument("--token", help="Bearer token (or $LETITPEEK_TOKEN)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("discover", help="Find phones on the LAN via mDNS")
+    sub.add_parser("status")
+    sub.add_parser("cameras")
+    sub.add_parser("settings")
+
+    c = sub.add_parser("capture", help="Take a photo")
+    c.add_argument("-o", "--output", default="shot.jpg")
+    c.add_argument("--quality", type=int)
+    c.add_argument("--max-width", type=int)
+    c.add_argument("--camera")
+    c.add_argument("--delay-ms", type=int)
+
+    pv = sub.add_parser("preview", help="Save the latest low-res frame")
+    pv.add_argument("-o", "--output", default="preview.jpg")
+
+    w = sub.add_parser("wait", help="Block until the scene changes")
+    w.add_argument("--threshold", type=float)
+    w.add_argument("--timeout-ms", type=int)
+
+    z = sub.add_parser("zoom")
+    z.add_argument("ratio", type=float)
+    f = sub.add_parser("focus")
+    f.add_argument("x", type=float)
+    f.add_argument("y", type=float)
+    f.add_argument("--lock", action="store_true")
+    t = sub.add_parser("torch")
+    t.add_argument("state", choices=["on", "off"])
+    s = sub.add_parser("set", help="PATCH /v1/settings with a JSON object")
+    s.add_argument("json_body")
+
+    a = p.parse_args()
+
+    if a.cmd == "discover":
+        for d in discover():
+            print(f"{d.name}\t{d.url}")
+        return
+
+    cl = LetItPeekClient.from_env(a.url, a.token)
+    try:
+        if a.cmd == "status":
+            print(json.dumps(cl.status(), indent=2))
+        elif a.cmd == "cameras":
+            print(json.dumps(cl.cameras(), indent=2))
+        elif a.cmd == "settings":
+            print(json.dumps(cl.settings(), indent=2))
+        elif a.cmd == "capture":
+            shot = cl.capture(quality=a.quality, max_width=a.max_width, camera=a.camera, delay_ms=a.delay_ms)
+            with open(a.output, "wb") as fh:
+                fh.write(shot.jpeg)
+            print(f"{a.output}: {shot.width}x{shot.height}, {len(shot.jpeg)} bytes, {shot.capture_ms} ms")
+        elif a.cmd == "preview":
+            data = cl.preview()
+            with open(a.output, "wb") as fh:
+                fh.write(data)
+            print(f"{a.output}: {len(data)} bytes")
+        elif a.cmd == "wait":
+            print(json.dumps(cl.wait_for_change(threshold=a.threshold, timeout_ms=a.timeout_ms)))
+        elif a.cmd == "zoom":
+            print(json.dumps(cl.zoom(a.ratio)))
+        elif a.cmd == "focus":
+            mode = "lock" if a.lock else "point"
+            print(json.dumps(cl.patch_settings(focus={"mode": mode, "x": a.x, "y": a.y})))
+        elif a.cmd == "torch":
+            print(json.dumps(cl.torch(a.state == "on")))
+        elif a.cmd == "set":
+            print(json.dumps(cl.patch_settings(**json.loads(a.json_body))))
+    except LetItPeekError as e:
+        sys.exit(f"error: {e}")
+
+
+if __name__ == "__main__":
+    main()

letitpeek_mcp-0.2.0/letitpeek_mcp/client.py

@@ -0,0 +1,120 @@
+"""Thin HTTP client for the LetItPeek REST API (/v1)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+class LetItPeekError(RuntimeError):
+    def __init__(self, code: str, message: str, status: int):
+        super().__init__(f"{code}: {message} (HTTP {status})")
+        self.code = code
+        self.status = status
+
+
+@dataclass
+class Capture:
+    jpeg: bytes
+    width: int
+    height: int
+    timestamp_ms: int
+    capture_ms: int
+
+
+class LetItPeekClient:
+    def __init__(self, url: str, token: str, timeout: float = 30.0):
+        self.url = url.rstrip("/")
+        self.token = token
+        self._http = httpx.Client(
+            base_url=self.url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_env(cls, url: str | None = None, token: str | None = None) -> "LetItPeekClient":
+        url = url or os.environ.get("LETITPEEK_URL")
+        token = token or os.environ.get("LETITPEEK_TOKEN")
+        if not url or not token:
+            raise SystemExit(
+                "LetItPeek URL/token missing. Pass --url/--token or set LETITPEEK_URL / LETITPEEK_TOKEN "
+                "(shown in the app's pairing card)."
+            )
+        return cls(url, token)
+
+    def _check(self, r: httpx.Response) -> httpx.Response:
+        if r.is_success:
+            return r
+        try:
+            err = r.json()["error"]
+            raise LetItPeekError(err["code"], err["message"], r.status_code)
+        except (ValueError, KeyError):
+            raise LetItPeekError("http_error", r.text[:200], r.status_code)
+
+    def health(self) -> bool:
+        return self._http.get("/v1/health").is_success
+
+    def status(self) -> dict[str, Any]:
+        return self._check(self._http.get("/v1/status")).json()
+
+    def cameras(self) -> list[dict[str, Any]]:
+        return self._check(self._http.get("/v1/cameras")).json()
+
+    def settings(self) -> dict[str, Any]:
+        return self._check(self._http.get("/v1/settings")).json()
+
+    def patch_settings(self, **fields: Any) -> dict[str, Any]:
+        body = {k: v for k, v in fields.items() if v is not None}
+        return self._check(self._http.patch("/v1/settings", json=body)).json()
+
+    def capture(
+        self,
+        quality: int | None = None,
+        max_width: int | None = None,
+        camera: str | None = None,
+        delay_ms: int | None = None,
+    ) -> Capture:
+        params: dict[str, Any] = {}
+        if quality is not None:
+            params["quality"] = quality
+        if max_width is not None:
+            params["max_width"] = max_width
+        if camera is not None:
+            params["camera"] = camera
+        if delay_ms is not None:
+            params["delay_ms"] = delay_ms
+        r = self._check(self._http.get("/v1/capture", params=params))
+        h = r.headers
+        return Capture(
+            jpeg=r.content,
+            width=int(h.get("X-Capture-Width", 0)),
+            height=int(h.get("X-Capture-Height", 0)),
+            timestamp_ms=int(h.get("X-Capture-Timestamp", 0)),
+            capture_ms=int(h.get("X-Capture-Ms", 0)),
+        )
+
+    def wait_for_change(self, threshold: float | None = None, timeout_ms: int | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if threshold is not None:
+            params["threshold"] = threshold
+        if timeout_ms is not None:
+            params["timeout_ms"] = timeout_ms
+        read_timeout = ((timeout_ms or 30_000) / 1000) + 15
+        r = self._http.get("/v1/wait_for_change", params=params, timeout=httpx.Timeout(10, read=read_timeout))
+        return self._check(r).json()
+
+    def preview(self) -> bytes:
+        return self._check(self._http.get("/v1/preview.jpg")).content
+
+    def focus(self, x: float, y: float) -> dict[str, Any]:
+        return self._check(self._http.post("/v1/focus", json={"x": x, "y": y})).json()
+
+    def zoom(self, ratio: float) -> dict[str, Any]:
+        return self._check(self._http.post("/v1/zoom", json={"ratio": ratio})).json()
+
+    def torch(self, on: bool) -> dict[str, Any]:
+        return self._check(self._http.post("/v1/torch", json={"on": on})).json()

letitpeek_mcp-0.2.0/letitpeek_mcp/discovery.py

@@ -0,0 +1,55 @@
+"""mDNS discovery of LetItPeek phones on the LAN (_letitpeek._tcp)."""
+
+from __future__ import annotations
+
+import socket
+import time
+from dataclasses import dataclass
+
+from zeroconf import ServiceBrowser, ServiceListener, Zeroconf
+
+SERVICE_TYPE = "_letitpeek._tcp.local."
+
+
+@dataclass
+class Found:
+    name: str
+    host: str
+    port: int
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+
+class _Listener(ServiceListener):
+    def __init__(self) -> None:
+        self.found: list[Found] = []
+
+    def add_service(self, zc: Zeroconf, type_: str, name: str) -> None:
+        info = zc.get_service_info(type_, name, timeout=2000)
+        if not info:
+            return
+        addrs = info.parsed_addresses(version=socket.AF_INET) if hasattr(info, "parsed_addresses") else []
+        if not addrs:
+            return
+        self.found.append(Found(name=name.removesuffix("." + SERVICE_TYPE), host=addrs[0], port=info.port or 0))
+
+    def update_service(self, zc: Zeroconf, type_: str, name: str) -> None:  # pragma: no cover
+        pass
+
+    def remove_service(self, zc: Zeroconf, type_: str, name: str) -> None:  # pragma: no cover
+        pass
+
+
+def discover(timeout: float = 3.0) -> list[Found]:
+    zc = Zeroconf()
+    listener = _Listener()
+    try:
+        ServiceBrowser(zc, SERVICE_TYPE, listener)
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            time.sleep(0.1)
+    finally:
+        zc.close()
+    return listener.found

letitpeek_mcp-0.2.0/letitpeek_mcp/server.py

@@ -0,0 +1,169 @@
+"""MCP stdio server exposing a LetItPeek phone camera as tools."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from mcp.server.mcpserver import Image, MCPServer
+
+from .client import LetItPeekClient
+from .discovery import discover
+
+MCP_DEFAULT_MAX_WIDTH = 1600
+MCP_DEFAULT_QUALITY = 80
+
+_client: LetItPeekClient | None = None
+
+
+def client() -> LetItPeekClient:
+    assert _client is not None, "client not initialised"
+    return _client
+
+
+mcp = MCPServer(
+    "letitpeek",
+    instructions=(
+        "A phone camera pointed at the physical world (a monitor, a dev board, an instrument). "
+        "Use capture_image to look. If text is blurry, call focus_at on the region of interest and "
+        "increase max_width. Use set_zoom to get closer. get_preview is fast but low quality."
+    ),
+)
+
+
+def _meta(prefix: str, extra: dict[str, Any]) -> str:
+    return prefix + " " + json.dumps(extra, separators=(",", ":"))
+
+
+@mcp.tool()
+def camera_status() -> str:
+    """Phone/camera status: device, battery, thermal state, IP, current settings, available cameras."""
+    return json.dumps(client().status(), indent=2)
+
+
+@mcp.tool()
+def list_cameras() -> str:
+    """List camera ids with facing, zoom range, torch availability and exposure range."""
+    return json.dumps(client().cameras(), indent=2)
+
+
+@mcp.tool(structured_output=False)
+def capture_image(
+    max_width: int = MCP_DEFAULT_MAX_WIDTH,
+    quality: int = MCP_DEFAULT_QUALITY,
+    camera: str | None = None,
+    delay_ms: int | None = None,
+) -> list[Any]:
+    """Take a high-quality photo with the phone camera and return it.
+
+    Use max_width=2560 or more when reading small text on a screen. `camera` is "back", "front"
+    or a camera id from list_cameras. `delay_ms` waits before capturing (e.g. after changing settings).
+    """
+    shot = client().capture(quality=quality, max_width=max_width, camera=camera, delay_ms=delay_ms)
+    return [
+        Image(data=shot.jpeg, format="jpeg"),
+        _meta("captured", {"w": shot.width, "h": shot.height, "ts": shot.timestamp_ms, "capture_ms": shot.capture_ms}),
+    ]
+
+
+@mcp.tool(structured_output=False)
+def get_preview() -> list[Any]:
+    """Return the latest low-resolution live frame instantly (no capture latency). Good for checking framing."""
+    return [Image(data=client().preview(), format="jpeg"), "preview frame (low resolution)"]
+
+
+@mcp.tool(structured_output=False)
+def wait_for_change(
+    threshold: float = 0.04,
+    timeout_ms: int = 30000,
+    capture: bool = True,
+    max_width: int = MCP_DEFAULT_MAX_WIDTH,
+) -> list[Any]:
+    """Block until the scene visibly changes (screen updates, LED turns on...) or the timeout elapses.
+
+    threshold is the mean grayscale difference (0..1) that counts as a change. Returns the detection
+    result and, when capture=True, a fresh photo.
+    """
+    r = client().wait_for_change(threshold=threshold, timeout_ms=timeout_ms)
+    out: list[Any] = [_meta("change", r)]
+    if capture:
+        shot = client().capture(quality=MCP_DEFAULT_QUALITY, max_width=max_width)
+        out.append(Image(data=shot.jpeg, format="jpeg"))
+    return out
+
+
+@mcp.tool()
+def set_zoom(ratio: float) -> str:
+    """Set optical/digital zoom ratio (1.0 = no zoom). See list_cameras for the supported range."""
+    return json.dumps(client().zoom(ratio))
+
+
+@mcp.tool()
+def focus_at(x: float, y: float, lock: bool = False) -> str:
+    """Focus and meter on a point given in normalised image coordinates (x, y in 0..1, origin top-left).
+
+    With lock=True the focus/exposure stays fixed on that point until changed.
+    """
+    mode = "lock" if lock else "point"
+    return json.dumps(client().patch_settings(focus={"mode": mode, "x": x, "y": y}))
+
+
+@mcp.tool()
+def set_torch(on: bool) -> str:
+    """Turn the phone's flashlight on or off (useful for dark electronics)."""
+    return json.dumps(client().torch(on))
+
+
+@mcp.tool()
+def set_exposure(index: int, lock: bool | None = None) -> str:
+    """Set exposure compensation index (negative = darker, helps with bright monitors). Optionally lock AE."""
+    return json.dumps(client().patch_settings(exposureIndex=index, aeLock=lock))
+
+
+@mcp.tool()
+def select_camera(camera: str) -> str:
+    """Switch camera: "back", "front", or an id from list_cameras."""
+    return json.dumps(client().patch_settings(camera=camera))
+
+
+@mcp.tool()
+def set_camera_settings(
+    resolution: str | None = None,
+    flicker: str | None = None,
+    rotate: int | None = None,
+    focus_auto: bool | None = None,
+) -> str:
+    """Adjust capture settings.
+
+    resolution: "max" | "1080p" | "720p" | "480p". flicker: "auto" | "50hz" | "60hz" | "off" (anti-banding
+    for screens). rotate: extra rotation 0/90/180/270 if the phone is mounted sideways. focus_auto=True
+    returns to continuous autofocus.
+    """
+    focus = {"mode": "auto"} if focus_auto else None
+    return json.dumps(client().patch_settings(resolution=resolution, flicker=flicker, rotate=rotate, focus=focus))
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="LetItPeek MCP stdio bridge")
+    p.add_argument("--url", help="Phone base URL, e.g. http://192.168.1.23:8420 (or $LETITPEEK_URL)")
+    p.add_argument("--token", help="Bearer token from the app (or $LETITPEEK_TOKEN)")
+    p.add_argument("--discover", action="store_true", help="Find the phone via mDNS instead of --url")
+    args = p.parse_args()
+
+    url = args.url
+    if args.discover and not url:
+        found = discover()
+        if not found:
+            sys.exit("No LetItPeek phone found on the LAN via mDNS")
+        url = found[0].url
+        print(f"discovered {found[0].name} at {url}", file=sys.stderr)
+
+    global _client
+    _client = LetItPeekClient.from_env(url, args.token)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

letitpeek_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "letitpeek-mcp"
+version = "0.2.0"
+description = "MCP stdio bridge and CLI for the LetItPeek Android camera server"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "nickzam" }]
+keywords = ["mcp", "camera", "android", "ai-agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Graphics :: Capture :: Digital Camera",
+]
+dependencies = [
+    "mcp>=2.0,<3",
+    "httpx>=0.27",
+    "zeroconf>=0.130",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/n-group4622738/letitpeek"
+Repository = "https://gitlab.com/n-group4622738/letitpeek"
+
+[project.scripts]
+letitpeek-mcp = "letitpeek_mcp.server:main"
+letitpeek = "letitpeek_mcp.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["letitpeek_mcp"]