mobridge-mcp 0.0.1

package/dist/protocol/schemas/tools.schema.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:tools.schema.json",
+  "title": "MCP tool I/O",
+  "description": "Input/output contracts for the 9 core MCP tools. mobile.workflow.run (10th) is added in P8 and intentionally absent here.",
+  "$defs": {
+    "annotation": {
+      "enum": ["READ_ONLY", "REVERSIBLE", "SIDE_EFFECT", "DESTRUCTIVE"],
+      "description": "Per-tool safety annotation surfaced to the host."
+    },
+
+    "device.connect": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "deviceId": { "$ref": "msm:common.schema.json#/$defs/deviceId" },
+          "pairingCode": { "type": "string" },
+          "transport": { "enum": ["ADB_FORWARD", "LAN"], "default": "ADB_FORWARD" },
+          "setup": { "enum": ["ask", "auto", "manual"], "description": "iOS only. How to bring up the XCTest Runner when it isn't running. 'ask' (default): return a SETUP_REQUIRED envelope with estimate + manual steps; 'auto': build + launch it now (~3-5 min first time). Ignored on Android." }
+        }
+      },
+      "output": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["deviceId", "sessionId", "capabilities"],
+            "properties": {
+              "deviceId": { "$ref": "msm:common.schema.json#/$defs/deviceId" },
+              "sessionId": { "type": "string" },
+              "capabilities": { "type": "array", "items": { "type": "string" } },
+              "expiresInMinutes": { "type": "integer" },
+              "platform": { "enum": ["ANDROID", "IOS"], "description": "Session platform. Optional for back-compat." },
+              "mode": { "type": ["string", "null"], "description": "iOS driver mode (PHYSICAL|SIMULATOR); null on Android." },
+              "supportedTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names actually advertised this session (platform ∩ profile). Informational; gating is at registration." },
+              "unsupportedCapabilities": { "type": "array", "items": { "type": "string" }, "description": "Capabilities the connected platform/mode cannot honor, e.g. BATTERYSTATS on iOS." }
+            }
+          },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "app.open": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["appAction"],
+        "properties": {
+          "appAction": { "$ref": "msm:action.schema.json#/$defs/appAction" },
+          "packageName": { "$ref": "msm:common.schema.json#/$defs/packageName" },
+          "bundleId": { "$ref": "msm:common.schema.json#/$defs/bundleId" },
+          "deepLink": { "type": "string" },
+          "verify": { "$ref": "msm:wait.schema.json" }
+        }
+      },
+      "output": {
+        "oneOf": [
+          { "$ref": "msm:action.schema.json#/$defs/actionResult" },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "screen.get": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "compact": { "type": "boolean", "default": true },
+          "tokenBudget": { "type": "integer", "minimum": 0 },
+          "metrics": { "type": "boolean", "default": false, "description": "Attach an opt-in `_metrics` capture-counter block (benchmarks only). Default off keeps the wire byte-identical." }
+        }
+      },
+      "output": {
+        "oneOf": [
+          { "$ref": "msm:screen-snapshot.schema.json" },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "screen.find": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["query"],
+        "properties": {
+          "query": { "$ref": "msm:query.schema.json" },
+          "queryMode": {
+            "enum": ["oracle", "targeted", "auto"],
+            "default": "oracle",
+            "description": "Resolution strategy. `oracle` (default) = full-walk capture then QueryEngine (ground truth). `targeted` = platform seed only, NO silent fallback (fails if the seed cannot prove completeness for the query class). `auto` = targeted iff eligibility + completeness are proven, else full-walk oracle (fail-closed)."
+          },
+          "metrics": { "type": "boolean", "default": false, "description": "Attach an opt-in `_find` block (seed/ancestor/walk/getChild counters + fallbackReason). Default off keeps the wire byte-identical." }
+        }
+      },
+      "output": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["matchCount", "matches"],
+            "properties": {
+              "matchCount": { "type": "integer", "minimum": 0 },
+              "matches": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["ref", "reason", "confidence"],
+                  "properties": {
+                    "ref": { "$ref": "msm:node-ref.schema.json" },
+                    "reason": { "type": "string", "description": "Which locator/criteria matched." },
+                    "confidence": { "$ref": "msm:common.schema.json#/$defs/confidence" }
+                  }
+                }
+              },
+              "generation": { "type": "integer", "description": "Capture generation these refs were built against; pair with screen.node/children and screen.act's generation gate." },
+              "mode": { "enum": ["oracle", "targeted", "auto"], "description": "The strategy actually executed (auto reports the resolved path)." },
+              "fallbackReason": { "type": ["string", "null"], "description": "When a targeted/auto request ran the oracle instead, why (e.g. UNSUPPORTED_QUERY_CLASS, ANCESTOR_INCOMPLETE, SEED_UNPROVEN, OVER_BUDGET)." },
+              "_find": { "type": "object", "additionalProperties": true, "description": "Opt-in instrumentation (metrics:true only)." }
+            }
+          },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "screen.act": {
+      "input": { "$ref": "msm:action.schema.json#/$defs/actionRequest" },
+      "output": {
+        "oneOf": [
+          { "$ref": "msm:action.schema.json#/$defs/actionResult" },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "screen.wait": {
+      "input": { "$ref": "msm:wait.schema.json" },
+      "output": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["satisfied"],
+            "properties": {
+              "satisfied": { "type": "boolean" },
+              "snapshotId": { "$ref": "msm:common.schema.json#/$defs/snapshotId" },
+              "elapsedMs": { "type": "integer" }
+            }
+          },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "screen.diff": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["fromSnapshot"],
+        "properties": {
+          "fromSnapshot": { "$ref": "msm:common.schema.json#/$defs/snapshotId" },
+          "toSnapshot": { "$ref": "msm:common.schema.json#/$defs/snapshotId" }
+        }
+      },
+      "output": {
+        "oneOf": [
+          { "$ref": "msm:diff.schema.json" },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "system.action": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action"],
+        "properties": {
+          "action": { "$ref": "msm:action.schema.json#/$defs/globalAction" },
+          "verify": { "$ref": "msm:wait.schema.json" }
+        }
+      },
+      "output": {
+        "oneOf": [
+          { "$ref": "msm:action.schema.json#/$defs/actionResult" },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    },
+
+    "capability.invoke": {
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["capability", "operation"],
+        "properties": {
+          "capability": { "enum": ["CLIPBOARD", "NOTIFICATION", "APP"] },
+          "operation": { "type": "string" },
+          "args": { "type": "object" }
+        }
+      },
+      "output": {
+        "oneOf": [
+          { "type": "object" },
+          { "$ref": "msm:error.schema.json" }
+        ]
+      }
+    }
+  }
+}

package/dist/protocol/schemas/wait.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:wait.schema.json",
+  "title": "WaitSpec",
+  "description": "Event-driven wait for a UI condition, with a stability window.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["condition"],
+  "properties": {
+    "condition": { "$ref": "#/$defs/condition" },
+    "timeoutMs": { "type": "integer", "minimum": 0, "default": 10000 },
+    "stableForMs": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 400,
+      "description": "Tree must be unchanged for this long before condition is evaluated satisfied."
+    }
+  },
+  "$defs": {
+    "condition": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "description": "Exactly one of the condition forms.",
+      "additionalProperties": false,
+      "properties": {
+        "anyOf": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/condition" }
+        },
+        "allOf": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/condition" }
+        },
+        "not": { "$ref": "#/$defs/condition" },
+        "nodeExists": { "$ref": "msm:query.schema.json" },
+        "nodeAbsent": { "$ref": "msm:query.schema.json" },
+        "nodeValueEquals": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["query", "value"],
+          "properties": {
+            "query": { "$ref": "msm:query.schema.json" },
+            "value": { "type": "string" }
+          }
+        },
+        "packageChanged": { "$ref": "msm:common.schema.json#/$defs/packageName" },
+        "windowChanged": { "type": "boolean" },
+        "screenStable": { "type": "boolean" },
+        "collectionPositionChanged": { "$ref": "msm:query.schema.json" },
+        "clipboardEquals": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/protocol/synonyms.json

