WordPress MCP Abilities API実装ガイド｜エラー解決と動作確認までの完全版

WordPress 6.9で導入されたAbilities APIとMCP Adapterプラグインを組み合わせると、Claude CodeからWordPressを直接操作できる。 本記事は、「【実装ガイド】WordPress MCPでAI連携｜Abilities API統合の全手順」の続編として、具体的な実装時のエラー解決に焦点を当てたものです。 詳細なアーキテクチャ全体像については、[前回の記事](https://wakatchi.dev/wordpress-mcp-adapter-base/) で解説しています。 実際に試してみたところ、いくつかの落とし穴にハマったので、解決方法を詳しく解説する。 ## こんな人におすすめ この記事は以下のような方に役立つはず。 - WordPress 6.9のAbilities APIを使ってカスタム機能を実装したい - MCP AdapterでClaude CodeからWordPressを操作したい - `mcp-adapter-discover-abilities`が空配列を返して困っている - 「mcp.public!=true」エラーの意味がわからない ## 目次 - [WordPress MCP連携で実現したいこと](#wordpress-mcp連携で実現したいこと) - [MCP Adapterが動かない3つのエラー](#mcp-adapterが動かない3つのエラー) - [エラー原因と解決への道筋](#エラー原因と解決への道筋) - [1. カテゴリ登録のフック名が違う](#1-カテゴリ登録のフック名が違う) - [2. MCP公開設定が未設定](#2-mcp公開設定が未設定) - [3. フック実行順序の理解不足](#3-フック実行順序の理解不足) - [Abilities APIの正しい実装手順](#abilities-apiの正しい実装手順) - [良かった点・得られた効果](#良かった点・得られた効果) - [【重要】動作確認の手順](#重要動作確認の手順) - [この記事のポイント（まとめ）](#この記事のポイントまとめ) - [補足：WordPress開発者向けのポイント](#補足wordpress開発者向けのポイント) ## WordPress MCP連携で実現したいこと WordPress 6.9のAbilities APIとMCP Adapterプラグインを使用して、Claude CodeからWordPressを直接操作するカスタムAbilitiesを実装しようとした。 正直なところ、公式ドキュメントが少なく、手探りで実装を進めるしかなかった。 ## MCP Adapterが動かない3つのエラー `mcp-adapter-discover-abilities`ツールを実行しても空配列が返され、登録したはずのAbilitiesが認識されない。 **エラー1**: カテゴリ登録時 ``` アビリティカテゴリーは wp_abilities_api_categories_init アクション上に登録されなければなりません ``` **エラー2**: Ability取得時 ``` Permission denied: Ability "mcp/create-blog-post" is not exposed via MCP (mcp.public!=true) ``` 意外にも、エラーメッセージは日本語で表示される。これが解決の糸口になった。 エラーが発生する流れを図にすると、以下のようになります。 ```mermaid sequenceDiagram participant Dev as 開発者 participant CC as Claude Code participant MCP as MCP Adapter participant WP as WordPress Dev->>CC: mcp-adapter-discover-abilities実行 CC->>MCP: Abilities取得リクエスト MCP->>WP: カテゴリ照会 alt カテゴリ登録エラー（誤ったフック使用） WP-->>MCP: エラー: 正しいフックで登録してください MCP-->>CC: 空配列 [] を返す CC-->>Dev: エラー: Abilitiesが見つかりません end alt MCP公開設定エラー（mcp.public!=true） MCP->>WP: Ability実行リクエスト WP-->>MCP: Permission denied: mcp.public!=true MCP-->>Dev: アクセス拒否エラー end ``` ## エラー原因と解決への道筋 私がハマったのは、以下の3つの問題が重なっていたこと。 ### 1. カテゴリ登録のフック名が違う 最初、Ability登録と同じフックでカテゴリを登録しようとしていた。 ```php // 誤: wp_abilities_api_init でカテゴリ登録 add_action( 'wp_abilities_api_init', function() { wp_register_ability_category( 'mcp-content', array(...) ); } ); ``` これだとエラーが出る。カテゴリには専用のフックがある。 ```php // 正: wp_abilities_api_categories_init を使う add_action( 'wp_abilities_api_categories_init', function() { wp_register_ability_category( 'mcp-content', array(...) ); } ); ``` ### 2. MCP公開設定が未設定 個人的に一番ハマったのがこれ。REST APIの公開設定（`show_in_rest`）を設定しても、MCP経由では動作しない。 ```php 'meta' => array( 'show_in_rest' => true, // これだけでは不十分 'mcp' => array( 'public' => true, // これが必要！ ), ), ``` `meta.mcp.public => true` を設定しないと、MCP Adapterがそのアビリティを認識しない。 ### 3. フック実行順序の理解不足 WordPressのフックは実行順序がある。 ```mermaid flowchart LR A[wp_abilities_api_categories_init<br/>カテゴリ登録] --> B[wp_abilities_api_init<br/>Ability登録] style A fill:#e1f5fe style B fill:#c8e6c9 ``` カテゴリが先に登録されていないと、Ability側で参照できない。この順序を理解するまでに時間がかかった。 ## Abilities APIの正しい実装手順 ### 完全な実装コード 実際に動作した完全なコードを以下に示す。 ```php // 1. カテゴリ登録（専用フック） add_action( 'wp_abilities_api_categories_init', function() { wp_register_ability_category( 'mcp-content', array( 'label' => 'Content Management', 'description' => 'Abilities for managing WordPress content', ) ); } ); // 2. Ability登録（別フック） add_action( 'wp_abilities_api_init', function() { wp_register_ability( 'mcp/create-blog-post', array( 'label' => 'Create Blog Post', 'description' => 'Create a new blog post', 'category' => 'mcp-content', 'meta' => array( 'show_in_rest' => true, 'mcp' => array( 'public' => true, // これが重要！ ), ), 'input_schema' => array( 'type' => 'object', 'properties' => array( 'title' => array( 'type' => 'string' ), 'content' => array( 'type' => 'string' ), ), 'required' => array( 'title', 'content' ), ), 'output_schema' => array( 'type' => 'object', 'properties' => array( 'post_id' => array( 'type' => 'integer' ), 'url' => array( 'type' => 'string' ), ), ), 'execute_callback' => function( $input ) { $post_id = wp_insert_post( array( 'post_title' => $input['title'], 'post_content' => $input['content'], 'post_status' => 'draft', ) ); return array( 'post_id' => $post_id, 'url' => get_permalink( $post_id ), ); }, 'permission_callback' => function() { return current_user_can( 'edit_posts' ); }, ) ); } ); ``` ## 良かった点・得られた効果 この実装が成功したことで、以下の効果があった。 **即時の効果** - Claude Codeから直接WordPressに記事を投稿できるようになった - 手動でWordPress管理画面を開く手間が省けた - 記事作成のワークフローが5分程度短縮された **長期的なメリット** - 実際に動かしてみると、Abilities APIの仕組みが深く理解できた - 他のカスタムAbility（画像アップロード、カテゴリ管理など）も同様に実装できる見通しが立った - MCP Adapterの内部動作がわかり、デバッグが容易になった ## 【重要】動作確認の手順 問題が解決したかどうかは、以下の手順で確認できる。 正常に動作する場合の流れを図にすると、以下のようになります。 ```mermaid sequenceDiagram participant Dev as 開発者 participant WP as WordPress participant CC as Claude Code participant MCP as MCP Adapter Note over Dev,WP: Step 1: コード実装 Dev->>WP: Code Snippetsでコードを保存 Note over CC,MCP: Step 2: MCP再接続 Dev->>CC: /mcp を実行 CC->>MCP: 再接続リクエスト MCP-->>CC: 接続完了 Note over CC,MCP: Step 3: Abilities確認 Dev->>CC: mcp-adapter-discover-abilities CC->>MCP: Abilities取得リクエスト MCP->>WP: Abilities API照会 WP-->>MCP: カテゴリ&Abilityリスト MCP-->>CC: Abilities情報を返す CC-->>Dev: 登録したAbilitiesが表示される Note over CC,MCP: Step 4: 動作確認 Dev->>CC: mcp-adapter-execute-ability CC->>MCP: Ability実行リクエスト MCP->>WP: Ability実行 WP-->>MCP: 実行結果 MCP-->>CC: 結果を返す CC-->>Dev: 記事作成完了 ``` 具体的な確認ステップは以下の通りです。 1. Code Snippetsでコードを保存 2. Claude Codeで `/mcp` を実行してMCPサーバーを再接続 3. `mcp-adapter-discover-abilities` でAbilitiesが表示されることを確認 4. `mcp-adapter-execute-ability` で実際に動作確認 ## この記事のポイント（まとめ） 今回の問題から得た教訓をまとめておく。 1. **WordPress 6.9 Abilities APIは2つのフックを使い分ける** - カテゴリ: `wp_abilities_api_categories_init` - Ability: `wp_abilities_api_init` 2. **MCP Adapterは`meta.mcp.public`をチェックする** - REST API公開の`show_in_rest`とは別の設定 - これを忘れると「Permission denied」エラーになる 3. **debug.logのエラーメッセージが解決の鍵** - 日本語でわかりやすいエラーが出るので、ログを確認する習慣をつける 4. **フックの実行順序を意識する** - カテゴリ → Ability の順序でないと参照エラーになる --- ## 補足：WordPress開発者向けのポイント ### PHP開発経験を活かす WordPress Abilities APIは、WordPressプラグイン開発の経験がある方ならすぐに理解できる設計になっています。既存の `add_action` フックシステムやWordPressプラグインの開発知識がそのまま活かせるでしょう。 ### debug.logの活用方法 WordPressのデバッグモードを有効にすると、`wp-content/debug.log` に詳細なエラー情報が出力されます。 MCP Adapterのトラブルシューティングには、このログの確認が欠かせません。本記事で紹介したエラーメッセージも、すべてこのログから取得したものです。 **debug.logの確認手順**: 1. WordPressの `wp-config.php` でデバッグモードを有効化 ```php define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); ``` 2. サーバー上の `wp-content/debug.log` を確認（SSHやFTPでアクセス） 3. エラーメッセージを検索 ### Code Snippetsプラグインの利点 本記事ではCode Snippetsプラグインを使用していますが、これは以下の理由から推奨です： - プラグイン開発の知識がなくても、すぐにPHPコードを追加可能 - WordPress管理画面から直接編集・管理できる - サーバーへのFTPアクセスが不要 - コードの有効/無効をワンクリックで切り替え可能 WordPressサイトの管理画面で効率的に開発を進めることができます。 --- ## 参考リンク - [WordPress Abilities API (GitHub)](https://github.com/developer-wp/abilities-api) - [MCP Adapter Plugin](https://wordpress.org/plugins/mcp-adapter/)