arc-control-mcp 0.3.0

package/src/jxa.js

@@ -0,0 +1,243 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_TIMEOUT_MS = 30000;
+const MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+
+// Shared helpers injected ahead of every script body. Arc's scripting bridge
+// refuses a bulk `w.tabs()` fetch but happily returns bulk property arrays
+// (`w.tabs.id()`), which is ~10x fewer Apple Events than looping per tab.
+// Exported so tests can parse-check it: node --check cannot see inside a
+// template literal, so a syntax error here would only appear at runtime.
+export const PREAMBLE = `
+const Arc = Application("Arc");
+
+// Arc keeps closed windows in its scripting collection as invisible phantoms
+// whose activeTab is unreachable, so every lookup must filter on visible().
+function liveWindows() {
+  const live = [];
+  for (let i = 0; i < Arc.windows.length; i++) {
+    const w = Arc.windows[i];
+    try {
+      if (w.visible()) live.push(w);
+    } catch (e) { /* phantom */ }
+  }
+  return live;
+}
+
+function mainWindow() {
+  const live = liveWindows();
+  if (live.length === 0) throw new Error("ARC_NO_WINDOW");
+  return live[0];
+}
+
+function requireArc() {
+  if (!Arc.running()) throw new Error("ARC_NOT_RUNNING");
+  if (liveWindows().length === 0) throw new Error("ARC_NO_WINDOW");
+}
+
+function snapshot() {
+  const rows = [];
+  const live = liveWindows();
+  for (let wi = 0; wi < live.length; wi++) {
+    const w = live[wi];
+    const ids = w.tabs.id();
+    const titles = w.tabs.title();
+    const urls = w.tabs.url();
+    const locations = w.tabs.location();
+    const windowId = w.id();
+    const activeId = w.activeTab.id();
+
+    // Which space each tab belongs to, so callers can tell agent tabs from the
+    // user's without opening anything.
+    const spaceOf = {};
+    try {
+      for (let si = 0; si < w.spaces.length; si++) {
+        const sp = w.spaces[si];
+        const spIds = sp.tabs.id();
+        const spTitle = sp.title();
+        for (let k = 0; k < spIds.length; k++) spaceOf[spIds[k]] = spTitle;
+      }
+    } catch (e) { /* spaces unavailable */ }
+
+    for (let ti = 0; ti < ids.length; ti++) {
+      rows.push({
+        id: ids[ti],
+        title: titles[ti],
+        url: urls[ti],
+        location: locations[ti],
+        space: spaceOf[ids[ti]] || null,
+        windowId: windowId,
+        windowIndex: wi + 1,
+        tabIndex: ti + 1,
+        isActive: ids[ti] === activeId
+      });
+    }
+  }
+  return rows;
+}
+
+function locate(tabId) {
+  const live = liveWindows();
+  for (let wi = 0; wi < live.length; wi++) {
+    const w = live[wi];
+    const ids = w.tabs.id();
+    for (let ti = 0; ti < ids.length; ti++) {
+      if (ids[ti] === tabId) return w.tabs[ti];
+    }
+  }
+  return null;
+}
+
+// Prefers a tab this agent opened, then falls back to whatever is active, so
+// the user can point it at their own tabs without looking up an id.
+function target() {
+  requireArc();
+  if (P.tab_id) {
+    const tab = locate(P.tab_id);
+    if (!tab) throw new Error("TAB_NOT_FOUND:" + P.tab_id);
+    return tab;
+  }
+  if (P.default_tab_id) {
+    const tab = locate(P.default_tab_id);
+    if (tab) return tab;
+  }
+  // Falling through to the user's active tab is only safe for a tool that
+  // reads. Doing it for one that acts is how an agent ends up reloading or
+  // navigating the tab someone is working in, so refuse and say what to pass.
+  if (P.allow_active_tab) return mainWindow().activeTab;
+  throw new Error("NO_TARGET_TAB");
+}
+
+function agentSpace() {
+  return P.agent_space ? findSpace(P.agent_space) : null;
+}
+
+// Arc returns the JSON encoding of whatever the page expression evaluated to,
+// so a string arrives wrapped in quotes and an object as JSON text.
+function evalJs(tab, code) {
+  const raw = Arc.execute(tab, { javascript: code });
+  // Arc returns empty when the injected script fails to parse. That is
+  // indistinguishable from a page value of null unless we say so explicitly.
+  if (raw === undefined || raw === null || raw === "") {
+    return {
+      __arc: 1,
+      ok: false,
+      name: "ScriptError",
+      error: "Arc returned no result for the injected script. It most likely failed to parse, or Arc is blocking JavaScript from Apple Events (Arc > Settings > Advanced)."
+    };
+  }
+  try { return JSON.parse(raw); } catch (e) { return raw; }
+}
+
+function describe(tab) {
+  const id = tab.id();
+  const owned = P.owned_ids || [];
+  // The mine flag makes it obvious in every response whether this touched an
+  // agent tab or one of the user's own.
+  return { id: id, title: tab.title(), url: tab.url(), location: tab.location(), mine: owned.indexOf(id) >= 0 };
+}
+
+function findSpace(needle) {
+  const w = mainWindow();
+  const count = w.spaces.length;
+  for (let i = 0; i < count; i++) {
+    const space = w.spaces[i];
+    if (space.id() === needle || space.title() === needle) return space;
+  }
+  return null;
+}
+`;
+
+// JSON is a JS-literal subset apart from the line separators, which older
+// JavaScriptCore parsers reject inside string literals.
+// Exported for unit tests; not part of the tool surface.
+export function jsLiteral(value) {
+  return JSON.stringify(value === undefined ? null : value)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+export class ArcError extends Error {}
+
+// osascript appends its own " (-2700)" style code to the thrown message
+function sentinel(message, name) {
+  const match = message.match(new RegExp(name + ':(.+?)(?:\\s*\\(-\\d+\\))?\\s*$', 'm'));
+  return match ? match[1].trim() : null;
+}
+
+// Exported for unit tests; not part of the tool surface.
+export function friendly(message) {
+  const tabNotFound = sentinel(message, 'TAB_NOT_FOUND');
+  if (tabNotFound) {
+    return `No open Arc tab has id ${tabNotFound}. Run list_tabs to get current tab ids (they change when a tab is closed and reopened).`;
+  }
+  const spaceNotFound = sentinel(message, 'SPACE_NOT_FOUND');
+  if (spaceNotFound) {
+    return `No Arc space matches "${spaceNotFound}". Run list_spaces to see the available ids and titles.`;
+  }
+  const noMatch = sentinel(message, 'SELECTOR_NO_MATCH');
+  if (noMatch) {
+    return `No element on the page matches the selector "${noMatch}".`;
+  }
+  if (message.includes('NO_TARGET_TAB')) {
+    return [
+      'This tool changes a tab, and no tab was given. This agent has not opened one yet, and',
+      'it will not act on whatever tab the user happens to be looking at.',
+      'Pass an explicit tab_id from list_tabs, or call open_url first to get your own tab.'
+    ].join('\n');
+  }
+  if (message.includes('ARC_NOT_RUNNING')) {
+    return 'Arc is not running. Launch Arc, or use open_url, which starts it.';
+  }
+  if (message.includes('ARC_NO_WINDOW')) {
+    return 'Arc is running but has no open windows. Open a window (Cmd-N) and try again.';
+  }
+  if (message.includes('-1743') || /not authoriz|assistive access/i.test(message)) {
+    return [
+      'Permission denied: controlling Arc needs automation access.',
+      'System Settings > Privacy & Security > Automation > enable "Arc" under this app,',
+      'then restart the app.'
+    ].join('\n');
+  }
+  if (/javascript/i.test(message) && /(turned off|disabled|not allowed)/i.test(message)) {
+    return 'Arc is blocking JavaScript from Apple Events. Enable it in Arc > Settings > Advanced ("Allow JavaScript from Apple Events").';
+  }
+  if (message.includes('-600') || /isn't running|is not running/i.test(message)) {
+    return 'Arc is not running. Launch Arc, or use open_url, which starts it.';
+  }
+  return message;
+}
+
+/**
+ * Run a JXA body against Arc. `params` is exposed to the script as `P`, so
+ * arguments are never string-concatenated into the source.
+ * The body's final expression must be a JSON string.
+ */
+export async function runJxa(body, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const script = `const P = ${jsLiteral(params)};\n${PREAMBLE}\n${body}`;
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync('osascript', ['-l', 'JavaScript', '-e', script], {
+      timeout: timeoutMs,
+      maxBuffer: MAX_BUFFER_BYTES
+    }));
+  } catch (error) {
+    if (error.killed || error.signal) {
+      throw new ArcError(`Arc did not respond within ${timeoutMs / 1000}s. It may be showing a dialog or busy loading.`);
+    }
+    // error.message embeds the whole `-e <script>` argv, which would false-match our sentinels
+    const detail = (error.stderr || '').trim() || error.message;
+    throw new ArcError(friendly(detail));
+  }
+
+  const text = stdout.trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ArcError(`Unexpected output from Arc: ${text.slice(0, 400)}`);
+  }
+}

