Register Yoast SEO abilities about analysis scores by leonidasmi · Pull Request #23062 · Yoast/wordpress-seo

leonidasmi · 2026-03-10T10:27:56Z

Context

WordPress 6.9 introduced the Abilities API and this PR intends to integrate with that, to give users the ability to use the results of Yoast SEO analysis for posts when they interact with their websites in AI agentic mode, via MCP servers.
This video demonstrates what we are actually adding with this PR.
- It shows how Claude, which is connected via MCP (using the official MCP adapter plugin) to a website with this PR active, uses our new abilities in order to respond to the user that asked for information about the SEO/Readability/Inclusive Language analyses of their latest posts.
- If you're interested in testing this flow yourself, this article explains how you can connect Claude to your MCP server in your website.

Summary

This PR can be summarized in the following changelog entry:

Adds a Yoast ability for retrieving scores for Yoast analyses for recent posts, using the Abilities API.

Relevant technical choices:

Test instructions

Test instructions for the acceptance test before the PR gets merged

This PR can be acceptance tested by following these steps:

Do a GET request to WP's http://example.com/wp-json/wp-abilities/v1/abilities endpoint and confirm that you see the yoast-seo/get-seo-scores ability we added and that it looks like this:

    {
        "name": "yoast-seo/get-seo-scores",
        "label": "Get SEO Scores",
        "description": "Get the SEO scores for the most recently modified posts.",
        "category": "yoast-seo",
        "input_schema": {
            "type": "object",
            "properties": {
                "number_of_posts": {
                    "type": "integer",
                    "description": "The number of recently modified posts to retrieve scores for. Defaults to 10.",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 10
                }
            }
        },
        "output_schema": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string",
                        "description": "The post title."
                    },
                    "score": {
                        "type": "string",
                        "enum": [
                            "na",
                            "bad",
                            "ok",
                            "good"
                        ],
                        "description": "The score slug."
                    },
                    "label": {
                        "type": "string",
                        "description": "A human-readable label for the score."
                    },
                    "focus_keyphrase": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The focus keyphrase for the post, or null if not set."
                    }
                }
            }
        },
        "meta": {
            "annotations": {
                "readonly": true,
                "destructive": false,
                "idempotent": true
            },
            "show_in_rest": true,
            "mcp": {
                "public": true
            }
        },
        "_links": {
            "self": [
                {
                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-seo-scores",
                    "targetHints": {
                        "allow": [
                            "GET"
                        ]
                    }
                }
            ],
            "collection": [
                {
                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities"
                }
            ],
            "wp:action-run": [
                {
                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-seo-scores/run"
                }
            ]
        }
    }

FOR DEVS: Take a look at the descriptions/input_schema/output_schema and verify that they make sense
- Those are basically the instructions for agents on how to use our Abilities, so verify having that in mind.
Also do the same for 2 other very similar abilities listed:
- One for readability of recent posts - yoast-seo/get-readability-scores
- One for inclusive language scores of recent posts - yoast-seo/get-inclusive-language-scores
Now confirm that if you disable SEO/Readability/Inclusive analysis, the respective ability doesn't appear in the results.

Actually run the abilities

For the SEO score one

In your latest posts, have
- a post that has no keyphrase
- a post that has a good SEO score (over 70)
- a post that has an ok SEO score (over 40)
- a post that has a bad SEO score
Do a GET request to http://dev.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-seo-scores/run?input[number_of_posts]=4 and you should get 4 arrays, one for each post of the above. The results should be sorted as, the most recently modified post first.
For the post that has no keyphrase, confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "na",
    "label": "Not available",
    "focus_keyphrase": null
}

For the post that has a good SEO score (over 70), confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "good",
    "label": "Good",
    "focus_keyphrase": "Your set keyphrase"
}

For the post that has an ok SEO score (over 40), confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "ok",
    "label": "OK",
    "focus_keyphrase": "Test keyphrase"
}

For the post that has a bad SEO score, confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "bad",
    "label": "Needs improvement",
    "focus_keyphrase": "test"
}

For the readability score one

In your latest posts, have
- a post that has no readability score (which means that it was created while Yoast was inactive and never saved via the editor while Yoast was active - you do need to run the SEOO once you re-activate Yoast though)
- a post that has a good readability score (over 70)
- a post that has an ok readability score (over 40)
- a post that has a bad readability score
Do a GET request to http://dev.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-readability-scores/run?input[number_of_posts]=4 and you should get 4 arrays, one for each post of the above
For a post that has no readability score (which means that it was created while Yoast was inactive and never saved via the editor while Yoast was active, confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "na",
    "label": "Not available"
}

For a post that has a good readability score (over 70), confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "good",
    "label": "Good"
}

For a post that has an ok readability score (over 40), confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "ok",
    "label": "OK"
}

For a post that has a bad readability score, confirm that you get a response like:

