arc-control-mcp 0.3.0

package/src/tools/scripting.js

@@ -0,0 +1,217 @@
+import { z, TAB_ID } from './schema.js';
+import { write, runPage } from './shared.js';
+import { ArcError } from '../jxa.js';
+
+// Cumulative budget for everything batch reports back. Individual read tools cap
+// themselves at 20000 characters each, so five of them already overshoot what a
+// client will accept, and a clipped response is unreadable rather than short.
+const MAX_BATCH_CHARS = 60000;
+
+export const tools = [
+  {
+    name: 'execute_javascript',
+    description: 'Run JavaScript in a tab and return the result. A bare expression, or a statement body that uses return, both work. The helper library is available as A (A.all, A.one, A.click, A.setValue, A.describe, A.visible).',
+    input: z.object({
+      code: z.string().describe('JavaScript to evaluate. An expression returns its value; a statement body returns whatever it returns, or null.'),
+      tab_id: TAB_ID.optional()
+    }),
+    annotations: write('Execute JavaScript', { destructive: true })
+  },
+  {
+    name: 'batch',
+    description:
+      'Run several tools in order in one call, passing the same tab through. Stops at the first failure unless continue_on_error is set. Use this to cut round trips: fill, fill, click, wait. ' +
+      `Results are capped at ${MAX_BATCH_CHARS} characters across all steps: past that the batch stops early and reports truncated, so pass max_chars to reading steps or split a read-heavy sequence across calls.`,
+    input: z.object({
+      steps: z
+        .array(
+          z.object({
+            tool: z.string().describe('Name of any other tool in this server'),
+            // A bag destined for another tool, so it has to survive validation
+            // whole: z.record keeps every key, where a z.object would strip the
+            // ones it does not know. The peer's own schema checks it later,
+            // because batch calls peers through the wrapped registry handlers.
+            args: z.record(z.string(), z.unknown()).optional().describe('Arguments for that tool')
+          })
+        )
+        .describe('Steps to run in order'),
+      tab_id: TAB_ID.optional().describe('Applied to every step that does not set its own'),
+      continue_on_error: z.boolean().default(false).describe('Keep going after a failing step')
+    }),
+    annotations: write('Batch', { destructive: true })
+  }
+];
+
+// `batch` needs to call peers, so the registry injects the full handler map.
+let lookup = () => ({});
+export function bindRegistry(fn) {
+  lookup = fn;
+}
+
+/** Parse-check a function body in Node. Returns the SyntaxError message, or null. */
+function parseError(body) {
+  try {
+    // Built, never called: constructing it is the parse check.
+    new Function('A', body);
+    return null;
+  } catch (error) {
+    return error.message;
+  }
+}
+
+/**
+ * Decide here, in Node, whether the caller's code is an expression or a
+ * statement body. Two reasons it cannot be decided in the page: a syntax error
+ * in the injected script fails at parse time, so no try/catch in the page can
+ * report it and Arc just returns empty, and a page with a strict CSP (GitHub,
+ * Google) can block the eval such a check would need.
+ * Newlines around the code keep a trailing line comment from eating the `);`.
+ */
+export function wrapUserCode(code) {
+  const expression = `return (\n${code}\n);`;
+  if (!parseError(expression)) return { form: 'expression', body: expression };
+
+  const statementError = parseError(code);
+  if (!statementError) return { form: 'statement', body: code };
+
+  throw new ArcError(
+    `That code does not parse: ${statementError}. It is not a valid expression either, ` +
+    'so nothing was sent to Arc.'
+  );
+}
+
+// Two step results describe the same tab when the id and the url match. Title
+// can flap on a single-page app without the step having changed tabs.
+const sameTab = (a, b) => !!a && !!b && a.id === b.id && a.url === b.url;
+
+/**
+ * The tab state most steps saw, which is the one worth hoisting out of the
+ * results. `>=` walks forward, so a tie picks the later state: after a
+ * navigation the caller cares about where the batch ended up.
+ */
+function commonTab(tabs) {
+  let best = null;
+  let bestCount = 0;
+  for (const tab of tabs) {
+    const count = tabs.filter((other) => sameTab(other, tab)).length;
+    if (count >= bestCount) {
+      best = tab;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+
+// Charged against the batch budget. JSON.stringify is what index.js serialises
+// the response with, so it is the right ruler for what the caller will receive.
+const resultChars = (entry) => JSON.stringify(entry ?? null).length;
+
+function withoutTab(value) {
+  if (!value || typeof value !== 'object' || !('tab' in value)) return value;
+  const { tab, ...rest } = value;
+  return rest;
+}
+
+export const handlers = {
+  execute_javascript: async (args) => {
+    const { form, body } = wrapUserCode(args.code);
+    const { result, note, tab } = await runPage(args, body);
+    // A statement body yields a value only through `return`, so an empty result
+    // there is worth explaining rather than reporting as a bare null.
+    const needsReturn = result === undefined && form === 'statement' && !/\breturn\b/.test(args.code);
+    const hint = needsReturn
+      ? 'Ran as a statement body, which produces a value only through `return`. Add one to get a result back.'
+      : null;
+    return {
+      ok: true,
+      // Says which wrapper was chosen, so a null result is never a mystery.
+      form,
+      result: result === undefined ? null : result,
+      ...(note || hint ? { note: note || hint } : {}),
+      tab
+    };
+  },
+
+  batch: async (args, extra) => {
+    const steps = args.steps || [];
+    const all = lookup();
+    const ran = [];
+    let budgetLeft = MAX_BATCH_CHARS;
+    let truncated = false;
+    let note = null;
+
+    // bindRegistry runs when registry.js is imported. Importing this module on
+    // its own leaves batch with no peers, and "Unknown tool: click" is a
+    // baffling way to find that out.
+    if (Object.keys(all).length === 0) {
+      throw new ArcError(
+        'batch has no tools to call because the registry was never bound. Import ' +
+        'src/registry.js, as src/index.js does, rather than this module on its own.'
+      );
+    }
+
+    for (const [index, step] of steps.entries()) {
+      // A cancelled caller is not going to read the rest, and every remaining
+      // step would spawn another osascript process on the user's machine.
+      if (extra?.signal?.aborted) {
+        note = `Cancelled after ${ran.length} of ${steps.length} steps. Whatever the steps already run did to the page stands.`;
+        break;
+      }
+      const handler = all[step.tool];
+      if (!handler) {
+        ran.push({ index, tool: step.tool, ok: false, error: `Unknown tool: ${step.tool}` });
+        if (!args.continue_on_error) break;
+        continue;
+      }
+      const stepArgs = { ...(args.tab_id ? { tab_id: args.tab_id } : {}), ...(step.args || {}) };
+      try {
+        // extra carries the client's AbortSignal, so a cancelled batch stops
+        // inside the step it is on rather than only between steps.
+        const value = await handler(stepArgs, extra);
+        const failed = value && value.ok === false;
+        ran.push({ index, tool: step.tool, ok: !failed, value });
+        if (failed && !args.continue_on_error) break;
+      } catch (error) {
+        ran.push({ index, tool: step.tool, ok: false, error: error.message });
+        if (!args.continue_on_error) break;
+      }
+
+      // Charged after the step, so the step that used up the budget still
+      // reports its result: it already ran, and dropping the value would hide
+      // a side effect the caller has to know about.
+      budgetLeft -= resultChars(ran[ran.length - 1]);
+      if (budgetLeft <= 0 && index < steps.length - 1) {
+        truncated = true;
+        note =
+          `Stopped after ${ran.length} of ${steps.length} steps: the results reached this batch's ` +
+          `${MAX_BATCH_CHARS} character budget, and a longer response would be clipped by the client ` +
+          'mid-JSON. Run the remaining steps as a second batch, and pass max_chars to the reading ' +
+          'steps (get_page_content, get_html) or a smaller limit to query_elements and get_links.';
+        break;
+      }
+    }
+
+    // The tab is usually the same for every step, and repeating it (url and
+    // all) once per step buried the actual results. Report it once and flag
+    // only the steps whose tab really differs.
+    const batchTab = commonTab(ran.map((r) => r.value && r.value.tab).filter(Boolean));
+
+    const results = ran.map(({ index, tool, ok, value, error }) => {
+      if (error !== undefined) return { index, tool, ok, error };
+      const stepTab = value && value.tab;
+      const out = { index, tool, ok, result: withoutTab(value) };
+      if (stepTab && !sameTab(stepTab, batchTab)) out.tab = stepTab;
+      return out;
+    });
+
+    return {
+      ran: results.length,
+      total: steps.length,
+      ok: results.every((r) => r.ok),
+      ...(truncated ? { truncated: true } : {}),
+      ...(note ? { note } : {}),
+      ...(batchTab ? { tab: batchTab } : {}),
+      results
+    };
+  }
+};

package/src/tools/shared.js

@@ -0,0 +1,100 @@
+import { runJxa, ArcError } from '../jxa.js';
+import * as state from '../state.js';
+import { pageScript } from '../page-lib.js';
+
+/**
+ * MCP tool annotations. The spec's defaults are counterintuitive:
+ * destructiveHint and openWorldHint both default to true, and destructiveHint
+ * and idempotentHint are only meaningful when readOnlyHint is false. Every
+ * hint is therefore stated rather than left to a client's inference.
+ *
+ * openWorld defaults to true because almost every tool here touches an
+ * arbitrary web page, and untrusted external content is precisely the open
+ * world the flag exists to describe. Pass openWorld: false only for tools that
+ * read Arc's own tab and space bookkeeping.
+ */
+export const read = (title, options = {}) => {
+  // Same guard as write(): a stale positional argument should crash at import
+  // rather than quietly resolve to a default nobody intended.
+  if (typeof options !== 'object' || options === null) {
+    throw new Error(`read("${title}") takes an options object. Pass { openWorld: false } instead of a boolean.`);
+  }
+  const { openWorld = true } = options;
+  return {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: openWorld
+  };
+};
+
+export const write = (title, options = {}) => {
+  // This used to take a positional boolean. Mislabelling a destructive tool as
+  // safe is the worst outcome here, so a stale call site must crash at import
+  // rather than quietly resolve to destructive: false.
+  if (typeof options !== 'object' || options === null) {
+    throw new Error(`write("${title}") takes an options object. Pass { destructive: true } instead of a boolean.`);
+  }
+  const { destructive = false, idempotent = false, openWorld = true } = options;
+  return {
+    title,
+    readOnlyHint: false,
+    destructiveHint: destructive,
+    idempotentHint: idempotent,
+    openWorldHint: openWorld
+  };
+};
+
+/** Adds the agent's implicit target and ownership info to every script. */
+export function scoped(args = {}) {
+  // The registry decides per tool whether falling back to the user's active
+  // tab is acceptable, and passes it down out of band rather than as a
+  // caller-settable argument.
+  const { __allowActiveTab, ...rest } = args;
+  return {
+    ...rest,
+    allow_active_tab: __allowActiveTab === true,
+    default_tab_id: state.currentTabId(),
+    agent_space: state.AGENT_SPACE,
+    owned_ids: state.ownedIds()
+  };
+}
+
+/**
+ * Turn a page envelope into a plain value, or raise the page's own error.
+ * Without this a thrown page script arrives as `null` and every handler
+ * spreads it into a cheerful `{ ok: true }`.
+ */
+export function unwrapPage(out) {
+  const { result, tab } = out || {};
+  if (!result || result.__arc !== 1) {
+    throw new ArcError(
+      'The page script returned nothing recognisable. Arc may be blocking JavaScript from Apple ' +
+      'Events (Arc > Settings > Advanced > "Allow JavaScript from Apple Events"), or the tab ' +
+      'navigated while the call was in flight.'
+    );
+  }
+  if (result.ok === false) {
+    throw new ArcError(`The page script failed: ${result.name}: ${result.error}`);
+  }
+  return { result: result.v, note: result.note, tab };
+}
+
+/** Resolve a tab, run DOM code in it, and return the value plus tab info. */
+export function runPage(args, body, timeoutMs) {
+  return runJxa(
+    `const tab = target();
+     JSON.stringify({ result: evalJs(tab, P.page_code), tab: describe(tab) });`,
+    scoped({ ...args, page_code: pageScript(body) }),
+    timeoutMs
+  ).then(unwrapPage);
+}
+
+/** Same, but for scripts whose value is the whole response. */
+export function runTab(args, jxaBody, timeoutMs) {
+  return runJxa(jxaBody, scoped(args), timeoutMs);
+}
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export { state };

package/src/tools/spaces.js

@@ -0,0 +1,66 @@
+import { z } from './schema.js';
+import { read, write, runTab } from './shared.js';
+
+export const tools = [
+  {
+    name: 'list_spaces',
+    description: 'List Arc spaces in the front window, with tab counts and which is active. Tabs pinned to the top of the sidebar (location topApp) belong to no space, so the reported tabsInSpaces plus topAppCount is what reconciles with totalTabs. Counts cover the front window only, while list_tabs covers every window.',
+    // strictObject, so the generated schema keeps additionalProperties: false.
+    input: z.strictObject({}),
+    annotations: read('List Spaces', { openWorld: false })
+  },
+  {
+    name: 'focus_space',
+    description: "Switch the front Arc window to a space. This changes what the user sees, so it is rarely needed: tabs in an unfocused space are still fully readable and scriptable.",
+    input: z.object({ space: z.string().describe('Space id or title from list_spaces') }),
+    annotations: write('Focus Space', { idempotent: true, openWorld: false })
+  }
+];
+
+export const handlers = {
+  list_spaces: (args) =>
+    runTab(
+      args,
+      `requireArc();
+       const w = mainWindow();
+       const activeId = w.activeSpace.id();
+       const spaces = [];
+       let tabsInSpaces = 0;
+       for (let i = 0; i < w.spaces.length; i++) {
+         const s = w.spaces[i];
+         const tabCount = s.tabs.length;
+         tabsInSpaces += tabCount;
+         spaces.push({
+           id: s.id(),
+           title: s.title(),
+           tabCount: tabCount,
+           isActive: s.id() === activeId,
+           isAgentSpace: s.title() === P.agent_space
+         });
+       }
+       // space.tabs excludes topApp favourites, so the per-space counts alone
+       // never add up to what list_tabs reports. Carry the missing number.
+       const locations = w.tabs.location();
+       let topAppCount = 0;
+       for (let k = 0; k < locations.length; k++) if (locations[k] === "topApp") topAppCount++;
+       JSON.stringify({
+         windowId: w.id(),
+         agentSpaceName: P.agent_space,
+         totalTabs: locations.length,
+         tabsInSpaces: tabsInSpaces,
+         topAppCount: topAppCount,
+         spaces: spaces
+       });`
+    ),
+
+  focus_space: (args) =>
+    runTab(
+      args,
+      `requireArc();
+       const space = findSpace(P.space);
+       if (!space) throw new Error("SPACE_NOT_FOUND:" + P.space);
+       Arc.focus(space);
+       delay(0.3);
+       JSON.stringify({ ok: true, action: "focused space", space: { id: space.id(), title: space.title() } });`
+    )
+};

package/src/tools/tabs.js

@@ -0,0 +1,189 @@
+import { runJxa } from '../jxa.js';
+import { z, TAB_ID } from './schema.js';
+import { read, write, scoped, runTab, state } from './shared.js';
+
+async function snapshotAll() {
+  const result = await runJxa(
+    `requireArc();
+     const space = agentSpace();
+     JSON.stringify({ tabs: snapshot(), agentSpace: space ? { id: space.id(), title: space.title() } : null });`,
+    scoped()
+  );
+  state.reconcile(result.tabs.map((t) => t.id));
+  return result;
+}
+
+export const tools = [
+  {
+    name: 'list_tabs',
+    description: "List Arc tabs. Rows are flagged 'mine' for tabs this agent opened and 'isActive' for the tab the user is on. Defaults to every tab; pass scope 'own' to narrow.",
+    input: z.object({
+      scope: z.enum(['all', 'own']).default('all').describe("'all' (default) or only this agent's tabs"),
+      query: z.string().describe('Case-insensitive substring matched against title and url').optional(),
+      space: z.string().describe('Only tabs in this space title').optional(),
+      window_id: z.string().describe('Restrict to one window id').optional()
+    }),
+    annotations: read('List Tabs', { openWorld: false })
+  },
+  {
+    name: 'get_current_tab',
+    description: "Get the tab a call with no tab_id would act on: this agent's current tab, or the active tab if it has none.",
+    input: z.object({ tab_id: TAB_ID.optional() }),
+    annotations: read('Get Current Tab', { openWorld: false })
+  },
+  {
+    name: 'switch_to_tab',
+    description: 'Make a tab the active tab in its window. Changes what the user sees, so prefer reading a tab by id when you only need its content.',
+    input: z.object({
+      // Mandatory here, so the fallback wording the shared schema carries would
+      // only be misleading.
+      tab_id: TAB_ID.describe('Arc tab id from list_tabs'),
+      activate: z.boolean().default(false).describe('Also bring Arc to the front')
+    }),
+    annotations: write('Switch To Tab', { idempotent: true, openWorld: false })
+  },
+  {
+    name: 'close_tab',
+    description:
+      "Close one tab. With no tab_id this closes this agent's own current tab, and is refused outright if the agent has not opened one: it will never close the tab the user is looking at. Pass an explicit tab_id from list_tabs to close any other tab. Closing cannot be undone and tab ids are not reused. To clean up after yourself, prefer close_own_tabs.",
+    input: z.object({ tab_id: TAB_ID.optional() }),
+    annotations: write('Close Tab', { destructive: true, openWorld: false })
+  },
+  {
+    name: 'close_own_tabs',
+    description: "Close every tab this agent opened, leaving the user's tabs alone. Tabs leaked by a previous run of this label are left alone too unless include_stale is set.",
+    input: z.object({
+      include_stale: z
+        .boolean()
+        .default(false)
+        .describe(
+          "Also close tabs left behind by dead sessions of this label (see staleTabCount in arc_status). Never touches a live agent's tabs."
+        )
+    }),
+    annotations: write('Close Own Tabs', { destructive: true, openWorld: false })
+  },
+  {
+    name: 'arc_status',
+    description: 'Report Arc state: which tabs this agent owns, whether the agent space exists, what a call with no tab_id resolves to, and how many tabs a previous run of this label left behind.',
+    // strictObject, so the generated schema keeps additionalProperties: false.
+    input: z.strictObject({}),
+    annotations: read('Arc Status', { openWorld: false })
+  }
+];
+
+export const handlers = {
+  arc_status: async () => {
+    const { tabs, agentSpace } = await snapshotAll();
+    const owned = new Set(state.ownedIds());
+    const active = tabs.find((t) => t.isActive);
+    // Mirrors target() in jxa.js: the agent's own tab only counts while it is
+    // still open, and a dead one falls through the same way as never having had
+    // one at all.
+    const currentTabId = state.currentTabId();
+    const ownTab = (currentTabId && tabs.find((t) => t.id === currentTabId)) || null;
+    return {
+      label: state.label(),
+      // Ownership is per session, so two agents can share a label without
+      // seeing each other's tabs. The file is where a restart looks for leaks.
+      sessionId: state.sessionId(),
+      stateFile: state.stateFile(),
+      isolation: agentSpace ? 'space' : 'shared-window',
+      agentSpace,
+      agentSpaceName: state.AGENT_SPACE,
+      // A read-only tool and one that changes a tab no longer resolve the same
+      // way once this agent owns no tab, so each gets its own answer rather
+      // than one reason that is only half true.
+      resolvesTo: ownTab
+        ? {
+            readOnly: { reason: "this agent's current tab", tab: ownTab },
+            mutating: { reason: "this agent's current tab", tab: ownTab }
+          }
+        : {
+            readOnly: {
+              reason: 'no agent tab, so a read-only tool falls back to the tab the user is looking at',
+              tab: active || null
+            },
+            mutating: {
+              reason:
+                "no agent tab, so a tool that changes a tab is refused rather than acting on the user's tab. Pass a tab_id from list_tabs, or call open_url first.",
+              tab: null
+            }
+          },
+      ownTabs: tabs.filter((t) => owned.has(t.id)),
+      staleTabCount: state.staleIds().length,
+      otherTabCount: tabs.filter((t) => !owned.has(t.id)).length
+    };
+  },
+
+  list_tabs: async (args) => {
+    const { tabs } = await snapshotAll();
+    const owned = new Set(state.ownedIds());
+    const scope = args.scope || 'all';
+
+    let rows = tabs.map((t) => ({ ...t, mine: owned.has(t.id) }));
+    if (scope === 'own') rows = rows.filter((t) => t.mine);
+    if (args.window_id) rows = rows.filter((t) => t.windowId === args.window_id);
+    if (args.space) rows = rows.filter((t) => t.space === args.space);
+    if (args.query) {
+      const q = args.query.toLowerCase();
+      rows = rows.filter((t) => (t.title || '').toLowerCase().includes(q) || (t.url || '').toLowerCase().includes(q));
+    }
+    return { scope, count: rows.length, tabs: rows };
+  },
+
+  get_current_tab: (args) => runTab(args, `const tab = target(); JSON.stringify(describe(tab));`),
+
+  switch_to_tab: async (args) => {
+    const result = await runTab(
+      args,
+      `const tab = target();
+       Arc.select(tab);
+       if (P.activate) Arc.activate();
+       delay(0.3);
+       JSON.stringify({ ok: true, action: "switched", tab: describe(tab) });`
+    );
+    state.focusOwn(result.tab.id);
+    return result;
+  },
+
+  close_tab: async (args) => {
+    const result = await runTab(
+      args,
+      `const tab = target();
+       const info = describe(tab);
+       Arc.close(tab);
+       JSON.stringify({ ok: true, action: "closed", tab: info });`
+    );
+    state.release(result.tab.id);
+    return result;
+  },
+
+  close_own_tabs: async (args = {}) => {
+    // Stale tabs are opt-in: reaping them by default would make every restart
+    // destructive, and a recycled pid could make a live sibling look dead.
+    const stale = args.include_stale ? state.staleIds() : [];
+    const ids = [...new Set([...state.ownedIds(), ...stale])];
+    if (ids.length === 0) return { ok: true, closed: 0, note: 'This agent had no tabs open.' };
+    const result = await runJxa(
+      `requireArc();
+       const closed = [];
+       for (let i = 0; i < P.ids.length; i++) {
+         const tab = locate(P.ids[i]);
+         if (!tab) continue;
+         closed.push({ id: P.ids[i], title: tab.title() });
+         Arc.close(tab);
+         delay(0.2);
+       }
+       JSON.stringify({ closed: closed });`,
+      { ids }
+    );
+    result.closed.forEach((t) => state.release(t.id));
+    const staleClosed = result.closed.filter((t) => stale.includes(t.id)).length;
+    return {
+      ok: true,
+      closed: result.closed.length,
+      ...(staleClosed > 0 ? { staleClosed } : {}),
+      tabs: result.closed
+    };
+  }
+};