ms-vite-plugin 1.1.2 → 1.1.3

package/dist/mcp/tools.js

@@ -0,0 +1,825 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DEVICE_PORT = void 0;
+exports.createMcpServer = createMcpServer;
+const mcp_1 = require("@modelcontextprotocol/sdk/server/mcp");
+const z = __importStar(require("zod/v4"));
+const fsExtra = __importStar(require("fs-extra"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const build_1 = require("../build");
+const packager_1 = require("../packager");
+const project_1 = require("../project");
+const ws_manager_1 = require("../ws-manager");
+const project_2 = require("./project");
+const device_config_1 = require("./device-config");
+Object.defineProperty(exports, "DEFAULT_DEVICE_PORT", { enumerable: true, get: function () { return device_config_1.DEFAULT_DEVICE_PORT; } });
+const docs_service_1 = require("./docs-service");
+const types_1 = require("./types");
+const version_1 = require("../version");
+/**
+ * 注册文档资源
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerDocResources(server)
+ */
+function registerDocResources(server) {
+    server.registerResource("current-language", "kuaijs://docs/current-language", {
+        title: "Current KuaiJS API language",
+        mimeType: "application/json",
+    }, async () => {
+        const language = (0, docs_service_1.getCurrentDocsLanguage)();
+        return {
+            contents: [
+                {
+                    uri: "kuaijs://docs/current-language",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        currentLanguage: language,
+                        label: types_1.DOC_LANGUAGE_LABELS[language],
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerResource("api-doc", new mcp_1.ResourceTemplate("kuaijs://docs/current/{slug}", {
+        list: async () => {
+            const language = (0, docs_service_1.getCurrentDocsLanguage)();
+            const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
+            return {
+                resources: docs.map((doc) => ({
+                    uri: `kuaijs://docs/current/${doc.slug}`,
+                    name: doc.title,
+                    description: `[${types_1.DOC_LANGUAGE_LABELS[language]}] ${doc.slug}`,
+                    mimeType: "text/markdown",
+                })),
+            };
+        },
+    }), {
+        title: "KuaiJS API documents",
+        mimeType: "text/markdown",
+    }, async (_uri, variables) => {
+        const language = (0, docs_service_1.getCurrentDocsLanguage)();
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
+        const slug = String(variables.slug || "");
+        const target = docs.find((doc) => doc.slug === slug);
+        if (!target) {
+            throw new Error(`文档不存在: ${slug}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: `kuaijs://docs/current/${target.slug}`,
+                    mimeType: "text/markdown",
+                    text: target.content,
+                },
+            ],
+        };
+    });
+}
+/**
+ * 注册文档工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerDocTools(server)
+ */
+function registerDocTools(server) {
+    server.registerTool("get_docs_language", {
+        title: "Get Docs Language",
+        description: "获取当前 KuaiJS API 文档语言。",
+        inputSchema: {},
+    }, async () => {
+        const language = (0, docs_service_1.getCurrentDocsLanguage)();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `当前文档语言: ${language} (${types_1.DOC_LANGUAGE_LABELS[language]})`,
+                },
+            ],
+        };
+    });
+    server.registerTool("set_docs_language", {
+        title: "Set Docs Language",
+        description: "设置当前 KuaiJS API 文档语言，影响后续文档查询与读取。",
+        inputSchema: {
+            language: z
+                .enum(["js", "js_zh", "python"])
+                .describe("文档语言：js | js_zh | python"),
+        },
+    }, async ({ language }) => {
+        const active = (0, docs_service_1.setCurrentDocsLanguage)(language);
+        const docsDir = (0, docs_service_1.getDocsDirByLanguage)(active);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `文档语言已切换为 ${active} (${types_1.DOC_LANGUAGE_LABELS[active]})\n目录: ${docsDir}`,
+                },
+            ],
+        };
+    });
+    server.registerTool("list_api_docs", {
+        title: "List API Docs",
+        description: "列出当前（或指定）语言下可用的 API 文档。",
+        inputSchema: {
+            language: z
+                .enum(["js", "js_zh", "python"])
+                .optional()
+                .describe("可选语言，不传则使用当前语言"),
+        },
+    }, async ({ language }) => {
+        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
+        const lines = docs.map((doc, index) => `${index + 1}. ${doc.title}\nslug: ${doc.slug}\nuri: ${(0, docs_service_1.getDocUri)(activeLanguage, doc.slug)}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: lines.length === 0
+                        ? `当前语言 ${activeLanguage} 下没有可用文档。`
+                        : [
+                            `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
+                            "",
+                            ...lines,
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.registerTool("search_api_docs", {
+        title: "Search API Docs",
+        description: "在当前（或指定）语言文档中按关键字搜索。",
+        inputSchema: {
+            query: z.string().min(1).describe("搜索关键字"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .default(5)
+                .describe("返回条数上限，默认 5"),
+            language: z
+                .enum(["js", "js_zh", "python"])
+                .optional()
+                .describe("可选语言，不传则使用当前语言"),
+        },
+    }, async ({ query, limit, language }) => {
+        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
+        const normalizedQuery = query.toLowerCase();
+        const matches = docs
+            .map((doc) => ({ doc, score: (0, docs_service_1.scoreApiDoc)(doc, normalizedQuery) }))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score || a.doc.slug.localeCompare(b.doc.slug))
+            .slice(0, limit)
+            .map((item) => item.doc);
+        const text = matches.length === 0
+            ? `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})\n未找到与 "${query}" 匹配的文档。`
+            : [
+                `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
+                "",
+                ...matches.map((doc, index) => `${index + 1}. ${doc.title}\nslug: ${doc.slug}\nuri: ${(0, docs_service_1.getDocUri)(activeLanguage, doc.slug)}`),
+            ].join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+        };
+    });
+    server.registerTool("read_api_doc", {
+        title: "Read API Doc",
+        description: "读取当前（或指定）语言下某个文档的完整 markdown 内容。",
+        inputSchema: {
+            slug: z.string().min(1).describe("文档 slug（文件名，不含 .md）"),
+            language: z
+                .enum(["js", "js_zh", "python"])
+                .optional()
+                .describe("可选语言，不传则使用当前语言"),
+        },
+    }, async ({ slug, language }) => {
+        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
+        const target = docs.find((doc) => doc.slug === slug);
+        if (!target) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `未找到文档 ${slug}.md（语言: ${activeLanguage}）。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `标题: ${target.title}\n语言: ${activeLanguage}\nURI: ${(0, docs_service_1.getDocUri)(activeLanguage, target.slug)}\n\n${target.content}`,
+                },
+            ],
+        };
+    });
+}
+/**
+ * 注册设备与项目执行工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerRuntimeTools(server)
+ */
+function registerRuntimeTools(server) {
+    /**
+     * 解析运行目标：
+     * - 显式 transport=ws: 强制走 ws
+     * - 显式 transport=http: 强制走 http
+     * - 未显式 transport:
+     *   1) 若传入 ip/port，则走 http
+     *   2) 若当前已有 ws 设备连接，则优先走 ws
+     *   3) 否则回退到 http 默认设备配置
+     * @param options 工具调用参数
+     * @returns 返回标准化后的请求目标
+     * @example
+     * const target = await resolvePreferredRuntimeTarget({ ip: "192.168.1.10" })
+     */
+    async function resolvePreferredRuntimeTarget(options) {
+        const hasHttpHint = options.ip !== undefined || options.port !== undefined;
+        const shouldUseWs = options.transport === "ws" ||
+            (options.transport === undefined &&
+                !hasHttpHint &&
+                ws_manager_1.WSManager.isConnected());
+        if (shouldUseWs) {
+            const wsPort = String(options.wsPort ?? 31111);
+            const wsWaitMs = String(options.wsWaitMs ?? 30000);
+            return {
+                transport: "ws",
+                wsPort,
+                wsWaitMs,
+                label: `transport=ws (wsPort=${wsPort})`,
+            };
+        }
+        const device = await (0, device_config_1.resolveDeviceConfig)(options.ip, options.port);
+        return {
+            transport: "http",
+            ip: device.ip,
+            port: (0, device_config_1.normalizePort)(device.port),
+            label: `${device.ip}:${device.port}`,
+        };
+    }
+    server.registerTool("set_device", {
+        title: "Set Device",
+        description: "设置默认设备连接信息。首次配置后，后续 run/stop 可不再传 ip。",
+        inputSchema: {
+            ip: z.string().min(1).describe("设备 IP 地址，例如 192.168.1.100"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+        },
+    }, async ({ ip, port }) => {
+        const config = await (0, device_config_1.setDeviceConfig)(ip, port);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `默认设备已设置为 ${config.ip}:${config.port}`,
+                },
+            ],
+        };
+    });
+    server.registerTool("get_device", {
+        title: "Get Device",
+        description: "查看当前默认设备配置。",
+        inputSchema: {},
+    }, async () => {
+        const config = await (0, device_config_1.readDeviceConfig)();
+        if (!config) {
+            return {
+                content: [
+                    { type: "text", text: "当前未设置默认设备，请先调用 set_device。" },
+                ],
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: `当前默认设备: ${config.ip}:${config.port}` },
+            ],
+        };
+    });
+    server.registerTool("take_screenshot", {
+        title: "Take Screenshot",
+        description: "获取设备截图。可返回 base64，或落地到文件后返回文件路径（默认写入系统临时目录）。",
+        inputSchema: {
+            transport: z
+                .enum(["http", "ws"])
+                .optional()
+                .describe("传输方式：http|ws；不传时自动优先 ws（若已连接）"),
+            ip: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("设备 IP 地址（transport=http 时可传；未传则使用 set_device 默认值）"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+            wsPort: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("WS 服务端口（transport=ws 时可选，默认 31111）"),
+            wsWaitMs: z
+                .number()
+                .int()
+                .min(1)
+                .max(600000)
+                .optional()
+                .describe("WS 等待连接超时毫秒（transport=ws 时可选，默认 30000）"),
+            format: z
+                .enum(["file", "base64"])
+                .optional()
+                .default("file")
+                .describe("截图返回格式：file=文件路径，base64=图片 base64"),
+            outputPath: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("当 format=file 时可指定输出路径，不传则写入系统临时目录"),
+        },
+    }, async ({ transport, ip, port, wsPort, wsWaitMs, format, outputPath }) => {
+        const target = await resolvePreferredRuntimeTarget({
+            transport,
+            ip,
+            port,
+            wsPort,
+            wsWaitMs,
+        });
+        const requestOptions = target.transport === "ws"
+            ? {
+                transport: "ws",
+                wsPort: target.wsPort,
+                wsWaitMs: target.wsWaitMs,
+            }
+            : {
+                ip: target.ip,
+                port: target.port,
+                transport: "http",
+            };
+        if (format === "base64") {
+            const base64 = await (0, project_1.getScreenshotBase64OnDevice)(requestOptions);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `截图成功: ${target.label}\nformat: base64\n${base64}`,
+                    },
+                ],
+            };
+        }
+        const image = await (0, project_1.getScreenshotOnDevice)(requestOptions);
+        const targetPath = outputPath && outputPath.trim()
+            ? path.resolve(outputPath.trim())
+            : path.join(os.tmpdir(), `ms-mcp-screenshot-${Date.now()}-${Math.random()
+                .toString(36)
+                .slice(2, 8)}.jpg`);
+        await fsExtra.ensureDir(path.dirname(targetPath));
+        await fsExtra.writeFile(targetPath, image);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `截图成功: ${target.label}\nformat: file\npath: ${targetPath}\nsize: ${image.length} bytes`,
+                },
+            ],
+        };
+    });
+    server.registerTool("get_node_source", {
+        title: "Get Node Source",
+        description: "获取设备当前页面节点 XML（/api/source）。",
+        inputSchema: {
+            transport: z
+                .enum(["http", "ws"])
+                .optional()
+                .describe("传输方式：http|ws；不传时自动优先 ws（若已连接）"),
+            ip: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("设备 IP 地址（transport=http 时可传；未传则使用 set_device 默认值）"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+            wsPort: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("WS 服务端口（transport=ws 时可选，默认 31111）"),
+            wsWaitMs: z
+                .number()
+                .int()
+                .min(1)
+                .max(600000)
+                .optional()
+                .describe("WS 等待连接超时毫秒（transport=ws 时可选，默认 30000）"),
+            maxDepth: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .default(50)
+                .describe("节点树最大深度，默认 50"),
+            timeout: z
+                .number()
+                .int()
+                .min(1)
+                .max(600)
+                .optional()
+                .default(120)
+                .describe("设备端节点抓取超时秒数，默认 120"),
+        },
+    }, async ({ transport, ip, port, wsPort, wsWaitMs, maxDepth, timeout }) => {
+        const target = await resolvePreferredRuntimeTarget({
+            transport,
+            ip,
+            port,
+            wsPort,
+            wsWaitMs,
+        });
+        const requestOptions = target.transport === "ws"
+            ? {
+                transport: "ws",
+                wsPort: target.wsPort,
+                wsWaitMs: target.wsWaitMs,
+            }
+            : {
+                ip: target.ip,
+                port: target.port,
+                transport: "http",
+            };
+        const source = await (0, project_1.getSourceOnDevice)(requestOptions, maxDepth, timeout);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `节点获取成功: ${target.label}\nmaxDepth: ${maxDepth}\ntimeout: ${timeout}\n\n${source}`,
+                },
+            ],
+        };
+    });
+    server.registerTool("watch_logs", {
+        title: "Watch Logs",
+        description: "通过 SSE 监听设备日志并自动判定异常。首次可传 ip，也可复用 set_device 保存的默认设备。",
+        inputSchema: {
+            ip: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("设备 IP 地址，未传则使用 set_device 保存的默认值"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+            durationSeconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(300)
+                .optional()
+                .default(15)
+                .describe("监听时长（秒），默认 15 秒，最大 300 秒"),
+            maxLogs: z
+                .number()
+                .int()
+                .min(10)
+                .max(5000)
+                .optional()
+                .default(200)
+                .describe("最多收集日志条数，默认 200"),
+        },
+    }, async ({ ip, port, durationSeconds, maxLogs }) => {
+        await (0, project_2.ensureValidKuaiJSProject)(process.cwd());
+        const device = await (0, device_config_1.resolveDeviceConfig)(ip, port);
+        const result = await (0, project_1.watchDeviceLogsBySse)(device.ip, device.port, durationSeconds * 1000, maxLogs);
+        const findingsPreview = result.findings
+            .slice(0, 20)
+            .map((item, index) => `${index + 1}. [${item.severity}] ${item.rule} | ${item.log.timestamp} | ${item.log.message}`)
+            .join("\n");
+        const logsPreview = result.logs
+            .slice(-20)
+            .map((log) => `[${log.timestamp}] [${log.level.toUpperCase()}] ${log.message}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `监听目标: ${device.ip}:${device.port}`,
+                        `监听时长: ${durationSeconds}s，收集日志: ${result.logs.length} 条，runtime_status: ${result.runtimeStatus.length} 条`,
+                        result.summary,
+                        "",
+                        "异常判定（最多展示前20条）:",
+                        findingsPreview || "未命中异常规则",
+                        "",
+                        "最新日志（最多展示最后20条）:",
+                        logsPreview || "无日志",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.registerTool("build_project", {
+        title: "Build Project",
+        description: "构建 KuaiJS 项目，支持开发模式与生产模式。",
+        inputSchema: {
+            dev: z
+                .boolean()
+                .optional()
+                .describe("是否开发模式构建，true=开发模式，false=生产模式"),
+        },
+    }, async ({ dev }) => {
+        await (0, project_2.ensureValidKuaiJSProject)(process.cwd());
+        await (0, build_1.buildAll)(Boolean(dev), process.cwd());
+        return {
+            content: [
+                { type: "text", text: `构建完成，模式: ${dev ? "dev" : "prod"}` },
+            ],
+        };
+    });
+    server.registerTool("package_project", {
+        title: "Package Project",
+        description: "执行生产构建并加密，返回 enc.msbundle 路径。",
+        inputSchema: {},
+    }, async () => {
+        await (0, project_2.ensureValidKuaiJSProject)(process.cwd());
+        const encryptedPath = await (0, packager_1.packageProject)(process.cwd());
+        return {
+            content: [{ type: "text", text: `打包完成: ${encryptedPath}` }],
+        };
+    });
+    server.registerTool("run_project", {
+        title: "Run Project",
+        description: "构建并同步到设备后运行项目。不传 transport 时会自动优先使用已连接的 WS 设备。",
+        inputSchema: {
+            transport: z
+                .enum(["http", "ws"])
+                .optional()
+                .describe("传输方式：http|ws；不传时自动优先 ws（若已连接）"),
+            ip: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("设备 IP 地址（transport=http 时可传；未传则使用 set_device 默认值）"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+            wsPort: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("WS 服务端口（transport=ws 时可选，默认 31111）"),
+            wsWaitMs: z
+                .number()
+                .int()
+                .min(1)
+                .max(600000)
+                .optional()
+                .describe("WS 等待连接超时毫秒（transport=ws 时可选，默认 30000）"),
+        },
+    }, async ({ transport, ip, port, wsPort, wsWaitMs }) => {
+        await (0, project_2.ensureValidKuaiJSProject)(process.cwd());
+        const target = await resolvePreferredRuntimeTarget({
+            transport,
+            ip,
+            port,
+            wsPort,
+            wsWaitMs,
+        });
+        await (0, project_1.runOnDevice)(target.transport === "ws"
+            ? {
+                transport: "ws",
+                wsPort: target.wsPort,
+                wsWaitMs: target.wsWaitMs,
+            }
+            : {
+                ip: target.ip,
+                port: target.port,
+                transport: "http",
+            });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `运行请求已发送到 ${target.label}`,
+                },
+            ],
+        };
+    });
+    server.registerTool("run_ui_project", {
+        title: "Run UI Project",
+        description: "构建并同步到设备后预览 UI。不传 transport 时会自动优先使用已连接的 WS 设备。",
+        inputSchema: {
+            transport: z
+                .enum(["http", "ws"])
+                .optional()
+                .describe("传输方式：http|ws；不传时自动优先 ws（若已连接）"),
+            ip: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("设备 IP 地址（transport=http 时可传；未传则使用 set_device 默认值）"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+            wsPort: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("WS 服务端口（transport=ws 时可选，默认 31111）"),
+            wsWaitMs: z
+                .number()
+                .int()
+                .min(1)
+                .max(600000)
+                .optional()
+                .describe("WS 等待连接超时毫秒（transport=ws 时可选，默认 30000）"),
+        },
+    }, async ({ transport, ip, port, wsPort, wsWaitMs }) => {
+        await (0, project_2.ensureValidKuaiJSProject)(process.cwd());
+        const target = await resolvePreferredRuntimeTarget({
+            transport,
+            ip,
+            port,
+            wsPort,
+            wsWaitMs,
+        });
+        await (0, project_1.runUIOnDevice)(target.transport === "ws"
+            ? {
+                transport: "ws",
+                wsPort: target.wsPort,
+                wsWaitMs: target.wsWaitMs,
+            }
+            : {
+                ip: target.ip,
+                port: target.port,
+                transport: "http",
+            });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `UI 预览请求已发送到 ${target.label}`,
+                },
+            ],
+        };
+    });
+    server.registerTool("stop_project", {
+        title: "Stop Project",
+        description: "停止设备上的项目。不传 transport 时会自动优先使用已连接的 WS 设备。",
+        inputSchema: {
+            transport: z
+                .enum(["http", "ws"])
+                .optional()
+                .describe("传输方式：http|ws；不传时自动优先 ws（若已连接）"),
+            ip: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("设备 IP 地址（transport=http 时可传；未传则使用 set_device 默认值）"),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("设备端口，默认 9800"),
+            wsPort: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe("WS 服务端口（transport=ws 时可选，默认 31111）"),
+            wsWaitMs: z
+                .number()
+                .int()
+                .min(1)
+                .max(600000)
+                .optional()
+                .describe("WS 等待连接超时毫秒（transport=ws 时可选，默认 30000）"),
+        },
+    }, async ({ transport, ip, port, wsPort, wsWaitMs }) => {
+        await (0, project_2.ensureValidKuaiJSProject)(process.cwd());
+        const target = await resolvePreferredRuntimeTarget({
+            transport,
+            ip,
+            port,
+            wsPort,
+            wsWaitMs,
+        });
+        await (0, project_1.stopOnDevice)(target.transport === "ws"
+            ? {
+                transport: "ws",
+                wsPort: target.wsPort,
+                wsWaitMs: target.wsWaitMs,
+            }
+            : {
+                ip: target.ip,
+                port: target.port,
+                transport: "http",
+            });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `停止请求已发送到 ${target.label}`,
+                },
+            ],
+        };
+    });
+}
+/**
+ * 创建并注册 MCP 工具
+ * @returns 返回已注册工具的 MCP Server 实例
+ * @example
+ * const server = createMcpServer()
+ */
+function createMcpServer() {
+    const server = new mcp_1.McpServer({
+        name: "ms-vite-plugin-mcp",
+        version: version_1.PACKAGE_VERSION,
+    });
+    registerDocResources(server);
+    registerDocTools(server);
+    registerRuntimeTools(server);
+    return server;
+}