@refore-ai/html-to-figma-mcp 0.0.1

package/README.md

@@ -0,0 +1,54 @@
+# @refore-ai/html-to-figma-mcp
+
+MCP (Model Context Protocol) server that lets AI agents — Claude Code, Claude Desktop, Codex,
+Cursor, Windsurf and any other MCP client — import HTML files and web pages onto your
+Figma canvas, through the [Refore HTML to Figma](https://www.figma.com/community/plugin/1385944139259302061/) plugin.
+
+## Requirements
+
+- 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 Desktop** — add to `claude_desktop_config.json`, then restart the app:
+
+```json
+{
+  "mcpServers": {
+    "html-to-figma": {
+      "command": "npx",
+      "args": ["-y", "@refore-ai/html-to-figma-mcp"]
+    }
+  }
+}
+```
+
+**Codex** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.html-to-figma]
+command = "npx"
+args = ["-y", "@refore-ai/html-to-figma-mcp"]
+```
+
+**Cursor / Windsurf / others** — use the same `command` / `args` as the Claude Desktop JSON above.
+
+Then open the Refore HTML to Figma plugin in Figma, go to the **MCP** tab and connect.
+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 |

package/index.mjs

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createServer } from "node:http";
+import { Server } from "socket.io";
+//#region src/platform-meta.ts
+/**
+* 面向 agent 的平台展示名（用于工具描述、npm README 等）。
+*
+* 与 libs/constants 的 `PLATFORM_NAME`（插件 UI 用，jsdesign 显示「即时设计」）不是一回事。
+*
+* 本文件同时被 src/platform.ts（打进发布产物）和 tsdown.config.ts（构建时渲染 README）import，
+* 因此这里只放纯数据：不引 runtime 依赖（`PlatformType` / `Region` 这类 enum 会把整个
+* @UseringOfficial/utils 打进 server 包），也不依赖 `__MCP_PLATFORM__` 等构建期注入的常量
+* （否则 tsdown config 加载阶段 import 就会报错）。
+*/
+const PLATFORM_DISPLAY_NAMES = {
+	figma: "Figma",
+	mastergo: "MasterGo",
+	jsdesign: "JSDesign",
+	"pixso-china": "Pixso",
+	"pixso-world": "Pixso"
+};
+//#endregion
+//#region src/platform.ts
+const MCP_PLATFORM = "figma";
+/** 从源 package.json 的 version 由 tsdown define 注入；测试环境未注入 → 兜底 '0.0.0-dev' */
+const MCP_SERVER_VERSION = "0.0.1";
+/** 面向 agent 的平台展示名（用于工具描述等） */
+const MCP_PLATFORM_NAME = PLATFORM_DISPLAY_NAMES[MCP_PLATFORM];
+/** 本 MCP server 的包名 / 日志前缀基名 */
+const MCP_SERVER_NAME = `html-to-${MCP_PLATFORM}-mcp`;
+/** stdout 归 MCP JSON-RPC 独占，本进程所有日志走 stderr */
+function mcpLog(message) {
+	process.stderr.write(`[${MCP_SERVER_NAME}] ${message}\n`);
+}
+//#endregion
+//#region src/import-source.ts
+const DEFAULT_VIEWPORT = {
+	width: 1920,
+	height: 1080
+};
+const MAX_PATH_LEN = 4096;
+const defaultIO = { readFile: (p) => readFile(p) };
+/** html 二义消解：绝对路径且不含换行且长度合理 → path，否则 content */
+function resolveHtmlInput(html) {
+	if (path.isAbsolute(html) && !html.includes("\n") && html.length <= MAX_PATH_LEN) return { kind: "path" };
+	return { kind: "content" };
+}
+function isEnoent(e) {
+	return typeof e === "object" && e !== null && e.code === "ENOENT";
+}
+async function normalizeHtmlSource(args, io = defaultIO) {
+	const input = resolveHtmlInput(args.html);
+	let html;
+	let baseDir;
+	if (input.kind === "path") {
+		try {
+			html = (await io.readFile(args.html)).toString("utf8");
+		} catch (e) {
+			if (isEnoent(e)) throw new Error(`${args.html} (ENOENT)`);
+			throw e;
+		}
+		baseDir = path.dirname(args.html);
+	} else html = args.html;
+	const pageName = input.kind === "path" ? path.basename(args.html) : void 0;
+	const assets = [];
+	for (const asset of args.assets ?? []) {
+		let bytes;
+		try {
+			bytes = await io.readFile(asset.path);
+		} catch (e) {
+			if (isEnoent(e)) throw new Error(`${asset.path} (ENOENT)`);
+			throw e;
+		}
+		const as = (asset.as ?? (baseDir ? path.relative(baseDir, asset.path).split(path.sep).join("/") : path.basename(asset.path))).replace(/^\.\//, "");
+		assets.push({
+			as,
+			dataBase64: bytes.toString("base64")
+		});
+	}
+	return {
+		kind: "html",
+		pageName,
+		html,
+		assets,
+		viewport: {
+			width: args.width ?? DEFAULT_VIEWPORT.width,
+			height: args.height ?? DEFAULT_VIEWPORT.height
+		},
+		target: args.target
+	};
+}
+//#endregion
+//#region src/tools.ts
+const targetSchema = z.object({
+	mode: z.enum(["insert", "replace"]),
+	nodeId: z.string()
+}).optional();
+function textResult(obj) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(obj)
+	}] };
+}
+function errorResult(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+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");
+		const taskId = randomUUID();
+		const submitP = hub.submit({
+			taskId,
+			kind,
+			payload
+		});
+		if (!wait) {
+			submitP.catch(() => {});
+			return textResult({ taskId });
+		}
+		try {
+			return textResult(await submitP);
+		} catch (e) {
+			return errorResult(e.message);
+		}
+	}
+	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.`,
+		inputSchema: {
+			html: z.string(),
+			assets: z.array(z.object({
+				path: z.string(),
+				as: z.string().optional()
+			})).optional(),
+			width: z.number().optional(),
+			height: z.number().optional(),
+			target: targetSchema,
+			wait: z.boolean().optional()
+		}
+	}, async (args) => {
+		let source;
+		try {
+			source = await normalizeHtmlSource(args);
+		} catch (e) {
+			return errorResult(e.message);
+		}
+		return runTask("html", source, args.wait ?? true);
+	});
+	server.registerTool("import_url", {
+		description: `Import a web page URL into ${MCP_PLATFORM_NAME}.`,
+		inputSchema: {
+			url: z.string(),
+			width: z.number().optional(),
+			height: z.number().optional(),
+			theme: z.string().optional(),
+			locale: z.string().optional(),
+			target: targetSchema,
+			wait: z.boolean().optional()
+		}
+	}, async (args) => {
+		return runTask("url", {
+			kind: "url",
+			url: args.url,
+			viewport: {
+				width: args.width ?? DEFAULT_VIEWPORT.width,
+				height: args.height ?? DEFAULT_VIEWPORT.height
+			},
+			theme: args.theme,
+			locale: args.locale,
+			target: args.target
+		}, args.wait ?? true);
+	});
+	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)");
+		try {
+			return textResult(await hub.taskWait(args.taskId));
+		} catch (e) {
+			return errorResult(e.message);
+		}
+	});
+	server.registerTool("get_task_status", {
+		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)");
+		try {
+			return textResult(await hub.taskQuery(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() }
+	}, async (args) => {
+		if (!hub.connected) return textResult({
+			ws_port: hub.port,
+			connected: false,
+			plugin: null
+		});
+		try {
+			const status = await hub.statusQuery({ includeTasks: args.include_tasks });
+			return textResult({
+				ws_port: hub.port,
+				connected: true,
+				plugin: {
+					queue: status.queue,
+					...status.tasks ? { tasks: status.tasks } : {}
+				}
+			});
+		} catch (e) {
+			return errorResult(e.message);
+		}
+	});
+}
+//#endregion
+//#region src/server.ts
+function createServer$1(deps) {
+	const server = new McpServer({
+		name: MCP_SERVER_NAME,
+		version: MCP_SERVER_VERSION
+	});
+	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–5499 段，按平台每 100 一格。
+* 每个新 MCP 产品应选独立的 base（如 6000/7000/...），互不重叠。
+*/
+const PLATFORM_PORT_BASE = {
+	figma: 5e3,
+	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;
+function defaultOriginCheck(origin) {
+	if (!origin || origin === "null") return true;
+	try {
+		const host = new URL(origin).hostname;
+		return host === "127.0.0.1" || host === "localhost";
+	} catch {
+		return false;
+	}
+}
+/**
+* MCP server 通用基座：portRange 内挑空闲端口绑 socket.io + 处理应用层 hello 握手（含 occupied /
+* force takeover）+ 维护主插件 socket。产品子类通过 opts 注入自己的 magic/事件监听器，
+* 用 protected getPlugin() 主动 emit 业务事件。
+*/
+var WsHubBase = class {
+	opts;
+	io = null;
+	plugin = null;
+	boundPort = 0;
+	pluginCleanups = /* @__PURE__ */ new Set();
+	/** 进程唯一身份，握手时通过 HelloAck 传给插件 —— 让插件能区分同 port 前后两个不同进程 */
+	connectionId = randomUUID();
+	constructor(opts) {
+		this.opts = opts;
+	}
+	get port() {
+		return this.boundPort;
+	}
+	get connected() {
+		return this.plugin !== null;
+	}
+	/** 返回当前活跃的插件 socket，供子类主动 emit 业务事件（如 task:submit）*/
+	getPlugin() {
+		return this.plugin;
+	}
+	async listen() {
+		const { start, end } = this.opts.portRange;
+		const originCheck = this.opts.allowedOrigins ?? defaultOriginCheck;
+		for (let p = start; p <= end; p++) try {
+			await this.tryListen(p, originCheck);
+			this.boundPort = p;
+			return p;
+		} catch (e) {
+			if (e.code === "EADDRINUSE") continue;
+			throw e;
+		}
+		throw new Error(`No free port in range ${start}-${end}`);
+	}
+	tryListen(port, originCheck) {
+		return new Promise((resolve, reject) => {
+			const http = createServer();
+			const io = new Server(http, {
+				maxHttpBufferSize: MAX_HTTP_BUFFER_SIZE,
+				transports: ["websocket"],
+				allowRequest: (req, cb) => cb(null, originCheck(req.headers.origin)),
+				cors: { origin: false }
+			});
+			io.on("connection", (socket) => this.onConnection(socket));
+			const onError = (e) => {
+				io.close();
+				http.close();
+				reject(e);
+			};
+			http.once("error", onError);
+			http.listen(port, "127.0.0.1", () => {
+				http.removeListener("error", onError);
+				this.io = io;
+				resolve();
+			});
+		});
+	}
+	onConnection(socket) {
+		socket.on("hello", (payload, ack) => {
+			if (payload?.magic !== this.opts.magic || payload?.protocolVersion !== this.opts.protocolVersion) {
+				ack({ error: { reason: "magic" } });
+				socket.disconnect(true);
+				return;
+			}
+			if (payload.platform !== this.opts.platformTag) {
+				ack({ error: { reason: "platform" } });
+				socket.disconnect(true);
+				return;
+			}
+			if (this.plugin && this.plugin.connected) {
+				if (!payload.force) {
+					ack({ error: {
+						reason: "occupied",
+						occupiedBy: this.opts.agent
+					} });
+					socket.disconnect(true);
+					return;
+				}
+				this.plugin.emit("superseded", {});
+				this.plugin.disconnect(true);
+			}
+			this.bindPlugin(socket);
+			ack({
+				agent: this.opts.agent,
+				wsPort: this.boundPort,
+				connectionId: this.connectionId
+			});
+		});
+	}
+	bindPlugin(socket) {
+		this.plugin = socket;
+		const cleanup = this.opts.onPluginBound?.(socket);
+		if (cleanup) this.pluginCleanups.add(cleanup);
+		socket.on("disconnect", () => {
+			if (this.plugin === socket) this.plugin = null;
+			const cleanups = [...this.pluginCleanups];
+			this.pluginCleanups.clear();
+			for (const fn of cleanups) try {
+				fn();
+			} catch {}
+		});
+	}
+	/** 握手完成后用真实 clientInfo 覆盖占位 agent（供子类/调用方 setAgent 使用）*/
+	setAgent(agent) {
+		this.opts.agent = agent;
+	}
+	async close() {
+		this.plugin?.disconnect(true);
+		this.plugin = null;
+		await new Promise((resolve) => {
+			if (!this.io) {
+				resolve();
+				return;
+			}
+			this.io.close(() => resolve());
+		});
+		this.io = null;
+	}
+};
+//#endregion
+//#region src/ws-hub.ts
+/**
+* html-to-figma MCP 的 server：在 `WsHubBase`（端口绑定 + hello 握手 + plugin socket 生命
+* 周期）之上加 task 命令与查询 RPC，全部走 socket.io ack 现问现答，本类不缓存任何 task 状态
+* （真源在插件的 active + history）。
+*/
+var WsHub = class extends WsHubBase {
+	/** 已 emit 但插件尚未 ack 的请求。插件掉线时统一 reject —— socket.io 不会自动结算掉线时的
+	* ack callback，不主动 reject 的话 wait:true 的 submit / taskWait / 查询类都会永远 hang */
+	pendingAcks = /* @__PURE__ */ new Set();
+	constructor(opts) {
+		super({
+			magic: MAGIC,
+			protocolVersion: 1,
+			platformTag: opts.platform,
+			agent: opts.agent,
+			portRange: getHtmlToFigmaPortRange(opts.platform),
+			allowedOrigins: opts.allowedOrigins,
+			onPluginBound: () => () => {
+				const pending = [...this.pendingAcks];
+				this.pendingAcks.clear();
+				for (const rejectFn of pending) rejectFn(/* @__PURE__ */ new Error("NO_PLUGIN: plugin disconnected before ack"));
+			}
+		});
+	}
+	emitWithAck(event, payload) {
+		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);
+			this.pendingAcks.add(abort);
+			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);
+			});
+		});
+	}
+	submit(payload) {
+		return this.emitWithAck("task:submit", payload);
+	}
+	cancel(taskId) {
+		this.getPlugin()?.emit("task:cancel", { taskId });
+	}
+	taskWait(taskId) {
+		return this.emitWithAck("task:wait", { taskId });
+	}
+	taskQuery(taskId) {
+		return this.emitWithAck("task:query", { taskId });
+	}
+	statusQuery(req) {
+		return this.emitWithAck("status:query", req);
+	}
+};
+//#endregion
+//#region src/index.ts
+async function main() {
+	const hub = new WsHub({
+		platform: MCP_PLATFORM,
+		agent: {
+			name: "unknown",
+			version: "0",
+			cwd: process.cwd()
+		}
+	});
+	mcpLog(`WS listening on 127.0.0.1:${await hub.listen()}`);
+	const server = createServer$1({ hub });
+	server.server.oninitialized = () => {
+		const info = server.server.getClientVersion();
+		if (info) hub.setAgent({
+			name: info.name,
+			version: info.version,
+			cwd: process.cwd()
+		});
+	};
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+main().catch((e) => {
+	mcpLog(`fatal: ${e.stack ?? e}`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@refore-ai/html-to-figma-mcp",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "html-to-figma-mcp": "index.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "socket.io": "^4.8.3",
+    "zod": "^3.25.76"
+  }
+}