@@ -0,0 +1,74 @@
+{
+  "$comment": "Source of truth for TextMatch.SEMANTIC_SYNONYM (schemaVersion 1). Deterministic table, NOT a model: principle 8 forbids a second LLM inside the runtime, so equivalence here is a lookup and nothing else. Each group is a set of labels that name the SAME UI affordance across languages/wordings. Matching is symmetric (any member matches any other) and applied after normalization (lowercase, whitespace collapsed) and diacritic folding, so 'Cài đặt' matches 'cai dat'. Mirrored byte-for-behavior in android-runtime SynonymTable.kt and protocol/validate/query-engine.mjs; SynonymTableParityTest fails the build if they drift.",
+  "version": 1,
+  "locales": ["en", "vi"],
+  "groups": [
+    ["settings", "setting", "cài đặt", "thiết lập", "tuỳ chọn", "tùy chọn"],
+    ["back", "go back", "quay lại", "trở lại", "trở về"],
+    ["next", "continue", "tiếp", "tiếp tục", "tiếp theo"],
+    ["previous", "prev", "trước", "trước đó"],
+    ["done", "finish", "complete", "xong", "hoàn tất", "hoàn thành"],
+    ["ok", "okay", "đồng ý", "được"],
+    ["cancel", "huỷ", "hủy", "huỷ bỏ", "hủy bỏ"],
+    ["close", "dismiss", "đóng"],
+    ["save", "lưu", "lưu lại"],
+    ["delete", "remove", "xoá", "xóa", "gỡ", "loại bỏ"],
+    ["edit", "sửa", "chỉnh sửa"],
+    ["add", "new", "create", "thêm", "tạo", "tạo mới"],
+    ["search", "find", "tìm", "tìm kiếm"],
+    ["send", "gửi"],
+    ["share", "chia sẻ"],
+    ["sign in", "log in", "login", "đăng nhập"],
+    ["sign out", "log out", "logout", "đăng xuất"],
+    ["sign up", "register", "đăng ký", "đăng kí"],
+    ["password", "mật khẩu"],
+    ["email", "e-mail", "thư điện tử"],
+    ["phone", "phone number", "số điện thoại", "điện thoại"],
+    ["username", "user name", "account", "tên đăng nhập", "tài khoản"],
+    ["confirm", "xác nhận"],
+    ["retry", "try again", "thử lại"],
+    ["refresh", "reload", "làm mới", "tải lại"],
+    ["yes", "có"],
+    ["no", "không"],
+    ["allow", "grant", "cho phép"],
+    ["deny", "block", "từ chối", "chặn"],
+    ["network", "internet", "mạng", "mạng và internet", "network & internet"],
+    ["wifi", "wi-fi", "wlan"],
+    ["bluetooth"],
+    ["notifications", "notification", "thông báo"],
+    ["battery", "pin"],
+    ["storage", "bộ nhớ", "lưu trữ"],
+    ["display", "screen", "màn hình", "hiển thị"],
+    ["sound", "volume", "âm thanh", "âm lượng"],
+    ["language", "ngôn ngữ"],
+    ["security", "bảo mật"],
+    ["privacy", "quyền riêng tư", "riêng tư"],
+    ["about", "about phone", "giới thiệu", "thông tin", "thông tin điện thoại"],
+    ["apps", "applications", "ứng dụng"],
+    ["home", "trang chủ", "màn hình chính"],
+    ["menu", "more", "thêm nữa", "tuỳ chọn khác", "tùy chọn khác"],
+    ["profile", "hồ sơ", "trang cá nhân"],
+    ["camera", "máy ảnh"],
+    ["gallery", "photos", "thư viện", "ảnh"],
+    ["download", "tải xuống", "tải về"],
+    ["upload", "tải lên"],
+    ["copy", "sao chép"],
+    ["paste", "dán"],
+    ["select", "choose", "chọn"],
+    ["start", "begin", "bắt đầu"],
+    ["stop", "dừng", "dừng lại"],
+    ["pause", "tạm dừng"],
+    ["play", "phát"],
+    ["update", "cập nhật"],
+    ["install", "cài đặt ứng dụng", "cài"],
+    ["uninstall", "gỡ cài đặt"],
+    ["pay", "payment", "thanh toán"],
+    ["order", "đặt hàng", "đơn hàng"],
+    ["cart", "giỏ hàng"],
+    ["skip", "bỏ qua", "bỏ qua bước này"],
+    ["help", "support", "trợ giúp", "hỗ trợ"],
+    ["error", "lỗi"],
+    ["warning", "cảnh báo"],
+    ["loading", "please wait", "đang tải", "vui lòng đợi", "vui lòng chờ"]
+  ]
+}

