@ait-co/devtools 0.1.22 → 0.1.23

package/dist/mcp/cli.js

@@ -0,0 +1,930 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { argv } from "node:process";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { EventEmitter } from "node:events";
+import { WebSocket } from "ws";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { Tunnel, bin, install } from "cloudflared";
+import qrcode from "qrcode-terminal";
+//#region src/mcp/ait-chii-source.ts
+function isObject$2(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Narrows an `AIT.getSdkCallHistory` response, tolerating a missing array. */
+function asSdkCallHistory(raw) {
+	if (isObject$2(raw) && Array.isArray(raw.calls)) return { calls: raw.calls };
+	return { calls: [] };
+}
+/** Narrows an `AIT.getMockState` response to an opaque record. */
+function asMockState(raw) {
+	return isObject$2(raw) ? raw : {};
+}
+/** Narrows an `AIT.getOperationalEnvironment` response. */
+function asOperationalEnvironment(raw) {
+	return {
+		environment: isObject$2(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
+		sdkVersion: isObject$2(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
+	};
+}
+var ChiiAitSource = class {
+	constructor(sender) {
+		this.sender = sender;
+	}
+	async get(method) {
+		const raw = await this.sender.sendCommand(method);
+		switch (method) {
+			case "AIT.getSdkCallHistory": return asSdkCallHistory(raw);
+			case "AIT.getMockState": return asMockState(raw);
+			case "AIT.getOperationalEnvironment": return asOperationalEnvironment(raw);
+			default: throw new Error(`Unknown AIT method: ${String(method)}`);
+		}
+	}
+};
+//#endregion
+//#region src/mcp/chii-connection.ts
+/**
+* Production `CdpConnection` backed by the local Chii relay.
+*
+* Topology (debug mode):
+*   phone target.js  --WS-->  Chii relay :9100  <--WS--  this connection
+*
+* The phone connects to the relay as a `target`; this module connects as a
+* `client` (the role a CDP frontend would take) so CDP events the page emits
+* (`Runtime.consoleAPICalled`, `Network.*`) flow back here. We buffer recent
+* events in ring buffers the tool layer reads via `getBufferedEvents`.
+*
+* Node-only: imports `ws`. Never bundled into the browser/in-app entries.
+*/
+/** Max events retained per domain ring buffer. */
+const DEFAULT_BUFFER_SIZE = 500;
+function isObject$1(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseInbound(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isObject$1(parsed)) return null;
+	const message = {};
+	if (typeof parsed.id === "number") message.id = parsed.id;
+	if (typeof parsed.method === "string") message.method = parsed.method;
+	if ("params" in parsed) message.params = parsed.params;
+	if ("result" in parsed) message.result = parsed.result;
+	if (isObject$1(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	return message;
+}
+const PHASE_1_EVENTS = [
+	"Runtime.consoleAPICalled",
+	"Network.requestWillBeSent",
+	"Network.responseReceived"
+];
+/**
+* Production CDP connection. Polls the relay for the first attached target,
+* opens a client websocket to it, enables Phase 1 domains, and buffers events.
+*/
+var ChiiCdpConnection = class {
+	relayBaseUrl;
+	bufferSize;
+	emitter = new EventEmitter();
+	buffers = /* @__PURE__ */ new Map();
+	targets = /* @__PURE__ */ new Map();
+	ws = null;
+	nextCommandId = 1;
+	/** In-flight enableDomains() promise — concurrent callers share it. */
+	enablingPromise = null;
+	/** Pending request→response commands keyed by CDP message id. */
+	pending = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.relayBaseUrl = options.relayBaseUrl.replace(/\/$/, "");
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+		for (const event of PHASE_1_EVENTS) this.buffers.set(event, []);
+		this.emitter.setMaxListeners(0);
+	}
+	/** Refresh the attached-target list from the relay's `GET /targets`. */
+	async refreshTargets() {
+		const res = await fetch(`${this.relayBaseUrl}/targets`);
+		if (!res.ok) throw new Error(`Chii relay /targets returned HTTP ${res.status} ${res.statusText}`);
+		const body = await res.json();
+		const list = isObject$1(body) && Array.isArray(body.targets) ? body.targets : [];
+		this.targets.clear();
+		for (const item of list) {
+			if (!isObject$1(item) || typeof item.id !== "string") continue;
+			this.targets.set(item.id, {
+				id: item.id,
+				title: typeof item.title === "string" ? item.title : "",
+				url: typeof item.url === "string" ? item.url : ""
+			});
+		}
+		return [...this.targets.values()];
+	}
+	listTargets() {
+		return [...this.targets.values()];
+	}
+	/**
+	* Connect a client websocket to the first attached target and enable Phase 1
+	* domains. Resolves once the socket is open and enable commands are sent.
+	*/
+	async enableDomains() {
+		if (this.ws && this.ws.readyState === WebSocket.OPEN) return;
+		if (this.enablingPromise) return this.enablingPromise;
+		this.enablingPromise = this._doEnableDomains().finally(() => {
+			this.enablingPromise = null;
+		});
+		return this.enablingPromise;
+	}
+	async _doEnableDomains() {
+		const target = (await this.refreshTargets())[0];
+		if (!target) throw new Error("No mini-app page attached to the Chii relay yet.");
+		const ws = new WebSocket(`${this.relayBaseUrl.replace(/^http/, "ws")}/client/${`devtools-mcp-${Date.now()}`}?target=${encodeURIComponent(target.id)}`);
+		this.ws = ws;
+		await new Promise((resolve, reject) => {
+			ws.once("open", () => resolve());
+			ws.once("error", (err) => reject(err));
+		});
+		ws.on("message", (data) => this.handleMessage(data.toString()));
+		this.sendFireAndForget("Runtime.enable");
+		this.sendFireAndForget("Network.enable");
+		this.sendFireAndForget("DOM.enable");
+		this.sendFireAndForget("Page.enable");
+	}
+	/** Fire-and-forget CDP message (used for `*.enable`, no result awaited). */
+	sendFireAndForget(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+		const id = this.nextCommandId++;
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params
+		}));
+	}
+	/**
+	* Issue a CDP command and resolve with its result (Phase 2). Rejects on a CDP
+	* error frame or when no websocket is open (no page attached yet).
+	*/
+	send(method, params) {
+		return this.sendCommand(method, params ?? {});
+	}
+	/**
+	* Issue an arbitrary request→response command over the relay and resolve with
+	* its raw result. Both the typed CDP {@link send} and the AIT domain (Phase 3
+	* `AIT.*` methods, forwarded over the same Chii channel) build on this.
+	*/
+	sendCommand(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
+		const id = this.nextCommandId++;
+		const ws = this.ws;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject
+			});
+			ws.send(JSON.stringify({
+				id,
+				method,
+				params
+			}));
+		});
+	}
+	handleMessage(raw) {
+		const message = parseInbound(raw);
+		if (!message) return;
+		if (typeof message.id === "number" && this.pending.has(message.id)) {
+			const waiter = this.pending.get(message.id);
+			this.pending.delete(message.id);
+			if (waiter) if (message.error) waiter.reject(new Error(message.error.message));
+			else waiter.resolve(message.result);
+			return;
+		}
+		if (typeof message.method !== "string") return;
+		if (!this.buffers.has(message.method)) return;
+		const event = message.method;
+		const buffer = this.buffers.get(event);
+		if (!buffer) return;
+		buffer.push(message.params);
+		if (buffer.length > this.bufferSize) buffer.shift();
+		this.emitter.emit(event, message.params);
+	}
+	getBufferedEvents(event) {
+		return this.buffers.get(event) ?? [];
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return () => this.emitter.off(event, listener);
+	}
+	/** Close the relay client websocket and reject any in-flight commands. */
+	close() {
+		this.ws?.close();
+		this.ws = null;
+		for (const waiter of this.pending.values()) waiter.reject(/* @__PURE__ */ new Error("Chii relay connection closed."));
+		this.pending.clear();
+	}
+};
+//#endregion
+//#region src/mcp/chii-relay.ts
+/**
+* Boots the local Chii relay server.
+*
+* Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome
+* WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.
+* The relay accepts a `target` websocket from the phone's injected `target.js`
+* and `client` websockets from CDP frontends (our MCP connection).
+*
+* Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app
+* entries.
+*/
+const require = createRequire(import.meta.url);
+function loadChiiServer() {
+	const mod = require("chii");
+	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
+	throw new Error("chii server module did not expose start()");
+}
+/** Starts the Chii relay on the given port and resolves once listening. */
+async function startChiiRelay(options = {}) {
+	const port = options.port ?? 9100;
+	const host = options.host ?? "127.0.0.1";
+	const httpServer = createServer();
+	await loadChiiServer().start({
+		server: httpServer,
+		domain: `${host}:${port}`,
+		port
+	});
+	await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(port, host, () => {
+			httpServer.off("error", reject);
+			resolve();
+		});
+	});
+	return {
+		port,
+		baseUrl: `http://${host}:${port}`,
+		close: () => new Promise((resolve) => {
+			httpServer.close(() => resolve());
+		})
+	};
+}
+//#endregion
+//#region src/mcp/tools.ts
+/** Static MCP tool descriptors (name + JSONSchema) for the Phase 1 surface. */
+const DEBUG_TOOL_DEFINITIONS = [
+	{
+		name: "list_console_messages",
+		description: "Lists recent console messages (console.log/warn/error/info) captured from the attached mini-app page over CDP (Runtime.consoleAPICalled). Read-only. Returns level, text, timestamp, and stringified args, oldest-first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "list_network_requests",
+		description: "Lists recent network requests (XHR/fetch) captured from the attached mini-app page over CDP (Network.requestWillBeSent + Network.responseReceived). Read-only. Returns url, method, status, and timing, oldest-first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "list_pages",
+		description: "Lists the mini-app page(s) the Chii relay currently sees attached, plus whether the cloudflared tunnel is up and the public wss relay URL the phone uses to attach. Call this first to confirm a page is attached before reading console/network.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "get_dom_document",
+		description: "Returns the DOM tree of the attached mini-app page over CDP (DOM.getDocument). Read-only. Use for structural/layout regression diagnosis (e.g. confirming an element exists, inspecting attributes). Returns the document root node with children.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "take_snapshot",
+		description: "Captures a serialized snapshot of the attached page over CDP (DOMSnapshot.captureSnapshot). Read-only. Returns the documents + interned strings table for visual-regression diagnosis (e.g. checking computed CSS custom properties like --sat against the live layout).",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "take_screenshot",
+		description: "Captures a PNG screenshot of the attached mini-app page over CDP (Page.captureScreenshot) so the agent can see the phone screen directly. Read-only. Returns an image content block.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "AIT.getSdkCallHistory",
+		description: "Returns the recent Apps In Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "AIT.getMockState",
+		description: "Returns the devtools mock state snapshot (window.__ait) — environment, permissions, location, auth, network, IAP, and more. Read-only. In dev mode this is the live browser mock state; in debug mode the in-app side reports it over the AIT domain.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "AIT.getOperationalEnvironment",
+		description: "Returns getOperationalEnvironment() plus the resolved SDK version — metadata raw CDP cannot observe. Read-only.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	}
+];
+const DEBUG_TOOL_NAMES = new Set(DEBUG_TOOL_DEFINITIONS.map((t) => t.name));
+function isDebugToolName(name) {
+	return DEBUG_TOOL_NAMES.has(name);
+}
+/** Renders a CDP `RemoteObject` console arg to a stable display string. */
+function renderRemoteObject(arg) {
+	if (arg.value !== void 0) {
+		if (typeof arg.value === "string") return arg.value;
+		try {
+			return JSON.stringify(arg.value);
+		} catch {
+			return String(arg.value);
+		}
+	}
+	if (arg.description !== void 0) return arg.description;
+	if (arg.className !== void 0) return arg.className;
+	return arg.subtype ?? arg.type;
+}
+function normalizeConsoleMessage(event) {
+	const args = event.args.map(renderRemoteObject);
+	return {
+		level: event.type,
+		text: args.join(" "),
+		timestamp: event.timestamp,
+		args
+	};
+}
+function listConsoleMessages(connection) {
+	return connection.getBufferedEvents("Runtime.consoleAPICalled").map((event) => normalizeConsoleMessage(event));
+}
+function listNetworkRequests(connection) {
+	const requests = connection.getBufferedEvents("Network.requestWillBeSent");
+	const responses = connection.getBufferedEvents("Network.responseReceived");
+	const responseByRequestId = /* @__PURE__ */ new Map();
+	for (const response of responses) responseByRequestId.set(response.requestId, response);
+	return requests.map((request) => {
+		const response = responseByRequestId.get(request.requestId);
+		return {
+			requestId: request.requestId,
+			url: request.request.url,
+			method: request.request.method,
+			status: response ? response.response.status : null,
+			statusText: response ? response.response.statusText : null,
+			startTime: request.timestamp,
+			endTime: response ? response.timestamp : null
+		};
+	});
+}
+function listPages(connection, tunnel) {
+	return {
+		pages: connection.listTargets(),
+		tunnel
+	};
+}
+/** Returns the DOM tree of the attached page (`DOM.getDocument`). */
+function getDomDocument(connection) {
+	return connection.send("DOM.getDocument", {
+		depth: -1,
+		pierce: true
+	});
+}
+/** Returns a serialized page snapshot (`DOMSnapshot.captureSnapshot`). */
+function takeSnapshot(connection) {
+	return connection.send("DOMSnapshot.captureSnapshot", {});
+}
+/** Captures a PNG screenshot of the attached page (`Page.captureScreenshot`). */
+async function takeScreenshot(connection) {
+	const { data } = await connection.send("Page.captureScreenshot", { format: "png" });
+	return {
+		data,
+		dataUri: `data:image/png;base64,${data}`,
+		mimeType: "image/png"
+	};
+}
+/** Set of tool names served by the AIT source rather than the CDP connection. */
+const AIT_TOOL_NAMES = new Set([
+	"AIT.getSdkCallHistory",
+	"AIT.getMockState",
+	"AIT.getOperationalEnvironment"
+]);
+/** True for the Phase 3 AIT.* tools (served by an `AitSource`, not CDP). */
+function isAitToolName(name) {
+	return AIT_TOOL_NAMES.has(name);
+}
+/** Returns the recent SDK call trace (`AIT.getSdkCallHistory`). */
+function getSdkCallHistory(source) {
+	return source.get("AIT.getSdkCallHistory");
+}
+/** Returns the devtools mock-state snapshot (`AIT.getMockState`). */
+function getMockState(source) {
+	return source.get("AIT.getMockState");
+}
+/** Returns the operational environment + SDK version (`AIT.getOperationalEnvironment`). */
+function getOperationalEnvironment(source) {
+	return source.get("AIT.getOperationalEnvironment");
+}
+//#endregion
+//#region src/mcp/tunnel.ts
+/**
+* cloudflared quick tunnel + attach banner for the debug-mode MCP server.
+*
+* On spawn, the debug server opens an accountless `*.trycloudflare.com` quick
+* tunnel to the local Chii relay so the phone can attach over a public wss URL,
+* then prints that URL + a secret token + an ASCII QR to the terminal. The
+* phone scans the QR (or pastes the URL) to attach; the in-app side passes the
+* token back. Phase 1 only generates + displays the token and makes it
+* available — full ACL enforcement is a later phase.
+*
+* Node-only: spawns the cloudflared binary and writes to stdout/stderr.
+*/
+/** Generates a 32-byte hex secret token used to gate attach. */
+function generateAttachToken() {
+	return randomBytes(32).toString("hex");
+}
+/** Ensures the cloudflared binary is installed (downloads + caches on first run). */
+async function ensureCloudflaredBin() {
+	const { existsSync } = await import("node:fs");
+	if (!existsSync(bin)) await install(bin);
+}
+/**
+* Opens a cloudflared quick tunnel to the local relay port and resolves once
+* the public URL is assigned.
+*/
+async function startQuickTunnel(localPort) {
+	await ensureCloudflaredBin();
+	const tunnel = Tunnel.quick(`http://127.0.0.1:${localPort}`);
+	const url = await new Promise((resolve, reject) => {
+		const onUrl = (assigned) => {
+			cleanup();
+			resolve(assigned);
+		};
+		const onError = (err) => {
+			cleanup();
+			reject(err);
+		};
+		const onExit = (code) => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`cloudflared exited before assigning a URL (code ${code})`));
+		};
+		const cleanup = () => {
+			tunnel.off("url", onUrl);
+			tunnel.off("error", onError);
+			tunnel.off("exit", onExit);
+		};
+		tunnel.once("url", onUrl);
+		tunnel.once("error", onError);
+		tunnel.once("exit", onExit);
+	});
+	return {
+		url,
+		wssUrl: url.replace(/^https/, "wss"),
+		stop: () => {
+			tunnel.stop();
+		}
+	};
+}
+/** Renders the attach banner (URL + token + ASCII QR) as a string. */
+async function renderAttachBanner(input) {
+	const payload = `${input.wssUrl}?token=${input.token}`;
+	const qr = await new Promise((resolve) => {
+		qrcode.generate(payload, { small: true }, (rendered) => resolve(rendered));
+	});
+	return [
+		"",
+		"AIT debug — attach a mini-app to this session",
+		"",
+		`  relay (wss): ${input.wssUrl}`,
+		`  token:       ${input.token}`,
+		"",
+		"  Open the dogfood mini-app with ?debug=1, then scan the QR",
+		"  (or paste the relay URL + token in the in-app attach form):",
+		"",
+		qr
+	].join("\n");
+}
+/** Prints the attach banner to stderr (stdout is the MCP stdio channel). */
+async function printAttachBanner(input) {
+	const banner = await renderAttachBanner(input);
+	process.stderr.write(`${banner}\n`);
+}
+//#endregion
+//#region src/mcp/debug-server.ts
+/**
+* @ait-co/devtools debug-mode MCP server (stdio) — Phase 1–3.
+*
+* Lets an AI coding agent attach to a running mini-app (real Toss WebView, or a
+* browser in dev mode) and read its console/network/DOM/screenshot over CDP plus
+* the AIT.* domain, without a human watching a phone. Transport is CDP-via-Chii:
+* a local Chii relay :9100 exposed through a cloudflared quick tunnel; the phone
+* attaches over the public wss URL.
+*
+*   AI host  --stdio-->  this server  --CDP client WS-->  Chii relay :9100
+*                                                          ^-- target WS -- phone
+*
+* The tool layer reads from an injectable `CdpConnection` (CDP) and `AitSource`
+* (AIT.*), so every tool is unit-testable with a fake (no phone). This module
+* wires the live pieces (relay + tunnel + production connection); the phone
+* roundtrip itself is phone-gated and deferred.
+*
+* Node-only.
+*/
+/**
+* Builds the debug-mode MCP server around an injected CDP connection + AIT
+* source + tunnel status getter. Pure wiring — does not start a relay or
+* tunnel, which is what makes the tool surface unit-testable.
+*/
+function createDebugServer(deps) {
+	const { connection, aitSource, getTunnelStatus } = deps;
+	const server = new Server({
+		name: "ait-debug",
+		version: "0.1.23"
+	}, { capabilities: { tools: {} } });
+	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const name = request.params.name;
+		if (!isDebugToolName(name)) return {
+			content: [{
+				type: "text",
+				text: `Unknown tool: ${name}`
+			}],
+			isError: true
+		};
+		if (isAitToolName(name)) try {
+			await connection.enableDomains();
+			switch (name) {
+				case "AIT.getSdkCallHistory": return jsonResult$1(await getSdkCallHistory(aitSource));
+				case "AIT.getMockState": return jsonResult$1(await getMockState(aitSource));
+				case "AIT.getOperationalEnvironment": return jsonResult$1(await getOperationalEnvironment(aitSource));
+				default: return unknownTool(name);
+			}
+		} catch (err) {
+			return errorResult(err, name);
+		}
+		try {
+			await connection.enableDomains();
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (name === "list_pages") return jsonResult$1(listPages(connection, getTunnelStatus()));
+			return {
+				content: [{
+					type: "text",
+					text: `${message}\nCall list_pages to confirm a mini-app has attached over the relay.`
+				}],
+				isError: true
+			};
+		}
+		try {
+			switch (name) {
+				case "list_console_messages": return jsonResult$1(listConsoleMessages(connection));
+				case "list_network_requests": return jsonResult$1(listNetworkRequests(connection));
+				case "list_pages": return jsonResult$1(listPages(connection, getTunnelStatus()));
+				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
+				case "take_snapshot": return jsonResult$1(await takeSnapshot(connection));
+				case "take_screenshot": {
+					const shot = await takeScreenshot(connection);
+					return { content: [{
+						type: "image",
+						data: shot.data,
+						mimeType: shot.mimeType
+					}] };
+				}
+				default: return unknownTool(name);
+			}
+		} catch (err) {
+			return errorResult(err, name);
+		}
+	});
+	return server;
+}
+function jsonResult$1(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}] };
+}
+function unknownTool(name) {
+	return {
+		content: [{
+			type: "text",
+			text: `Unknown tool: ${name}`
+		}],
+		isError: true
+	};
+}
+function errorResult(err, name) {
+	return {
+		content: [{
+			type: "text",
+			text: `${name} failed: ${err instanceof Error ? err.message : String(err)}\nCall list_pages to confirm a mini-app has attached over the relay.`
+		}],
+		isError: true
+	};
+}
+/**
+* Boots the live debug stack and serves it over stdio:
+*   1. start the Chii relay,
+*   2. open a cloudflared quick tunnel to it,
+*   3. print QR + secret token,
+*   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
+*/
+async function runDebugServer(options = {}) {
+	const relayPort = options.relayPort ?? 9100;
+	const relay = await startChiiRelay({ port: relayPort });
+	let tunnel = null;
+	let tunnelStatus = {
+		up: false,
+		wssUrl: null
+	};
+	const token = generateAttachToken();
+	try {
+		tunnel = await startQuickTunnel(relayPort);
+		tunnelStatus = {
+			up: true,
+			wssUrl: tunnel.wssUrl
+		};
+		await printAttachBanner({
+			wssUrl: tunnel.wssUrl,
+			token
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[ait-debug] Failed to open cloudflared quick tunnel: ${message}\n[ait-debug] The relay is up locally; attach over the public URL is unavailable until the tunnel starts.
+`);
+	}
+	const connection = new ChiiCdpConnection({ relayBaseUrl: relay.baseUrl });
+	const server = createDebugServer({
+		connection,
+		aitSource: new ChiiAitSource(connection),
+		getTunnelStatus: () => tunnelStatus
+	});
+	const transport = new StdioServerTransport();
+	const shutdown = () => {
+		connection.close();
+		tunnel?.stop();
+		relay.close();
+		server.close();
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	await server.connect(transport);
+}
+//#endregion
+//#region src/mcp/ait-http-source.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+var HttpAitSource = class {
+	stateEndpoint;
+	fetchImpl;
+	constructor(options) {
+		this.stateEndpoint = options.stateEndpoint;
+		this.fetchImpl = options.fetchImpl ?? ((url) => fetch(url));
+	}
+	async fetchState() {
+		const res = await this.fetchImpl(this.stateEndpoint);
+		if (!res.ok) throw new Error(`Failed to fetch mock state from ${this.stateEndpoint}: HTTP ${res.status} ${res.statusText}. Ensure the Vite dev server is running with the @ait-co/devtools unplugin option \`mcp: true\`.`);
+		const body = await res.json();
+		return isObject(body) ? body : {};
+	}
+	async get(method) {
+		switch (method) {
+			case "AIT.getMockState": return await this.fetchState();
+			case "AIT.getOperationalEnvironment": {
+				const state = await this.fetchState();
+				return {
+					environment: typeof state.environment === "string" ? state.environment : "unknown",
+					sdkVersion: typeof state.appVersion === "string" ? state.appVersion : null
+				};
+			}
+			case "AIT.getSdkCallHistory": return { calls: [] };
+			default: throw new Error(`Unknown AIT method: ${String(method)}`);
+		}
+	}
+};
+//#endregion
+//#region src/mcp/server.ts
+/**
+* @ait-co/devtools dev-mode MCP server (stdio).
+*
+* Exposes the live browser mock state from a running Vite dev server to AI
+* coding agents via the Model Context Protocol (MCP).
+*
+* Architecture:
+*   Browser (aitState) → Vite dev server endpoint (/api/ait-devtools/state)
+*                      ← HTTP GET ← this stdio MCP server ← AI agent
+*
+* The Vite endpoint is registered by the unplugin when `mcp: true` is set in
+* the plugin options (see `src/unplugin/index.ts`).
+*
+* Phase 3 tool-surface alignment: dev mode and debug mode now expose the same
+* `AIT.*` tools (`AIT.getMockState`, `AIT.getOperationalEnvironment`,
+* `AIT.getSdkCallHistory`). In dev mode they are backed by the HTTP mock-state
+* endpoint (see `HttpAitSource`); in debug mode by the Chii channel. So an AI
+* sees a coherent tool whether attached to a phone (debug) or a dev browser
+* (dev). `devtools_get_mock_state` (the original devtools#130 name) is kept as a
+* backward-compatible alias of `AIT.getMockState`.
+*
+* This module is reached via the `devtools-mcp --mode=dev` CLI entry (see
+* `cli.ts`); the default (no flag) bin mode is the debug-mode CDP/Chii server.
+*
+* Usage (in your MCP client config, e.g. Claude Desktop):
+*   {
+*     "mcpServers": {
+*       "ait-devtools": {
+*         "command": "pnpm",
+*         "args": ["exec", "devtools-mcp", "--mode=dev"],
+*         "env": { "AIT_DEVTOOLS_URL": "http://localhost:5173" }
+*       }
+*     }
+*   }
+*/
+/** Tool descriptors served by the dev-mode server. */
+const DEV_TOOL_DEFINITIONS = [
+	{
+		name: "AIT.getMockState",
+		description: "Returns the devtools mock state snapshot (window.__ait) from the running browser session — environment, permissions, location, auth, network, IAP, and more. Read-only. Requires the Vite dev server running with the @ait-co/devtools unplugin option `mcp: true`. Same tool as in debug mode, where the in-app side reports it over the AIT domain.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "AIT.getOperationalEnvironment",
+		description: "Returns the operational environment + SDK/app version derived from the dev mock state. Read-only.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "AIT.getSdkCallHistory",
+		description: "Returns the SDK call trace. In dev mode the HTTP mock-state endpoint records no trace, so this returns an empty list; in debug mode it is populated over the AIT domain. Read-only.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
+	{
+		name: "devtools_get_mock_state",
+		description: "Backward-compatible alias of AIT.getMockState (the original devtools#130 name). Returns the current AIT DevTools mock state snapshot. Read-only. Prefer AIT.getMockState in new configs.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	}
+];
+const DEV_TOOL_NAMES = new Set(DEV_TOOL_DEFINITIONS.map((t) => t.name));
+/** Builds the dev-mode MCP server (does not connect a transport). */
+function createDevServer(deps = {}) {
+	const stateEndpoint = `${process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"}/api/ait-devtools/state`;
+	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
+	const server = new Server({
+		name: "ait-devtools",
+		version: "0.1.23"
+	}, { capabilities: { tools: {} } });
+	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const name = request.params.name;
+		if (!DEV_TOOL_NAMES.has(name)) return {
+			content: [{
+				type: "text",
+				text: `Unknown tool: ${name}`
+			}],
+			isError: true
+		};
+		try {
+			const effective = name === "devtools_get_mock_state" ? "AIT.getMockState" : name;
+			if (!isAitToolName(effective)) return {
+				content: [{
+					type: "text",
+					text: `Unknown tool: ${name}`
+				}],
+				isError: true
+			};
+			switch (effective) {
+				case "AIT.getMockState": return jsonResult(await getMockState(aitSource));
+				case "AIT.getOperationalEnvironment": return jsonResult(await getOperationalEnvironment(aitSource));
+				case "AIT.getSdkCallHistory": return jsonResult(await getSdkCallHistory(aitSource));
+				default: return {
+					content: [{
+						type: "text",
+						text: `Unknown tool: ${name}`
+					}],
+					isError: true
+				};
+			}
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: `${err instanceof Error ? err.message : String(err)}\nIs the Vite dev server running with the @ait-co/devtools unplugin option \`mcp: true\`? Is AIT_DEVTOOLS_URL set correctly?`
+				}],
+				isError: true
+			};
+		}
+	});
+	return server;
+}
+function jsonResult(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}] };
+}
+/** Builds the dev-mode server and connects it over stdio. */
+async function runDevServer() {
+	const server = createDevServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+//#endregion
+//#region src/mcp/cli.ts
+/**
+* `devtools-mcp` bin entry.
+*
+* Single bin, two transports selected by `--mode`:
+*   - (default, no flag) debug mode — CDP/Chii relay + cloudflared quick tunnel.
+*     Attach a running mini-app (real Toss WebView or a browser) and read its
+*     console + network over CDP without a human watching a phone.
+*   - `--mode=dev` — dev mode — reads the live browser mock state from a running
+*     Vite dev server (the devtools#130 `devtools_get_mock_state` surface).
+*
+* Node-only stdio process.
+*/
+/** Parses `--mode=<value>` / `--mode <value>` from argv; default `debug`. */
+function parseMode(argv) {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === void 0) continue;
+		if (arg.startsWith("--mode=")) return normalizeMode(arg.slice(7));
+		if (arg === "--mode") {
+			const next = argv[i + 1];
+			if (next === void 0) throw new Error("--mode requires a value: 'debug' (default) or 'dev'.");
+			return normalizeMode(next);
+		}
+	}
+	return "debug";
+}
+function normalizeMode(value) {
+	if (value === "dev") return "dev";
+	if (value === "debug") return "debug";
+	throw new Error(`Unknown --mode '${value}'. Expected 'debug' (default) or 'dev'.`);
+}
+async function main() {
+	if (parseMode(process.argv.slice(2)) === "dev") await runDevServer();
+	else await runDebugServer();
+}
+/** True when this file is the process entry (the bin), not an import. */
+function isEntrypoint() {
+	const entry = argv[1];
+	if (entry === void 0) return false;
+	try {
+		return fileURLToPath(import.meta.url) === entry;
+	} catch {
+		return false;
+	}
+}
+if (isEntrypoint()) main().catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`[devtools-mcp] fatal: ${message}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export { parseMode };
+
+//# sourceMappingURL=cli.js.map