| 1 | #!/usr/bin/env python3 |
| 2 | """Script Snow Globe's VMs through the Computer MCP, using only the standard library. |
| 3 | |
| 4 | Connect once; approve the VMs this script may use in your browser: |
| 5 | |
| 6 | python3 computer.py login # prints a link to open |
| 7 | python3 computer.py login 'http://127.0.0.1:9/callback?code=…' |
| 8 | |
| 9 | The approval page redirects to an address that does not load. Copy that |
| 10 | address from the browser into the second command. The connection renews |
| 11 | itself while used at least once every 30 days; manage or revoke it in the |
| 12 | dashboard's MCP settings. |
| 13 | |
| 14 | python3 computer.py tools # tool names and descriptions |
| 15 | python3 computer.py call computer_list |
| 16 | python3 computer.py call computer_exec '{"vm": "m3-devbox", "script": "sw_vers"}' --png after.png |
| 17 | python3 computer.py upload m3-devbox ./app.zip /tmp/app.zip |
| 18 | python3 computer.py download m3-devbox /tmp/log.txt ./log.txt |
| 19 | |
| 20 | From Python: |
| 21 | |
| 22 | from computer import Computer |
| 23 | vm = Computer() |
| 24 | print(vm.call("computer_list")) |
| 25 | shot = vm.call("computer_shot", vm="m3-devbox")["png"] # PNG bytes |
| 26 | vm.call("computer_input", vm="m3-devbox", screenshot=False, |
| 27 | actions=[{"type": "click", "x": 400, "y": 300}]) |
| 28 | |
| 29 | `call` returns the tool's JSON result. A screenshot that comes with it, as |
| 30 | `computer_exec`, `computer_input` and `computer_ui_action` send by default, |
| 31 | appears as PNG bytes under "png". Failures raise `ComputerError`. |
| 32 | """ |
| 33 | import argparse |
| 34 | import base64 |
| 35 | import fcntl |
| 36 | import hashlib |
| 37 | import json |
| 38 | import os |
| 39 | import secrets |
| 40 | import shutil |
| 41 | import socket |
| 42 | import sys |
| 43 | import time |
| 44 | from pathlib import Path |
| 45 | from urllib.error import HTTPError |
| 46 | from urllib.parse import parse_qs, urlencode, urlsplit |
| 47 | from urllib.request import Request, urlopen |
| 48 | |
| 49 | ORIGIN = "https://snowglobe.paperclover.net/" |
| 50 | RESOURCE = ORIGIN + "mcp/computer" |
| 51 | REDIRECT = "http://127.0.0.1:9/callback" |
| 52 | SCOPES = "computer:read computer:control computer:create offline_access" |
| 53 | STATE = Path.home() / ".config/computer-mcp/state.json" |
| 54 | |
| 55 | |
| 56 | class ComputerError(Exception): |
| 57 | pass |
| 58 | |
| 59 | |
| 60 | def _http(url, data=None, headers=(), method=None): |
| 61 | """Return (status, body) without raising on HTTP error statuses.""" |
| 62 | request = Request(url, data=data, headers=dict(headers), method=method) |
| 63 | try: |
| 64 | with urlopen(request, timeout=900) as response: |
| 65 | return response.status, response.read() |
| 66 | except HTTPError as error: |
| 67 | return error.code, error.read() |
| 68 | |
| 69 | |
| 70 | def _form(path, fields): |
| 71 | status, body = _http(ORIGIN + path, urlencode(fields).encode(), |
| 72 | {"Content-Type": "application/x-www-form-urlencoded"}) |
| 73 | if status != 200: |
| 74 | raise ComputerError(f"{path}: HTTP {status} {body[:200].decode(errors='replace')}") |
| 75 | return json.loads(body) |
| 76 | |
| 77 | |
| 78 | class _State: |
| 79 | """The token file, locked so concurrent scripts never replay a rotated refresh token.""" |
| 80 | |
| 81 | def __enter__(self): |
| 82 | STATE.parent.mkdir(mode=0o700, parents=True, exist_ok=True) |
| 83 | self.lock = open(STATE.with_suffix(".lock"), "a") |
| 84 | fcntl.flock(self.lock, fcntl.LOCK_EX) |
| 85 | self.value = json.loads(STATE.read_text()) if STATE.exists() else {} |
| 86 | return self |
| 87 | |
| 88 | def save(self): |
| 89 | partial = STATE.with_suffix(".partial") |
| 90 | partial.write_text(json.dumps(self.value)) |
| 91 | partial.chmod(0o600) |
| 92 | partial.replace(STATE) |
| 93 | |
| 94 | def keep(self, tokens): |
| 95 | self.value.update(access_token=tokens["access_token"], refresh_token=tokens["refresh_token"], |
| 96 | expires_at=time.time() + tokens["expires_in"] - 60) |
| 97 | self.save() |
| 98 | |
| 99 | def __exit__(self, *_): |
| 100 | self.lock.close() |
| 101 | |
| 102 | |
| 103 | def login(redirected=None): |
| 104 | """Without an address, print the approval link; with one, finish connecting.""" |
| 105 | with _State() as state: |
| 106 | if redirected is None: |
| 107 | if "client_id" not in state.value: |
| 108 | status, body = _http(ORIGIN + "oauth/register", json.dumps({ |
| 109 | "client_name": f"computer.py on {socket.gethostname()}", "redirect_uris": [REDIRECT], |
| 110 | "token_endpoint_auth_method": "none"}).encode(), {"Content-Type": "application/json"}) |
| 111 | if status != 201: |
| 112 | raise ComputerError(f"Registration failed: {body[:200]!r}") |
| 113 | state.value["client_id"] = json.loads(body)["client_id"] |
| 114 | verifier, nonce = secrets.token_urlsafe(48), secrets.token_urlsafe(16) |
| 115 | state.value["pending"] = {"verifier": verifier, "state": nonce} |
| 116 | state.save() |
| 117 | challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode() |
| 118 | return ORIGIN + "oauth/authorize?" + urlencode({ |
| 119 | "response_type": "code", "client_id": state.value["client_id"], "redirect_uri": REDIRECT, |
| 120 | "scope": SCOPES, "state": nonce, "resource": RESOURCE, |
| 121 | "code_challenge": challenge, "code_challenge_method": "S256"}) |
| 122 | pending = state.value.pop("pending", None) |
| 123 | query = {key: values[0] for key, values in parse_qs(urlsplit(redirected).query).items()} |
| 124 | if pending is None or query.get("state") != pending["state"]: |
| 125 | raise ComputerError("That address belongs to a different login. Run `computer.py login` again.") |
| 126 | if "code" not in query: |
| 127 | raise ComputerError(f"The approval was not granted: {query.get('error', 'no code')}.") |
| 128 | state.keep(_form("oauth/token", { |
| 129 | "grant_type": "authorization_code", "code": query["code"], "code_verifier": pending["verifier"], |
| 130 | "redirect_uri": REDIRECT, "client_id": state.value["client_id"], "resource": RESOURCE})) |
| 131 | |
| 132 | |
| 133 | class Computer: |
| 134 | def __init__(self): |
| 135 | self._token = None |
| 136 | |
| 137 | def _access(self, rejected=None): |
| 138 | """Return a current access token, renewing it if expired or just rejected.""" |
| 139 | with _State() as state: |
| 140 | value = state.value |
| 141 | if "refresh_token" not in value: |
| 142 | raise ComputerError("Not connected. Run `computer.py login` first.") |
| 143 | if value["access_token"] == rejected or value["expires_at"] <= time.time(): |
| 144 | try: |
| 145 | state.keep(_form("oauth/token", {"grant_type": "refresh_token", "client_id": value["client_id"], |
| 146 | "refresh_token": value["refresh_token"], "resource": RESOURCE})) |
| 147 | except ComputerError as error: |
| 148 | raise ComputerError(f"The connection ended ({error}). Run `computer.py login` again.") from None |
| 149 | return value["access_token"] |
| 150 | |
| 151 | def _rpc(self, method, params): |
| 152 | message = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode() |
| 153 | self._token = self._token or self._access() |
| 154 | for retry in (True, False): |
| 155 | status, body = _http(RESOURCE, message, {"Authorization": "Bearer " + self._token, |
| 156 | "Content-Type": "application/json", |
| 157 | "Accept": "application/json, text/event-stream"}) |
| 158 | if status != 401 or not retry: |
| 159 | break |
| 160 | self._token = self._access(rejected=self._token) |
| 161 | if status != 200: |
| 162 | raise ComputerError(f"HTTP {status}: {body[:300].decode(errors='replace')}") |
| 163 | reply = json.loads(body) |
| 164 | if "error" in reply: |
| 165 | raise ComputerError(reply["error"]["message"]) |
| 166 | return reply["result"] |
| 167 | |
| 168 | def tools(self): |
| 169 | return self._rpc("tools/list", {})["tools"] |
| 170 | |
| 171 | def call(self, tool, **arguments): |
| 172 | result = self._rpc("tools/call", {"name": tool, "arguments": arguments}) |
| 173 | text = next(block["text"] for block in result["content"] if block["type"] == "text") |
| 174 | if result.get("isError"): |
| 175 | raise ComputerError(text) |
| 176 | value = json.loads(text) |
| 177 | for block in result["content"]: |
| 178 | if block["type"] == "image": |
| 179 | value["png"] = base64.b64decode(block["data"]) |
| 180 | return value |
| 181 | |
| 182 | def upload(self, vm, local, remote, overwrite=False): |
| 183 | size = os.path.getsize(local) |
| 184 | ticket = self.call("computer_upload", vm=vm, path=remote, size=size, overwrite=overwrite) |
| 185 | with open(local, "rb") as file: |
| 186 | status, body = _http(ticket["url"], file, {"Content-Length": str(size)}, "PUT") |
| 187 | if status != 200: |
| 188 | raise ComputerError(f"Upload failed: {body[:300].decode(errors='replace')}") |
| 189 | return json.loads(body) |
| 190 | |
| 191 | def download(self, vm, remote, local): |
| 192 | ticket = self.call("computer_download", vm=vm, path=remote) |
| 193 | try: |
| 194 | with urlopen(ticket["url"], timeout=900) as response, open(local, "wb") as file: |
| 195 | shutil.copyfileobj(response, file) |
| 196 | except HTTPError as error: |
| 197 | raise ComputerError(f"Download failed: {error.read()[:300].decode(errors='replace')}") from None |
| 198 | |
| 199 | |
| 200 | def main(): |
| 201 | parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) |
| 202 | commands = parser.add_subparsers(dest="command", required=True) |
| 203 | commands.add_parser("login").add_argument("redirected", nargs="?") |
| 204 | commands.add_parser("tools") |
| 205 | call = commands.add_parser("call") |
| 206 | call.add_argument("tool") |
| 207 | call.add_argument("arguments", nargs="?", default="{}", help="JSON object") |
| 208 | call.add_argument("--png", help="save a returned screenshot here") |
| 209 | for name, fields in [("upload", ["vm", "local", "remote"]), ("download", ["vm", "remote", "local"])]: |
| 210 | command = commands.add_parser(name) |
| 211 | for field in fields: |
| 212 | command.add_argument(field) |
| 213 | commands.choices["upload"].add_argument("--overwrite", action="store_true") |
| 214 | args = parser.parse_args() |
| 215 | try: |
| 216 | if args.command == "login": |
| 217 | link = login(args.redirected) |
| 218 | print(f"Open this link and approve:\n\n{link}\n\nThen run: computer.py login '<address you land on>'" |
| 219 | if link else "Connected.") |
| 220 | elif args.command == "tools": |
| 221 | for tool in Computer().tools(): |
| 222 | print(f"{tool['name']}: {tool.get('description', '')}") |
| 223 | elif args.command == "call": |
| 224 | value = Computer().call(args.tool, **json.loads(args.arguments)) |
| 225 | png = value.pop("png", None) if isinstance(value, dict) else None |
| 226 | if png and args.png: |
| 227 | Path(args.png).write_bytes(png) |
| 228 | print(json.dumps(value, indent=2)) |
| 229 | elif args.command == "upload": |
| 230 | print(json.dumps(Computer().upload(args.vm, args.local, args.remote, args.overwrite))) |
| 231 | else: |
| 232 | Computer().download(args.vm, args.remote, args.local) |
| 233 | except ComputerError as error: |
| 234 | sys.exit(f"computer.py: {error}") |
| 235 | |
| 236 | |
| 237 | if __name__ == "__main__": |
| 238 | main() |