@ait-co/devtools 0.1.45 → 0.1.48

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../../src/mcp/ait-source.ts","../../src/mcp/server.ts"],"mappings":";;;;;;;AAsBA;;;;;AAGA;;;;;;;;;;;;;KAHY,kBAAA;AAqBZ;AAAA,UAlBiB,UAAA;;EAEf,MAAA;EAiBiB;EAfjB,IAAA;EAwBsB;EAtBtB,SAAA;EAsByB;EApBzB,MAAA;EAuBe;EArBf,MAAA;;EAEA,KAAA;EAuBU;EArBV,QAAA,EAAU,kBAAA;AAAA;;UAIK,iBAAA;EACf,KAAA,EAAO,UAAA;AAAA;;;;;;;KASG,YAAA,GAAe,MAAA;;UAGV,yBAAA;EAW2C;EAT1D,WAAA;EAYuB;EAVvB,UAAA;AAAA;;UAIe,YAAA;EACf,uBAAA,EAAyB,iBAAA;EACzB,kBAAA,EAAoB,YAAA;EACpB,+BAAA,EAAiC,yBAAA;AAAA;AAAA,KAGvB,aAAA,SAAsB,YAAA;;;;;UAMjB,SAAA;EACf,GAAA,WAAc,aAAA,EAAe,MAAA,EAAQ,CAAA,GAAI,OAAA,CAAQ,YAAA,CAAa,CAAA;AAAA;;;UCkN/C,mBAAA;EDnNS;ECqNxB,SAAA,GAAY,SAAA;AAAA;;iBA8IE,eAAA,CAAgB,IAAA,GAAM,mBAAA,GAA2B,MAAA;;iBAuF3C,YAAA,CAAA,GAAgB,OAAA"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../../src/mcp/ait-source.ts","../../src/mcp/server.ts"],"mappings":";;;;;;;AAsBA;;;;;AAGA;;;;;;;;;;;;;KAHY,kBAAA;AAqBZ;AAAA,UAlBiB,UAAA;;EAEf,MAAA;EAiBiB;EAfjB,IAAA;EAwBsB;EAtBtB,SAAA;EAsByB;EApBzB,MAAA;EAuBe;EArBf,MAAA;;EAEA,KAAA;EAuBU;EArBV,QAAA,EAAU,kBAAA;AAAA;;UAIK,iBAAA;EACf,KAAA,EAAO,UAAA;AAAA;;;;;;;KASG,YAAA,GAAe,MAAA;;UAGV,yBAAA;EAW2C;EAT1D,WAAA;EAYuB;EAVvB,UAAA;AAAA;;UAIe,YAAA;EACf,uBAAA,EAAyB,iBAAA;EACzB,kBAAA,EAAoB,YAAA;EACpB,+BAAA,EAAiC,yBAAA;AAAA;AAAA,KAGvB,aAAA,SAAsB,YAAA;;;;;UAMjB,SAAA;EACf,GAAA,WAAc,aAAA,EAAe,MAAA,EAAQ,CAAA,GAAI,OAAA,CAAQ,YAAA,CAAa,CAAA;AAAA;;;UC6P/C,mBAAA;ED9PS;ECgQxB,SAAA,GAAY,SAAA;AAAA;;iBA8IE,eAAA,CAAgB,IAAA,GAAM,mBAAA,GAA2B,MAAA;;iBAqH3C,YAAA,CAAA,GAAgB,OAAA"}

package/dist/mcp/server.js

@@ -38,6 +38,51 @@ var HttpAitSource = class {
 	}
 };
 //#endregion