package/dist/protocol/validate/package-lock.json

@@ -0,0 +1,71 @@
+{
+  "name": "msm-protocol-validate",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "msm-protocol-validate",
+      "devDependencies": {
+        "ajv": "^8.17.1"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.4",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz",
+      "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    }
+  }
+}

package/dist/protocol/validate/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "msm-protocol-validate",
+  "private": true,
+  "type": "module",
+  "description": "P0 gate: fixture query runner (no deps) + optional JSON Schema lint (ajv).",
+  "scripts": {
+    "test": "node run-fixtures.mjs",
+    "lint:schemas": "node schema-lint.mjs"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1"
+  }
+}

package/dist/protocol/validate/query-engine.mjs

@@ -0,0 +1 @@
+const c=new Set(["BUTTON","INPUT","LINK","LIST_ITEM","CHECKBOX","RADIO","SWITCH","TAB","SLIDER","MENU"]);function a(t){return(t??"").toLowerCase().replace(/\s+/g," ").trim()}import{readFileSync as d}from"node:fs";import{fileURLToPath as I}from"node:url";import{dirname as m,join as N}from"node:path";const h=JSON.parse(d(N(m(I(import.meta.url)),"..","synonyms.json"),"utf8")).groups;function f(t){return(t??"").toLowerCase().replace(/\s+/g," ").trim().normalize("NFD").replace(new RegExp("\\p{Mn}+","gu"),"").replace(/đ/g,"d")}const s=new Map;h.forEach((t,e)=>{for(const n of t){const r=f(n);s.has(r)||s.set(r,new Set),s.get(r).add(e)}});function E(t,e){const n=f(t),r=f(e);if(!n||!r)return!1;if(n===r)return!0;const o=s.get(n),u=s.get(r);if(!o||!u)return!1;for(const i of o)if(u.has(i))return!0;return!1}function l(t,e){if(e==null)return!1;switch(t.match??"NORMALIZED_EXACT"){case"EXACT":return e===t.value;case"NORMALIZED_EXACT":return a(e)===a(t.value);case"CONTAINS":return a(e).includes(a(t.value));case"REGEX":{if(t.value.length>200)return!1;try{return new RegExp(t.value).test(e)}catch{return!1}}case"SEMANTIC_SYNONYM":return E(e,t.value);default:return!1}}function g(t,e,n){let r=t.parentId?n.get(t.parentId):null;for(;r;){let o=!0;if(e.role&&r.role!==e.role&&(o=!1),o&&e.resourceId&&r.resourceId!==e.resourceId&&(o=!1),o&&e.text&&!l(e.text,r.text)&&(o=!1),o)return!0;r=r.parentId?n.get(r.parentId):null}return!1}function O(t,e,n){if(e.role&&t.role!==e.role||e.text&&!l(e.text,t.text)||e.label&&!l(e.label,t.label)||e.resourceId&&t.resourceId!==e.resourceId)return!1;if(e.state){for(const[r,o]of Object.entries(e.state))if(t.state?.[r]!==o)return!1}return!(e.within&&!g(t,e.within,n))}function p(t){const e=t.nodes.some(r=>r.role==="CANVAS"),n=t.nodes.filter(r=>c.has(r.role)&&r.state?.clickable).length;return e&&n===0}function S(t,e){const n=new Map(t.nodes.map(o=>[o.nodeId,o]));let r=t.nodes.filter(o=>O(o,e,n));return e.firstVisible&&(r=r.slice(0,1)),typeof e.nth=="number"&&(r=r[e.nth]?[r[e.nth]]:[]),r}function x(t,e){const n=S(t,e);return n.length===0?{matchCount:0,nodeIds:[],error:p(t)?"VISION_REQUIRED":"NODE_NOT_FOUND"}:{matchCount:n.length,nodeIds:n.map(r=>r.nodeId),ambiguous:n.length>1}}export{x as find,f as fold,S as matchNodes,a as normalize,E as synonymEquivalent};

