1#!/usr/bin/env python3
2"""Script Snow Globe's VMs through the Computer MCP, using only the standard library.
3
4Connect 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
9The approval page redirects to an address that does not load. Copy that
10address from the browser into the second command. The connection renews
11itself while used at least once every 30 days; manage or revoke it in the
12dashboard'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
20From 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,
31appears as PNG bytes under "png". Failures raise `ComputerError`.
32"""
33import argparse
34import base64
35import fcntl
36import hashlib
37import json
38import os
39import secrets
40import shutil
41import socket
42import sys
43import time
44from pathlib import Path
45from urllib.error import HTTPError
46from urllib.parse import parse_qs, urlencode, urlsplit
47from urllib.request import Request, urlopen
48
49ORIGIN = "https://snowglobe.paperclover.net/"
50RESOURCE = ORIGIN + "mcp/computer"
51REDIRECT = "http://127.0.0.1:9/callback"
52SCOPES = "computer:read computer:control computer:create offline_access"
53STATE = Path.home() / ".config/computer-mcp/state.json"
54
55
56class ComputerError(Exception):
57 pass
58
59
60def _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
70def _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
78class _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
103def 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
133class 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
200def 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
237if __name__ == "__main__":
238 main()