+//#region src/mcp/envelope.ts
+/**
+* Returns `true` when `AIT_MCP_COMPAT=chrome-devtools` is set, which bypasses
+* envelope wrapping and returns raw payloads (0.1.x back-compat).
+*/
+function isCompatMode() {
+	return process.env.AIT_MCP_COMPAT === "chrome-devtools";
+}
+/**
+* Maps `McpEnvironment` to `EnvelopeEnv`. After #307 these are the same
+* union (`mock | relay-dev | relay-live`), so this is identity — kept as a
+* named export for surface stability if envelope env diverges in the future.
+*/
+function toEnvelopeEnv(env) {
+	return env;
+}
+/**
+* Wraps `data` in a `ToolEnvelope<T>` **unless** compat mode is active, in
+* which case `data` is returned as-is.
+*
+* Use this at every tool call-site in `debug-server.ts` and `server.ts`.
+*
+* @example
+* ```ts
+* return jsonResult(wrapEnvelope(listPages(connection, tunnel), {
+*   tool: 'list_pages',
+*   env: resolveEnvironment(),
+*   attached: connection.listTargets().length > 0,
+* }));
+* ```
+*/
+function wrapEnvelope(data, ctx) {
+	if (isCompatMode()) return data;
+	return {
+		ok: true,
+		data,
+		meta: {
+			tool: ctx.tool,
+			env: toEnvelopeEnv(ctx.env),
+			attached: ctx.attached,
+			contentType: ctx.contentType ?? "json"
+		}
+	};
+}
+//#endregion
 //#region src/mcp/errors.ts
 /**
 * 한국어 한 줄 "원인 + 다음 행동" 포맷으로 에러 결과를 빌드한다.
@@ -53,6 +98,17 @@ function mcpError(message) {
 		isError: true
 	};
 }
+/**
+* Tier A/B 환경 불일치 거부 메시지.
+*
+* @param toolName    - 거부된 tool 이름.
+* @param requiredEnv - 해당 tool이 요구하는 환경 ('mock' | 'relay').
+* @param currentEnv  - 현재 세션 환경.
+* @param reason      - 환경이 결정된 근거 (EnvironmentReason 문자열).
+*/
+function tierRejectionError(toolName, requiredEnv, currentEnv, reason) {
+	return mcpError(`${`${toolName}은 ${requiredEnv === "relay" ? "relay (실기기 연결)" : "mock (로컬 브라우저)"} 환경에서만 사용할 수 있습니다. 현재 환경: ${currentEnv === "relay" ? "relay" : "mock"} (${reason}). ${requiredEnv === "relay" ? "relay로 전환하려면 MCP_ENV=relay 설정 후 서버를 재시작하고 build_attach_url → QR 스캔으로 실기기를 attach하세요." : "mock으로 전환하려면 MCP_ENV=mock 설정 후 서버를 재시작하세요."}`}\n\n${`tool ${toolName} is available only in ${requiredEnv}. Current environment is ${currentEnv} (${reason}).`}`);
+}
 //#endregion
 //#region src/mcp/sdk-signatures.ts
 function isObject(v) {
@@ -224,7 +280,7 @@ new Set([
 	},
 	{
 		name: "build_attach_url",
-		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). Requires MCP_ENV=relay (set automatically when a relay tunnel is detected).",
+		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). Requires MCP_ENV=relay-dev or relay-live (set automatically in debug-mode default).\n\nTOTP auth: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the returned attachUrl automatically includes the current one-time code (at=<code>) — the URL is single-use for that 30-second step. The response includes a `totp` field with `expiresAt` (ISO timestamp). If the phone scan happens after expiresAt, the relay will reject the code — just call build_attach_url again to get a fresh one-time URL. Without AIT_DEBUG_TOTP_SECRET, the attachUrl has no expiry.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -277,7 +333,7 @@ new Set([
 	},
 	{
 		name: "measure_safe_area",
-		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Tier C per RFC #277: the same Runtime.evaluate probe runs in both `mock` (devtools panel page with window.__ait state) and `relay` (real-device WebView with window.__sdk). The result includes a `source: \"mock\" | \"relay\"` field so consumers can identify provenance without inspecting payload values. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires a page to be attached — call list_pages first.",
+		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Tier C per RFC #277: the same Runtime.evaluate probe runs in both `mock` (devtools panel page with window.__ait state) and `relay` (real-device WebView with window.__sdk). The result includes a `source: \"mock\" | \"relay-dev\" | \"relay-live\"` field so consumers can identify provenance without inspecting payload values. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires a page to be attached — call list_pages first.",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -319,7 +375,7 @@ new Set([
 	},
 	{
 		name: "call_sdk",
-		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 2/3 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. If a Runtime.exceptionThrown event was observed within [callStart-50ms, callEnd+200ms], the result also includes `recentException` for crash triage. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle) — redeploy via dogfood channel: `ait build && aitcc app deploy`.\n\nSECURITY: method name, args, and result value are not redacted — never include secrets.\n\nLIVE guard: when running against a live/production relay (relay-live env, MCP_ENV=relay-live), this tool requires `confirm: true` to acknowledge that the SDK call may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.\n\nIMPORTANT — 인자 시그니처 (잘못된 인자로 호출하면 토스 앱 crash 위험):\n  setDeviceOrientation:        call_sdk(\"setDeviceOrientation\", [{ type: \"landscape\" }])  // NOT \"landscape\"\n  setIosSwipeGestureEnabled:   call_sdk(\"setIosSwipeGestureEnabled\", [{ isEnabled: false }])\n  setSecureScreen:             call_sdk(\"setSecureScreen\", [{ enabled: true }])\n  setScreenAwakeMode:          call_sdk(\"setScreenAwakeMode\", [{ enabled: true }])\n  getOperationalEnvironment:   call_sdk(\"getOperationalEnvironment\", [])\n  getPlatformOS:               call_sdk(\"getPlatformOS\", [])\n  getDeviceId:                 call_sdk(\"getDeviceId\", [])\n  getLocale:                   call_sdk(\"getLocale\", [])\n  getNetworkStatus:            call_sdk(\"getNetworkStatus\", [])\n  getSchemeUri:                call_sdk(\"getSchemeUri\", [])\n  requestReview:               call_sdk(\"requestReview\", [])\n  closeView:                   call_sdk(\"closeView\", [])",
+		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 3/4 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. (env 2 PWA does not inject the SDK — call_sdk is not available there.) Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. If a Runtime.exceptionThrown event was observed within [callStart-50ms, callEnd+200ms], the result also includes `recentException` for crash triage. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle) — redeploy via dogfood channel: `ait build && aitcc app deploy`.\n\nSECURITY: method name, args, and result value are not redacted — never include secrets.\n\nLIVE guard: when running against a live/production relay (relay-live env, MCP_ENV=relay-live), this tool requires `confirm: true` to acknowledge that the SDK call may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.\n\nIMPORTANT — 인자 시그니처 (잘못된 인자로 호출하면 토스 앱 crash 위험):\n  setDeviceOrientation:        call_sdk(\"setDeviceOrientation\", [{ type: \"landscape\" }])  // NOT \"landscape\"\n  setIosSwipeGestureEnabled:   call_sdk(\"setIosSwipeGestureEnabled\", [{ isEnabled: false }])\n  setSecureScreen:             call_sdk(\"setSecureScreen\", [{ enabled: true }])\n  setScreenAwakeMode:          call_sdk(\"setScreenAwakeMode\", [{ enabled: true }])\n  getOperationalEnvironment:   call_sdk(\"getOperationalEnvironment\", [])\n  getPlatformOS:               call_sdk(\"getPlatformOS\", [])\n  getDeviceId:                 call_sdk(\"getDeviceId\", [])\n  getLocale:                   call_sdk(\"getLocale\", [])\n  getNetworkStatus:            call_sdk(\"getNetworkStatus\", [])\n  getSchemeUri:                call_sdk(\"getSchemeUri\", [])\n  requestReview:               call_sdk(\"requestReview\", [])\n  closeView:                   call_sdk(\"closeView\", [])",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -373,7 +429,7 @@ new Set([
 	},
 	{
 		name: "get_diagnostics",
-		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (kind: mock|relay-dev|relay-live, env: mock|relay backward-compat, reason, liveGuardActive: true when relay-live LIVE guard is active), serverLockHolder (pid + startedAt from the lock file, or null), nextRecommendedAction ({tool, reason} or null — the single next tool to call). All fields are nullable — missing data is null, not an error. debug-mode only — dev-mode (--mode=dev) does not support relay diagnostics. Tier C (both mock and relay). Call this first when debugging session state.",
+		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (kind: mock|relay-dev|relay-live, env: mock|relay backward-compat, reason, liveGuardActive: true when relay-live LIVE guard is active), serverLockHolder (pid + startedAt from the lock file, or null), nextRecommendedAction ({tool, reason} or null — the single next tool to call; in local-target mode tunnel.up=false is normal so \"restart\" is never recommended). All fields are nullable — missing data is null, not an error. debug-mode only — dev-mode (--mode=dev) does not support relay diagnostics. Tier C (both mock and relay). Call this first when debugging session state.",
 		inputSchema: {
 			type: "object",
 			properties: { recent_errors_limit: {
@@ -640,6 +696,29 @@ const DEV_TOOL_DEFINITIONS = [
 		},
 		availableIn: "both"
 	},
+	{
+		name: "build_attach_url",
+		description: "Turns an `ait deploy --scheme-only` URL into a self-attaching deep link for a real device. NOT available in dev-mode — requires a live cloudflared relay (Tier B, relay-only). To use this tool: restart the MCP server with `--mode=debug` (or omit --mode) and set MCP_ENV=relay, then call build_attach_url to generate the QR for phone scanning. See: https://docs.aitc.dev/guides/debug-relay",
+		inputSchema: {
+			type: "object",
+			properties: {
+				scheme_url: {
+					type: "string",
+					description: "The intoss-private:// URL from `ait deploy --scheme-only`."
+				},
+				wait_for_attach: {
+					type: "boolean",
+					description: "If true, block until a page attaches."
+				},
+				open_in_browser: {
+					type: "boolean",
+					description: "If true (default), open the QR PNG in the OS browser."
+				}
+			},
+			required: ["scheme_url"]
+		},
+		availableIn: "relay"
+	},
 	{
 		name: "evaluate",
 		description: "Evaluates an arbitrary JavaScript expression via CDP Runtime.evaluate. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug` for CDP access.",
@@ -730,6 +809,12 @@ const CDP_ONLY_TOOL_NAMES = new Set([
 	"list_exceptions"
 ]);
 /**
+* Tier B tools — relay-only per RFC #277.
+* Listed in dev-mode tool surface (issue #323) so agents get a hand-off hint
+* toward `--mode=debug` instead of "Unknown tool".
+*/
+const TIER_B_TOOL_NAMES = new Set(["build_attach_url"]);
+/**
 * Builds the `list_pages` dev-mode shim response.
 * Returns the Vite dev URL as a single-entry page list with `devMode: true`.
 */
@@ -844,13 +929,14 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.45"
+		version: "0.1.48"
 	}, { 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 mcpError(`알 수 없는 tool: ${name}`);
 		if (CDP_ONLY_TOOL_NAMES.has(name)) return mcpError(`${name}: ${CDP_UNAVAILABLE_IN_DEV_MODE}`);
+		if (TIER_B_TOOL_NAMES.has(name)) return tierRejectionError(name, "relay", "mock", "dev-mode — Vite HTTP endpoint, no CDP/relay connection. `--mode=debug` (または `devtools-mcp` without --mode) + MCP_ENV=relay로 재시작하세요.");
 		try {
 			const effective = name === "devtools_get_mock_state" ? "AIT.getMockState" : name;
 			if (isAitToolName(effective)) switch (effective) {
@@ -860,13 +946,13 @@ function createDevServer(deps = {}) {
 				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
 			switch (name) {
-				case "list_pages": return jsonResult(buildDevListPagesResult(devtoolsUrl));
-				case "get_diagnostics": return jsonResult(await buildDevDiagnostics(devtoolsUrl, stateEndpoint, (url) => fetch(url)));
-				case "measure_safe_area": return jsonResult(await buildDevMeasureSafeArea(aitSource));
+				case "list_pages": return envelopeResult("list_pages", buildDevListPagesResult(devtoolsUrl));
+				case "get_diagnostics": return envelopeResult("get_diagnostics", await buildDevDiagnostics(devtoolsUrl, stateEndpoint, (url) => fetch(url)));
+				case "measure_safe_area": return envelopeResult("measure_safe_area", await buildDevMeasureSafeArea(aitSource));
 				case "call_sdk": {
 					const sdkName = request.params.arguments?.name;
 					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 메서드 이름을 전달하세요.");
-					return jsonResult(await buildDevCallSdk(sdkName, aitSource));
+					return envelopeResult("call_sdk", await buildDevCallSdk(sdkName, aitSource));
 				}
 				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
@@ -882,6 +968,26 @@ function jsonResult(value) {
 		text: JSON.stringify(value, null, 2)
 	}] };
 }
+/**
+* Wraps `value` in a `ToolEnvelope` (when compat mode is off) and returns it
+* as a text content block. In dev-mode `env` is always `'mock'` and
+* `attached` is always `true` (the Vite dev server is the single implicit
+* "attached" page).
+*
+* When `AIT_MCP_COMPAT=chrome-devtools` the envelope is skipped and the raw
+* value is returned — identical to `jsonResult` (0.1.x back-compat).
+*/
+function envelopeResult(tool, value) {
+	const wrapped = wrapEnvelope(value, {
+		tool,
+		env: "mock",
+		attached: true
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(wrapped, null, 2)
+	}] };
+}
 /** Builds the dev-mode server and connects it over stdio. */
 async function runDevServer() {
 	const server = createDevServer();