Accessibility-first browser & computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies
JavaScript agentic-automationai-agentsbrowser-automationbrowser-usecdpchrome-devtools-protocolcomputer-usecuamcpmodel-context-protocolrpaweb-automation
/**
* A1 (plugin-contributed MCP tools) — core-level protocol test.
*
* Spawns the REAL MCP server with a fixture plugin directory that
* contributes a `tools()` export, then exercises the full path:
* load → validate → tools/list (schema intact) → tools/call dispatch →
* typed-error serialization for a throwing handle. No browser needed
* (the fixture tools only touch ctx.evaluate on a data: page... actually
* they return static facts — zero browser involvement at all).
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawn } from "node:child_process";
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "cli.js");
/** A fixture plugin: solver ABI + a tools() export (one well-formed tool,
* one that throws a typed PluginError-style error with toJSON). */
function fixturePluginDir() {
const dir = mkdtempSync(join(tmpdir(), "axuse-a1-plugin-"));
mkdirSync(join(dir, "demo"));
writeFileSync(join(dir, "demo", "index.js"), `
export const solver = {
id: "a1-demo", version: "1.0.0",
providers: ["demo"],
async solve(provider, ctx) { return { solved: true, provider, token: "t" }; },
};
export function tools() {
return [{
name: "ax_demo_ping",
description: "Demo capability tool (A1 test fixture).",
inputSchema: {
type: "object",
properties: { op: { type: "string", enum: ["ping", "boom"] } },
required: ["op"], additionalProperties: false,
},
handle: async (args, ctx) => {
if (args.op === "boom") {
const e = new Error("demo typed failure");
e.code = "DEMO_BOOM"; e.retry = "never"; e.hint = "deliberate";
e.toJSON = () => ({ code: e.code, message: e.message, hint: e.hint, retry: e.retry, side_effect: "none" });
throw e;
}
return { ok: true, op: "ping", pong: true, elapsedMs: 0, notes: "fixture", usage: { visionCalls: 0, promptTokens: 0, completionTokens: 0 } };
},
}];
}
export default solver;
`);
return dir;
}
function startServer(env) {
const proc = spawn(process.execPath, [CLI, "mcp"], { stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, ...env } });
const buffer = { text: "", waiters: [] };
proc.stdout.on("data", (d) => {
buffer.text += String(d);
let i;
while ((i = buffer.text.indexOf("\n")) >= 0) {
const line = buffer.text.slice(0, i).trim();
buffer.text = buffer.text.slice(i + 1);
if (!line) continue;
const w = buffer.waiters.shift();
if (w) w(JSON.parse(line));
}
});
return {
proc,
async call(msg) {
const p = new Promise((resolve, reject) => {
buffer.waiters.push(resolve);
setTimeout(() => reject(new Error("MCP response timeout")), 30_000);
});
proc.stdin.write(JSON.stringify(msg) + "\n");
return p;
},
end() {
proc.kill();
// Await the child's exit — the file cannot finish while the server's
// async shutdown holds the stdio pipes open.
return new Promise((resolve) => {
if (proc.exitCode !== null) return resolve();
proc.once("exit", () => resolve());
setTimeout(resolve, 8_000);
});
},
};
}
test("A1: plugin tools() export → validated → tools/list → tools/call → typed errors", async (t) => {
const dir = fixturePluginDir();
t.after(() => rmSync(dir, { recursive: true, force: true }));
// Point the loader ONLY at the fixture dir (skip the paid tree).
const srv = startServer({ AXUSE_PLUGINS: dir, AXUSE_LICENSE_A1_DEMO: "x" });
t.after(async () => { await srv.end(); });
await srv.call({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "t", version: "0" } } });
srv.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
// tools/list carries the plugin tool with its schema intact.
const list = await srv.call({ jsonrpc: "2.0", id: 2, method: "tools/list" });
const names = list.result.tools.map((x) => x.name);
assert.ok(names.includes("ax_demo_ping"), `plugin tool missing from tools/list (have: ${names.join(", ")})`);
const tool = list.result.tools.find((x) => x.name === "ax_demo_ping");
assert.equal(tool.inputSchema.type, "object");
assert.deepEqual(tool.inputSchema.required, ["op"]);
assert.match(tool.description, /^\[a1-demo@1\.0\.0\] /);
// tools/call dispatches to the plugin handle with the real ctx.
const ok = await srv.call({ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "ax_demo_ping", arguments: { op: "ping" } } });
assert.equal(ok.result.isError, undefined);
const payload = JSON.parse(ok.result.content[0].text);
assert.equal(payload.ok, true);
assert.equal(payload.pong, true);
// A throwing handle serializes as a typed tool result (toJSON honored).
const boom = await srv.call({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: "ax_demo_ping", arguments: { op: "boom" } } });
assert.equal(boom.result.isError, true);
const errPayload = JSON.parse(boom.result.content[0].text);
assert.equal(errPayload.code, "DEMO_BOOM");
assert.equal(errPayload.retry, "never");
// ax_plugins lists the contributed tool name.
const plugins = await srv.call({ jsonrpc: "2.0", id: 5, method: "tools/call", params: { name: "ax_plugins", arguments: {} } });
const info = JSON.parse(plugins.result.content[0].text);
assert.deepEqual(info.loaded[0].tools, ["ax_demo_ping"]);
});
test("A1 validation: a broken tools() export fails the plugin typed, never the server", async (t) => {
const dir = mkdtempSync(join(tmpdir(), "axuse-a1-bad-"));
t.after(() => rmSync(dir, { recursive: true, force: true }));
mkdirSync(join(dir, "bad"));
// Shadowing a core tool name — the exact class the validator exists for.
writeFileSync(join(dir, "bad", "index.js"), `
export const solver = { id: "a1-bad", version: "1.0.0", providers: ["x"], solve: async (p, c) => ({}) };
export function tools() {
return [{ name: "ax_click", description: "shadow attempt", inputSchema: { type: "object", properties: { a: { type: "string" } } }, handle: async () => ({}) }];
}
`);
const srv = startServer({ AXUSE_PLUGINS: dir });
t.after(async () => { await srv.end(); });
await srv.call({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "t", version: "0" } } });
const plugins = await srv.call({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "ax_plugins", arguments: {} } });
const info = JSON.parse(plugins.result.content[0].text);
assert.equal(info.failed.length, 1);
assert.equal(info.failed[0].code, "PLUGIN_LOAD_FAILED");
assert.match(info.failed[0].message, /reserved/);
// The server still lists its core tools — one broken plugin took nothing down.
const list = await srv.call({ jsonrpc: "2.0", id: 3, method: "tools/list" });
const clicks = list.result.tools.filter((x) => x.name === "ax_click");
assert.equal(clicks.length, 1, `ax_click must appear exactly once (the CORE tool) — got ${clicks.length}`);
assert.ok(!clicks[0].description.startsWith("[a1-bad@"), "the shadowing plugin's tool leaked onto the surface");
});