package/dist/protocol/validate/run-fixtures.mjs

@@ -0,0 +1,6 @@
+import{readdirSync as S,readFileSync as l,statSync as $,existsSync as m}from"node:fs";import{fileURLToPath as x}from"node:url";import{dirname as y,join as a}from"node:path";import{find as N}from"./query-engine.mjs";const b=y(x(import.meta.url)),I=a(b,"..","fixtures"),k=["schemaVersion","deviceId","snapshotId","timestamp","packageName","windowId","orientation","screenStateId","compact","nodes","treeHash"];function w(o,s){const n=new Set(o),e=new Set(s);if(n.size!==e.size)return!1;for(const i of n)if(!e.has(i))return!1;return!0}function E(o){const s=[];for(const e of k)e in o||s.push(`missing field: ${e}`);o.schemaVersion!==1&&s.push(`schemaVersion must be 1, got ${o.schemaVersion}`);const n=new Set;for(const e of o.nodes??[])n.has(e.nodeId)&&s.push(`duplicate nodeId: ${e.nodeId}`),n.add(e.nodeId),e.parentId&&!o.nodes.some(i=>i.nodeId===e.parentId)&&s.push(`node ${e.nodeId} has dangling parentId ${e.parentId}`);return s}let p=0,u=0;const d=[];for(const o of S(I)){const s=a(I,o);if(!$(s).isDirectory())continue;const n=a(s,"snapshot.json"),e=a(s,"expected.json");if(!m(n)||!m(e))continue;const i=JSON.parse(l(n,"utf8")),g=JSON.parse(l(e,"utf8")),h=E(i);p++,h.length?d.push(`[${o}] snapshot invalid: ${h.join("; ")}`):u++;for(const f of g){p++;const c=N(i,f.query),t=f.expect;let r=c.matchCount===t.matchCount;r&&t.nodeIds&&(r=w(c.nodeIds,t.nodeIds)),r&&t.error&&(r=c.error===t.error),r&&typeof t.ambiguous=="boolean"&&(r=(c.ambiguous??!1)===t.ambiguous),r?u++:d.push(`[${o}] ${f.name}
+    expected ${JSON.stringify(t)}
+    got      ${JSON.stringify(c)}`)}}if(console.log(`
+Fixture gate: ${u}/${p} checks passed`),d.length){console.log(`
+FAILURES:`);for(const o of d)console.log("  - "+o);process.exit(1)}console.log(`All fixture checks passed.
+`);

