[wp-meta] [Making WordPress.org] #8239: New search_dev_docs MCP tool for developer.wordpress.org access

[Making WordPress.org]

#8239: New search_dev_docs MCP tool for developer.wordpress.org access
-------------------------+--------------------
 Reporter:  jakeom       |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:
Component:  API          |   Keywords:
-------------------------+--------------------
 == Proposal

 Add a `search_dev_docs` Ability to the existing `wporg-abilities` mu-
 plugin that lets MCP-connected AI agents search and retrieve content from
 developer.wordpress.org — including the Block Editor Handbook, Plugin
 Handbook, Theme Handbook, REST API Reference, Code Reference, and the
 Developer Blog.

 == Context

 The `wporg-abilities` plugin
 ([source](https://github.com/WordPress/wordpress.org/tree/trunk/wordpress.org/public_html
 /wp-content/plugins/wporg-abilities)) already registers Abilities for the
 Plugin Directory submission workflow (validate, submit, get-status, get-
 feedback, etc.). This ticket proposes extending that plugin with a
 documentation search Ability covering the developer handbooks.

 == Problem

 AI coding assistants frequently generate outdated or incorrect WordPress
 code because they lack real-time access to the canonical developer
 documentation. The Abilities API and the WordPress MCP Adapter (shipped in
 7.0) provide the infrastructure to solve this, but no Ability currently
 exposes developer.wordpress.org content to connected agents.

 A first-party Ability registered alongside the existing `wporg-abilities`
 tools would make accurate, up-to-date documentation discoverable by any
 MCP-connected agent automatically.

 == Proposed Ability Interface

 {{{
 Ability name:  search_dev_docs

 Parameters:
   query       (string, required)  — Natural-language or keyword search
 query.
   handbook    (string, optional)  — Scope to a specific handbook:
                                      block-editor | plugins | themes |
                                      rest-api | code-reference | apis |
 news
   per_page    (integer, optional) — Number of results (default 5, max 20).

 Returns:
   Array of objects:
     - title        (string)  — Page/section title
     - url          (string)  — Canonical URL on developer.wordpress.org
     - excerpt      (string)  — Relevant snippet (plain text, ≤500 chars)
     - handbook     (string)  — Source handbook slug
     - last_updated (string)  — ISO 8601 date
 }}}

 == Authentication

 This Ability should be **unauthenticated**. The content on
 developer.wordpress.org is entirely public, and requiring auth would
 unnecessarily limit adoption. The Abilities API supports per-ability
 capability requirements, so this can coexist in the same plugin alongside
 the authenticated Plugin Directory submission tools without issue.

 == Example Usage

 An agent connected via MCP could call:

 {{{
 search_dev_docs({ query: "register_block_type", handbook: "block-editor"
 })
 }}}

 And receive structured results pointing to the relevant Block Editor
 Handbook pages, enabling the agent to generate accurate, up-to-date code.

 == Implementation Notes

 * Register as an Ability in the existing `wporg-abilities` plugin so the
 tool is auto-discoverable alongside the Plugin Directory tools.
 * Could be backed by the existing WordPress.org search/REST infrastructure
 or a dedicated Elasticsearch index over handbook content.
 * Results should return plain-text excerpts (not full HTML) to stay within
 typical MCP token budgets.
 * Read-only — no capability requirement needed.
 * Rate limiting should be considered to prevent abuse of an
 unauthenticated endpoint.

 == Related

 * wporg-abilities plugin:
 https://github.com/WordPress/wordpress.org/tree/trunk/wordpress.org/public_html
 /wp-content/plugins/wporg-abilities
 * AI Building Blocks for WordPress:
 https://make.wordpress.org/ai/2025/07/17/ai-building-blocks-for-wordpress/
 * Introducing the WordPress Abilities API:
 https://developer.wordpress.org/news/2025/11/14/introducing-the-wordpress-
 abilities-api/
 * WordPress MCP Adapter: https://developer.wordpress.org/news/2026/02/04
 /from-abilities-to-ai-agents-introducing-the-wordpress-mcp-adapter/

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/8239>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org