yoke-mcp 0.1.0

package/extension/browser/snapshot.js

@@ -0,0 +1,154 @@
+/**
+ * Collects interactive elements, tags each with a stable reference, and stashes
+ * the mapping on the page so a later click can resolve it.
+ *
+ * Runs in the page. Everything it needs is defined inside it.
+ */
+export function collectSnapshot(maxElements) {
+    const SELECTOR = [
+        'a[href]', 'button', 'input', 'select', 'textarea', 'summary',
+        '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]',
+        '[role="tab"]', '[role="menuitem"]', '[role="option"]', '[contenteditable="true"]',
+        '[onclick]', '[tabindex]:not([tabindex="-1"])',
+    ].join(',');
+    const visible = (element) => {
+        const rect = element.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) {
+            return false;
+        }
+        const style = getComputedStyle(element);
+        return style.visibility !== 'hidden' && style.display !== 'none' && style.opacity !== '0';
+    };
+    const nameOf = (element) => {
+        const aria = element.getAttribute('aria-label');
+        if (aria) {
+            return aria.trim();
+        }
+        const input = element;
+        if (input.labels && input.labels.length > 0) {
+            return (input.labels[0]?.innerText ?? '').trim();
+        }
+        if (input.placeholder) {
+            return input.placeholder.trim();
+        }
+        const title = element.getAttribute('title');
+        if (title) {
+            return title.trim();
+        }
+        const alt = element.getAttribute('alt');
+        if (alt) {
+            return alt.trim();
+        }
+        return (element.innerText ?? element.textContent ?? '').trim().slice(0, 120);
+    };
+    const roleOf = (element) => {
+        const explicit = element.getAttribute('role');
+        if (explicit) {
+            return explicit;
+        }
+        const tag = element.tagName.toLowerCase();
+        if (tag === 'a') {
+            return 'link';
+        }
+        if (tag === 'button' || tag === 'summary') {
+            return 'button';
+        }
+        if (tag === 'select') {
+            return 'combobox';
+        }
+        if (tag === 'textarea') {
+            return 'textbox';
+        }
+        if (tag === 'input') {
+            const type = element.type;
+            if (type === 'checkbox' || type === 'radio' || type === 'submit' || type === 'button') {
+                return type;
+            }
+            // Its own role rather than textbox, so a password field stays visible to a
+            // caller that has to type into it while its value can be withheld.
+            // Collapsing it into textbox is what made the value impossible to redact.
+            if (type === 'password') {
+                return 'password';
+            }
+            return 'textbox';
+        }
+        return 'generic';
+    };
+    const isSecret = (element) => element.tagName.toLowerCase() === 'input' && element.type === 'password';
+    const registry = new Map();
+    const elements = [];
+    let index = 0;
+    for (const element of Array.from(document.querySelectorAll(SELECTOR))) {
+        if (elements.length >= maxElements) {
+            break;
+        }
+        if (!visible(element)) {
+            continue;
+        }
+        index += 1;
+        const ref = `e${index}`;
+        registry.set(ref, element);
+        const rect = element.getBoundingClientRect();
+        const input = element;
+        elements.push({
+            ref,
+            role: roleOf(element),
+            name: nameOf(element),
+            tag: element.tagName.toLowerCase(),
+            ...(input.value && !isSecret(element) ? { value: String(input.value).slice(0, 80) } : {}),
+            ...(input.disabled ? { disabled: true } : {}),
+            // Centre point, kept for the click path and never shown to a caller.
+            x: Math.round(rect.left + rect.width / 2),
+            y: Math.round(rect.top + rect.height / 2),
+        });
+    }
+    // Parked on the window so a later resolve can find the same elements without
+    // re-walking the DOM, which would renumber everything.
+    window.__yokeRefs = registry;
+    return { url: location.href, title: document.title, elements };
+}
+/**
+ * Where a reference is now, resolved in the page, and what is on top of it.
+ *
+ * Re-read at click time rather than trusted from the snapshot, because a page
+ * that scrolled or reflowed since would otherwise be clicked in the wrong place.
+ * The hit test is here rather than in the caller because it has to happen at the
+ * same moment as the measurement: anything later is a different page.
+ */
+export function locateRef(ref) {
+    const registry = window.__yokeRefs;
+    const element = registry?.get(ref);
+    if (!element) {
+        return { x: 0, y: 0, found: false };
+    }
+    element.scrollIntoView({ block: 'center', inline: 'center' });
+    const rect = element.getBoundingClientRect();
+    const x = Math.round(rect.left + rect.width / 2);
+    const y = Math.round(rect.top + rect.height / 2);
+    const top = document.elementFromPoint(x, y);
+    const describe = (node) => {
+        const id = node.id ? `#${node.id}` : '';
+        const first = node.classList.length > 0 ? `.${node.classList[0]}` : '';
+        return `${node.tagName.toLowerCase()}${id}${first}`;
+    };
+    let hit;
+    if (!top) {
+        hit = 'nothing';
+    }
+    else if (top === element) {
+        hit = 'self';
+    }
+    else if (element.contains(top) || top.contains(element)) {
+        hit = 'nested';
+    }
+    else {
+        hit = 'covered';
+    }
+    return {
+        x,
+        y,
+        found: true,
+        hit,
+        ...(hit === 'covered' && top ? { topmost: describe(top) } : {}),
+    };
+}