{
    "title": "THE TITLE OF THE POST,
    "score": "bad",
    "label": "Needs improvement"
}

For the inclusivity score one

Repeat the same steps for the readability tests, the conditions are the same and the endpoint is: /wp-json/wp-abilities/v1/abilities/yoast-seo/get-inclusive-language-scores/run?input[number_of_posts]=4

Edge cases

Now run one of the abilities for an id of a post that hasn't been created an indexable for
- Reset indexables and without going to a different page, run one of the abilities
- Confirm you get an empty array as a response.
Now run the ability of an analysis that's not enabled (eg. disable the readability analysis from Yoast settings)
- Confirm you get a 404 with a Ability not found. message
Now run the ability of the inclusive language analysis on a site with language non-english
- Confirm you get a 404 with a Ability not found. message
Now run one of the abilities while logged in as Author
- Confirm you get a 403 with a Sorry, you are not allowed to execute this ability. message
Now install the PR/RC in a WP site that's pre 6.9
- Confirm that you get a 404

Disable the abilities via hooks

Add the following snippet in your site:

add_action( 'wp_abilities_api_init', function() { 
        if ( wp_has_ability( 'yoast-seo/get-seo-scores' ) ) {
            wp_unregister_ability( 'yoast-seo/get-seo-scores' );
        }
    }, 20
); // Run after Yoast registers at default priority 10

Confirm that running the SEO score ability gets you a 404 - Ability not found response.

Relevant test scenarios

Changes should be tested with the browser console open
Changes should be tested on different posts/pages/taxonomies/custom post types/custom taxonomies
Changes should be tested on different editors (Default Block/Gutenberg/Classic/Elementor/other)
Changes should be tested on different browsers
Changes should be tested on multisite

Test instructions for QA when the code is in the RC

QA should use the same steps as above.

QA can test this PR by following these steps:

Impact check

This PR affects the following parts of the plugin, which may require extra testing:

Other environments

This PR also affects Shopify. I have added a changelog entry starting with [shopify-seo], added test instructions for Shopify and attached the Shopify label to this PR.
This PR also affects Yoast SEO for Google Docs. I have added a changelog entry starting with [yoast-doc-extension], added test instructions for Yoast SEO for Google Docs and attached the Google Docs Add-on label to this PR.

Documentation

I have written documentation for this change. For example, comments in the Relevant technical choices, comments in the code, documentation on Confluence / shared Google Drive / Yoast developer portal, or other.

Quality assurance

I have tested this code to the best of my abilities.
During testing, I had activated all plugins that Yoast SEO provides integrations for.
I have added unit tests to verify the code works as intended.
If any part of the code is behind a feature flag, my test instructions also cover cases where the feature flag is switched off.
I have written this PR in accordance with my team's definition of done.
I have checked that the base branch is correctly set.
I have run grunt build:images and commited the results, if my PR introduces new images or SVGs.

Innovation

No innovation project is applicable for this PR.
This PR falls under an innovation project. I have attached the innovation label.
I have added my hours to the WBSO document.

Fixes #

coveralls · 2026-03-10T10:39:40Z

Pull Request Test Coverage Report for Build 4d046a7cb4cccf440b890379cf797088736bd3f5

Details

43 of 197 (21.83%) changed or added relevant lines in 5 files are covered.
No unchanged relevant lines lost coverage.
Overall first build on hackathon/wp-abilities at 49.929%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/abilities/domain/score-result.php	0	10	0.0%
src/abilities/application/score-retriever.php	9	53	16.98%
src/abilities/user-interface/abilities-integration.php	20	120	16.67%

Totals
Change from base Build b6af95c079e10165cab56ea4ef224a3d3c29b93e:	49.9%
Covered Lines:	19314
Relevant Lines:	38683

💛 - Coveralls

…abilities

Copilot

Pull request overview

This PR adds a Yoast SEO integration for WordPress 6.9’s Abilities API, exposing abilities that let authorized users retrieve recent post analysis scores (SEO, readability, inclusive language) for agentic/MCP use.

Changes:

Add an Abilities_API_Conditional to only load the integration when the Abilities API is available (WP 6.9+).
Introduce an Abilities_Integration that registers a Yoast category plus score-retrieval abilities (gated by enabled analysis features).
Add supporting services (Score_Retriever, Enabled_Analysis_Features_Checker, Score_Result) and unit tests for the new behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`src/conditionals/abilities-api-conditional.php`	Adds a WP-version conditional for enabling the integration.
`src/abilities/user-interface/abilities-integration.php`	Registers the Yoast ability category and score abilities (SEO/readability/inclusive language).
`src/abilities/infrastructure/enabled-analysis-features-checker.php`	Determines which analyses are enabled (incl. language support check for inclusive language).
`src/abilities/application/score-retriever.php`	Fetches recent post indexables and maps them to ability output payloads.
`src/abilities/domain/score-result.php`	Value object for serializing score output.
`tests/Unit/Conditionals/Abilities_API_Conditional_Test.php`	Unit tests for the version conditional.
`tests/Unit/Abilities/User_Interface/Abilities_Integration_Test.php`	Unit tests for ability/category registration and permission callback wiring.
`tests/Unit/Abilities/Infrastructure/Enabled_Analysis_Features_Checker_Test.php`	Unit tests for enabled-feature detection behavior.
`tests/Unit/Abilities/Application/Score_Retriever_Test.php`	Unit tests for score retrieval/mapping output (SEO/readability/inclusive).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