package/dist/protocol/validate/schema-lint.mjs

@@ -0,0 +1,2 @@
+import{readdirSync as r,readFileSync as c,statSync as S,existsSync as j}from"node:fs";import{fileURLToPath as v}from"node:url";import{dirname as y,join as t}from"node:path";const i=y(v(import.meta.url)),l=t(i,"..","schemas"),f=t(i,"..","fixtures");let m;try{({default:m}=await import("ajv/dist/2020.js"))}catch{console.error("ajv not installed. Run: cd protocol/validate && npm install"),process.exit(2)}const h=new m({allErrors:!0,strict:!1});for(const o of r(l)){if(!o.endsWith(".schema.json"))continue;const s=JSON.parse(c(t(l,o),"utf8"));h.addSchema(s,s.$id)}const d=h.getSchema("msm:screen-snapshot.schema.json");let p=0,e=0;for(const o of r(f)){const s=t(f,o);if(!S(s).isDirectory())continue;const n=t(s,"snapshot.json");if(!j(n))continue;const u=JSON.parse(c(n,"utf8"));if(d(u))p++;else{e++,console.log(`[${o}] INVALID`);for(const a of d.errors)console.log(`    ${a.instancePath} ${a.message}`)}}console.log(`
+Schema lint: ${p} valid, ${e} invalid`),process.exit(e?1:0);

package/dist/protocol/validate/validate-file.mjs

