diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index da3015fe..b2e5eac2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -19,6 +19,7 @@ on: paths: - Makefile - .github/workflows/release.yml + - packaging/mcp/** permissions: contents: read @@ -50,6 +51,10 @@ jobs: - name: make dist run: make dist VERSION="$VERSION" + # The MCP bundle and the MCP Registry entry, from the archives above. + - name: make mcpb + run: make mcpb VERSION="$VERSION" + # Read back, not assumed: every archive against its checksum, and the # binary asked what version it is. - name: Verify @@ -63,6 +68,40 @@ jobs: rm -rf "mobium_${VERSION}_linux_amd64" ls -l + # The bundle checked by the tools that will read it: its manifest by + # the MCPB CLI, the registry entry by mcp-publisher against the live + # registry, both pinned, mcp-publisher checked against its checksums — + # and the bundle run, through its launcher, as an MCP server. + - name: Verify the MCP bundle and registry entry + env: + DISABLE_TELEMETRY: '1' + run: | + mkdir -p /tmp/mcpb && cd /tmp/mcpb + unzip -q "$GITHUB_WORKSPACE/dist/mobium-${VERSION}.mcpb" + npx -y @anthropic-ai/mcpb@2.1.2 validate manifest.json + python3 - <<'PY' + import json, subprocess + p = subprocess.Popen(["server/mobium", "mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True) + def req(i, m, params): + p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": m, "params": params}) + "\n") + p.stdin.flush() + while True: + r = json.loads(p.stdout.readline()) + if r.get("id") == i: + return r["result"] + req(1, "initialize", {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "ci", "version": "1"}}) + n = len(req(2, "tools/list", {})["tools"]) + p.stdin.close(); p.wait(timeout=30) + assert n > 0, "the bundle's server listed no tools" + print(f"the bundle's server answered, with {n} tools") + PY + b=https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1 + curl -fsSLO "$b/mcp-publisher_linux_amd64.tar.gz" && curl -fsSLO "$b/registry_1.8.1_checksums.txt" + grep ' mcp-publisher_linux_amd64.tar.gz$' registry_1.8.1_checksums.txt | sha256sum -c + tar -xzf mcp-publisher_linux_amd64.tar.gz mcp-publisher + cd "$GITHUB_WORKSPACE/dist" && /tmp/mcpb/mcp-publisher validate server.json + shasum -a 256 -c SHA256SUMS + - uses: actions/upload-artifact@v4 with: name: dist @@ -88,4 +127,4 @@ jobs: run: | gh release create "$GITHUB_REF_NAME" dist/* \ --repo "$GITHUB_REPOSITORY" --verify-tag --title "mobium ${GITHUB_REF_NAME}" \ - --notes "Prebuilt mobium for macOS, Linux and Windows, amd64 and arm64. Check a download against SHA256SUMS. The macOS binaries are not notarized; see docs/SETUP.md." + --notes "Prebuilt mobium for macOS, Linux and Windows, amd64 and arm64, and mobium-${GITHUB_REF_NAME#v}.mcpb, the MCP bundle for macOS and Linux. Check a download against SHA256SUMS. The macOS binaries are not notarized; see docs/SETUP.md." diff --git a/Makefile b/Makefile index e1798cbc..43e57260 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ BIN := bin/mobium VERSION := $(shell cat VERSION 2>/dev/null || echo dev) -.PHONY: all build dist test fmt fmt-check vet lint clients java crosscompile api api-check flags flags-check quickstart license-check docs-check ci clean +.PHONY: all build dist mcpb test fmt fmt-check vet lint clients java crosscompile api api-check flags flags-check quickstart license-check docs-check ci clean all: build test @@ -96,6 +96,11 @@ dist: @cd $(DIST) && shasum -a 256 mobium_* > SHA256SUMS @echo "wrote $(DIST)/SHA256SUMS" +# mcpb packs the MCP bundle and the MCP Registry entry from what make dist +# built: dist/mobium-$(VERSION).mcpb and dist/server.json. See packaging/mcp. +mcpb: + @python3 packaging/mcp/build.py $(VERSION) $(DIST) + crosscompile: @for t in $(CROSS); do \ os=$${t%/*}; arch=$${t#*/}; \ diff --git a/assets/branding/README.md b/assets/branding/README.md index ba61c312..bd121b46 100644 --- a/assets/branding/README.md +++ b/assets/branding/README.md @@ -5,6 +5,7 @@ | [mobium-mark.svg](mobium-mark.svg) | **The master.** The glyph alone, as vectors | | [mobium-icon.svg](mobium-icon.svg) | App icon: the mark on the dark ground, inside a rounded square | | [mobium-icon-light.svg](mobium-icon-light.svg) | The same icon on white | +| [mobium-icon-512.png](mobium-icon-512.png) | The app icon as a 512² PNG, transparent outside the rounded square — rendered from mobium-icon.svg by headless Chrome, for the MCP bundle | | [favicon.svg](favicon.svg) | The mark at tab size | | [mobium-logo.png](mobium-logo.png) | The original: glyph over the wordmark, on white, 1254² | | [mobium-logo-variants.png](mobium-logo-variants.png) | The original's three settings — light, dark, app icon | diff --git a/assets/branding/mobium-icon-512.png b/assets/branding/mobium-icon-512.png new file mode 100644 index 00000000..645d29ee Binary files /dev/null and b/assets/branding/mobium-icon-512.png differ diff --git a/docs/RELEASE-CHECKLIST.md b/docs/RELEASE-CHECKLIST.md index e981b848..cc0c1c6c 100644 --- a/docs/RELEASE-CHECKLIST.md +++ b/docs/RELEASE-CHECKLIST.md @@ -235,3 +235,34 @@ supported when those pass, and only then. - [ ] `make crosscompile` passes (CI does this) - [ ] On Windows: `go test ./internal/daemon/ ./internal/paths/` passes, and the CLI auto-starts a daemon that survives its terminal closing + +## The MCP Registry + +The release workflow attaches `mobium-.mcpb` — the MCP bundle for +macOS and Linux — and `server.json`, the registry entry pointing at it, +after checking both ([packaging/mcp](../packaging/mcp/README.md)). Publishing +the entry is a person's step, under the name `dev.mobium/mobium`, which the +registry grants to whoever proves control of `mobium.dev`. + +Once, before the first publish: + +- [ ] An Ed25519 key, made with OpenSSL 3 (macOS's own `openssl` cannot): + `/opt/homebrew/opt/openssl@3/bin/openssl genpkey -algorithm Ed25519 -out mcp-registry.pem`, + kept out of every repository +- [ ] Its TXT record on the **apex** of `mobium.dev` — not under a selector — + as `mcp-publisher` prints it: + `mobium.dev. IN TXT "v=MCPv1; k=ed25519; p="`, beside the + Maven Central record already there + +Each release, after the release workflow has attached the assets: + +- [ ] `mcp-publisher` v1.8.1 or later, checked against the release's + `registry__checksums.txt` +- [ ] `mcp-publisher login dns --domain mobium.dev --private-key ` +- [ ] Download the release's `server.json` and, beside it, + `mcp-publisher publish` +- [ ] The entry is there: + `curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=mobium" | grep -o '"dev.mobium/mobium"[^}]*"version":"[^"]*"'` + shows the new version. Search matches the part of a name after the + slash, so searching for `dev.mobium` finds nothing, measured with the + registry's own `io.modelcontextprotocol/everything` diff --git a/packaging/mcp/README.md b/packaging/mcp/README.md new file mode 100644 index 00000000..eed9c502 --- /dev/null +++ b/packaging/mcp/README.md @@ -0,0 +1,30 @@ +# MCP packaging + +What puts Mobium's MCP server — `mobium mcp` — into the +[MCP Registry](https://registry.modelcontextprotocol.io) and into clients +that install MCP bundles, such as Claude Desktop. + +| File | What it is | +| --- | --- | +| [manifest.json](manifest.json) | The MCPB manifest, a template: the version and the tool list are filled in at build time | +| [launcher.sh](launcher.sh) | The bundle's entry point, `server/mobium`: a bundle names one command per operating system and none per architecture, so this picks the build for the machine and runs it | +| [server.json](server.json) | The registry entry, a template: the version and the bundle's SHA-256 are filled in at build time | +| [build.py](build.py) | Builds both from the release archives: `make dist && make mcpb` | + +`make mcpb` writes `dist/mobium-.mcpb` — a zip of the macOS and +Linux builds for both architectures, the launcher, the manifest and the +icon — and `dist/server.json`, and adds the bundle to `SHA256SUMS`. The +manifest's tools are read from the release's own binary, asked `tools/list` +over MCP, so they are exactly what ships. The same inputs build the same +bundle, byte for byte. + +Windows is left out of the bundle while Windows is unsupported; it joins +when [WINDOWS.md](../../docs/WINDOWS.md) says it passes. + +The [release workflow](../../.github/workflows/release.yml) builds both on a +tag, and on any pull request that touches this directory, and checks them +with the tools that will read them: the manifest with the MCPB CLI, the +registry entry with `mcp-publisher validate` against the live registry, and +the bundle by running it, through its launcher, as an MCP server. Publishing +the entry is a person's step: [RELEASE-CHECKLIST.md](../../docs/RELEASE-CHECKLIST.md), +"The MCP Registry". diff --git a/packaging/mcp/build.py b/packaging/mcp/build.py new file mode 100644 index 00000000..16b4d43e --- /dev/null +++ b/packaging/mcp/build.py @@ -0,0 +1,120 @@ +"""Builds the MCP bundle and the registry entry for a release. + + python3 packaging/mcp/build.py [dist] + +Reads the release archives `make dist` wrote, so the bundle carries exactly +the binaries being released, and writes into the same directory: + +- mobium-.mcpb: an MCPB bundle (a zip) holding the macOS and Linux + builds for both architectures, the launcher that picks one, the manifest + and the icon. Windows joins when Windows is supported. +- server.json: the MCP Registry entry, pointing at the bundle's release URL + with its SHA-256, ready for `mcp-publisher publish`. + +The manifest's tool list comes from the release's own binary — the build +for the machine this runs on, asked `tools/list` over MCP — so it names +exactly the tools that ship, described as they describe themselves. +""" + +import hashlib +import json +import pathlib +import platform +import subprocess +import sys +import tarfile +import tempfile +import zipfile + +HERE = pathlib.Path(__file__).resolve().parent +ROOT = HERE.parent.parent +BUILDS = ["darwin_arm64", "darwin_amd64", "linux_amd64", "linux_arm64"] +# One fixed timestamp for every entry, so the same inputs give the same bundle. +STAMP = (2026, 1, 1, 0, 0, 0) + + +def binary(dist, version, build): + archive = dist / f"mobium_{version}_{build}.tar.gz" + with tarfile.open(archive) as t: + return t.extractfile(t.getmember(f"mobium_{version}_{build}/mobium")).read() + + +def host_build(): + system = {"Darwin": "darwin", "Linux": "linux"}.get(platform.system()) + machine = {"x86_64": "amd64", "AMD64": "amd64", "arm64": "arm64", "aarch64": "arm64"}.get(platform.machine()) + if not system or not machine: + sys.exit(f"build.py runs on macOS or Linux, not {platform.system()} {platform.machine()}") + return f"{system}_{machine}" + + +def list_tools(exe): + """The tools the binary serves, from `mobium mcp`'s own tools/list.""" + p = subprocess.Popen([str(exe), "mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, text=True) + def request(i, method, params): + p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": method, "params": params}) + "\n") + p.stdin.flush() + while True: + line = p.stdout.readline() + if not line: + sys.exit(f"{exe} mcp ended before answering {method}") + answer = json.loads(line) + if answer.get("id") == i: + return answer["result"] + request(1, "initialize", {"protocolVersion": "2024-11-05", "capabilities": {}, + "clientInfo": {"name": "mcpb-build", "version": "1"}}) + tools = request(2, "tools/list", {})["tools"] + p.stdin.close() + p.wait(timeout=30) + return tools + + +def first_sentence(text): + end = text.find(". ") + return text if end < 0 else text[: end + 1] + + +def main(): + if len(sys.argv) < 2: + sys.exit("usage: build.py [dist]") + version = sys.argv[1] + dist = pathlib.Path(sys.argv[2] if len(sys.argv) > 2 else ROOT / "dist") + + with tempfile.TemporaryDirectory() as tmp: + exe = pathlib.Path(tmp) / "mobium" + exe.write_bytes(binary(dist, version, host_build())) + exe.chmod(0o755) + served = list_tools(exe) + tools = [{"name": t["name"], "description": first_sentence(t["description"])} for t in served] + + manifest = json.loads((HERE / "manifest.json").read_text()) + manifest["version"] = version + manifest["tools"] = tools + + bundle = dist / f"mobium-{version}.mcpb" + with zipfile.ZipFile(bundle, "w", zipfile.ZIP_DEFLATED) as z: + def add(name, data, mode=0o644): + info = zipfile.ZipInfo(name, STAMP) + info.external_attr = (0o100000 | mode) << 16 + info.compress_type = zipfile.ZIP_DEFLATED + z.writestr(info, data) + + add("manifest.json", json.dumps(manifest, indent=2) + "\n") + add("icon.png", (ROOT / "assets/branding/mobium-icon-512.png").read_bytes()) + add("LICENSE", (ROOT / "LICENSE").read_bytes()) + add("server/mobium", (HERE / "launcher.sh").read_bytes(), 0o755) + for build in BUILDS: + add(f"server/mobium-{build.replace('_', '-')}", binary(dist, version, build), 0o755) + + digest = hashlib.sha256(bundle.read_bytes()).hexdigest() + sums = dist / "SHA256SUMS" + lines = [l for l in (sums.read_text().splitlines() if sums.exists() else []) if not l.endswith(".mcpb")] + sums.write_text("\n".join(lines + [f"{digest} {bundle.name}"]) + "\n") + server = (HERE / "server.json").read_text().replace("@VERSION@", version).replace("@SHA256@", digest) + (dist / "server.json").write_text(server) + print(f" {bundle.name} {bundle.stat().st_size} bytes, {len(tools)} tools, sha256 {digest}") + print(f" server.json") + + +if __name__ == "__main__": + main() diff --git a/packaging/mcp/launcher.sh b/packaging/mcp/launcher.sh new file mode 100755 index 00000000..af6533b1 --- /dev/null +++ b/packaging/mcp/launcher.sh @@ -0,0 +1,14 @@ +#!/bin/sh +# The MCPB bundle's entry point. A bundle names one command per operating +# system and none per architecture, so this picks the build for the machine +# it finds itself on and hands over to it: `mobium mcp`, and whatever the +# client passed. +dir=$(cd "$(dirname "$0")" && pwd) +case "$(uname -s)-$(uname -m)" in + Darwin-arm64) build=darwin-arm64 ;; + Darwin-x86_64) build=darwin-amd64 ;; + Linux-x86_64) build=linux-amd64 ;; + Linux-aarch64 | Linux-arm64) build=linux-arm64 ;; + *) echo "mobium: this bundle has no build for $(uname -s) $(uname -m)" >&2; exit 1 ;; +esac +exec "$dir/mobium-$build" "$@" diff --git a/packaging/mcp/manifest.json b/packaging/mcp/manifest.json new file mode 100644 index 00000000..1800b182 --- /dev/null +++ b/packaging/mcp/manifest.json @@ -0,0 +1,35 @@ +{ + "manifest_version": "0.3", + "name": "mobium", + "display_name": "Mobium", + "version": "@VERSION@", + "description": "Drive native Android and iOS apps on emulators, phones, simulators and iPhones, WebViews included.", + "long_description": "Mobium automates native mobile apps for AI agents: map the screen, tap, type and swipe by locator, wait for states, answer system dialogs, reach into WebViews, take screenshots and recordings, and set network conditions, location and accessibility settings. It drives Android through UiAutomator2 and iOS through WebDriverAgent, directly, with no Appium and no Node. It needs the platform's own tools on the machine: Android's platform-tools for Android, Xcode for iOS.", + "author": { + "name": "Lana Begunova", + "url": "https://github.com/mobiumdev" + }, + "repository": { + "type": "git", + "url": "https://github.com/mobiumdev/mobium" + }, + "homepage": "https://github.com/mobiumdev/mobium", + "documentation": "https://github.com/mobiumdev/mobium/blob/main/docs/guides/mcp.md", + "support": "https://github.com/mobiumdev/mobium/issues", + "license": "MIT", + "icon": "icon.png", + "keywords": ["mobile", "android", "ios", "automation", "testing", "uiautomator2", "webdriveragent", "emulator", "simulator"], + "server": { + "type": "binary", + "entry_point": "server/mobium", + "mcp_config": { + "command": "${__dirname}/server/mobium", + "args": ["mcp"], + "env": {} + } + }, + "tools": [], + "compatibility": { + "platforms": ["darwin", "linux"] + } +} diff --git a/packaging/mcp/server.json b/packaging/mcp/server.json new file mode 100644 index 00000000..f51ba085 --- /dev/null +++ b/packaging/mcp/server.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "dev.mobium/mobium", + "title": "Mobium", + "description": "Drive native Android and iOS apps: emulators, phones, simulators, iPhones, WebViews.", + "version": "@VERSION@", + "websiteUrl": "https://github.com/mobiumdev/mobium", + "repository": { + "url": "https://github.com/mobiumdev/mobium", + "source": "github" + }, + "packages": [ + { + "registryType": "mcpb", + "identifier": "https://github.com/mobiumdev/mobium/releases/download/v@VERSION@/mobium-@VERSION@.mcpb", + "fileSha256": "@SHA256@", + "transport": { + "type": "stdio" + } + } + ] +}