Weapp Dev MCP

🚀 微信小程序 MCP 服務器

本項目是基於 FastMCP 的服務器，藉助 miniprogram-automator 實現微信開發者工具的自動化操作。該服務器提供了 MCP 工具，能讓 AI 助手對小程序頁面進行導航、檢查和操作，類似於 playwright-mcp，不過是專門為微信生態系統定製的。

🚀 快速開始

前置要求

• 已安裝支持命令行訪問（cli / cli.bat）的微信開發者工具。
• 本地安裝了 Node.js 18+ 和 npm。
• 擁有可在開發者工具中打開的小程序項目。

快速開始（npm 包）

@yfme/weapp-dev-mcp 已發佈到 npm，普通用戶無需克隆倉庫或手動執行 node dist/index.js。下面的命令會直接從 npm 下載可執行版本。

使用 npx 臨時運行（推薦）

npx -y \
  -p @modelcontextprotocol/sdk@1.17.2 \
  -p fastmcp@3.23.0 \
  -p @yfme/weapp-dev-mcp \
  weapp-dev-mcp

• -y：自動確認依賴安裝。
• -p：顯式釘住 @modelcontextprotocol/sdk@1.17.2 與 fastmcp@3.23.0，可避免新版 SDK 在啟動階段拋出 “Server does not support completions” 錯誤。
• weapp-dev-mcp：包中導出的 CLI 名稱。

安裝到項目/全局

npm install --save-dev \
  @modelcontextprotocol/sdk@1.17.2 \
  fastmcp@3.23.0 \
  @yfme/weapp-dev-mcp

npx weapp-dev-mcp

或者使用 npm install -g ... && weapp-dev-mcp，同樣需要鎖定 SDK 和 fastmcp 的版本。

⚠️ 重要提示

只有在本倉庫內開發時，才建議直接運行 node dist/index.js。一般用戶請按照以上 npm 包方式啟動。

📦 MCP 客戶端集成

配置

若要在 Claude Desktop 或其他 MCP 客戶端中使用此服務器，請在配置文件中添加以下內容：

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": [
        "-y",
        "-p", "@modelcontextprotocol/sdk@1.17.2",
        "-p", "fastmcp@3.23.0",
        "-p", "@yfme/weapp-dev-mcp",
        "weapp-dev-mcp"
      ],
      "env": {
        "WEAPP_WS_ENDPOINT": "ws://localhost:9420"
      }
    }
  }
}

啟動微信開發者工具

在使用 MCP 服務器之前，需先啟動微信開發者工具並開啟 WebSocket 服務。

💡 使用建議

1. 打開微信開發者工具。
2. 進入 設置 → 安全設置 → 服務端口。
3. 開啟 "HTTP 調試" 和 "自動化測試"。

使用命令行啟動

使用命令行啟動微信開發者工具並自動開啟 WebSocket 服務：

macOS/Linux：

/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420

Windows：

"C:\Program Files (x86)\Tencent\微信web開發者工具\cli.bat" auto --project C:\path\to\your\project --auto-port 9420

其中：

• --project：指定小程序項目目錄路徑（請替換為實際的項目路徑）。
• --auto-port：指定 WebSocket 服務端口（默認 9420）。

⚠️ 重要提示

由於沙箱機制，部分客戶端不允許 MCP 訪問項目目錄以外的微信開發者工具的 cli，所以這裡只介紹了使用 WebSocket 服務。

環境變量配置

可通過環境變量控制自動化工具如何連接到微信開發者工具：

⚠️ 重要提示

當啟動開發者工具（launch 模式）時，必須通過 MCP 工具參數提供小程序項目目錄：在執行操作前通過 connection.projectPath 提供（例如通過 mp_ensureConnection）。該值一旦建立，將在後續調用中持久化。

工具調用可以通過 connection 對象覆蓋這些默認值中的大部分。

常見錯誤

• Server does not support completions (required for completion/complete)
  新版 @modelcontextprotocol/sdk 在啟動階段強制要求 completions 能力，而當前版本的 weapp-dev-mcp 尚未實現相關接口。按照“快速開始”章節的命令顯式安裝 @modelcontextprotocol/sdk@1.17.2 與 fastmcp@3.23.0 可立即規避；未來版本將內置兼容邏輯。

💻 可用工具

應用工具（Application Tools）

• mp_ensureConnection：確保自動化會話就緒；可選擇強制重連或覆蓋連接設置。
• mp_navigate：在小程序內導航，支持 navigateTo、redirectTo、reLaunch、switchTab 或 navigateBack。
• mp_screenshot：捕獲屏幕截圖並返回（或保存到磁盤）。
• mp_callWx：調用微信小程序 API 方法（如 wx.showToast）。
• mp_getLogs：獲取小程序控制臺日志，可選擇獲取後清除。

頁面工具（Page Tools）

• page_getElement：通過選擇器獲取頁面元素。
• page_waitElement：等待元素出現在頁面上（⚠️ 不適用於自定義組件內部元素）。
• page_waitTimeout：等待指定的毫秒數。
• page_getData：獲取當前頁面的數據對象，可指定路徑。
• page_setData：使用 setData 更新當前頁面的數據。
• page_callMethod：調用當前頁面實例上暴露的方法。

元素工具（Element Tools）

• element_tap：通過 CSS 選擇器點擊 WXML 元素。
• element_input：向元素輸入文本（適用於 input 和 textarea 組件）。
• element_callMethod：調用自定義組件實例的方法（需要 ID 選擇器）。
• element_getData：獲取自定義組件實例的渲染數據（需要 ID 選擇器）。
• element_setData：設置自定義組件實例的渲染數據（需要 ID 選擇器）。
• element_getInnerElement：獲取元素內的元素（相當於 element.$(selector)）。
• element_getInnerElements：獲取元素內的元素數組（相當於 element.$$(selector)）。
• element_getSize：獲取元素大小（寬度和高度）。
• element_getWxml：獲取元素 WXML（內部或外部）。

每個工具都接受可選的 connection 塊來覆蓋環境默認值（項目路徑、CLI 路徑、WebSocket 端點等）。

📚 使用技巧

一般提示

• 連接前，在微信開發者工具中啟用自動化（設置 → 安全設置 → 服務端口）。
• 推薦首先調用 mp_ensureConnection 來驗證連接並查看系統/頁面詳情。
• 使用 WEAPP_AUTOCLOSE=true 適合無狀態的一次性交互。
• 導航時始終使用絕對路徑（以 / 開頭）：/pages/mine/mine。
• tabBar 頁面使用 switchTab，普通頁面使用 navigateTo。

操作自定義組件

🔴 重要：必須使用 ID 選擇器（如 #my-component）來定位自定義組件。

操作自定義組件時，有兩種方法：

方法一：使用 innerSelector 參數（推薦）

適用於 element_tap、element_input、element_getSize、element_getWxml 等工具：

{
  "selector": "#my-component",
  "innerSelector": ".inner-button"
}

• selector：自定義組件的 ID 選擇器。
• innerSelector：組件內部元素的選擇器。

方法二：使用元素內查詢工具

適用於 element_getInnerElement 和 element_getInnerElements：

{
  "selector": "#my-component",
  "targetSelector": ".inner-button"
}

限制說明

• page_waitElement 不適用於自定義組件內部元素。請使用 page_waitTimeout 配合元素查詢工具進行輪詢檢查。
• 自定義組件操作（如 element_callMethod、element_getData、element_setData）要求組件具有 id 屬性。