@ait-co/devtools 0.1.43 → 0.1.45

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;;;UCkB/C,mBAAA;ED/BY;ECiC3B,SAAA,GAAY,SAAA;AAAA;;iBAIE,eAAA,CAAgB,IAAA,GAAM,mBAAA,GAA2B,MAAA;;iBA6D3C,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;;;UCkN/C,mBAAA;EDnNS;ECqNxB,SAAA,GAAY,SAAA;AAAA;;iBA8IE,eAAA,CAAgB,IAAA,GAAM,mBAAA,GAA2B,MAAA;;iBAuF3C,YAAA,CAAA,GAAgB,OAAA"}

package/dist/mcp/server.js

@@ -38,6 +38,22 @@ var HttpAitSource = class {
 	}
 };
 //#endregion
+//#region src/mcp/errors.ts
+/**
+* 한국어 한 줄 "원인 + 다음 행동" 포맷으로 에러 결과를 빌드한다.
+*
+* @param message - 사용자에게 보여줄 에러 본문 (원인 + 다음 행동 포함).
+*/
+function mcpError(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+//#endregion
 //#region src/mcp/sdk-signatures.ts
 function isObject(v) {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -198,7 +214,7 @@ new Set([
 	},
 	{
 		name: "list_pages",
-		description: "Returns the single active page (at most one) the relay sees attached. When a second page attaches, the previous one is evicted (last-attach wins — single-attach model). The result includes `singleAttachModel: true` so the agent knows the array is always 0 or 1 entries. Also returns whether the cloudflared tunnel is up and the public wss relay URL. Each page entry includes a `lastSeenAt` ISO timestamp (last inbound CDP message from that target — useful to detect stale entries when the phone app backgrounded). The result also includes `crashDetectedAt` (ISO timestamp or null): when non-null, a page crash was detected via Inspector.targetCrashed / Target.targetDestroyed since the last attach, the pages list will be empty, and `crashWarning` shows a Korean hint to re-attach. Call this first to confirm a page is attached before reading console/network.",
+		description: "Returns the single active page (at most one) the relay sees attached. When a second page attaches, the previous one is evicted (last-attach wins — single-attach model). The result includes `singleAttachModel: true` so the agent knows the array is always 0 or 1 entries. Also returns whether the cloudflared tunnel is up and the public wss relay URL. The `tunnel` field includes `droppedAt` (ISO timestamp or null/undefined): when non-null the tunnel has permanently dropped after 3 failed reissue attempts — restart the debug server with `npx @ait-co/devtools devtools-mcp`. Each page entry includes a `lastSeenAt` ISO timestamp (last inbound CDP message from that target — useful to detect stale entries when the phone app backgrounded). The result also includes `crashDetectedAt` (ISO timestamp or null): when non-null, a page crash was detected via Inspector.targetCrashed / Target.targetDestroyed since the last attach, the pages list will be empty, and `crashWarning` shows a Korean hint to re-attach. Call this first to confirm a page is attached before reading console/network. When a page attaches or detaches the server emits notifications/tools/list_changed — call tools/list again to get the full updated tool surface.",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -208,7 +224,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. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 90 s), then returns the attached page info too. 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).",
+		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).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -218,7 +234,7 @@ new Set([
 				},
 				wait_for_attach: {
 					type: "boolean",
-					description: "If true, block after returning the QR until a page attaches to the relay (polls listTargets ~1 s interval, timeout 90 s). On attach, the response includes the attached page list. On timeout, returns an error with a list_pages retry hint."
+					description: "If true, block after returning the QR until a page attaches to the relay (polls listTargets ~1 s interval, timeout 30 s). On attach, the response includes the attached page list. On timeout, call build_attach_url again to resume polling."
 				},
 				open_in_browser: {
 					type: "boolean",
@@ -251,7 +267,7 @@ new Set([
 	},
 	{
 		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.",
+		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 — this is the only debug tool that returns an image; all other debug tools return text (JSON).",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -271,13 +287,19 @@ new Set([
 	},
 	{
 		name: "evaluate",
-		description: "Evaluates an arbitrary JavaScript expression on the attached mini-app page via CDP Runtime.evaluate (returnByValue: true) and returns the result. NOT read-only — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires the relay to be attached — call list_pages first. Throws if the evaluation throws an exception on the page.",
+		description: "Evaluates an arbitrary JavaScript expression on the attached mini-app page via CDP Runtime.evaluate (returnByValue: true) and returns the result. NOT read-only — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires the relay to be attached — call list_pages first. Throws if the evaluation throws an exception on the page.\n\nSECURITY: expression and result are not redacted — never include secrets or auth tokens in the expression.\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 expression may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.",
 		inputSchema: {
 			type: "object",
-			properties: { expression: {
-				type: "string",
-				description: "JavaScript expression to evaluate in the page context."
-			} },
+			properties: {
+				expression: {
+					type: "string",
+					description: "JavaScript expression to evaluate in the page context."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required when MCP_ENV=relay-live. Set to `true` to explicitly acknowledge that this expression may have side effects on real/live users. Omitting this in a relay-live session results in a structured rejection error. Has no effect in mock or relay-dev sessions."
+				}
+			},
 			required: ["expression"]
 		},
 		availableIn: "both"
@@ -297,7 +319,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).\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 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\", [])",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -309,6 +331,10 @@ new Set([
 					type: "array",
 					description: "Arguments to pass to the SDK method (optional, default []).",
 					items: {}
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required when MCP_ENV=relay-live. Set to `true` to explicitly acknowledge that this SDK call may have side effects on real/live users. Omitting this in a relay-live session results in a structured rejection error. Has no effect in mock or relay-dev sessions."
 				}
 			},
 			required: ["name"]
@@ -344,6 +370,19 @@ new Set([
 			required: []
 		},
 		availableIn: "both"
+	},
+	{
+		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.",
+		inputSchema: {
+			type: "object",
+			properties: { recent_errors_limit: {
+				type: "number",
+				description: "Maximum number of recent server-side errors to include (default 10, max 50)."
+			} },
+			required: []
+		},
+		availableIn: "both"
 	}
 ].map((t) => t.name));
 `
@@ -459,6 +498,27 @@ function getOperationalEnvironment(source) {
 * (dev). `devtools_get_mock_state` (the original devtools#130 name) is kept as a
 * backward-compatible alias of `AIT.getMockState`.
 *
+* Issue #305 (M2-1) — dev/debug tool-surface unification:
+* dev-mode now also exposes `list_pages`, `get_diagnostics`, `measure_safe_area`,
+* and `call_sdk` so the docs/qa/scenarios.md acceptance sequence
+* `list_pages → measure_safe_area → call_sdk` works in dev mode without
+* "Unknown tool" failures.
+*
+* - `list_pages`       — shim: returns the Vite dev URL as a single-entry array.
+* - `get_diagnostics`  — dumps dev-mode server state (endpoint URL, last fetch
+*                        error, reachability, mode/environment metadata).
+* - `measure_safe_area`— reads safeAreaInsets from the mock state snapshot
+*                        (source: 'mock-vite').
+* - `call_sdk`         — reads mock state and builds a mock-equivalent result
+*                        using window.__ait.state for supported methods; returns
+*                        an explicit tier-filter error for methods that require
+*                        a live CDP bridge.
+* - CDP-only tools (`evaluate`, `take_screenshot`, `get_dom_document`,
+*                   `take_snapshot`, `list_console_messages`,
+*                   `list_network_requests`, `list_exceptions`) — return an
+*                   explicit tier-filter error explaining that CDP is unavailable
+*                   in dev-mode and pointing to `--mode=local` or `--mode=debug`.
+*
 * 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.
 *
@@ -473,12 +533,18 @@ function getOperationalEnvironment(source) {
 *     }
 *   }
 */
+/** Error message prefix for CDP-dependent tools called in dev-mode. */
+const CDP_UNAVAILABLE_IN_DEV_MODE = "dev-mode에서는 CDP 연결이 없어 이 도구를 사용할 수 없습니다. 실기기 또는 로컬 Chromium에 붙이려면 `devtools-mcp --mode=local` 또는 `devtools-mcp` (debug 모드 기본)로 전환하세요.";
 /**
 * Tool descriptors served by the dev-mode server.
 *
 * All dev-mode tools are Tier C (both envs) per RFC #277 — the dev-mode server
 * itself is the mock-side embodiment of those Tier C tools. `availableIn` is
 * declared so the surface stays consistent with the debug-mode registry.
+*
+* Issue #305: CDP-only tools are also listed with explicit descriptions so
+* agents do not get "Unknown tool" failures — they get a clear tier-filter
+* error message instead.
 */
 const DEV_TOOL_DEFINITIONS = [
 	{
@@ -520,56 +586,292 @@ const DEV_TOOL_DEFINITIONS = [
 			required: []
 		},
 		availableIn: "both"
+	},
+	{
+		name: "list_pages",
+		description: "dev-mode: returns the Vite dev server URL as a single-entry page list. No CDP relay is involved — `tunnel.up` is always false and `devMode: true` marks this as a shim result. Call this first to confirm the dev server is reachable. In debug mode (`devtools-mcp` / `--mode=local`) this returns real attached pages.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "get_diagnostics",
+		description: "dev-mode: returns server diagnostics — Vite endpoint URL, last fetch timestamp/error, mock state endpoint reachability, mode (\"dev\"), and environment metadata. Call this when the dev server connection is suspect. In debug mode this returns tunnel/relay/attach status instead.",
+		inputSchema: {
+			type: "object",
+			properties: { recent_errors_limit: {
+				type: "number",
+				description: "Ignored in dev-mode (no error ring buffer). Present for schema parity."
+			} },
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "measure_safe_area",
+		description: "dev-mode: reads safe-area insets from the mock state snapshot via the Vite endpoint. Returns `{ source: \"mock-vite\", sdkInsets, sdkInsetsSource: \"window.__ait\", ... }`. Values reflect what the DevTools panel reports at the time of the last state push. In debug mode this runs a Runtime.evaluate CDP probe on the attached page.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "call_sdk",
+		description: "dev-mode: calls a mock SDK method via the Vite mock state endpoint. Supported methods read from window.__ait mock state (e.g. getOperationalEnvironment). Returns the same `{ok, value}` / `{ok, error}` envelope as debug mode. In debug mode this calls the real SDK via window.__sdkCall over CDP.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: {
+					type: "string",
+					description: "Mock SDK method name to call (e.g. \"getOperationalEnvironment\")."
+				},
+				args: {
+					type: "array",
+					description: "Arguments (ignored in dev-mode mock path; present for schema parity).",
+					items: {}
+				}
+			},
+			required: ["name"]
+		},
+		availableIn: "both"
+	},
+	{
+		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.",
+		inputSchema: {
+			type: "object",
+			properties: { expression: {
+				type: "string",
+				description: "JavaScript expression to evaluate."
+			} },
+			required: ["expression"]
+		},
+		availableIn: "both"
+	},
+	{
+		name: "take_screenshot",
+		description: "Captures a PNG screenshot via CDP Page.captureScreenshot. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "get_dom_document",
+		description: "Returns the DOM tree via CDP DOM.getDocument. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "take_snapshot",
+		description: "Captures a serialized page snapshot via CDP DOMSnapshot.captureSnapshot. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_console_messages",
+		description: "Lists console messages captured via CDP Runtime.consoleAPICalled. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_network_requests",
+		description: "Lists network requests captured via CDP Network events. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_exceptions",
+		description: "Lists JS exceptions captured via CDP Runtime.exceptionThrown. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: { limit: {
+				type: "number",
+				description: "Maximum exceptions to return."
+			} },
+			required: []
+		},
+		availableIn: "both"
 	}
 ];