package/extension/icons/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" fill="none"
+     stroke="#1098ad" stroke-width="16" stroke-linecap="round" stroke-linejoin="round">
+  <!-- The grip bar with a horn turning up at each end, and the column below it.
+       Every centreline is a multiple of 8 and the stroke is 16, so at 16px each
+       line lands on a pixel boundary instead of straddling two. -->
+  <path d="M24 24V64h80V24"/>
+  <path d="M64 64v40"/>
+</svg>

package/extension/manifest.json

@@ -0,0 +1,28 @@
+{
+  "manifest_version": 3,
+  "name": "Yoke",
+  "version": "0.1.0",
+  "description": "Let MCP clients drive your signed in Chrome: tabs, page text, trusted input, screenshots, console, and network.",
+  "icons": {
+    "16": "icons/16.png",
+    "32": "icons/32.png",
+    "48": "icons/48.png",
+    "128": "icons/128.png"
+  },
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyt9Vs20B0gvtrAGrHnM1tCwXLa8mtRp/GLfYqMwwIAg1osvEAzk+aAhBam4wYrVI0p6y97qgcp0diwi6zHx/9z5feuklqRtPbI+JJSdJIIUZfJTs06HPfdKvMFUyLeyTVeIIqOPqkNPNUrRRa7QrZ3iAPE3+zpBUbR/t9EeW5VPFW7pM+PPZ0Jnv7GyyrTWRQ5veA5Y0N0PTJK8uBUu8uVa863inuVyTxUCxslD76whBuR5GqjTkzl9T0CzZ0Oo5aTJm+0ni+LT4g6sQIEKRukAvL1rj+Y5tTD4K5hh/4+d/u2t07uDlE5iymW3xdiYJ+hBuXPSz2nj+OWV19iJcLwIDAQAB",
+  "minimum_chrome_version": "116",
+  "permissions": [
+    "tabs",
+    "tabGroups",
+    "nativeMessaging",
+    "scripting",
+    "debugger"
+  ],
+  "background": {
+    "service_worker": "browser/background.js",
+    "type": "module"
+  },
+  "host_permissions": [
+    "<all_urls>"
+  ]
+}

package/extension/protocol.js

@@ -0,0 +1,8 @@
+// The shapes the three processes agree on.
+//
+// One file so the extension, the host and the server cannot drift: a request the
+// server can send is exactly a request the extension knows how to answer, and
+// the compiler is what enforces that rather than a comment asking nicely.
+/** Bumped when a message shape changes in a way an older peer cannot read. */
+export const PROTOCOL = 1;
+export const isResponse = (value) => typeof value === 'object' && value !== null && 'id' in value && 'ok' in value;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "yoke-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for browser automation in the Chrome you are already signed in to, with no tab-group boundary.",
+  "bin": {
+    "yoke": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "!dist/*.sh",
+    "!dist/*.bat",
+    "extension/",
+    "LICENSE",
+    "README.md",
+    "ROADMAP.md",
+    "MOTIVATION.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.extension.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.extension.json --noEmit",
+    "test": "npm run build && node --test --experimental-strip-types test/*.test.ts",
+    "lint": "tsc --noEmit",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "check:versions": "node scripts/check-versions.mjs",
+    "prepublishOnly": "npm run clean && npm run build && npm run check:versions"
+  },
+  "keywords": [
+    "mcp",
+    "chrome",
+    "browser-automation",
+    "extension",
+    "tab-groups"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hamzahamidi/yoke.git"
+  },
+  "main": "dist/mcp-server.js",
+  "devDependencies": {
+    "@types/chrome": "^0.0.270",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "type": "module",
+  "homepage": "https://github.com/hamzahamidi/yoke#readme",
+  "bugs": {
+    "url": "https://github.com/hamzahamidi/yoke/issues"
+  }
+}