ms-vite-plugin 1.1.20 → 1.1.21

package/dist/mcp/httpapi-docs-service.d.ts

@@ -0,0 +1,73 @@
+/**
+ * HTTP API 请求方法
+ */
+export type HttpApiMethod = "GET" | "POST";
+/**
+ * HTTP API 文档条目
+ */
+export type HttpApiDocEntry = {
+    /** 稳定 slug，可用于读取单个接口文档 */
+    slug: string;
+    /** 接口请求方法 */
+    method: HttpApiMethod;
+    /** 接口路径 */
+    path: string;
+    /** 接口标题 */
+    title: string;
+    /** 所属一级章节 */
+    section: string;
+    /** 文档片段起始行号（1-based） */
+    startLine: number;
+    /** 文档片段结束行号（1-based） */
+    endLine: number;
+    /** 接口完整 markdown 片段 */
+    content: string;
+};
+/**
+ * 获取 HTTP API 文档路径
+ * @returns 返回 docs/httpapi/api.md 的绝对路径
+ * @example
+ * const filePath = getHttpApiDocPath()
+ */
+export declare function getHttpApiDocPath(): string;
+/**
+ * 读取 HTTP API markdown 文档
+ * @returns 返回完整 markdown 文本
+ * @example
+ * const markdown = await readHttpApiMarkdown()
+ */
+export declare function readHttpApiMarkdown(): Promise<string>;
+/**
+ * 根据 method/path 生成稳定 slug
+ * @param method HTTP 请求方法
+ * @param apiPath HTTP API 路径
+ * @returns 返回可用于 MCP 资源路径的 slug
+ * @example
+ * createHttpApiSlug("GET", "/api/control/click")
+ */
+export declare function createHttpApiSlug(method: HttpApiMethod, apiPath: string): string;
+/**
+ * 解析 HTTP API markdown 为接口条目
+ * @returns 返回按文档顺序排列的接口条目
+ * @example
+ * const entries = await getHttpApiDocEntries()
+ */
+export declare function getHttpApiDocEntries(): Promise<HttpApiDocEntry[]>;
+/**
+ * 计算 HTTP API 文档条目搜索分数
+ * @param entry 文档条目
+ * @param normalizedQuery 已转小写的搜索词
+ * @returns 返回匹配分数，0 表示不匹配
+ * @example
+ * scoreHttpApiDocEntry(entry, "click")
+ */
+export declare function scoreHttpApiDocEntry(entry: HttpApiDocEntry, normalizedQuery: string): number;
+/**
+ * 根据 slug 或 path 查找 HTTP API 文档条目
+ * @param identifier slug 或 API 路径
+ * @param method 可选 HTTP 方法，用于同路径多方法时消歧
+ * @returns 找到时返回条目，否则返回 undefined
+ * @example
+ * const entry = await findHttpApiDocEntry("/api/control/click", "GET")
+ */
+export declare function findHttpApiDocEntry(identifier: string, method?: HttpApiMethod): Promise<HttpApiDocEntry | undefined>;

package/dist/mcp/httpapi-docs-service.js