+/** All tool names served in dev-mode (including tier-filter stubs). */
 const DEV_TOOL_NAMES = new Set(DEV_TOOL_DEFINITIONS.map((t) => t.name));
+/** CDP-only tools — return a tier-filter error in dev-mode. */
+const CDP_ONLY_TOOL_NAMES = new Set([
+	"evaluate",
+	"take_screenshot",
+	"get_dom_document",
+	"take_snapshot",
+	"list_console_messages",
+	"list_network_requests",
+	"list_exceptions"
+]);
+/**
+* Builds the `list_pages` dev-mode shim response.
+* Returns the Vite dev URL as a single-entry page list with `devMode: true`.
+*/
+function buildDevListPagesResult(devtoolsUrl) {
+	return {
+		pages: [{
+			url: devtoolsUrl,
+			title: "dev fixture",
+			attached: true
+		}],
+		tunnel: { up: false },
+		devMode: true,
+		singleAttachModel: true
+	};
+}
+/**
+* Builds the `get_diagnostics` dev-mode response.
+* Probes the mock state endpoint reachability and returns server metadata.
+*/
+async function buildDevDiagnostics(devtoolsUrl, stateEndpoint, fetchImpl) {
+	let reachable = false;
+	let lastFetchError = null;
+	let lastFetchAt = null;
+	try {
+		const res = await fetchImpl(stateEndpoint);
+		reachable = res.ok;
+		lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+		if (!res.ok) lastFetchError = `HTTP ${res.status} ${res.statusText}`;
+	} catch (err) {
+		lastFetchError = err instanceof Error ? err.message : String(err);
+		lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+	}
+	return {
+		mode: "dev",
+		devtoolsUrl,
+		mcpStateEndpoint: stateEndpoint,
+		mockStateEndpointReachable: reachable,
+		lastFetchAt,
+		lastFetchError,
+		environment: {
+			kind: "mock",
+			reason: "dev-mode — Vite HTTP endpoint, no CDP connection"
+		},
+		nextRecommendedAction: reachable ? null : "mock state endpoint가 응답하지 않습니다. Vite dev 서버가 `mcp: true` 옵션으로 실행 중인지 확인하고, 필요하면 dev 서버를 재시작하세요."
+	};
+}
+/**
+* Builds the `measure_safe_area` dev-mode response from mock state.
+* Reads `safeAreaInsets` from the AIT mock state and returns a parity-schema
+* result with `source: 'mock-vite'`.
+*/
+async function buildDevMeasureSafeArea(aitSource) {
+	const rawInsets = (await aitSource.get("AIT.getMockState")).safeAreaInsets;
+	let sdkInsets = null;
+	if (rawInsets !== null && typeof rawInsets === "object" && !Array.isArray(rawInsets)) {
+		const r = rawInsets;
+		sdkInsets = {
+			top: typeof r.top === "number" ? r.top : 0,
+			right: typeof r.right === "number" ? r.right : 0,
+			bottom: typeof r.bottom === "number" ? r.bottom : 0,
+			left: typeof r.left === "number" ? r.left : 0
+		};
+	}
+	return {
+		source: "mock-vite",
+		cssEnv: {
+			top: 0,
+			right: 0,
+			bottom: 0,
+			left: 0
+		},
+		sdkInsets,
+		sdkInsetsSource: sdkInsets !== null ? "window.__ait" : null,
+		...sdkInsets === null ? { sdkInsetsError: "window.__ait.state.safeAreaInsets not found in mock state snapshot" } : {},
+		innerWidth: null,
+		innerHeight: null,
+		devicePixelRatio: null,
+		userAgent: null,
+		navBarHeight: null,
+		navBarHeightSource: "not-available-in-dev-mode"
+	};
+}
+/**
+* Builds the `call_sdk` dev-mode response.
+*
+* Supported methods are served from the mock state snapshot. Unsupported
+* methods return `{ ok: false, error: 'dev-mode-unsupported: ...' }` so the
+* agent gets an informative message rather than a generic failure.
+*/
+async function buildDevCallSdk(methodName, aitSource) {
+	switch (methodName) {
+		case "getOperationalEnvironment": {
+			const env = await aitSource.get("AIT.getOperationalEnvironment");
+			return {
+				ok: true,
+				value: {
+					environment: env.environment,
+					sdkVersion: env.sdkVersion
+				}
+			};
+		}
+		default: return {
+			ok: false,
+			error: `dev-mode-unsupported: "${methodName}"은 dev-mode에서 직접 호출할 수 없습니다. CDP bridge(window.__sdkCall)가 없으므로 실제 SDK 호출은 \`--mode=local\` 또는 debug 모드에서만 가능합니다. 지원 메서드: getOperationalEnvironment (mock state에서 읽음).`
+		};
+	}
+}
 /** 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 devtoolsUrl = process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173";
+	const stateEndpoint = `${devtoolsUrl}/api/ait-devtools/state`;
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.43"
+		version: "0.1.45"
 	}, { 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
-		};
+		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}`);
 		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) {
+			if (isAitToolName(effective)) 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
-				};
+				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 "call_sdk": {
+					const sdkName = request.params.arguments?.name;
+					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 메서드 이름을 전달하세요.");
+					return jsonResult(await buildDevCallSdk(sdkName, aitSource));
+				}
+				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
 		} 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 mcpError(`${name} 실패: ${err instanceof Error ? err.message : String(err)}\nVite dev 서버가 @ait-co/devtools unplugin \`mcp: true\` 옵션으로 실행 중인지 확인하세요. AIT_DEVTOOLS_URL 환경변수가 올바르게 설정됐는지도 확인하세요.`);
 		}
 	});
 	return server;