package/src/page-lib.js

@@ -0,0 +1,219 @@
+/**
+ * Helpers injected into the page ahead of every DOM expression. Composed in
+ * Node and shipped through Arc's `execute javascript`, so tool code stays
+ * ordinary JavaScript instead of nested string building inside JXA.
+ */
+export const PAGE_LIB = `
+var A = (function () {
+  var api = {};
+
+  var TEXT_PREFIX = 'text=';
+
+  // Named keys get a legacy keyCode. Printable characters are handled
+  // separately, since keypress needs a charCode to look real to old handlers.
+  var KEY_CODES = {
+    Enter: 13, Tab: 9, Escape: 27, Backspace: 8, Delete: 46, Space: 32,
+    ArrowDown: 40, ArrowUp: 38, ArrowLeft: 37, ArrowRight: 39,
+    Home: 36, End: 35, PageUp: 33, PageDown: 34
+  };
+
+  var TEXT_CANDIDATES = 'a,button,[role=button],[role=link],[role=menuitem],[role=option],[role=tab],input,label,summary,li,td,th,h1,h2,h3,h4,h5,h6,span,div,p,legend,option';
+
+  function textOf(el) {
+    var t = el.innerText;
+    if (t === undefined || t === null || t === '') t = el.value;
+    if (t === undefined || t === null) t = '';
+    return String(t).trim();
+  }
+
+  // "text=Sign in" matches on visible text, anything else is a CSS selector.
+  // Exact matches come back before substring matches, so the obvious target
+  // wins on a page where the same word appears inside longer labels.
+  api.all = function (selector, root, opts) {
+    root = root || document;
+    opts = opts || {};
+    if (selector.indexOf(TEXT_PREFIX) !== 0) {
+      return Array.prototype.slice.call(root.querySelectorAll(selector));
+    }
+
+    var needle = selector.slice(TEXT_PREFIX.length).trim().toLowerCase();
+    var nodes = root.querySelectorAll(TEXT_CANDIDATES);
+    var hits = [];
+    for (var i = 0; i < nodes.length; i++) {
+      var t = textOf(nodes[i]).toLowerCase();
+      if (!t || t.length > 300) continue;
+      var exact = t === needle;
+      if (!exact && (opts.exact || t.indexOf(needle) === -1)) continue;
+      // Keep the innermost match only: drop ancestors already collected, and
+      // skip this node when a descendant of it is already in the list.
+      var nested = false;
+      for (var j = 0; j < hits.length; j++) {
+        if (hits[j].el.contains(nodes[i])) { hits.splice(j, 1); j--; }
+      }
+      for (var k = 0; k < hits.length; k++) {
+        if (nodes[i].contains(hits[k].el)) { nested = true; break; }
+      }
+      if (!nested) hits.push({ el: nodes[i], exact: exact });
+    }
+
+    var out = [];
+    for (var e = 0; e < hits.length; e++) if (hits[e].exact) out.push(hits[e].el);
+    for (var s = 0; s < hits.length; s++) if (!hits[s].exact) out.push(hits[s].el);
+    return out;
+  };
+
+  api.one = function (selector, nth, opts) {
+    var list = api.all(selector, null, opts);
+    return list[nth || 0] || null;
+  };
+
+  api.visible = function (el) {
+    if (!el || !el.getBoundingClientRect) return false;
+    var r = el.getBoundingClientRect();
+    // A 1x1 box is the standard screen-reader clipping trick, not something a
+    // user could click, so report it as hidden.
+    if (r.width < 2 || r.height < 2) return false;
+    var s = window.getComputedStyle(el);
+    if (s.visibility === 'hidden' || s.display === 'none' || s.opacity === '0') return false;
+    if (s.clipPath && /inset\\(\\s*(?:100%|50%)/.test(s.clipPath)) return false;
+    return true;
+  };
+
+  api.describe = function (el, verbose) {
+    if (!el) return null;
+    var cap = verbose ? 200 : 120;
+    var attrs = {};
+    for (var i = 0; i < el.attributes.length; i++) {
+      var a = el.attributes[i];
+      if (a.name === 'style') continue;
+      attrs[a.name] = a.value.length > cap ? a.value.slice(0, cap) + '\\u2026' : a.value;
+    }
+    var out = {
+      tag: el.tagName.toLowerCase(),
+      text: textOf(el).slice(0, verbose ? 400 : 200) || null,
+      value: 'value' in el ? el.value : null,
+      href: el.href || null,
+      visible: api.visible(el),
+      disabled: !!el.disabled,
+      checked: 'checked' in el ? !!el.checked : null,
+      attrs: attrs
+    };
+    // rect is the bulkiest field and is rarely actionable, so it is opt-in.
+    if (verbose) {
+      var r = el.getBoundingClientRect();
+      out.rect = { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) };
+    }
+    return out;
+  };
+
+  api.center = function (el) {
+    var r = el.getBoundingClientRect();
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+  };
+
+  api.click = function (el) {
+    el.scrollIntoView({ block: 'center', inline: 'center' });
+    var p = api.center(el);
+    var opts = { bubbles: true, cancelable: true, view: window, clientX: p.x, clientY: p.y, button: 0 };
+    ['pointerdown', 'mousedown', 'pointerup', 'mouseup', 'click'].forEach(function (type) {
+      var Ctor = type.indexOf('pointer') === 0 && window.PointerEvent ? PointerEvent : MouseEvent;
+      el.dispatchEvent(new Ctor(type, opts));
+    });
+    return true;
+  };
+
+  // Uses the native setter so React and other frameworks see the change.
+  api.setValue = function (el, value) {
+    if (el.isContentEditable) {
+      el.focus();
+      el.textContent = value;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      return true;
+    }
+    var tag = el.tagName.toLowerCase();
+    if (tag === 'select') {
+      throw new Error('A <select> cannot be filled. Use select_option instead.');
+    }
+    if (tag !== 'input' && tag !== 'textarea') {
+      throw new Error('<' + tag + '> is not an input, textarea or contenteditable element, so it cannot be filled.');
+    }
+    if (el.disabled) throw new Error('<' + tag + '> is disabled, so it cannot be filled.');
+    if (el.readOnly) throw new Error('<' + tag + '> is readonly, so it cannot be filled.');
+    var proto = tag === 'textarea' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+    var setter = Object.getOwnPropertyDescriptor(proto, 'value');
+    el.focus();
+    if (setter && setter.set) setter.set.call(el, value); else el.value = value;
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return true;
+  };
+
+  api.key = function (el, key) {
+    var printable = key.length === 1;
+    var code = printable ? key.charCodeAt(0) : (KEY_CODES[key] || 0);
+    var init = { key: key, keyCode: code, which: code, bubbles: true, cancelable: true };
+    el.dispatchEvent(new KeyboardEvent('keydown', init));
+    if (code) {
+      el.dispatchEvent(new KeyboardEvent('keypress', {
+        key: key, keyCode: code, which: code, charCode: printable ? code : 0,
+        bubbles: true, cancelable: true
+      }));
+    }
+    el.dispatchEvent(new KeyboardEvent('keyup', init));
+    return true;
+  };
+
+  api.miss = function (selector) {
+    return { error: 'no_match', selector: selector };
+  };
+
+  // Every injected script resolves to one of these two envelopes, so the Node
+  // side can tell "returned nothing" apart from "threw".
+  api.envelope = function (v) {
+    var out = { __arc: 1, ok: true };
+    var json;
+    try {
+      json = JSON.stringify(v);
+    } catch (e) {
+      return api.failure(new Error('Result is not JSON-serialisable: ' + (e && e.message ? e.message : e)));
+    }
+    if (json !== undefined) out.v = v;
+    if (json === '{}' && v && typeof v === 'object') {
+      var ctor = v.constructor && v.constructor.name;
+      if (ctor && ctor !== 'Object') {
+        out.note = ctor + ' has no JSON representation. Return specific properties, or A.describe(el) for an element.';
+      }
+    }
+    return out;
+  };
+
+  api.failure = function (e) {
+    return {
+      __arc: 1,
+      ok: false,
+      name: e && e.name ? String(e.name) : 'Error',
+      error: e && e.message ? String(e.message) : String(e)
+    };
+  };
+
+  return api;
+})();
+`;
+
+/**
+ * Wrap page code so it always resolves to an envelope: `{ __arc: 1, ok: true,
+ * v }` when it returned, `{ __arc: 1, ok: false, name, error }` when it threw.
+ * Arc hands back an empty string for a thrown script, which is otherwise
+ * indistinguishable from a page value of null.
+ */
+export function pageScript(body) {
+  return `${PAGE_LIB}
+(function(){
+  try {
+    return A.envelope((function(){
+${body}
+    })());
+  } catch (e) { return A.failure(e); }
+})()`;
+}