@@ -0,0 +1,188 @@
+"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.getHttpApiDocPath = getHttpApiDocPath;
+exports.readHttpApiMarkdown = readHttpApiMarkdown;
+exports.createHttpApiSlug = createHttpApiSlug;
+exports.getHttpApiDocEntries = getHttpApiDocEntries;
+exports.scoreHttpApiDocEntry = scoreHttpApiDocEntry;
+exports.findHttpApiDocEntry = findHttpApiDocEntry;
+const fsExtra = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/**
+ * 获取 HTTP API 文档路径
+ * @returns 返回 docs/httpapi/api.md 的绝对路径
+ * @example
+ * const filePath = getHttpApiDocPath()
+ */
+function getHttpApiDocPath() {
+    return path.resolve(__dirname, "..", "..", "docs", "httpapi", "api.md");
+}
+/**
+ * 读取 HTTP API markdown 文档
+ * @returns 返回完整 markdown 文本
+ * @example
+ * const markdown = await readHttpApiMarkdown()
+ */
+async function readHttpApiMarkdown() {
+    const filePath = getHttpApiDocPath();
+    if (!(await fsExtra.pathExists(filePath))) {
+        throw new Error(`HTTP API 文档不存在: ${filePath}`);
+    }
+    return fsExtra.readFile(filePath, "utf8");
+}
+/**
+ * 根据 method/path 生成稳定 slug
+ * @param method HTTP 请求方法
+ * @param apiPath HTTP API 路径
+ * @returns 返回可用于 MCP 资源路径的 slug
+ * @example
+ * createHttpApiSlug("GET", "/api/control/click")
+ */
+function createHttpApiSlug(method, apiPath) {
+    return `${method.toLowerCase()}-${apiPath}`
+        .replace(/^get-\//, "get-")
+        .replace(/^post-\//, "post-")
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+}
+/**
+ * 解析 HTTP API markdown 为接口条目
+ * @returns 返回按文档顺序排列的接口条目
+ * @example
+ * const entries = await getHttpApiDocEntries()
+ */
+async function getHttpApiDocEntries() {
+    const markdown = await readHttpApiMarkdown();
+    const lines = markdown.split(/\r?\n/);
+    const entries = [];
+    let currentSection = "";
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const sectionMatch = line.match(/^#\s+(.+)$/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1]?.trim() ?? "";
+            continue;
+        }
+        const titleMatch = line.match(/^##\s+(.+)$/);
+        if (!titleMatch) {
+            continue;
+        }
+        const title = titleMatch[1]?.trim() ?? "";
+        let method = null;
+        let apiPath = "";
+        for (let cursor = index + 1; cursor < Math.min(lines.length, index + 8); cursor += 1) {
+            const endpointMatch = (lines[cursor] ?? "").match(/^(GET|POST)\s+(\/\S+)/);
+            if (endpointMatch) {
+                method = endpointMatch[1];
+                apiPath = endpointMatch[2] ?? "";
+                break;
+            }
+        }
+        if (!method || !apiPath) {
+            continue;
+        }
+        let endIndex = lines.length;
+        for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+            if (/^##\s+/.test(lines[cursor] ?? "")) {
+                endIndex = cursor;
+                break;
+            }
+        }
+        entries.push({
+            slug: createHttpApiSlug(method, apiPath),
+            method,
+            path: apiPath,
+            title,
+            section: currentSection,
+            startLine: index + 1,
+            endLine: endIndex,
+            content: lines.slice(index, endIndex).join("\n").trim(),
+        });
+    }
+    return entries;
+}
+/**
+ * 计算 HTTP API 文档条目搜索分数
+ * @param entry 文档条目
+ * @param normalizedQuery 已转小写的搜索词
+ * @returns 返回匹配分数，0 表示不匹配
+ * @example
+ * scoreHttpApiDocEntry(entry, "click")
+ */
+function scoreHttpApiDocEntry(entry, normalizedQuery) {
+    const query = normalizedQuery.trim();
+    if (!query) {
+        return 0;
+    }
+    let score = 0;
+    if (entry.path.toLowerCase() === query) {
+        score += 100;
+    }
+    if (`${entry.method} ${entry.path}`.toLowerCase() === query) {
+        score += 120;
+    }
+    if (entry.path.toLowerCase().includes(query)) {
+        score += 60;
+    }
+    if (entry.title.toLowerCase().includes(query)) {
+        score += 50;
+    }
+    if (entry.section.toLowerCase().includes(query)) {
+        score += 20;
+    }
+    if (entry.content.toLowerCase().includes(query)) {
+        score += 10;
+    }
+    return score;
+}
+/**
+ * 根据 slug 或 path 查找 HTTP API 文档条目
+ * @param identifier slug 或 API 路径
+ * @param method 可选 HTTP 方法，用于同路径多方法时消歧
+ * @returns 找到时返回条目，否则返回 undefined
+ * @example
+ * const entry = await findHttpApiDocEntry("/api/control/click", "GET")
+ */
+async function findHttpApiDocEntry(identifier, method) {
+    const normalizedIdentifier = identifier.trim();
+    const entries = await getHttpApiDocEntries();
+    return entries.find((entry) => {
+        const methodMatches = method ? entry.method === method : true;
+        return (methodMatches &&
+            (entry.slug === normalizedIdentifier || entry.path === normalizedIdentifier));
+    });
+}

package/dist/mcp/httpapi-tools.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * 注册 HTTP API 文档与通用调用工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerHttpApiTools(server)
+ */
+export declare function registerHttpApiTools(server: McpServer): void;

package/dist/mcp/httpapi-tools.js

@@ -0,0 +1,345 @@
+"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.registerHttpApiTools = registerHttpApiTools;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const z = __importStar(require("zod/v4"));
+const httpapi_docs_service_1 = require("./httpapi-docs-service");
+const tool_utils_1 = require("./tool-utils");
+/**
+ * HTTP API 文档完整资源 URI
+ */
+const HTTP_API_DOC_RESOURCE_URI = "kuaijs://httpapi/api";
+/**
+ * 格式化 HTTP API 文档搜索摘要
+ * @param entry HTTP API 文档条目
+ * @param index 列表序号
+ * @returns 返回摘要文本
+ * @example
+ * formatHttpApiDocSummary(entry, 0)
+ */
+function formatHttpApiDocSummary(entry, index) {
+    return [
+        `${index + 1}. ${entry.title}`,
+        `method: ${entry.method}`,
+        `path: ${entry.path}`,
+        `slug: ${entry.slug}`,
+        `section: ${entry.section || "未分组"}`,
+        `lines: ${entry.startLine}-${entry.endLine}`,
+        `uri: kuaijs://httpapi/endpoints/${entry.slug}`,
+    ].join("\n");
+}
+/**
+ * 标准化并校验 HTTP API 路径输入
+ * @param apiPath 用户传入路径
+ * @returns 返回标准化后的路径
+ * @example
+ * normalizeHttpApiPath("/api/status")
+ */
+function normalizeHttpApiPath(apiPath) {
+    const normalizedPath = apiPath.trim();
+    if (/^https?:\/\//i.test(normalizedPath)) {
+        throw new Error("path 只能传 HTTP API 相对路径，不能传完整 URL。");
+    }
+    if (!normalizedPath.startsWith("/")) {
+        throw new Error("path 必须以 / 开头，例如 /api/status。");
+    }
+    if (normalizedPath.includes("?")) {
+        throw new Error("path 不能包含 query string，请使用 query 参数传递查询参数。");
+    }
+    return normalizedPath;
+}
+/**
+ * 将 query 参数追加到 URL
+ * @param url 目标 URL
+ * @param query 可选 query 参数
+ * @returns 无返回值
+ * @example
+ * appendQueryParams(url, { x: 1 })
+ */
+function appendQueryParams(url, query) {
+    if (!query) {
+        return;
+    }
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+}
+/**
+ * 读取响应体并按要求格式化
+ * @param response fetch 响应对象
+ * @param responseFormat 响应格式
+ * @returns 返回格式化文本
+ * @example
+ * const text = await readHttpApiResponseText(response, "json")
+ */
+async function readHttpApiResponseText(response, responseFormat) {
+    const responseText = await response.text();
+    if (responseFormat === "text") {
+        return responseText;
+    }
+    try {
+        return (0, tool_utils_1.formatRuntimeJsonText)(JSON.parse(responseText));
+    }
+    catch {
+        throw new Error("响应不是有效 JSON；如需读取文本响应，请设置 responseFormat=text。");
+    }
+}
+/**
+ * 注册 HTTP API 文档与通用调用工具
+ * @param server MCP 服务实例
+ * @returns 无返回值
+ * @example
+ * registerHttpApiTools(server)
+ */
+function registerHttpApiTools(server) {
+    server.registerResource("http-api-doc", HTTP_API_DOC_RESOURCE_URI, {
+        title: "KuaiJS HTTP API document",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: HTTP_API_DOC_RESOURCE_URI,
+                mimeType: "text/markdown",
+                text: await (0, httpapi_docs_service_1.readHttpApiMarkdown)(),
+            },
+        ],
+    }));
+    server.registerResource("http-api-endpoint", new mcp_js_1.ResourceTemplate("kuaijs://httpapi/endpoints/{slug}", {
+        list: async () => {
+            const entries = await (0, httpapi_docs_service_1.getHttpApiDocEntries)();
+            return {
+                resources: entries.map((entry) => ({
+                    uri: `kuaijs://httpapi/endpoints/${entry.slug}`,
+                    name: `${entry.method} ${entry.path}`,
+                    description: `${entry.title} [${entry.section || "未分组"}]`,
+                    mimeType: "text/markdown",
+                })),
+            };
+        },
+    }), {
+        title: "KuaiJS HTTP API endpoint documents",
+        mimeType: "text/markdown",
+    }, async (_uri, variables) => {
+        const slug = String(variables.slug || "");
+        const entry = await (0, httpapi_docs_service_1.findHttpApiDocEntry)(slug);
+        if (!entry) {
+            throw new Error(`HTTP API 文档不存在: ${slug}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: `kuaijs://httpapi/endpoints/${entry.slug}`,
+                    mimeType: "text/markdown",
+                    text: entry.content,
+                },
+            ],
+        };
+    });
+    server.registerTool("search_http_api_docs", {
+        title: "Search HTTP API Docs",
+        description: "搜索 docs/httpapi/api.md 中声明的 HTTP API。调用 http_api_call 前应先用本工具确认接口 method、path、参数和 slug。",
+        inputSchema: {
+            query: z
+                .string()
+                .min(1)
+                .describe("搜索关键词，例如 click、/api/control/click、截图"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .default(8)
+                .describe("返回条数上限，默认 8"),
+        },
+    }, async ({ query, limit }) => {
+        const normalizedQuery = query.toLowerCase();
+        const entries = await (0, httpapi_docs_service_1.getHttpApiDocEntries)();
+        const matches = entries
+            .map((entry) => ({
+            entry,
+            score: (0, httpapi_docs_service_1.scoreHttpApiDocEntry)(entry, normalizedQuery),
+        }))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score ||
+            a.entry.path.localeCompare(b.entry.path) ||
+            a.entry.method.localeCompare(b.entry.method))
+            .slice(0, limit)
+            .map((item) => item.entry);
+        return (0, tool_utils_1.createTextToolResult)(matches.length === 0
+            ? `未找到与 "${query}" 匹配的 HTTP API 文档。\n文档: ${(0, httpapi_docs_service_1.getHttpApiDocPath)()}`
+            : [
+                `HTTP API 文档: ${(0, httpapi_docs_service_1.getHttpApiDocPath)()}`,
+                "",
+                ...matches.map((entry, index) => formatHttpApiDocSummary(entry, index)),
+            ].join("\n"));
+    });
+    server.registerTool("read_http_api_doc", {
+        title: "Read HTTP API Doc",
+        description: "按 slug 或 path 读取 docs/httpapi/api.md 中某个接口的完整片段。调用 http_api_call 前应读取目标接口片段，确认参数位置、类型和返回结构。",
+        inputSchema: {
+            identifier: z
+                .string()
+                .min(1)
+                .describe("接口 slug 或 path，例如 get-api-control-click 或 /api/control/click"),
+            method: z
+                .enum(["GET", "POST"])
+                .optional()
+                .describe("可选 HTTP 方法，用于同路径多方法时消歧"),
+        },
+    }, async ({ identifier, method }) => {
+        const entry = await (0, httpapi_docs_service_1.findHttpApiDocEntry)(identifier, method);
+        if (!entry) {
+            return (0, tool_utils_1.createTextToolResult)(`未找到 HTTP API 文档: ${identifier}\n请先调用 search_http_api_docs 搜索可用接口。`, true);
+        }
+        return (0, tool_utils_1.createTextToolResult)([
+            `title: ${entry.title}`,
+            `method: ${entry.method}`,
+            `path: ${entry.path}`,
+            `slug: ${entry.slug}`,
+            `section: ${entry.section || "未分组"}`,
+            `lines: ${entry.startLine}-${entry.endLine}`,
+            "",
+            entry.content,
+        ].join("\n"));
+    });
+    server.registerTool("http_api_call", {
+        title: "HTTP API Call",
+        description: "调用 docs/httpapi/api.md 中已声明的 HTTP API。使用前应先调用 search_http_api_docs/read_http_api_doc 获取 docSlug，并确认 method、path、query/body 参数；本工具会拒绝 docSlug、method、path 不匹配的调用。",
+        inputSchema: {
+            method: z
+                .enum(["GET", "POST"])
+                .describe("HTTP 方法，必须与 HTTP API 文档一致"),
+            path: z
+                .string()
+                .min(1)
+                .describe("HTTP API 相对路径，例如 /api/control/click；不能包含 query string"),
+            docSlug: z
+                .string()
+                .min(1)
+                .describe("search_http_api_docs/read_http_api_doc 返回的接口 slug"),
+            query: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional()
+                .describe("query 参数；GET 接口通常使用 query 传参"),
+            body: z
+                .unknown()
+                .optional()
+                .describe("POST 请求体；对象会按 JSON 提交"),
+            responseFormat: z
+                .enum(["json", "text"])
+                .optional()
+                .default("json")
+                .describe("响应解析格式，默认 json"),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(1000)
+                .max(600000)
+                .optional()
+                .default(30000)
+                .describe("请求超时时间，默认 30000 毫秒"),
+        },
+    }, async ({ method, path, docSlug, query, body, responseFormat, timeoutMs, }) => {
+        const apiPath = normalizeHttpApiPath(path);
+        const entry = await (0, httpapi_docs_service_1.findHttpApiDocEntry)(docSlug);
+        if (!entry) {
+            return (0, tool_utils_1.createTextToolResult)([
+                `HTTP API 文档中不存在该 docSlug: ${docSlug}`,
+                "请先调用 search_http_api_docs 搜索可用接口，再调用 read_http_api_doc 确认参数和 slug。",
+            ].join("\n"), true);
+        }
+        if (entry.method !== method || entry.path !== apiPath) {
+            return (0, tool_utils_1.createTextToolResult)([
+                "HTTP API 调用与文档条目不匹配。",
+                `传入: ${method} ${apiPath} (${docSlug})`,
+                `文档: ${entry.method} ${entry.path} (${entry.slug})`,
+                "请重新调用 read_http_api_doc 确认目标接口。",
+            ].join("\n"), true);
+        }
+        if (method === "GET" && body !== undefined) {
+            return (0, tool_utils_1.createTextToolResult)("GET 接口不能传 body，请使用 query 参数。", true);
+        }
+        const target = await (0, tool_utils_1.resolveRuntimeHttpTarget)();
+        const url = new URL(`http://${target.ip}:${target.port}${apiPath}`);
+        appendQueryParams(url, query);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const headers = {};
+            let requestBody;
+            if (body !== undefined) {
+                if (typeof body === "string") {
+                    requestBody = body;
+                    headers["Content-Type"] = "text/plain; charset=utf-8";
+                }
+                else {
+                    requestBody = JSON.stringify(body);
+                    headers["Content-Type"] = "application/json";
+                }
+            }
+            const response = await fetch(url.toString(), {
+                method,
+                signal: controller.signal,
+                headers: Object.keys(headers).length > 0 ? headers : undefined,
+                body: requestBody,
+            });
+            const responseText = await readHttpApiResponseText(response, responseFormat);
+            return (0, tool_utils_1.createTextToolResult)([
+                `HTTP API 调用${response.ok ? "成功" : "失败"}: ${method} ${apiPath}`,
+                `设备: ${target.label}`,
+                `文档: ${entry.title} (${entry.slug}, lines ${entry.startLine}-${entry.endLine})`,
+                `状态码: ${response.status}`,
+                "",
+                responseText,
+            ].join("\n"), !response.ok);
+        }
+        catch (error) {
+            const message = error instanceof Error && error.name === "AbortError"
+                ? `请求超时: ${timeoutMs}ms`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            return (0, tool_utils_1.createTextToolResult)(`HTTP API 调用失败: ${method} ${apiPath}\n${message}`, true);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    });
+}