authoravatarclover caruso<git@paperclover.net>2026-10-23 15:02:06-07:00
committeravatarclover caruso<git@paperclover.net>2026-10-24 19:01:23-07:00
logeeb6ec5089743d764d55bf4ba8769701afa235a3
tree6e0a1c5a8d937529e5f0a482f9c59a8c8d73eba2
parent7fc742ba86e4d7175659d4a5c5fade792c175d96
signature Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

Add a standard-library client for scripting VMs through the Computer MCP

Agents in the Knife container can import it or call it from the shell. It logs in once with a pasted redirect, then renews its token under a file lock so concurrent scripts never replay a rotated refresh token. Assisted-by: claude-opus-5.5

2 files changed, 440 insertions(+), 0 deletions(-)

tools/computer-client-test.py created+202
......@@ -0,0 +1,202 @@
1#!/usr/bin/env python3
2"""computer.py against a local dashboard whose host socket is a stub with one VM."""
3import argparse
4import base64
5import http.client
6import json
7import os
8import socket
9import socketserver
10import sqlite3
11import struct
12import subprocess
13import sys
14import tempfile
15import threading
16import time
17import unittest
18from pathlib import Path
19from urllib.parse import urlsplit
20from urllib.request import Request
21
22sys.path.insert(0, str(Path(__file__).parent))
23import computer # noqa: E402
24
25PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl6qWQAAAAASUVORK5CYII="
26HOST = "snowglobe.paperclover.net"
27
28
29class Host(socketserver.StreamRequestHandler):
30 owner = None
31 files = {}
32
33 def handle(self):
34 request = json.loads(self.rfile.readline())
35 try:
36 reply = {"value": self.answer(request["operation"], request.get("payload") or {})}
37 except KeyError as missing:
38 reply = {"error": f"missing {missing}", "status": 404}
39 body = json.dumps(reply).encode()
40 try:
41 self.wfile.write(struct.pack(">I", len(body)) + body)
42 except BrokenPipeError:
43 pass # The dashboard can drop a request before its reply.
44
45 def answer(self, operation, payload):
46 if operation == "vm.computers":
47 return [{"name": "test-vm", "owner": self.owner, "capabilities": ["computer"], "platform": "linux",
48 "os": "Fedora", "arch": "x86_64", "state": "running", "aiOwned": False}]
49 if operation == "vm.owner":
50 return {"owner": self.owner}
51 if operation != "vm.computer":
52 raise KeyError(operation)
53 request, files = payload["request"], self.files
54 if request["action"] == "exec":
55 return {"exit": 0, "stdout": "ran " + request["script"], "png": PNG}
56 if request["action"] == "shot":
57 return {"png": PNG}
58 operation, path = request["operation"], request["path"]
59 if operation == "stat":
60 return {"directory": True} if path.endswith("/") else {"directory": False, "size": len(files[path])}
61 if operation == "write":
62 files[path] = files.get(path, b"")[:request["offset"]] + base64.b64decode(request["data"])
63 elif operation == "commit":
64 files[request["destination"]] = files.pop(path)
65 elif operation == "read":
66 data = files[path][request["offset"]:request["offset"] + request["length"]]
67 return {"data": base64.b64encode(data).decode()}
68 elif operation == "remove":
69 files.pop(path, None)
70 return {}
71
72
73class Client(unittest.TestCase):
74 @classmethod
75 def setUpClass(cls):
76 cls.temporary = tempfile.TemporaryDirectory(prefix="computer-client-")
77 data = Path(cls.temporary.name).resolve()
78 proof = os.urandom(32).hex()
79 (data / "proof").write_text(proof)
80 with socket.socket() as available:
81 available.bind(("127.0.0.1", 0))
82 port = available.getsockname()[1]
83 host = socketserver.ThreadingUnixStreamServer(str(data / "host.sock"), Host)
84 threading.Thread(target=host.serve_forever, daemon=True).start()
85 environment = {**os.environ, "SNOWGLOBE_DOMAIN": "paperclover.net", "SNOWGLOBE_DATA_DIR": str(data),
86 "SNOWGLOBE_PUBLIC_ORIGIN": "https://" + HOST, "SNOWGLOBE_AUTH_RP_ID": "auth.paperclover.net",
87 "SNOWGLOBE_FILE_ORIGIN": "https://file.paperclover.net", "SNOWGLOBE_AUTH_REQUIRED": "1",
88 "SNOWGLOBE_WEB_DIR": str(Path("dashboard/dist").resolve()), "PORT": str(port),
89 "SNOWGLOBE_PROXY_TOKEN_FILE": str(data / "proof"), "SNOWGLOBE_HOST_SOCKET": str(data / "host.sock")}
90 account = json.loads(subprocess.run([BINARY, "--preview-account"], env=environment, check=True,
91 capture_output=True, text=True).stdout)
92 with sqlite3.connect(data / "accounts.sqlite") as db:
93 Host.owner = db.execute("SELECT id FROM users WHERE username='preview'").fetchone()[0]
94 cls.log = data / "server.log"
95 cls.server = subprocess.Popen([BINARY], env=environment, stdout=cls.log.open("wb"), stderr=subprocess.STDOUT)
96 deadline = time.monotonic() + 30
97 while True:
98 try:
99 socket.create_connection(("127.0.0.1", port), timeout=0.1).close()
100 break
101 except OSError:
102 assert cls.server.poll() is None and time.monotonic() < deadline, cls.log.read_text()[-2000:]
103 time.sleep(0.05)
104 cls.headers = {"Host": HOST, "Snowglobe-Proxy-Token": proof, "X-Snowglobe-Client-IP": "127.0.0.1"}
105 cls.port = port
106 real = computer.urlopen
107
108 def local(request, timeout=None):
109 request = Request(request) if isinstance(request, str) else request
110 url = urlsplit(request.full_url)
111 assert url.netloc == HOST, request.full_url
112 request.full_url = f"http://127.0.0.1:{port}{url.path}" + (f"?{url.query}" if url.query else "")
113 for key, value in cls.headers.items():
114 request.add_header(key, value)
115 return real(request, timeout=timeout)
116
117 computer.urlopen = local
118 computer.ORIGIN, computer.RESOURCE = f"https://{HOST}/", f"https://{HOST}/mcp/computer"
119 computer.STATE = data / "client/state.json"
120 cls.cookies = {}
121 csrf = cls.request("/auth/status")["csrf"]
122 cls.request("/auth/password", "POST", {"csrf": csrf, "username": account["username"],
123 "password": account["password"], "next": "/"})
124
125 @classmethod
126 def tearDownClass(cls):
127 cls.server.terminate()
128 cls.server.wait(timeout=10)
129 cls.temporary.cleanup()
130
131 @classmethod
132 def request(cls, path, method="GET", body=None):
133 headers = {**cls.headers, "Cookie": "; ".join(f"{k}={v}" for k, v in cls.cookies.items())}
134 if body is not None:
135 headers.update({"Origin": "https://" + HOST, "Content-Type": "application/json"})
136 connection = http.client.HTTPConnection("127.0.0.1", cls.port, timeout=30)
137 connection.request(method, path, json.dumps(body) if body is not None else None, headers)
138 response = connection.getresponse()
139 content = response.read()
140 for cookie in response.headers.get_all("set-cookie") or []:
141 key, value = cookie.split(";", 1)[0].split("=", 1)
142 cls.cookies[key] = value
143 assert response.status in (200, 302), (path, response.status, content[:300])
144 return response.headers["location"] if response.status == 302 else json.loads(content)
145
146 def connect(self):
147 link = urlsplit(computer.login())
148 pending = self.request(f"{link.path}?{link.query}").removeprefix("/connect/")
149 self.assertEqual(self.request(f"/api/mcp/consent/{pending}")["scopes"], computer.SCOPES.split())
150 return self.request(f"/api/mcp/consent/{pending}", "POST", {"resources": ["test-vm"]})["redirect"]
151
152 def test_end_to_end(self):
153 with self.assertRaisesRegex(computer.ComputerError, "login"):
154 computer.Computer().call("computer_list")
155 redirected = self.connect()
156 with self.assertRaisesRegex(computer.ComputerError, "different login"):
157 computer.login(redirected.replace("state=", "state=x"))
158 redirected = self.connect()
159 self.assertIsNone(computer.login(redirected))
160 self.assertEqual(computer.STATE.stat().st_mode & 0o777, 0o600)
161
162 vm = computer.Computer()
163 self.assertIn("computer_exec", {tool["name"] for tool in vm.tools()})
164 self.assertEqual([c["id"] for c in vm.call("computer_list")["computers"]], ["test-vm"])
165 ran = vm.call("computer_exec", vm="test-vm", script="uname")
166 self.assertEqual((ran["stdout"], ran["png"]), ("ran uname", base64.b64decode(PNG)))
167 with self.assertRaisesRegex(computer.ComputerError, "granted"):
168 vm.call("computer_shot", vm="other-vm")
169
170 source = Path(self.temporary.name) / "payload.bin"
171 source.write_bytes(os.urandom(200_000))
172 self.assertEqual(vm.upload("test-vm", source, "/tmp/payload.bin")["bytes"], 200_000)
173 vm.download("test-vm", "/tmp/payload.bin", source.with_suffix(".back"))
174 self.assertEqual(source.with_suffix(".back").read_bytes(), source.read_bytes())
175
176 self.assertIn("png", vm.call("computer_shot", vm="test-vm"))
177
178 state = json.loads(computer.STATE.read_text())
179 computer.STATE.write_text(json.dumps({**state, "access_token": "x" * 43}))
180 self.assertTrue(computer.Computer().call("computer_list")["computers"])
181
182 # Concurrent renewals must not replay a refresh token, which would revoke the connection.
183 state = json.loads(computer.STATE.read_text())
184 computer.STATE.write_text(json.dumps({**state, "expires_at": 0}))
185 results = []
186 threads = [threading.Thread(target=lambda: results.append(computer.Computer().call("computer_list")))
187 for _ in range(6)]
188 for thread in threads:
189 thread.start()
190 for thread in threads:
191 thread.join()
192 self.assertEqual(len(results), 6)
193 self.assertNotEqual(json.loads(computer.STATE.read_text())["refresh_token"], state["refresh_token"])
194 self.assertTrue(computer.Computer().call("computer_list")["computers"])
195
196
197if __name__ == "__main__":
198 parser = argparse.ArgumentParser()
199 parser.add_argument("--binary", type=Path, default=Path("dashboard/target/debug/home-dashboard"))
200 args, rest = parser.parse_known_args()
201 BINARY = str(args.binary.resolve())
202 unittest.main(argv=[sys.argv[0], *rest])
tools/computer.py created+238
......@@ -0,0 +1,238 @@
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()