這禮拜的主題比較硬一點，但如果你有在用 AI 開發外掛然後想讓自己的 Antigravity 或是 Claude Code 讀到網站的內容像是查訂單，這篇教學就非常適合貼給 AI 請它幫你開發～

話說之前做 DWP 的 LINE 聊天機器人查 WooCommerce 訂單，會員可以直接在 LINE 裡問訂單狀態、查活動，背後是 OpenAI 的 Function Call 在跑。整個架子是自己刻的——每一個會員問句能對應到的後端動作，要自己定義一份 JSON Schema 告訴模型「這個工具吃什麼參數、回什麼結構」，再寫一個 dispatcher 收到 model 的 tool_calls 之後手動 routing 到對應的 WP 函式，回傳值也要自己塞回對話 context。

換一家模型供應商就要重做一次 schema 格式（OpenAI、Anthropic、Gemini 的欄位名稱都不一樣），漏處理一個錯誤路徑 LINE 那邊就吐出一堆奇怪的字。一份「查訂單狀態」的能力，被綁死在這個 LINE Bot 專案裡，搬不到別處用。

直到 WordPress 6.9 把 WordPress Abilities API 正式收進 core，加上 Automattic 維護的 MCP Adapter，這套東西就有了官方標準。同一個 ability 一次註冊，就同時能從 PHP、REST API、跟 MCP（給 Claude Code、Claude Desktop、Cursor 這些 AI client 直接呼叫）三個路徑使用。這篇就是用我們做的 cdx-mcp 外掛當實例，把整條路走過一次。

WordPress Abilities API 是什麼

Abilities API 是 WordPress 6.9 開始進 core 的官方標準，讓你把一段「可被外部呼叫的功能」用統一格式註冊起來，附上輸入／輸出 schema、權限檢查跟標籤——之後 PHP、REST、AI agent 都能用同一份定義去呼叫它。

對應到之前 LINE Bot 自刻 Function Call 的痛點，差別在：

手刻 Function CallAbilities API每個 model 廠商一份 schema一份 input／output schema 全平台共用自己寫 dispatcher routing用 wp_register_ability( $name, $args ) 註冊自己驗證權限、自己回錯誤permission_callback + 回 WP_Error 是標準約定只能在那個專案內用註冊完同時走 PHP／REST／MCP

註冊一個 ability 需要的關鍵欄位：

• label 跟 description：description 是寫給 AI 看的，講清楚做什麼、吃什麼、回什麼
• category：先用 wp_register_ability_category() 註冊好，ability 才能歸到那個 category 底下
• input_schema / output_schema：JSON Schema 格式
• execute_callback：實際做事的 PHP function
• permission_callback：Required，不是 optional（官方 PHP API 文件曾經寫成 optional，後來修正）
• meta.annotations：標示這個 ability 的特性（唯讀、是否會破壞資料、是否冪等）

meta.annotations 這幾個旗標被 MCP Adapter 自動映射成 readOnlyHint、destructiveHint、idempotentHint，AI 會看這幾個值來決定要不要自動呼叫。特別注意 destructive 預設值是 true，純查詢的 ability 一定要手動設成 false，不然 Claude 會以為這動作有破壞性而拒絕自動執行。這是文件埋得比較深的雷。

MCP Adapter 把 ability 轉成 MCP tool

Abilities API 解決了「功能怎麼註冊」，MCP Adapter 解決的是「怎麼讓 AI agent 找得到並呼叫它」。

Model Context Protocol（MCP）是 Anthropic 推出的開放協定，讓 AI client（Claude Code、Claude Desktop、Cursor、VS Code 等）能透過統一介面去呼叫外部工具。MCP Adapter 就是 WordPress 這端的橋——把已註冊的 ability 包裝成 MCP server 暴露出去，AI client 用 tools/list 跟 tools/call 兩個方法就能讀到 schema 並執行。

裝起來有兩種選擇：

1. 用 default server：裝完 mcp-adapter 外掛就會自動建一個叫 mcp-adapter-default-server 的 server，要把 ability 加進去得在註冊時加一個 meta.mcp.public = true 旗標
2. 自己建 custom server：在自己的外掛裡明確指定要暴露哪些 ability，乾淨可控，且不需要那個 public 旗標

我走第二條直接用 Composer 安裝，就不用讓使用者還要另外去裝 adapter 外掛了。

實戰：cdx-mcp 外掛把 WooCommerce 訂單查詢變 MCP tool

我做了一個外掛叫 cdx-mcp，功能很單純：給一個 WooCommerce 訂單 ID，回傳這筆訂單的完整結構化資料（狀態、金額、客戶、付款方式、品項），給 Claude Code 直接拿來查訂單。整個外掛大概 200 行 PHP，因為程式碼有點多，請幫我移駕到這邊吧：https://oberonlai.blog/wordpress-abilities-api-mcp-server/​