@weapp-vite/mcp 1.2.1 → 1.3.1

package/README.md

@@ -35,6 +35,16 @@ const handle = await startWeappViteMcpServer({
 await handle.close?.()
 ```
 
+`streamable-http` 模式会同时暴露 DevTools runtime REST 接口，默认前缀为
+`/api/weapp/devtools`。可以通过 `restEndpoint` 调整，或设为 `false` 关闭：
+
+```ts
+const handle = await startWeappViteMcpServer({
+  transport: 'streamable-http',
+  restEndpoint: '/api/weapp/devtools',
+})
+```
+
 ## 主要 Tools
 
 - `workspace_catalog`: 输出 `weapp-vite / wevu / wevu-compiler` 目录、版本、脚本
@@ -47,6 +57,50 @@ await handle.close?.()
 - `compare_weapp_screenshot`: 面向“截图对比 / diff / baseline / 视觉回归”语义，执行 `weapp-vite compare --json`
 - `run_repo_command`: 执行仓库级命令（`pnpm/node/git/rg`）
 
+### DevTools Runtime Tools
+
+这些工具复用 `weapp-ide-cli` 的 automator 会话能力，面向已经能被微信开发者工具打开的小程序项目：
+
+- `weapp_devtools_connect`: 确认 DevTools automator 会话可用
+- `weapp_devtools_active_page` / `weapp_devtools_page_stack`: 读取当前页面与页面栈
+- `weapp_devtools_route`: 执行 `navigateTo` / `redirectTo` / `reLaunch` / `switchTab` / `navigateBack`
+- `weapp_devtools_capture`: 截取当前小程序视口
+- `weapp_devtools_host_api`: 调用 `wx.*` API
+- `weapp_devtools_console`: 读取 MCP 会话期间捕获的 console/exception 日志
+- `weapp_runtime_find_node` / `weapp_runtime_find_nodes` / `weapp_runtime_wait_node`: 查询和等待页面元素
+- `weapp_runtime_page_state` / `weapp_runtime_update_page_state` / `weapp_runtime_invoke_page`: 操作页面实例
+- `weapp_runtime_tap_node` / `weapp_runtime_input_node`: 操作页面元素
+- `weapp_runtime_component_state` / `weapp_runtime_update_component_state` / `weapp_runtime_invoke_component`: 操作组件实例
+- `weapp_runtime_find_child` / `weapp_runtime_find_children`: 查询组件内部元素
+- `weapp_runtime_node_markup` / `weapp_runtime_node_styles` / `weapp_runtime_node_attrs` / `weapp_runtime_measure_node`: 读取元素结构与渲染信息
+
+建议调用顺序：先 `weapp_devtools_connect`，再 `weapp_devtools_active_page`，之后再执行 `weapp_devtools_capture` 或 `weapp_runtime_*`。
+
+### DevTools Runtime REST
+
+REST 接口和 MCP runtime tools 复用同一个 automator 会话管理器，适合脚本或其他非 MCP 客户端连续操控模拟器：
+
+- `POST /api/weapp/devtools/connect`
+- `POST /api/weapp/devtools/route`
+- `GET|POST /api/weapp/devtools/active-page`
+- `GET|POST /api/weapp/devtools/page-stack`
+- `POST /api/weapp/devtools/capture`
+- `POST /api/weapp/devtools/host-api`
+- `GET|DELETE /api/weapp/devtools/console`
+- `DELETE /api/weapp/devtools/session`
+
+示例：
+
+```bash
+curl -X POST http://127.0.0.1:3088/api/weapp/devtools/route \
+  -H 'content-type: application/json' \
+  -d '{"projectPath":"dist/build/mp-weixin","transition":"reLaunch","path":"pages/index/index"}'
+
+curl -X POST http://127.0.0.1:3088/api/weapp/devtools/capture \
+  -H 'content-type: application/json' \
+  -d '{"projectPath":"dist/build/mp-weixin","outputPath":".tmp/home.png"}'
+```
+
 ## 主要 Resources
 
 - `weapp-vite://workspace/catalog`
@@ -64,6 +118,8 @@ await handle.close?.()
 
 - `plan-weapp-vite-change`: 生成 weapp-vite/wevu 改造计划提示词
 - `debug-wevu-runtime`: 生成 wevu runtime 排查提示词
+- `inspect-mini-program-page`: 连接 DevTools 并检查页面渲染状态
+- `recover-mini-program-connection`: 按固定顺序恢复 automator 连接
 
 ## 开发
 

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { DevtoolsRuntimeHooks } from '@weapp-vite/devtools-runtime';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 declare const MCP_SERVER_NAME = "@weapp-vite/mcp";
@@ -85,14 +86,78 @@ declare function searchTextInDirectory(root: string, query: string, options?: {
     maxResults?: number;
 }): Promise<SearchMatch[]>;
 
+interface MiniProgramElement {
+    tagName?: string;
+    $?: (selector: string) => Promise<MiniProgramElement | null>;
+    $$?: (selector: string) => Promise<MiniProgramElement[]>;
+    tap: () => Promise<void>;
+}
+interface MiniProgramPage {
+    path: string;
+    query?: unknown;
+    $: (selector: string) => Promise<MiniProgramElement | null>;
+    $$?: (selector: string) => Promise<MiniProgramElement[]>;
+    data: (path?: string) => Promise<unknown>;
+    size: () => Promise<unknown>;
+    scrollTop: () => Promise<unknown>;
+    waitFor: (milliseconds: number) => Promise<void>;
+}
+interface MiniProgramLike {
+    on: (name: 'console' | 'exception', handler: (payload: unknown) => void) => void;
+    off?: (name: 'console' | 'exception', handler: (payload: unknown) => void) => void;
+    currentPage: () => Promise<MiniProgramPage>;
+    systemInfo: () => Promise<unknown>;
+    pageStack: () => Promise<MiniProgramPage[]>;
+    navigateTo: (url: string) => Promise<MiniProgramPage>;
+    redirectTo: (url: string) => Promise<MiniProgramPage>;
+    reLaunch: (url: string) => Promise<MiniProgramPage>;
+    switchTab: (url: string) => Promise<MiniProgramPage>;
+    navigateBack: () => Promise<MiniProgramPage>;
+    screenshot: () => Promise<string | Uint8Array>;
+    callWxMethod: (method: string, ...args: unknown[]) => Promise<unknown>;
+}
+interface RuntimeConnectionInput {
+    projectPath: string;
+    timeout?: number;
+    preferOpenedSession?: boolean;
+}
+interface RuntimeConsoleLogEntry {
+    level: string;
+    message: string;
+    timestamp: number;
+    raw: unknown;
+}
+declare class RuntimeSessionManager {
+    private readonly workspaceRoot;
+    private readonly runtimeHooks;
+    private readonly logs;
+    private readonly attachedSessions;
+    private readonly maxLogs;
+    constructor(workspaceRoot: string, runtimeHooks?: DevtoolsRuntimeHooks);
+    close(input: RuntimeConnectionInput): Promise<void>;
+    clearLogs(): void;
+    getLogs(): RuntimeConsoleLogEntry[];
+    resolveProjectPath(projectPath: string): string;
+    resolveWorkspacePath(filePath: string): string;
+    withMiniProgram<T>(input: RuntimeConnectionInput, runner: (miniProgram: MiniProgramLike) => Promise<T>): Promise<T>;
+    withPage<T>(input: RuntimeConnectionInput, runner: (page: MiniProgramPage, miniProgram: MiniProgramLike) => Promise<T>): Promise<T>;
+    private attach;
+    private detach;
+    private pushLog;
+}
+
 interface CreateServerOptions {
+    runtimeHooks?: DevtoolsRuntimeHooks;
     workspaceRoot?: string;
 }
 declare function createWeappViteMcpServer(options?: CreateServerOptions): Promise<{
+    runtimeManager: RuntimeSessionManager;
     server: McpServer;
     workspaceRoot: string;
 }>;
 
+declare const DEFAULT_RUNTIME_REST_ENDPOINT = "/api/weapp/devtools";
+
 declare const DEFAULT_MCP_HOST = "127.0.0.1";
 declare const DEFAULT_MCP_PORT = 3088;
 declare const DEFAULT_MCP_ENDPOINT = "/mcp";
@@ -101,6 +166,7 @@ interface StartMcpServerOptions extends CreateServerOptions {
     host?: string;
     port?: number;
     endpoint?: string;
+    restEndpoint?: string | false;
     unref?: boolean;
     quiet?: boolean;
     onReady?: (message: string) => void;
@@ -135,5 +201,5 @@ declare function resolveWorkspaceRoot(start?: string): string;
 declare function assertInsideRoot(root: string, targetPath: string): string;
 declare function resolveSubPath(root: string, relativePath: string): string;
 
-export { DEFAULT_MAX_FILE_CHARS, DEFAULT_MAX_OUTPUT_CHARS, DEFAULT_MAX_RESULTS, DEFAULT_MCP_ENDPOINT, DEFAULT_MCP_HOST, DEFAULT_MCP_PORT, DEFAULT_TIMEOUT_MS, EXPOSED_PACKAGES, MCP_SERVER_NAME, MCP_SERVER_VERSION, SKIPPED_DIR_NAMES, assertInsideRoot, createWeappViteMcpServer, formatJson, listFilesInDirectory, loadExposedCatalog, loadPackageSummary, normalizeErrorMessage, readFileContent, resolveSubPath, resolveWorkspaceRoot, runCommand, searchTextInDirectory, startStdioServer, startWeappViteMcpServer, toToolError, toToolResult };
+export { DEFAULT_MAX_FILE_CHARS, DEFAULT_MAX_OUTPUT_CHARS, DEFAULT_MAX_RESULTS, DEFAULT_MCP_ENDPOINT, DEFAULT_MCP_HOST, DEFAULT_MCP_PORT, DEFAULT_RUNTIME_REST_ENDPOINT, DEFAULT_TIMEOUT_MS, EXPOSED_PACKAGES, MCP_SERVER_NAME, MCP_SERVER_VERSION, SKIPPED_DIR_NAMES, assertInsideRoot, createWeappViteMcpServer, formatJson, listFilesInDirectory, loadExposedCatalog, loadPackageSummary, normalizeErrorMessage, readFileContent, resolveSubPath, resolveWorkspaceRoot, runCommand, searchTextInDirectory, startStdioServer, startWeappViteMcpServer, toToolError, toToolResult };
 export type { CommandResult, CreateServerOptions, ExposedPackageId, ExposedPackageSummary, McpServerHandle, SearchMatch, StartMcpServerOptions };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { DevtoolsRuntimeHooks } from '@weapp-vite/devtools-runtime';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 declare const MCP_SERVER_NAME = "@weapp-vite/mcp";
@@ -85,14 +86,78 @@ declare function searchTextInDirectory(root: string, query: string, options?: {
     maxResults?: number;
 }): Promise<SearchMatch[]>;
 
+interface MiniProgramElement {
+    tagName?: string;
+    $?: (selector: string) => Promise<MiniProgramElement | null>;
+    $$?: (selector: string) => Promise<MiniProgramElement[]>;
+    tap: () => Promise<void>;
+}
+interface MiniProgramPage {
+    path: string;
+    query?: unknown;
+    $: (selector: string) => Promise<MiniProgramElement | null>;
+    $$?: (selector: string) => Promise<MiniProgramElement[]>;
+    data: (path?: string) => Promise<unknown>;
+    size: () => Promise<unknown>;
+    scrollTop: () => Promise<unknown>;
+    waitFor: (milliseconds: number) => Promise<void>;
+}
+interface MiniProgramLike {
+    on: (name: 'console' | 'exception', handler: (payload: unknown) => void) => void;
+    off?: (name: 'console' | 'exception', handler: (payload: unknown) => void) => void;
+    currentPage: () => Promise<MiniProgramPage>;
+    systemInfo: () => Promise<unknown>;
+    pageStack: () => Promise<MiniProgramPage[]>;
+    navigateTo: (url: string) => Promise<MiniProgramPage>;
+    redirectTo: (url: string) => Promise<MiniProgramPage>;
+    reLaunch: (url: string) => Promise<MiniProgramPage>;
+    switchTab: (url: string) => Promise<MiniProgramPage>;
+    navigateBack: () => Promise<MiniProgramPage>;
+    screenshot: () => Promise<string | Uint8Array>;
+    callWxMethod: (method: string, ...args: unknown[]) => Promise<unknown>;
+}
+interface RuntimeConnectionInput {
+    projectPath: string;
+    timeout?: number;
+    preferOpenedSession?: boolean;
+}
+interface RuntimeConsoleLogEntry {
+    level: string;
+    message: string;
+    timestamp: number;
+    raw: unknown;
+}
+declare class RuntimeSessionManager {
+    private readonly workspaceRoot;
+    private readonly runtimeHooks;
+    private readonly logs;
+    private readonly attachedSessions;
+    private readonly maxLogs;
+    constructor(workspaceRoot: string, runtimeHooks?: DevtoolsRuntimeHooks);
+    close(input: RuntimeConnectionInput): Promise<void>;
+    clearLogs(): void;
+    getLogs(): RuntimeConsoleLogEntry[];
+    resolveProjectPath(projectPath: string): string;
+    resolveWorkspacePath(filePath: string): string;
+    withMiniProgram<T>(input: RuntimeConnectionInput, runner: (miniProgram: MiniProgramLike) => Promise<T>): Promise<T>;
+    withPage<T>(input: RuntimeConnectionInput, runner: (page: MiniProgramPage, miniProgram: MiniProgramLike) => Promise<T>): Promise<T>;
+    private attach;
+    private detach;
+    private pushLog;
+}
+
 interface CreateServerOptions {
+    runtimeHooks?: DevtoolsRuntimeHooks;
     workspaceRoot?: string;
 }
 declare function createWeappViteMcpServer(options?: CreateServerOptions): Promise<{
+    runtimeManager: RuntimeSessionManager;
     server: McpServer;
     workspaceRoot: string;
 }>;
 
+declare const DEFAULT_RUNTIME_REST_ENDPOINT = "/api/weapp/devtools";
+
 declare const DEFAULT_MCP_HOST = "127.0.0.1";
 declare const DEFAULT_MCP_PORT = 3088;
 declare const DEFAULT_MCP_ENDPOINT = "/mcp";
@@ -101,6 +166,7 @@ interface StartMcpServerOptions extends CreateServerOptions {
     host?: string;
     port?: number;
     endpoint?: string;
+    restEndpoint?: string | false;
     unref?: boolean;
     quiet?: boolean;
     onReady?: (message: string) => void;
@@ -135,5 +201,5 @@ declare function resolveWorkspaceRoot(start?: string): string;
 declare function assertInsideRoot(root: string, targetPath: string): string;
 declare function resolveSubPath(root: string, relativePath: string): string;
 
-export { DEFAULT_MAX_FILE_CHARS, DEFAULT_MAX_OUTPUT_CHARS, DEFAULT_MAX_RESULTS, DEFAULT_MCP_ENDPOINT, DEFAULT_MCP_HOST, DEFAULT_MCP_PORT, DEFAULT_TIMEOUT_MS, EXPOSED_PACKAGES, MCP_SERVER_NAME, MCP_SERVER_VERSION, SKIPPED_DIR_NAMES, assertInsideRoot, createWeappViteMcpServer, formatJson, listFilesInDirectory, loadExposedCatalog, loadPackageSummary, normalizeErrorMessage, readFileContent, resolveSubPath, resolveWorkspaceRoot, runCommand, searchTextInDirectory, startStdioServer, startWeappViteMcpServer, toToolError, toToolResult };
+export { DEFAULT_MAX_FILE_CHARS, DEFAULT_MAX_OUTPUT_CHARS, DEFAULT_MAX_RESULTS, DEFAULT_MCP_ENDPOINT, DEFAULT_MCP_HOST, DEFAULT_MCP_PORT, DEFAULT_RUNTIME_REST_ENDPOINT, DEFAULT_TIMEOUT_MS, EXPOSED_PACKAGES, MCP_SERVER_NAME, MCP_SERVER_VERSION, SKIPPED_DIR_NAMES, assertInsideRoot, createWeappViteMcpServer, formatJson, listFilesInDirectory, loadExposedCatalog, loadPackageSummary, normalizeErrorMessage, readFileContent, resolveSubPath, resolveWorkspaceRoot, runCommand, searchTextInDirectory, startStdioServer, startWeappViteMcpServer, toToolError, toToolResult };
 export type { CommandResult, CreateServerOptions, ExposedPackageId, ExposedPackageSummary, McpServerHandle, SearchMatch, StartMcpServerOptions };