Communitygithub.com

nekuda-ai/webmcp-kit

讓你的網站支援 AI 代理:一個專為 Claude Code 和 Codex 設計的外掛,為你的網路應用程式新增 WebMCP 工具。

webmcp-kit 是什麼?

WebMCP Kit 是一個階梯式驗證框架,專為開發者設計,用於檢查網站是否正確註冊並運作 WebMCP 工具。它可獨立執行,也是 `implement` 技能中 Phase F 的基礎。該技能支援 Claude Code、Codex 和 Cursor 等平台,利用內建的瀏覽器驅動程式(而非外部工具)來啟動隔離的 Chrome 150+ 實例。驗證過程分為多個階段:啟動網站、發現已宣告的工具、調用唯讀工具,以及(在指定情況下)調用會變更狀態的工具。最終會為每個工具生成一份報告,狀態包括「已驗證」、「失敗」或「無法驗證」。此技能對於確保網站對 AI 代理友善、且工具能正確註冊和運作至關重要。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add nekuda-ai/webmcp-kit

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

WebMCP Kit — 驗證

執行階段檢查,確認網站的 WebMCP 工具已註冊並能正常運作。可獨立執行,也是 implement 技能在 Phase F 中所使用的階梯。

開始之前

  • 網站必須在本地端執行。如果網站自帶執行手冊(包含生命週期指令、基本 URL、測試身份),請使用它;否則使用網站自己的開發腳本。切勿假設存在任何測試環境(harness)。
  • 使用此外掛內建的瀏覽器驅動程式。請勿要求設定 MCP、安裝全域的 chrome-devtools、Playwright 或手動驅動瀏覽器。

內建瀏覽器驅動程式

僅解析一次外掛根目錄。當主機有匯出時,使用 CLAUDE_PLUGIN_ROOT 或 PLUGIN_ROOT。否則,使用此技能顯示的絕對基本目錄(包含此 SKILL.md 的目錄)並向上兩層。請勿從儲存庫 checkout 位置猜測。

為整個階梯執行一次驅動程式會話:

plugin_root="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}"
if [ -z "$plugin_root" ]; then
  skill_dir="<此技能的絕對基本目錄>"
  plugin_root="$(cd "$skill_dir/../.." && pwd -P)"
fi
webmcp="${plugin_root}/scripts/webmcp.sh"

"$webmcp" browser status
"$webmcp" browser start
"$webmcp" browser status
"$webmcp" browser new_page "<本機 URL>" --output-format=json
"$webmcp" browser list_webmcp_tools <pageId> --output-format=json
"$webmcp" browser execute_webmcp_tool <pageId> <toolName> --input '<JSON 物件>' --output-format=json
"$webmcp" browser take_snapshot <pageId> --output-format=json
"$webmcp" browser list_console_messages <pageId> --output-format=json
"$webmcp" browser list_network_requests <pageId> --output-format=json
"$webmcp" browser stop

在 Windows 上,使用 PowerShell 套用相同的備援邏輯,並使用內建指令入口:

$pluginRoot = if ($env:CLAUDE_PLUGIN_ROOT) { $env:CLAUDE_PLUGIN_ROOT } elseif ($env:PLUGIN_ROOT) { $env:PLUGIN_ROOT } else { (Resolve-Path "<此技能的絕對基本目錄>\..\..").Path }
$webmcp = Join-Path $pluginRoot "scripts\webmcp.cmd"
& $webmcp browser status
& $webmcp browser start

透過 & $webmcp browser ... 執行其餘的階梯指令,並務必以 & $webmcp browser stop 結束。

start 會解析官方的 chrome-devtools-mcp@latest,啟動一個主機會話範圍內隔離的無頭 Chrome 150+,並帶有 --category-experimental-webmcp 和 --enable-features=WebMCP 參數,同時停用使用統計和 CrUX,並編輯網路標頭。當並行執行共用一個工作區時,將 WEBMCP_BROWSER_SESSION_ID 設為任意唯一值;否則,入口會優先使用 Claude/Codex 會話(如果可用),然後是工作區。它首先使用支援的已安裝或快取的瀏覽器;如果沒有,且在 Chrome for Testing 發佈的平台上,它會將穩定版 Chrome 下載到使用者快取中並在後續重複使用。你可以傳遞 --executable-path <路徑> 來指定已知安全的測試瀏覽器。在不支援的主機(如 Linux arm64)上,請安裝原生 Chrome/Chromium 150+ 並改為設定 WEBMCP_BROWSER_PATH。

如果 start 失敗,請報告其確切的 Node/npm、下載、架構、共用函式庫或啟動錯誤,並將依賴瀏覽器的工具標記為 無法驗證。切勿使用 sudo、系統套件管理器或一般的 Chrome 設定檔。在非正常中斷的執行後,請在重試前先使用 status,然後 stop。在清理時務必停止驅動程式,包括在階梯執行失敗之後。

階梯

  1. 啟動。 網站啟動;基準頁面呈現;與乾淨載入相比,沒有新的主控台錯誤。
  2. 發現。 在每個宣告的頁面和驗證狀態上——檢查匿名和已登入(如果相關)——列出已註冊的工具。確認每個工具應出現的位置都出現,在不應出現的位置(未登入的帳戶工具、錯誤角色的工具)則確實不存在,並在其宣告的退出條件(空購物車、登出)下取消註冊。導航是昂貴的單位:每個頁面 × 驗證狀態僅訪問一次,並在該次單一訪問中滿足該頁面上每個工具的期望——切勿為每個工具導航一次。
  3. 調用唯讀工具。 使用範例輸入調用唯讀工具;檢查回傳的資料以及可見的 ui_effect。按頁面批次處理:在發現工具的訪問中調用該頁面的工具。
  4. 調用會變更狀態的工具。 僅針對本地/開發/種子資料,並需獲得明確許可。切勿向第三方或生產服務發送真實的 POST 請求。沒有安全的方式可以調用 → 就不要調用;回報「無法驗證」。

報告——每個工具一個狀態

  • 已驗證 — 按宣告註冊並調用(註明達到的階梯階段)。
  • 失敗 — 未註冊或出錯;必須修復或移除,絕不可出貨。
  • 無法驗證 — 看似合理但未經證實(無瀏覽器,或無安全調用方式);出貨時需標記。

輸出每個工具的表格,並重申任何「無法驗證」的項目。

相關技能