@refore-ai/html-to-figma-mcp 0.0.5 → 0.1.2

package/README.md

@@ -1,3 +1,4 @@
+
 # @refore-ai/html-to-figma-mcp
 
 Your agent opens page after page — browsing through whatever you asked for, say a whole user flow
@@ -12,13 +13,13 @@ Figma canvas, through the [Refore HTML to Figma](https://www.figma.com/community
 
 - Node.js 18+
 - Figma, with the [Refore HTML to Figma](https://www.figma.com/community/plugin/1385944139259302061/) plugin installed
-
+  
 ## Setup
 
 **Claude Code**
 
 ```bash
-claude mcp add html-to-figma -- npx -y @refore-ai/html-to-figma-mcp
+claude mcp add refore-html-to-figma -- npx -y @refore-ai/html-to-figma-mcp
 ```
 
 **Claude Desktop** — add to `claude_desktop_config.json`, then restart the app:
@@ -26,7 +27,7 @@ claude mcp add html-to-figma -- npx -y @refore-ai/html-to-figma-mcp
 ```json
 {
   "mcpServers": {
-    "html-to-figma": {
+    "refore-html-to-figma": {
       "command": "npx",
       "args": ["-y", "@refore-ai/html-to-figma-mcp"]
     }
@@ -37,7 +38,7 @@ claude mcp add html-to-figma -- npx -y @refore-ai/html-to-figma-mcp
 **Codex** — add to `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.html-to-figma]
+[mcp_servers.refore-html-to-figma]
 command = "npx"
 args = ["-y", "@refore-ai/html-to-figma-mcp"]
 ```
@@ -49,10 +50,14 @@ Now ask your agent to import a page.
 
 ## Tools
 
-| Tool | Purpose |
-| ---- | ------- |
-| `import_html` | Import inline HTML or a local `.html` file path. Optional `assets` (local files the HTML references), `viewport`, `target` (insert under / replace an existing node), `wait` |
-| `import_url` | Import a web page by URL |
-| `get_status` | Returns `ws_port` / `connected` / `queue { mine, total, running }` |
-| `wait_task` | Block until a task settles, then return its final result |
-| `get_task_status` | Non-blocking check of a task's current phase / result |
+| Tool                     | Purpose                                                                                                                                                                                                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `import_html`            | Preferred import path: import inline HTML or a local `.html` file path. Optional `assets` (local files the HTML references), `viewport`, `target` (insert under / replace an existing node — replace accepts a `nodeId` or a previous import's `taskId`), `wait`                                                                 |
+| `no_browser_fallback`    | Fallback for when the agent cannot get the page DOM for any reason: the agent first asks the user to choose between plugin-side URL fetching (public pages, no login state, fetched from the plugin edition's service region) and recording with the Refore browser extension; only calls this tool if the user picks the former |
+| `get_capture_guide`      | Returns the standard DOM-capture playbook: capture script (strip scripts / canvas to img / base injection), strategies for getting a large dump out of browser tooling, and the import-verify-redo loop                                                                                                                          |
+| `get_node_info`          | Inspect a node's bounds / visibility / direct children to verify an import                                                                                                                                                                                                                                                       |
+| `export_node_screenshot` | Export a PNG screenshot of a node (longest edge defaults to 1024px)                                                                                                                                                                                                                                                              |
+| `remove_import`          | Remove the artifact of a previous import task (idempotent; only tasks of this connection)                                                                                                                                                                                                                                        |
+| `get_status`             | Returns `ws_port` / `connected` / `queue { mine, total, running }`                                                                                                                                                                                                                                                               |
+| `wait_task`              | Block until a task settles, then return its final result                                                                                                                                                                                                                                                                         |
+| `get_task_status`        | Non-blocking check of a task's current phase / result                                                                                                                                                                                                                                                                            |

package/index.mjs

@@ -29,7 +29,7 @@ const PLATFORM_DISPLAY_NAMES = {
 //#region src/platform.ts
 const MCP_PLATFORM = "figma";
 /** 从源 package.json 的 version 由 tsdown define 注入；测试环境未注入 → 兜底 '0.0.0-dev' */
-const MCP_SERVER_VERSION = "0.0.5";
+const MCP_SERVER_VERSION = "0.1.2";
 /** 面向 agent 的平台展示名（用于工具描述等） */
 const MCP_PLATFORM_NAME = PLATFORM_DISPLAY_NAMES[MCP_PLATFORM];
 /** 本 MCP server 的包名 / 日志前缀基名 */
@@ -38,6 +38,190 @@ const MCP_SERVER_NAME = `html-to-${MCP_PLATFORM}-mcp`;
 function mcpLog(message) {
 	process.stderr.write(`[${MCP_SERVER_NAME}] ${message}\n`);
 }
+function getPortRange(base, size = 30) {
+	return {
+		start: base,
+		end: base + size - 1
+	};
+}
+//#endregion
+//#region ../../libs/html-to-figma-mcp-protocol/src/port-segments.ts
+/**
+* html-to-figma MCP 在整个 MCP 端口空间里占用 5000–5599 段，平台 base 按整百间隔
+* （5000–5099 空置不用），实际绑定/扫描只用每个 base 起的前 DEFAULT_PORT_SEGMENT_SIZE
+* 个端口（如 figma 为 5500–5529），其余留作扩容余量。
+* 每个新 MCP 产品应选独立的 base（如 6000/7000/...），互不重叠。
+*/
+const PLATFORM_PORT_BASE = {
+	figma: 5500,
+	mastergo: 5100,
+	jsdesign: 5200,
+	"pixso-china": 5300,
+	"pixso-world": 5400
+};
+function getHtmlToFigmaPortRange(platform) {
+	return getPortRange(PLATFORM_PORT_BASE[platform], 30);
+}
+//#endregion
+//#region ../../libs/html-to-figma-mcp-protocol/src/protocol.ts
+/** 产品身份魔术字符串。服务端 hello 校验时，payload.magic 必须与此值相等 */
+const MAGIC = "refore-html-to-design-mcp";
+//#endregion
+//#region src/capture-guide.ts
+/**
+* agent 抓取页面 DOM 的标准作业指南，由 `get_capture_guide` 工具原文返回。
+* 只写通用方法论与本 MCP 自身工具的用法；第三方浏览器工具的能力按特征描述（能否写文件 /
+* 是否截断返回值 / 是否有内容过滤），不点名易变的工具细节——指南随 npm 包发版，改动成本高。
+* 代码块用 `~~~` 围栏而不是反引号围栏：正文放在模板字面量里，避免逐处转义反引号。
+*/
+const CAPTURE_GUIDE = `# Capturing a rendered page for import_html
+
+Workflow rhythm — capture is part of walking the flow, not a phase after it. When the task spans
+several pages/states, import each one the moment you first reach it: capture, submit with
+wait:false, keep walking while the plugin imports, then wait_task the previous submission
+(mechanics in section 4). Never navigate the whole flow to the end and only then come back to
+capture page by page — the second walk doubles the work, and interaction states (opened dialogs,
+filled forms, drag mid-states) may not be reproducible on re-navigation.
+
+## 1. Capture script (run inside the page)
+
+Before capturing, scroll through the page once — bottom, then back to top — so lazy-loaded content
+(especially images below the fold) actually loads. Scroll incrementally, not in one jump:
+IntersectionObserver-based lazy loading only triggers for content that has entered the viewport.
+
+~~~js
+for (let y = 0; y < document.body.scrollHeight; y += innerHeight) {
+  window.scrollTo(0, y);
+  await new Promise((r) => setTimeout(r, 300));
+  if (y > innerHeight * 100) break; // infinite feeds never end; cap and move on
+}
+window.scrollTo(0, 0);
+await new Promise((r) => setTimeout(r, 500));
+~~~
+
+Then run this in the page context and use the returned string as the HTML to import:
+
+~~~js
+(() => {
+  const clone = document.documentElement.cloneNode(true);
+
+  // canvas pixels do not serialize with HTML: snapshot each one into an <img>.
+  // Size the img with the CSS layout box from getBoundingClientRect() — canvas.width/height are
+  // DEVICE pixels (2x on Retina displays) and would blow the img out of its container.
+  const liveCanvases = document.querySelectorAll('canvas');
+  clone.querySelectorAll('canvas').forEach((c, i) => {
+    const live = liveCanvases[i];
+    if (!live) return;
+    const rect = live.getBoundingClientRect();
+    const img = document.createElement('img');
+    try {
+      img.src = live.toDataURL('image/png');
+    } catch {
+      // tainted canvas (cross-origin content) cannot be exported; keep the size so layout holds
+    }
+    img.style.cssText = getComputedStyle(live).cssText;
+    img.style.width = rect.width + 'px';
+    img.style.height = rect.height + 'px';
+    img.style.maxWidth = '100%';
+    c.replaceWith(img);
+  });
+
+  // scripts must not re-run inside the import renderer (SPA re-execution would wipe the captured DOM)
+  clone.querySelectorAll('script').forEach((s) => s.remove());
+
+  // make relative asset URLs resolve against the original origin
+  const base = document.createElement('base');
+  base.href = location.href;
+  const head =
+    clone.querySelector('head') ?? clone.insertBefore(document.createElement('head'), clone.firstChild);
+  head.prepend(base);
+
+  return '<!DOCTYPE html>\\n' + clone.outerHTML;
+})();
+~~~
+
+Capture per page STATE, not per URL: walk the flow and dump once for every state you want imported
+(opened dialog, filled form, drag mid-state, ...).
+
+Dumps are single-use artifacts: capture fresh from the live browser on every import run. Never
+reuse dump files left over from earlier sessions or runs — they may predate capture-script fixes,
+and the page data or viewport may have changed since; none of that is visible from the file itself.
+
+## 2. Getting a large dump out of the browser tooling
+
+SPA pages easily reach 300 KB+. Try these channels in order:
+
+1. **File path**: if your browser tool can write results to a file, write the HTML to an absolute
+   path and pass that path as import_html's "html" argument. If the write is denied as outside the
+   tool's allowed/workspace roots, do NOT brute-force other directories — the allowed set comes from
+   that tool's own MCP configuration, and clients without MCP "roots" support are often limited to
+   the OS temp directory: macOS is $TMPDIR (/var/folders/..., not /tmp), Windows is %TEMP%
+   (C:\\Users\\<name>\\AppData\\Local\\Temp), Linux is /tmp. Try the OS temp directory once, then
+   move on to channel 2 or 3.
+2. **gzip + base64** (when tool return values get truncated): compress inside the page —
+
+   ~~~js
+   const bytes = new TextEncoder().encode(html);
+   const buf = await new Response(
+     new Blob([bytes]).stream().pipeThrough(new CompressionStream('gzip')),
+   ).arrayBuffer();
+   let bin = '';
+   for (const b of new Uint8Array(buf)) bin += String.fromCharCode(b);
+   return { htmlLen: bytes.length, gzBase64: btoa(bin) };
+   ~~~
+
+   then locally: printf '%s' "$GZ_BASE64" | base64 -d | gunzip > page.html — and verify the restored
+   byte count matches htmlLen.
+3. **Download**: if the return channel filters or blocks content, trigger a download inside the page
+   (a.href = URL.createObjectURL(new Blob([html])); a.download = 'page.html'; a.click()) and read the
+   file from the user's Downloads directory.
+4. **None of the above works**: follow the no_browser_fallback tool's instructions.
+
+Never substitute a curl / anonymous re-fetch of the URL for the captured DOM — that is not the page
+actually open in the browser (no login state, no interaction state).
+
+## 3. Validate the dump before importing
+
+- The file must start with <!DOCTYPE html>. Some tools serialize the evaluate result as JSON when
+  writing it to a file (the whole content wrapped in quotes with escaped characters, sometimes with
+  the extension changed to .json) — if so, JSON.parse it back to plain HTML first:
+
+  ~~~bash
+  node -e "const fs=require('fs');fs.writeFileSync('page.html',JSON.parse(fs.readFileSync('page.json','utf8')))"
+  ~~~
+
+- The number of data:image/png occurrences should be at least the number of exportable canvases on
+  the page — confirms the chart snapshots made it into the dump.
+- If a check fails, fix the transfer channel or re-capture; never import a dump that fails
+  validation.
+
+## 4. Import, verify, redo
+
+- Pipeline, do not batch: import each state right after capturing it, instead of dumping all pages
+  first and importing at the end. Interleave with depth 1: submit state N with wait:false (returns
+  the taskId immediately), keep walking the flow and capture state N+1 while the plugin imports
+  (its task queue is serial), then wait_task(N) and verify state N — any failure costs at most one
+  wasted capture instead of N.
+- Verification runs entirely on the Figma side (get_node_info + export_node_screenshot) against
+  the baseline you froze at capture time — the browser never needs to navigate back. Take a
+  viewport screenshot of the page right when you capture it, as the comparison baseline. Check:
+  visibleAreaRatio is 1 and the root size matches the viewport; the exported image has no large
+  blank areas or overflowing elements and is the same page you captured.
+- import_html with "width" matching the capture viewport.
+- To fix a bad result, first diagnose WHERE the problem lives by inspecting the saved dump: does
+  it actually contain the content that came out wrong (e.g. grep for the data:image snapshot of a
+  blank chart, or the missing section's text)? If the dump has it, fix WITHOUT the browser —
+  re-import the SAME dump with corrected params (width), or edit the dump in place when content
+  is present but wrongly expressed or obstructed (strip leftover scripts, fix the <base> href,
+  correct snapshot img sizes, delete stray overlays/tooltips) — then re-import with
+  target: {mode:"replace", taskId} to swap the result in place. Only when the dump itself lacks the
+  content is the fix capture-side: restore the page state and re-capture. Editing the dump cannot
+  fix MISSING content. At most 2 replace re-imports on top of the initial import (3 imports total —
+  every import consumes quota), each changing one input-side variable; if it still mismatches, keep
+  the closest result and report the differences to the user.
+- Only when the user explicitly asks to import and verify each page before moving on: stay on the
+  page, submit with wait:true, verify, and only then continue the flow. Slower; not the default.
+`;
 //#endregion
 //#region src/import-source.ts
 const DEFAULT_VIEWPORT = {
@@ -62,7 +246,7 @@ async function normalizeHtmlSource(args, io = defaultIO) {
 		try {
 			html = (await io.readFile(args.html)).toString("utf8");
 		} catch (e) {
-			if (isEnoent(e)) throw new Error(`${args.html} (ENOENT)`);
+			if (isEnoent(e)) throw new Error(`${args.html} (ENOENT). If you could not write the dump due to path restrictions, use the OS temp directory (macOS: \$TMPDIR under /var/folders, NOT /tmp; Windows: %TEMP%) or see get_capture_guide for other transfer channels.`);
 			throw e;
 		}
 		baseDir = path.dirname(args.html);
@@ -97,10 +281,13 @@ async function normalizeHtmlSource(args, io = defaultIO) {
 }
 //#endregion
 //#region src/tools.ts
-const targetSchema = z.object({
+const targetSchema = z.union([z.object({
 	mode: z.enum(["insert", "replace"]),
 	nodeId: z.string()
-}).optional();
+}).strict(), z.object({
+	mode: z.literal("replace"),
+	taskId: z.string()
+}).strict()]).describe("Where the imported root node lands. `{mode:\"insert\", nodeId}` appends it as a child of that node; `{mode:\"replace\", nodeId}` moves it into that node's place (parent / stacking order / coordinates) and deletes it; `{mode:\"replace\", taskId}` does the same against a previous import of this MCP connection — that is the way to redo a bad import in place. Replacing is safe: the target is only deleted after this import succeeds, and if it was already deleted manually the import falls back to the default placement with `targetApplied: false`. Redo discipline: at most 2 replace re-imports on top of the initial import (3 imports total), and only when you changed an input-side variable (different HTML dump, added assets, viewport, params) — identical input reproduces identical output, and every import consumes paid quota. If the result still doesn't match after that, KEEP the closest result (do not remove it) and report the concrete differences to the user — it is likely a parsing-engine limitation; do not attempt node-by-node canvas fixes.").optional();
 function textResult(obj) {
 	return { content: [{
 		type: "text",
@@ -118,15 +305,25 @@ function errorResult(message) {
 }
 function registerTools(server, deps) {
 	const { hub } = deps;
-	async function runTask(kind, payload, wait) {
-		if (!hub.connected) return errorResult("Plugin not connected (NO_PLUGIN); open and connect the plugin MCP tab");
+	function noPluginError() {
+		return errorResult(`Plugin not connected (NO_PLUGIN). In the design tool, open the plugin's MCP tab, click rescan, and confirm port ${hub.port} (${hub.agent.name}) shows as connected.`);
+	}
+	/** capability 门控：未连接 / 插件太老没有该能力时给出明确文案，而不是 emit 出去等超时 */
+	function gateCapability(capability, label) {
+		if (!hub.connected) return noPluginError();
+		if (!hub.hasCapability(capability)) return errorResult(`Connected plugin version does not support ${label}; please update the plugin`);
+		return null;
+	}
+	async function runTask(kind, payload, opts) {
+		if (!hub.connected) return noPluginError();
+		if (payload.target && "taskId" in payload.target && !hub.hasCapability("task:submit#target.taskId")) return errorResult("Connected plugin version does not support `target` by taskId; please update the plugin (or target the imported node directly with `{mode:\"replace\", nodeId}`)");
 		const taskId = randomUUID();
 		const submitP = hub.submit({
 			taskId,
 			kind,
 			payload
 		});
-		if (!wait) {
+		if (!opts.wait) {
 			submitP.catch(() => {});
 			return textResult({ taskId });
 		}
@@ -136,8 +333,9 @@ function registerTools(server, deps) {
 			return errorResult(e.message);
 		}
 	}
+	let captureGuideServed = false;
 	server.registerTool("import_html", {
-		description: `Import a snippet of HTML or an HTML file into ${MCP_PLATFORM_NAME}. If \`html\` is an absolute path it is read as a file, otherwise treated as HTML content.`,
+		description: `Import a snippet of HTML or an HTML file into ${MCP_PLATFORM_NAME}. If \`html\` is an absolute path it is read as a file, otherwise treated as HTML content. BEFORE opening the first target page, call \`get_capture_guide\` once — importing a dumped file without having read it is rejected, and it fixes the workflow rhythm (import each page the moment you reach it — never walk the whole flow first) plus traps that otherwise waste paid imports (lazy loading, canvas snapshots, where dump files can be written). This is the preferred import path: whenever you can open or render the page yourself (walking a flow, pages behind login, states after interaction), dump the rendered DOM and import it with this tool. When the user only gives you a URL, still default to this tool — a URL is just the target's address, not a method choice. If you cannot get the page DOM into your hands for ANY reason (no browser tooling, return-value truncation, content filters blocking the transfer, ...), do not fetch the page by other means — follow the instructions of the \`no_browser_fallback\` tool instead.`,
 		inputSchema: {
 			html: z.string(),
 			assets: z.array(z.object({
@@ -150,16 +348,17 @@ function registerTools(server, deps) {
 			wait: z.boolean().optional()
 		}
 	}, async (args) => {
+		if (!captureGuideServed && resolveHtmlInput(args.html).kind === "path") return errorResult("Call get_capture_guide first, then retry this import. It covers capture traps that waste paid imports (lazy-loaded content, canvas snapshots, which directories dump files can be written to). This check fires only once per session.");
 		let source;
 		try {
 			source = await normalizeHtmlSource(args);
 		} catch (e) {
 			return errorResult(e.message);
 		}
-		return runTask("html", source, args.wait ?? true);
+		return runTask("html", source, { wait: args.wait ?? true });
 	});
-	server.registerTool("import_url", {
-		description: `Import a web page URL into ${MCP_PLATFORM_NAME}.`,
+	server.registerTool("no_browser_fallback", {
+		description: `Fallback URL import into ${MCP_PLATFORM_NAME} for when you cannot get the page DOM into your hands for ANY reason: no browser tooling at all, return-value truncation, content filters blocking the DOM transfer, etc. If the DOM is not in your hands after reasonable attempts, this tool IS the designated next step — never invent detours like re-fetching the URL with curl (an anonymous re-fetch is NOT the page actually open in the browser). Before calling, present the user with this choice and wait for their answer: (A) send the URL to the plugin, which fetches and imports the page server-side from the plugin edition's service region — the Chinese edition fetches from mainland China, so sites unreachable there (e.g. google.com) are bound to fail; suits public no-login pages reachable from that region; (B) the user records the page with the Refore HTML to Figma browser extension (named Refore HTML to Design in the Chinese edition) — suits pages behind login, with post-interaction state, or unreachable from the service region. Only call this tool after the user chooses A; if they choose B, guide them to use the browser extension instead. Server-side fetching is anonymous and carries no login state. Whenever you can obtain the DOM yourself, use import_html instead.`,
 		inputSchema: {
 			url: z.string(),
 			width: z.number().optional(),
@@ -180,13 +379,23 @@ function registerTools(server, deps) {
 			theme: args.theme,
 			locale: args.locale,
 			target: args.target
-		}, args.wait ?? true);
+		}, { wait: args.wait ?? true });
+	});
+	server.registerTool("get_capture_guide", {
+		description: "Return the standard playbook for capturing a rendered page DOM for import_html: the workflow rhythm (import each page the moment you reach it — never walk the whole flow first and capture afterwards), a ready-to-run capture script (strips <script>, snapshots <canvas> into <img>, injects <base>), strategies for getting a large dump out of browser tooling (file path / gzip+base64 / download), and the import-verify-redo loop. Call it once BEFORE opening the first target page — reading it only at import time is too late to fix the rhythm. Importing a dumped file without having read it is rejected.",
+		inputSchema: {}
+	}, async () => {
+		captureGuideServed = true;
+		return { content: [{
+			type: "text",
+			text: CAPTURE_GUIDE
+		}] };
 	});
 	server.registerTool("wait_task", {
 		description: "Block until a task finishes and return its result.",
 		inputSchema: { taskId: z.string() }
 	}, async (args) => {
-		if (!hub.connected) return errorResult("Plugin not connected (NO_PLUGIN)");
+		if (!hub.connected) return noPluginError();
 		try {
 			return textResult(await hub.taskWait(args.taskId));
 		} catch (e) {
@@ -197,13 +406,67 @@ function registerTools(server, deps) {
 		description: "Return a task's current status snapshot (non-blocking). Returns null if the taskId is unknown or was submitted by a different MCP connection.",
 		inputSchema: { taskId: z.string() }
 	}, async (args) => {
-		if (!hub.connected) return errorResult("Plugin not connected (NO_PLUGIN)");
+		if (!hub.connected) return noPluginError();
 		try {
 			return textResult(await hub.taskQuery(args.taskId));
 		} catch (e) {
 			return errorResult(e.message);
 		}
 	});
+	server.registerTool("get_node_info", {
+		description: "Inspect a node's position, size, visibility and children — use it after an import to verify the result landed where expected (pass the rootNodeId from the import result). Returns id/name/type, absolute bounds, visible flags, parentId, visibleAreaRatio (fraction of the node area inside all clipping ancestors: 1 = fully visible, 0 = fully clipped out of view), childrenTotal and up to 50 direct-children summaries. Returns {\"node\":null} if the node no longer exists. Verification only — this MCP has no node-editing tools; fix problems by re-importing with corrected input (see `target: {mode:\"replace\", taskId}` on the import tools).",
+		inputSchema: { nodeId: z.string() }
+	}, async (args) => {
+		const gate = gateCapability("node:info", "get_node_info");
+		if (gate) return gate;
+		try {
+			return textResult(await hub.nodeInfo({ nodeId: args.nodeId }));
+		} catch (e) {
+			return errorResult(e.message);
+		}
+	});
+	server.registerTool("export_node_screenshot", {
+		description: "Export a rendered PNG screenshot of a node (e.g. an imported rootNodeId) to visually verify the import shows the intended page — catches coarse errors like a blank frame, a login page, or a clipped/misplaced result. Not for pixel-perfect comparison. `maxDimension` caps the longest edge in px (default 1024; downscale only). Also returns a text part with the exported width/height as fallback for clients that cannot display images.",
+		inputSchema: {
+			nodeId: z.string(),
+			maxDimension: z.number().optional()
+		}
+	}, async (args) => {
+		const gate = gateCapability("node:export", "export_node_screenshot");
+		if (gate) return gate;
+		try {
+			const res = await hub.nodeExport({
+				nodeId: args.nodeId,
+				maxDimension: args.maxDimension
+			});
+			return { content: [{
+				type: "image",
+				data: res.pngBase64,
+				mimeType: "image/png"
+			}, {
+				type: "text",
+				text: JSON.stringify({
+					nodeId: args.nodeId,
+					width: res.width,
+					height: res.height
+				})
+			}] };
+		} catch (e) {
+			return errorResult(e.message);
+		}
+	});
+	server.registerTool("remove_import", {
+		description: "Remove the imported artifact of a previous import task (by taskId; only tasks submitted through this MCP connection). Use it to undo a wrong import or clean up test imports — it cannot delete arbitrary nodes and is not a general editing tool. Idempotent: returns \"already-gone\" if the node was already deleted. To re-import a fixed version into the old node's place, prefer `target: {mode:\"replace\", taskId}` on the import tools over remove + import (that keeps the old node if the re-import fails). When giving up after failed retries, keep the closest result instead of removing it, and report the differences to the user.",
+		inputSchema: { taskId: z.string() }
+	}, async (args) => {
+		const gate = gateCapability("import:remove", "remove_import");
+		if (gate) return gate;
+		try {
+			return textResult(await hub.removeImport({ taskId: args.taskId }));
+		} catch (e) {
+			return errorResult(e.message);
+		}
+	});
 	server.registerTool("get_status", {
 		description: "Return this MCP's WS port, plugin connection state, and queue status. Set `include_tasks` to also get the list of tasks submitted by this connection.",
 		inputSchema: { include_tasks: z.boolean().optional() }
@@ -230,41 +493,26 @@ function registerTools(server, deps) {
 }
 //#endregion
 //#region src/server.ts
+/**
+* MCP server instructions：客户端握手时就进入 agent 上下文，是唯一早于「开始打开页面」的
+* 引导通道——tool description 要等工具被加载才可见，get_capture_guide 的门禁要到首次导入
+* 才触发，都晚于 agent 决定「先把流程走完再回头抓」的时刻。这里只放必须在走流程前就位的
+* 内容：路由声明 + 节奏规则，其余细节仍归 get_capture_guide。
+*
+* 客户端延迟加载工具时 instructions 是唯一的发现面：Claude Code 把它注入系统提示词（2KB
+* 截断）；Codex 把它渲染进 tool_search 的来源清单并计入 BM25 检索语料（plugin 形态只保留
+* 前 1000 字节）。因此路由声明必须是第一句、全文不得超过 1000 字节（有测试锁定）；中文
+* 触发词是给 BM25 命中中文 query 用的——其余语料全是英文，纯中文搜索词否则一个都对不上。
+*/
+const SERVER_INSTRUCTIONS = `Use this MCP whenever the user asks to import, convert or restore a web page, URL, or HTML into ${MCP_PLATFORM_NAME} (中文指令如「把网页/URL/HTML 导入到 ${MCP_PLATFORM_NAME}」，产品名「网页转设计」). Capturing is part of walking the flow, not a phase after it: call get_capture_guide BEFORE opening the first target page, then capture and import each page/state the moment you first reach it (submit with wait:false, keep walking while the plugin imports, then wait_task the previous submission). Never walk the whole flow to the end and only then start capturing — the second walk doubles the work and interaction states may not be reproducible on re-navigation.`;
 function createServer$1(deps) {
 	const server = new McpServer({
 		name: MCP_SERVER_NAME,
 		version: MCP_SERVER_VERSION
-	});
+	}, { instructions: SERVER_INSTRUCTIONS });
 	registerTools(server, deps);
 	return server;
 }
-function getPortRange(base, size = 100) {
-	return {
-		start: base,
-		end: base + size - 1
-	};
-}
-//#endregion
-//#region ../../libs/html-to-figma-mcp-protocol/src/port-segments.ts
-/**
-* html-to-figma MCP 在整个 MCP 端口空间里占用 5000–5599 段，按平台每 100 一格；
-* 其中 5000–5099 空置不用，figma 落在 5500–5599。
-* 每个新 MCP 产品应选独立的 base（如 6000/7000/...），互不重叠。
-*/
-const PLATFORM_PORT_BASE = {
-	figma: 5500,
-	mastergo: 5100,
-	jsdesign: 5200,
-	"pixso-china": 5300,
-	"pixso-world": 5400
-};
-function getHtmlToFigmaPortRange(platform) {
-	return getPortRange(PLATFORM_PORT_BASE[platform], 100);
-}
-//#endregion
-//#region ../../libs/html-to-figma-mcp-protocol/src/protocol.ts
-/** 产品身份魔术字符串。服务端 hello 校验时，payload.magic 必须与此值相等 */
-const MAGIC = "refore-html-to-design-mcp";
 //#endregion
 //#region ../../libs/mcp-transport/src/mcp/ws-hub-base.ts
 const MAX_HTTP_BUFFER_SIZE = 100 * 1024 * 1024;
@@ -288,6 +536,8 @@ var WsHubBase = class {
 	plugin = null;
 	boundPort = 0;
 	pluginCleanups = /* @__PURE__ */ new Set();
+	/** 当前绑定插件在 hello 中声明的能力集；老插件不声明 → 空集 */
+	pluginCapabilities = /* @__PURE__ */ new Set();
 	/** 进程唯一身份，握手时通过 HelloAck 传给插件 —— 让插件能区分同 port 前后两个不同进程 */
 	connectionId = randomUUID();
 	constructor(opts) {
@@ -299,10 +549,18 @@ var WsHubBase = class {
 	get connected() {
 		return this.plugin !== null;
 	}
+	/** 本进程对外展示的 agent 元信息（初始为占位，握手后由 setAgent 覆盖为真实 clientInfo） */
+	get agent() {
+		return this.opts.agent;
+	}
 	/** 返回当前活跃的插件 socket，供子类主动 emit 业务事件（如 task:submit）*/
 	getPlugin() {
 		return this.plugin;
 	}
+	/** 当前绑定插件是否声明了某能力。无插件连接时一律 false */
+	hasCapability(capability) {
+		return this.plugin !== null && this.pluginCapabilities.has(capability);
+	}
 	async listen() {
 		const { start, end } = this.opts.portRange;
 		const originCheck = this.opts.allowedOrigins ?? defaultOriginCheck;
@@ -363,7 +621,7 @@ var WsHubBase = class {
 				this.plugin.emit("superseded", {});
 				this.plugin.disconnect(true);
 			}
-			this.bindPlugin(socket);
+			this.bindPlugin(socket, payload.capabilities ?? []);
 			ack({
 				agent: this.opts.agent,
 				wsPort: this.boundPort,
@@ -371,12 +629,16 @@ var WsHubBase = class {
 			});
 		});
 	}
-	bindPlugin(socket) {
+	bindPlugin(socket, capabilities) {
 		this.plugin = socket;
+		this.pluginCapabilities = new Set(capabilities);
 		const cleanup = this.opts.onPluginBound?.(socket);
 		if (cleanup) this.pluginCleanups.add(cleanup);
 		socket.on("disconnect", () => {
-			if (this.plugin === socket) this.plugin = null;
+			if (this.plugin === socket) {
+				this.plugin = null;
+				this.pluginCapabilities = /* @__PURE__ */ new Set();
+			}
 			const cleanups = [...this.pluginCleanups];
 			this.pluginCleanups.clear();
 			for (const fn of cleanups) try {
@@ -404,6 +666,12 @@ var WsHubBase = class {
 //#endregion
 //#region src/ws-hub.ts
 /**
+* 查询类 RPC 的 ack 超时：向不支持某事件的老插件 emit 时 ack 永不回来，没有超时就是永久
+* hang。只用于查询/轻命令；TaskSubmit / TaskWait 的 ack 是任务完成信号（wait:true 时分钟级
+* 是正常的），绝不能套。
+*/
+const DEFAULT_QUERY_TIMEOUT_MS = 3e4;
+/**
 * html-to-figma MCP 的 server：在 `WsHubBase`（端口绑定 + hello 握手 + plugin socket 生命
 * 周期）之上加 task 命令与查询 RPC，全部走 socket.io ack 现问现答，本类不缓存任何 task 状态
 * （真源在插件的 active + history）。
@@ -412,6 +680,7 @@ var WsHub = class extends WsHubBase {
 	/** 已 emit 但插件尚未 ack 的请求。插件掉线时统一 reject —— socket.io 不会自动结算掉线时的
 	* ack callback，不主动 reject 的话 wait:true 的 submit / taskWait / 查询类都会永远 hang */
 	pendingAcks = /* @__PURE__ */ new Set();
+	queryTimeoutMs;
 	constructor(opts) {
 		super({
 			magic: MAGIC,
@@ -426,17 +695,31 @@ var WsHub = class extends WsHubBase {
 				for (const rejectFn of pending) rejectFn(/* @__PURE__ */ new Error("NO_PLUGIN: plugin disconnected before ack"));
 			}
 		});
+		this.queryTimeoutMs = opts.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS;
 	}
-	emitWithAck(event, payload) {
+	/**
+	* @param timeoutMs 可选 ack 超时。只给查询类 RPC 传；命令类（TaskSubmit）的 ack 是任务
+	* 完成信号，不能传（见 DEFAULT_QUERY_TIMEOUT_MS 注释）
+	*/
+	emitWithAck(event, payload, timeoutMs) {
 		const plugin = this.getPlugin();
 		if (!plugin || !plugin.connected) return Promise.reject(/* @__PURE__ */ new Error("NO_PLUGIN: plugin not connected"));
 		return new Promise((resolve, reject) => {
-			const abort = (err) => reject(err);
+			let settled = false;
+			let timer;
+			const settle = (fn) => {
+				if (settled) return;
+				settled = true;
+				if (timer !== void 0) clearTimeout(timer);
+				this.pendingAcks.delete(abort);
+				fn();
+			};
+			const abort = (err) => settle(() => reject(err));
 			this.pendingAcks.add(abort);
+			if (timeoutMs !== void 0) timer = setTimeout(() => abort(/* @__PURE__ */ new Error(`TIMEOUT: plugin did not ack ${event} within ${timeoutMs}ms`)), timeoutMs);
 			plugin.emit(event, payload, (res) => {
-				this.pendingAcks.delete(abort);
-				if (res && typeof res === "object" && "error" in res && typeof res.error === "string") reject(new Error(res.error));
-				else resolve(res);
+				if (res && typeof res === "object" && "error" in res && typeof res.error === "string") settle(() => reject(new Error(res.error)));
+				else settle(() => resolve(res));
 			});
 		});
 	}
@@ -450,10 +733,19 @@ var WsHub = class extends WsHubBase {
 		return this.emitWithAck("task:wait", { taskId });
 	}
 	taskQuery(taskId) {
-		return this.emitWithAck("task:query", { taskId });
+		return this.emitWithAck("task:query", { taskId }, this.queryTimeoutMs);
 	}
 	statusQuery(req) {
-		return this.emitWithAck("status:query", req);
+		return this.emitWithAck("status:query", req, this.queryTimeoutMs);
+	}
+	nodeInfo(req) {
+		return this.emitWithAck("node:info", req, this.queryTimeoutMs);
+	}
+	nodeExport(req) {
+		return this.emitWithAck("node:export", req, this.queryTimeoutMs);
+	}
+	removeImport(req) {
+		return this.emitWithAck("import:remove", req, this.queryTimeoutMs);
 	}
 };
 //#endregion
@@ -477,6 +769,17 @@ async function main() {
 			cwd: process.cwd()
 		});
 	};
+	let shuttingDown = false;
+	const shutdown = () => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		mcpLog("stdio closed; shutting down");
+		setTimeout(() => process.exit(0), 2e3).unref();
+		hub.close().catch((e) => mcpLog(`hub close failed: ${e.message}`)).finally(() => process.exit(0));
+	};
+	server.server.onclose = shutdown;
+	process.stdin.once("end", shutdown);
+	process.stdin.once("close", shutdown);
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refore-ai/html-to-figma-mcp",
-  "version": "0.0.5",
+  "version": "0.1.2",
   "type": "module",
   "bin": {
     "html-to-figma-mcp": "index.mjs"