thijsoo

Couple of comments.

thijsoo · 2026-04-02T10:10:41Z

+	 *
+	 * @return void
+	 */
+	private function register_seo_scores_ability(): void {


This might be a bit overkill so feel free to ignore. but if you make each ability its own integration you can have the enabled feature check be the conditional to just ignore the integration instead of having an early return. I think that would be a bit more clean but also a bit more code 🤷

I want to play it safe and avoid having these calculations in the conditionals because it's much earlier in the call stack that way and I dont think we have so complex calculations in there before. (the one that worries me more is the inclusive language check because it implicates languages/locales and stuff like that.)

So I think it's ok to not do that now, if that's alright.

Allows for a simpler implementation and also removed doing the same checks for the inclusive language feature twice

One for the abilities categories and one for the abilities themselves

thijsoo

CR + ACC 👍

leonidasmi added 2 commits March 5, 2026 13:41

Register Yoast SEO abilities about analysis scores

45ba0c2

Merge branch 'trunk' into hackathon/wp-abilities

4737d87

leonidasmi added the changelog: enhancement Needs to be included in the 'Enhancements' category in the changelog label Mar 10, 2026

leonidasmi added 8 commits March 10, 2026 13:14

Improve detecting the right WordPress version before registering the …

ef7feee

…abilities

Allow only admins and SEO managers to use the abilities

2ebf7d7

Refactor and improve

db6253d

Make abilitites not readonly

37b9fd0

Make abilities be about recent posts

09490df

Make this a read-only ability

77b1c5f

Merge branch 'trunk' into hackathon/wp-abilities

7d9f139

Remove ability to get all scores and refactor to simplify solution

83ef1fc

leonidasmi force-pushed the hackathon/wp-abilities branch from 9dfe841 to 83ef1fc Compare March 30, 2026 10:21

leonidasmi requested a review from Copilot March 30, 2026 10:50

Copilot started reviewing on behalf of leonidasmi March 30, 2026 10:51 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

leonidasmi added 5 commits March 30, 2026 14:01

Remove dead code

c143c06

Put upper limit for the amount of posts

8415fa6

Improve code coverage

ce5f97a

Remove noindex from the seo score ability

5ed9b22

Remove numeric scores from the abilities

e0b64c8

leonidasmi requested a review from Copilot April 2, 2026 07:08

Copilot started reviewing on behalf of leonidasmi April 2, 2026 07:09 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

leonidasmi added 2 commits April 2, 2026 10:25

Improve docblock of score property

b836cb2

Improve docblock for mixed arguments

1057e65

leonidasmi marked this pull request as ready for review April 2, 2026 09:45

thijsoo requested changes Apr 2, 2026

View reviewed changes

leonidasmi added 2 commits April 2, 2026 15:35

Remove the feature checker and use the existing repository

032e191

Allows for a simpler implementation and also removed doing the same checks for the inclusive language feature twice

Split the abilities user interfaces into two classes

2d3d0b2

One for the abilities categories and one for the abilities themselves

leonidasmi force-pushed the hackathon/wp-abilities branch from 35c9250 to 2d3d0b2 Compare April 2, 2026 12:54

thijsoo added this to the 27.5 milestone Apr 3, 2026

thijsoo approved these changes Apr 3, 2026

View reviewed changes

thijsoo merged commit 70996fc into trunk Apr 3, 2026
28 checks passed

thijsoo deleted the hackathon/wp-abilities branch April 3, 2026 07:28

Conversation

leonidasmi commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Summary

Relevant technical choices:

Test instructions

Test instructions for the acceptance test before the PR gets merged

Actually run the abilities

For the SEO score one

For the readability score one

For the inclusivity score one

Edge cases

Disable the abilities via hooks

Relevant test scenarios

Test instructions for QA when the code is in the RC

Impact check

Other environments

Documentation

Quality assurance

Innovation

Uh oh!

coveralls commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 4d046a7cb4cccf440b890379cf797088736bd3f5

Details

💛 - Coveralls

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thijsoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

thijsoo Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

leonidasmi Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thijsoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

leonidasmi commented Mar 10, 2026 •

edited

Loading

coveralls commented Mar 10, 2026 •

edited

Loading

leonidasmi Apr 2, 2026 •

edited

Loading