@skillbuilder/minitool-e2e 0.0.0-beta-20261027053041051

package/lib/mcp/server.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMinitoolE2ETools = registerMinitoolE2ETools;
+exports.createMinitoolE2EMcpServer = createMinitoolE2EMcpServer;
+/**
+ * 把一套会话暴露成 14 个 MCP tool（stdio + JSON-RPC）。工具分两组、名字就是边界，权威清单在
+ * `../contract.ts`；只剩 network 尚未实现，如实返回 not_implemented。
+ *
+ * 下面的名字仍写字面量（比 `E2E_TOOL_NAMES[3]` 可读），靠 `contract.test.ts` 断言
+ * 「注册集合 === contract 声明集合」双向一致兜底 —— 少注册或拼错都会红。
+ *
+ * MCP 这一层的意义是能力隔离：独立进程、独立依赖（chromium 只在这侧），出码 Agent 只认工具名，
+ * 以后换远端浏览器集群或给别的 Agent 复用都只需换端点。
+ *
+ * ⚠️ 一个进程只服务**一个**会话。并发靠起多个进程 —— 沙箱 1 核 2GiB，并发浏览器只会互相拖死。
+ */
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const contract_1 = require("../contract");
+const session_1 = require("../session");
+/**
+ * ★ 必须取 contract.ts 那个常量，不能在这里另写一遍字面量：
+ * prompt 里点名的工具名是 `mcp__{这个 server 名}__{工具名}`（由 contract 的 `toMcpToolName` 推导）。
+ * 两边一旦漂移，**每一个** prompt 里的工具名都会是错的，而下面那个一致性测试比的是裸工具名、
+ * 抓不到这种漂移 —— 所以只能靠同源。
+ */
+const SERVER_NAME = contract_1.MINITOOL_E2E_MCP_SERVER_NAME;
+const SERVER_VERSION = "0.0.1";
+/**
+ * 把 E2E tools 注册到调用方提供的 server，供 redminitool 聚合认证、构建、发布等能力。
+ * E2E 包只拥有自己的工具与会话状态，不再强制拥有整个 MCP server。
+ */
+function registerMinitoolE2ETools(server, opts = {}) {
+    let session = null;
+    const requireSession = () => {
+        if (!session)
+            throw new Error("尚未打开会话，请先调用 e2e_open。");
+        return session;
+    };
+    const asJson = (value) => ({
+        content: [{ type: "text", text: JSON.stringify(value ?? null, null, 2) }],
+    });
+    // ══ 通用能力：任何产物形态都成立 ══
+    server.registerTool("e2e_open", {
+        title: "Open artifact",
+        description: "Launch Chromium + miniapp-simulator and load the built artifact. Must be called first. " +
+            "Does NOT probe the game bridge — call e2e_game_attach for that (games only).",
+        inputSchema: {
+            distDir: zod_1.z.string().optional().describe("Artifact directory containing index.html"),
+            entry: zod_1.z.string().optional(),
+            viewport: zod_1.z
+                .object({
+                width: zod_1.z.number().int().positive(),
+                height: zod_1.z.number().int().positive(),
+                deviceScaleFactor: zod_1.z.number().positive().optional(),
+            })
+                .optional(),
+        },
+    }, async ({ distDir, entry, viewport }) => {
+        const target = distDir ?? opts.distDir ?? process.env.MINITOOL_E2E_DIST_DIR;
+        if (!target) {
+            throw new Error("缺少产物目录：请传 distDir 或设置 MINITOOL_E2E_DIST_DIR。");
+        }
+        if (session) {
+            await session.close().catch(() => undefined);
+            session = null;
+        }
+        // ★ open 失败必须就地收尾，否则进程再也退不掉（实测踩过）：create() 先起 Chromium、
+        // open() 才读产物目录 ⇒ 目录有问题时**浏览器已经在跑**。留着它会让事件循环永不为空，
+        // MCP client 断开后进程也不退，在沙箱里就是个吃满内存的孤儿；后续工具还会打到一个
+        // 什么都没加载的页面上，报出完全指错方向的错。
+        const pending = await session_1.MinitoolE2ESession.create({ ...opts, viewport: opts.viewport });
+        try {
+            const result = await pending.open({ distDir: target, entry, viewport });
+            session = pending;
+            return asJson(result);
+        }
+        catch (err) {
+            await pending.close().catch(() => undefined);
+            throw err;
+        }
+    });
+    server.registerTool("e2e_logs", {
+        title: "Read runtime logs",
+        description: "Drain simulator console output, guest errors, CSP violations and failed requests.",
+        inputSchema: { level: zod_1.z.enum(["debug", "info", "warn", "error"]).optional() },
+    }, async ({ level }) => asJson(await requireSession().logs(level)));
+    server.registerTool("e2e_screenshot", {
+        title: "Capture frame",
+        description: "Capture the current rendered frame for visual verification.",
+        inputSchema: {},
+    }, async () => {
+        const shot = await requireSession().screenshot();
+        return {
+            content: [
+                // ★ 这个 text part 同时是「图片已进桶」的**声明**：出码侧 event-bridge 看它里面有没有非空
+                //   `url`，来决定要不要把下面的 image part 剥掉再推给浏览器（见 agentbase 的
+                //   `stripUploadedImageParts`，`codegen-agent/src/codegen/shared/event-bridge.ts` 是调用方）。
+                //   改这里的 JSON 形状前先看那两处 —— 形状一变，剥图判定就失效，base64 又会开始往前端传，
+                //   而前端还在等 url。
+                //   `description` 是人话，模型读的是它；`url` / `fileKey` 是给前端和排障用的。
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        description: shot.description,
+                        url: shot.url ?? null,
+                        fileKey: shot.fileKey ?? null,
+                    }),
+                },
+                // 模型必须真看到这一帧（`contract.ts` 的流程明确要求「看首帧」），所以 image part 删不得 ——
+                // 被剥掉的只是推给浏览器的那一份副本。
+                { type: "image", data: shot.data, mimeType: shot.mimeType },
+            ],
+        };
+    });
+    server.registerTool("e2e_close", {
+        title: "Close session",
+        description: "Close the e2e session and release Chromium after collecting evidence.",
+        inputSchema: {},
+    }, async () => {
+        if (!session)
+            return asJson({ closed: false });
+        const result = await session.close();
+        session = null;
+        return asJson(result);
+    });
+    // 以下 1 个**尚未实现**（network）。description 第一句与返回体都刻意写明「不可作为判定依据」且
+    // 不含空集合 —— 否则模型会把空结果读成「查过了没问题」并据此判 PASS，那比没有这个工具更糟。
+    server.registerTool("e2e_network", {
+        title: "Observe network (not implemented)",
+        description: "NOT IMPLEMENTED — the result must not be used as evidence. " +
+            "Intended to list requests the mini-tool made, with status code and response body.",
+        inputSchema: {
+            scope: zod_1.z.enum(["all", "failed"]).optional(),
+            limit: zod_1.z.number().int().positive().optional(),
+        },
+    }, async ({ scope, limit }) => asJson(await requireSession().network({ scope, limit })));
+    server.registerTool("e2e_dom", {
+        title: "Inspect rendered DOM",
+        description: "Summarise the rendered DOM so blank-screen and whether a required element exists can " +
+            "be judged without a screenshot. Each node carries a stable CSS selector, tag, text and " +
+            "rect (in logical CSS px, same space as e2e_screenshot and e2e_interact x/y). For canvas " +
+            "/ game artifacts this also returns sceneTree — the read-only Pixi/Three scene hierarchy " +
+            "from the simulator inspector. Each scene node has: ref (unique, `<providerId>:<node>`), " +
+            "label, visible, selectable (whether it can be hit), and source.file + source.definitionKey " +
+            "(source location). Multiple canvases appear as multiple providers (each with providerId + " +
+            "engine); refs are providerId-prefixed so they stay unique.",
+        inputSchema: {
+            selector: zod_1.z.string().optional(),
+            maxNodes: zod_1.z.number().int().positive().optional(),
+        },
+    }, async ({ selector, maxNodes }) => asJson(await requireSession().dom({ selector, maxNodes })));
+    server.registerTool("e2e_interact", {
+        title: "Dispatch a simulator gesture or guest input",
+        description: "Dispatch a simulator-backed gesture, reload or guest input against any artifact (unlike e2e_game_act, " +
+            "which uses the game bridge). Prefer `selector` (targets the element center); only use x/y for " +
+            "canvas/composite UI where a selector cannot reach. x/y are logical CSS px — same scale as " +
+            "e2e_screenshot and e2e_dom rect (see the viewport field on e2e_open).",
+        inputSchema: {
+            action: zod_1.z.enum(["tap", "doubleTap", "longPress", "scroll", "swipe", "input", "reload"]),
+            selector: zod_1.z.string().optional(),
+            text: zod_1.z.string().optional(),
+            x: zod_1.z.number().optional(),
+            y: zod_1.z.number().optional(),
+            toX: zod_1.z.number().optional(),
+            toY: zod_1.z.number().optional(),
+            deltaX: zod_1.z
+                .number()
+                .optional()
+                .describe("Horizontal scroll distance; scroll requires a non-zero deltaX or deltaY"),
+            deltaY: zod_1.z
+                .number()
+                .optional()
+                .describe("Vertical scroll distance; scroll requires a non-zero deltaX or deltaY"),
+            duration: zod_1.z.number().optional(),
+        },
+    }, async (input) => asJson(await requireSession().interact(input)));
+    server.registerTool("e2e_health", {
+        title: "Runtime health summary",
+        description: "Summarise uncaught guest errors, console errors/warnings and navigation into explicit " +
+            "counts plus a small sample. Returns status ok/degraded; never an empty collection.",
+        inputSchema: {},
+    }, async () => asJson(await requireSession().health()));
+    // ══ 游戏专属：全部经 window.__GAME_TEST__ 桥，只有 game_2d/game_3d 模板在 ?playtest=1 下才挂。
+    // 非游戏产物调下面任何一个都会 reject ⇒ 先用 e2e_game_attach 判定桥在不在。
+    server.registerTool("e2e_game_attach", {
+        title: "Attach game bridge",
+        description: "Wait for the artifact's game test bridge and report whether it exists. " +
+            "Games only: call it after e2e_open and before any other e2e_game_* tool. " +
+            "A non-game artifact will wait out the timeout and report bridgeAvailable=false.",
+        inputSchema: { timeoutMs: zod_1.z.number().int().positive().max(60_000).optional() },
+    }, async ({ timeoutMs }) => asJson(await requireSession().gameAttach(timeoutMs)));
+    server.registerTool("e2e_game_manifest", {
+        title: "Read game rules",
+        description: "Read the game test manifest: objective, supported actions, milestones, win/loss rules.",
+        inputSchema: {},
+    }, async () => asJson(await requireSession().manifest()));
+    server.registerTool("e2e_game_snapshot", {
+        title: "Inspect game state",
+        description: "Read a semantic snapshot of current game state (phase, player, score, entities).",
+        inputSchema: {},
+    }, async () => asJson(await requireSession().snapshot()));
+    server.registerTool("e2e_game_act", {
+        title: "Play game action",
+        description: "Perform one manifest-declared action, then return the observed result.",
+        inputSchema: { action: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()) },
+    }, async ({ action }) => asJson(await requireSession().act(action)));
+    server.registerTool("e2e_game_step", {
+        title: "Advance game clock",
+        description: "Advance the deterministic clock by N ms. Also the way to force a render frame — " +
+            "playtest mode stops the ticker, and pointer hit-testing silently fails before the first render.",
+        inputSchema: { ms: zod_1.z.number().int().min(1).max(30_000) },
+    }, async ({ ms }) => asJson(await requireSession().step(ms)));
+    server.registerTool("e2e_game_reset", {
+        title: "Reset game",
+        description: "Reset the game, optionally with a deterministic random seed.",
+        inputSchema: { seed: zod_1.z.number().int().optional() },
+    }, async ({ seed }) => asJson(await requireSession().reset(seed)));
+}
+function createMinitoolE2EMcpServer(opts = {}) {
+    const server = new mcp_js_1.McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    registerMinitoolE2ETools(server, opts);
+    return server;
+}

package/lib/mcp/stdio-entry.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * MCP stdio 入口。★ stdout 是 JSON-RPC 通道，**任何**多余输出都会破坏协议帧 ——
+ * 本进程所有日志一律走 stderr，别在任何地方 console.log。
+ */
+const stdio_1 = require("./stdio");
+(0, stdio_1.runMinitoolE2EStdioServer)().catch((err) => {
+    process.stderr.write(`[minitool-e2e] MCP server failed: ${err instanceof Error ? err.stack : String(err)}\n`);
+    process.exit(1);
+});

package/lib/mcp/stdio.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMinitoolE2EStdioServer = runMinitoolE2EStdioServer;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const server_1 = require("./server");
+/**
+ * 在 stdio 上启动小工具 MCP server。
+ *
+ * stdout 是 MCP JSON-RPC 专用通道，这里以及调用方都不得向 stdout 输出日志。
+ */
+async function runMinitoolE2EStdioServer(opts = {}) {
+    const server = (0, server_1.createMinitoolE2EMcpServer)({
+        ...opts,
+        distDir: opts.distDir ?? process.env.MINITOOL_E2E_DIST_DIR,
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("[minitool-e2e] MCP server ready on stdio\n");
+}