@@ -0,0 +1 @@
+import{readdirSync as m,readFileSync as r}from"node:fs";import{fileURLToPath as l}from"node:url";import{dirname as f,join as a,resolve as d}from"node:path";const p=f(l(import.meta.url)),c=a(p,"..","schemas"),e=process.argv[2];e||(console.error("usage: node validate-file.mjs <snapshot.json>"),process.exit(2));const{default:h}=await import("ajv/dist/2020.js"),n=new h({allErrors:!0,strict:!1});for(const o of m(c)){if(!o.endsWith(".schema.json"))continue;const t=JSON.parse(r(a(c,o),"utf8"));n.addSchema(t,t.$id)}const i=n.getSchema("msm:screen-snapshot.schema.json"),s=JSON.parse(r(d(e),"utf8"));i(s)&&(console.log(`VALID: ${e} (${s.nodes.length} nodes, ${s.compact?"compact":"full"})`),process.exit(0)),console.log(`INVALID: ${e}`);for(const o of i.errors)console.log(`  ${o.instancePath} ${o.message}`);process.exit(1);

package/integrity.json

@@ -0,0 +1,4 @@
+{
+  "buildId": "3d89790-20260802091136",
+  "bundleSha256": "3dca6b6e68a7d79ea10d26c07bff1d01a3dd04491905dcc8ced35806bad4fd93"
+}

