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 を取得します（内部または外部）。

各ツールは、環境のデフォルト値（プロジェクトパス、CLI パス、WebSocket エンドポイントなど）を上書きするためのオプションの connection ブロックを受け取ります。

使用上のヒント

一般的なヒント

• 接続する前に、微信開発者ツールで自動化を有効にしてください（「設定 → セキュリティ設定 → サービスポート」）。
• 最初に mp_ensureConnection を呼び出して、接続を検証し、システム/ページの詳細を確認することをおすすめします。
• WEAPP_AUTOCLOSE=true を使用すると、ステートレスな一度限りのインタラクションに適しています。
• ナビゲートするときは常に絶対パス（/ で始まる）を使用してください：/pages/mine/mine。
• tabBar ページには switchTab を、通常のページには navigateTo を使用してください。

カスタムコンポーネントの操作

🔴 重要：カスタムコンポーネントを特定するには、必ず ID セレクタ（例：#my-component）を使用してください。

カスタムコンポーネントを操作するには、2 つの方法があります。

方法 1：innerSelector パラメータを使用する（推奨）

element_tap、element_input、element_getSize、element_getWxml などのツールに適用されます。

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

• selector：カスタムコンポーネントの ID セレクタ。
• innerSelector：コンポーネント内の要素のセレクタ。

方法 2：要素内のクエリツールを使用する

element_getInnerElement と element_getInnerElements に適用されます。

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

制限事項

• page_waitElement はカスタムコンポーネント内の要素には適用できません。page_waitTimeout と要素クエリツールを組み合わせてポーリングチェックを行ってください。
• カスタムコンポーネントの操作（element_callMethod、element_getData、element_setData など）では、コンポーネントに id 属性が必要です。