package/src/registry.js

@@ -0,0 +1,99 @@
+import { toJSONSchema } from 'zod';
+
+import { ArcError } from './jxa.js';
+import * as tabs from './tools/tabs.js';
+import * as navigation from './tools/navigation.js';
+import * as content from './tools/content.js';
+import * as interact from './tools/interact.js';
+import * as spaces from './tools/spaces.js';
+import * as scripting from './tools/scripting.js';
+
+// Drop a module in here and its tools are exposed; nothing else needs changing.
+const MODULES = { tabs, navigation, content, interact, spaces, scripting };
+
+export const TOOLS = [];
+export const HANDLERS = {};
+
+// A malformed tool definition is invisible over MCP: the client just sees a
+// tool that behaves oddly. Failing at import turns that into a startup crash
+// with the offending module named.
+/**
+ * The wire schema is generated, never hand-written. `io: 'input'` is what keeps
+ * a field with a default out of `required`, and drops the blanket
+ * additionalProperties so a tool can opt into it with z.strictObject.
+ */
+function schemaFrom(input) {
+  const json = toJSONSchema(input, { io: 'input' });
+  // $schema is meaningful for a standalone document, not for an inputSchema.
+  delete json.$schema;
+  return json;
+}
+
+function readableIssues(error) {
+  return error.issues
+    .map((issue) => {
+      const path = issue.path.join('.');
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join('; ');
+}
+
+function validate(moduleName, tool) {
+  const where = `${moduleName}.${tool?.name ?? '<unnamed>'}`;
+  if (!tool?.name) throw new Error(`Module ${moduleName} has a tool with no name`);
+  if (typeof tool.description !== 'string' || !tool.description.trim()) {
+    throw new Error(`Tool ${where} has no description, so a model cannot tell when to call it`);
+  }
+  if (!tool.input || typeof tool.input.safeParse !== 'function') {
+    throw new Error(`Tool ${where} needs an "input" Zod schema (see src/tools/schema.js)`);
+  }
+  const json = schemaFrom(tool.input);
+  if (json.type !== 'object' || !json.properties) {
+    throw new Error(`Tool ${where}'s input must be a z.object, so its schema describes named arguments`);
+  }
+  if (!tool.annotations?.title) {
+    throw new Error(`Tool ${where} has no annotations.title`);
+  }
+  return json;
+}
+
+/**
+ * One wrapper carries both cross-cutting concerns, so `batch` gets them for its
+ * steps too: arguments are validated against the tool's own schema, and the
+ * tool's read-only hint decides whether resolving to the user's active tab is
+ * acceptable.
+ */
+function wrap(tool, handler) {
+  const allowActiveTab = tool.annotations.readOnlyHint === true;
+  return async (args = {}, extra) => {
+    const parsed = tool.input.safeParse(args ?? {});
+    if (!parsed.success) {
+      // A bad argument is the tool failing, not the protocol failing, so this
+      // surfaces as an isError result the model can read and correct.
+      throw new ArcError(`Invalid arguments for ${tool.name}. ${readableIssues(parsed.error)}`);
+    }
+    return handler({ ...parsed.data, __allowActiveTab: allowActiveTab }, extra);
+  };
+}
+
+for (const [name, module] of Object.entries(MODULES)) {
+  for (const tool of module.tools) {
+    if (HANDLERS[tool.name]) throw new Error(`Duplicate tool name ${tool.name} in module ${name}`);
+    if (!module.handlers[tool.name]) throw new Error(`Module ${name} declares ${tool.name} with no handler`);
+    const inputSchema = validate(name, tool);
+    // Display precedence is top-level title, then annotations.title, then name.
+    // Deriving it here beats repeating the same string on 26 tool definitions.
+    const { input, ...rest } = tool;
+    TOOLS.push({ ...rest, title: tool.title ?? tool.annotations.title, inputSchema });
+    HANDLERS[tool.name] = wrap(tool, module.handlers[tool.name]);
+  }
+  for (const handlerName of Object.keys(module.handlers)) {
+    if (!module.tools.some((t) => t.name === handlerName)) {
+      throw new Error(`Module ${name} has handler ${handlerName} with no tool definition`);
+    }
+  }
+}
+
+scripting.bindRegistry(() => HANDLERS);
+
+export const MODULE_NAMES = Object.keys(MODULES);