New search_dev_docs MCP tool for developer.wordpress.org access

[jakeom]

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/