package/loader.cjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// npx entrypoint for mobridge-mcp. Tiny, NOT obfuscated (a few KB).
+//
+// Why compile-on-first-run instead of shipping a prebuilt .jsc: V8 cachedData is keyed
+// to the EXACT V8 build, not the Node major — a prebuilt .jsc only runs on that one V8,
+// and the user's V8 is unknowable. So we ship an OBFUSCATED CJS bundle; on first run we
+// compile it to .jsc against the user's own Node and cache it; later runs load the cache
+// instantly. If compiling/loading fails (unknown V8, no bytenode, read-only HOME) we fall
+// back to requiring the obfuscated JS directly — robust beats bytecode-only. Either way
+// what sits on disk is obfuscated (not source); bytecode is a runtime hardening layer.
+"use strict";
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const BUILD_ID = "3d89790-20260802091136"; // pack-npx stamps the real build id
+const ROOT = __dirname; // package root (loader.cjs sits here)
+const DIST = path.join(ROOT, "dist");
+const BUNDLE = path.join(DIST, "main.obf.cjs");
+
+// Asset roots the bundled server/installer read via env (import.meta.url is unreliable
+// once bundled/compiled — see src/assets.ts, src/install.ts, src/index.ts).
+process.env.MOBRIDGE_PKG_ROOT = process.env.MOBRIDGE_PKG_ROOT || ROOT;
+process.env.MOBRIDGE_DIST = process.env.MOBRIDGE_DIST || DIST;
+
+const die = (msg) => {
+  process.stderr.write(`[mobridge-mcp] ${msg}\n`);
+  process.exit(1);
+};
+const sha256 = (file) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+function readManifest() {
+  const p = path.join(ROOT, "integrity.json");
+  if (!fs.existsSync(p)) die("integrity.json missing — package broken, reinstall.");
+  let m;
+  try { m = JSON.parse(fs.readFileSync(p, "utf8")); } catch { die("integrity.json unreadable — package broken."); }
+  if (m.buildId !== BUILD_ID) die(`build mismatch: loader=${BUILD_ID} bundle=${m.buildId}. Refusing to run.`);
+  if (!fs.existsSync(BUNDLE)) die("dist/main.obf.cjs missing — package broken.");
+  const got = sha256(BUNDLE);
+  if (m.bundleSha256 && got !== m.bundleSha256) {
+    die(`integrity fail: main.obf.cjs was modified (${got.slice(0, 12)} != ${String(m.bundleSha256).slice(0, 12)}).`);
+  }
+}
+
+// Ensure the package's own node_modules is resolvable from a .jsc that lives outside the
+// package (in ~/.mobridge/bytecode). Externals: @modelcontextprotocol/sdk, ws, ajv, @clack/prompts.
+function injectNodePath() {
+  try {
+    const nm = path.dirname(path.dirname(require.resolve("ws/package.json")));
+    process.env.NODE_PATH = process.env.NODE_PATH ? `${nm}${path.delimiter}${process.env.NODE_PATH}` : nm;
+    require("node:module").Module._initPaths();
+  } catch { /* deps resolve normally when running the in-package fallback */ }
+}
+
+// Cache .jsc by (V8 build + buildId): a V8 patch bump changes the key -> recompile.
+function cachedJscPath() {
+  const key = `${process.versions.v8}-${BUILD_ID}`.replace(/[^\w.-]/g, "_");
+  const dir = path.join(os.homedir(), ".mobridge", "bytecode", key);
+  return { dir, file: path.join(dir, "main.jsc") };
+}
+
+function loadViaBytecode() {
+  let bytenode;
+  try { bytenode = require("bytenode"); } catch { return false; } // no bytenode -> fallback JS
+  const { dir, file } = cachedJscPath();
+  try {
+    if (!fs.existsSync(file)) {
+      fs.mkdirSync(dir, { recursive: true });
+      bytenode.compileFile({ filename: BUNDLE, output: file }); // compiled against the user's own Node
+    }
+    injectNodePath();
+    require(file);
+    return true;
+  } catch (err) {
+    process.stderr.write(`[mobridge-mcp] bytecode unavailable (${err && err.message ? err.message : err}); running obfuscated JS directly.\n`);
+    return false;
+  }
+}
+
+readManifest();
+if (!loadViaBytecode()) {
+  injectNodePath();
+  require(BUNDLE); // fallback: run the obfuscated JS bundle directly
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "mobridge-mcp",
+  "version": "0.0.1",
+  "description": "MoBridge MCP — a stdio MCP server exposing on-device Android/iOS UIs as fast semantic read / observe / find / act / verify tools plus screenshots. Ships an installer that wires it into Claude Code, Claude Desktop, Cursor and Codex.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "android",
+    "ios",
+    "accessibility",
+    "ui-automation",
+    "claude",
+    "cursor",
+    "mobridge"
+  ],
+  "license": "UNLICENSED",
+  "bin": {
+    "mobridge-mcp": "loader.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.18.0",
+    "ajv": "^8.17.1",
+    "@clack/prompts": "^0.10.0",
+    "bytenode": "^1.6.0"
+  },
+  "files": [
+    "loader.cjs",
+    "dist",
+    "resources",
+    "integrity.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/resources/ios/MobileSemantic/Fixture/MobileSemanticFixtureApp.swift

@@ -0,0 +1,50 @@
+import SwiftUI
+
+// Deterministic fixture app under test. Deployment target 14.0 so the same binary runs on the
+// physical iPhone 7 Plus (iOS 14.2) later. Elements carry stable accessibilityIdentifiers so the
+// TS resolver can locate by automationId; two same-labelled "Continue" buttons give a controlled
+// AMBIGUOUS_MATCH case; signing in flips to a "welcome" screen for wait/diff.
+@main
+struct MobileSemanticFixtureApp: App {
+    var body: some Scene {
+        WindowGroup { ContentView() }
+    }
+}
+
+struct ContentView: View {
+    @State private var username = ""
+    @State private var signedIn = false
+    @State private var playing = false
+
+    var body: some View {
+        if signedIn {
+            VStack(spacing: 16) {
+                Text("Welcome")
+                    .accessibilityIdentifier("welcome")
+                // A plain Button whose OWN title flips on tap — a reliable XCUI hit target (unlike a
+                // SwiftUI switch), giving a deterministic NODE_STATE_CHANGED postcondition.
+                Button(playing ? "Pause" : "Play") { playing.toggle() }
+                    .accessibilityIdentifier("playPause")
+                Button("Sign Out") { signedIn = false }
+                    .accessibilityIdentifier("signOut")
+            }
+            .padding()
+        } else {
+            VStack(spacing: 16) {
+                Text("Sign In").font(.title)
+                TextField("Username", text: $username)
+                    .accessibilityIdentifier("username")
+                    .textFieldStyle(.roundedBorder)
+                Button("Sign In") { signedIn = true }
+                    .accessibilityIdentifier("signIn")
+                // Two buttons with the SAME visible label "Continue" -> ambiguity when a NodeRef
+                // relies on ROLE_LABEL alone; distinct identifiers let a stronger locator disambiguate.
+                HStack(spacing: 24) {
+                    Button("Continue") {}.accessibilityIdentifier("continuePrimary")
+                    Button("Continue") {}.accessibilityIdentifier("continueSecondary")
+                }
+            }
+            .padding()
+        }
+    }
+}