Lightweight SEO for WordPress — no bloat, no upsells, just what you need.
Essential SEO without the weight: meta tags, Open Graph, Twitter Cards, XML sitemaps, Schema/JSON-LD, canonical URLs, per-post SEO fields with live preview, Product schema for custom post type catalogs, IndexNow submission, Google Analytics and Google Ads tags, llms.txt, and a Markdown version of every post for AI agents.
- WordPress 7.1+
- PHP 8.4+
Download thatseoagent.zip from the latest release. It is the plugin ready to install, built for each release: nothing to compile, and only the files WordPress loads, without the sources, docs and tests of this repository. Upload it under Plugins → Add New Plugin → Upload Plugin, or install it with WP-CLI:
wp plugin install https://github.com/thatseoagent/thatseoagent/releases/latest/download/thatseoagent.zip --activateActivate and it works; the defaults need no configuration. Settings — site identity, homepage, analytics and tags, llms.txt, IndexNow — live in their own ThatSeoAgent admin menu.
With WooCommerce active, WooCommerce marks up its products — the Product with its prices, and the BreadcrumbList of the shop's pages — and ThatSeoAgent keeps their title, description and sharing image. WooCommerce's products are never a product catalog.
While another SEO plugin is active (Yoast SEO, Rank Math, All in One SEO, SEOPress, The SEO Framework, Squirrly), ThatSeoAgent outputs nothing in <head> but the analytics tags, serves no sitemaps or llms.txt and leaves robots.txt alone, so the two never duplicate each other's tags. The analytics tags stay because other SEO plugins do not print them: activating one does not cost the site its analytics. Import that plugin's data with wp thatseoagent import, then deactivate it.
- Meta tags — title, description, Open Graph, Twitter Cards, article metadata
- XML sitemaps — auto-generated and paginated at 1000 URLs per file, without the posts kept out of search or protected by a password
- Robots meta —
noindexon search results, 404 pages and private posts, largest image and text previews everywhere else, through core'swp_robots - Schema/JSON-LD — WebSite, Organization or Person, Article with its author as a Person (with a job title and profiles elsewhere, from two fields the plugin adds to the user profile), WebPage, CollectionPage, ProfilePage, BreadcrumbList, FAQPage (from question headings and Details blocks)
- Dashboard widget — the bulletin's headline, on the colour of its level, and its three most serious warnings on the WordPress dashboard, for administrators, in the admin's own markup
- Admin screen — a site bulletin: whether the site is fine in one sentence, on the color of its warning level, the warnings in force and what to do about each; plus the product report, llms.txt and settings
- Product catalogs — a theme or plugin declares its custom post type as a catalog, with its brand, category, specifications and gallery; each entry becomes a validated schema.org Product
- Breadcrumbs — the trail the schema states, for a theme to print with
thatseoagent_breadcrumbs(),[thatseoagent_breadcrumbs]or the Breadcrumbs block; accessible markup, no styles - Canonical URLs — replaces core's
rel_canonical; each page of a paginated listing or post is its own canonical, withrel="prev"/rel="next" - Per-post SEO — title/description meta box with live search preview, and a "Keep out of search results" box (
noindex), exposed to the REST API - Crawl cleanup — no shortlink, RSD, WLW or generator tag, comment feeds out of search indexes; optionally only the main feed, and spam searches sent to the homepage
- Attachment pages — redirected to their file, as WordPress does on sites installed since 6.4
- Site identity — declare whether the site represents a Person or an Organization
- Site verification — Google Search Console, Bing, Yandex, Baidu and Pinterest codes, printed on the homepage
- Analytics and tags — Google Analytics 4 and Google Ads IDs, alone or pasted as Google's whole snippet, loaded through one Google tag (gtag.js); any other service's code in the head, after the opening
<body>or in the footer, editable only by users who may publish unfiltered HTML - Homepage SEO — custom title/description with
%%sitename%%,%%tagline%%,%%sep%% - IndexNow — notify Bing/Yandex on publish (opt-in: no key, no requests)
- Markdown for AI agents — any post or page at its URL plus
.md, with YAML frontmatter, announced by arel="alternate"link in the head and in aLinkheader; the page's own URL answersAccept: text/markdownwith it too - llms.txt — a generated index of the site linking to the Markdown versions, and
llms-full.txtwith their full text in one file - AI crawlers — see which AI crawlers can read the site and why, check each one against the live server, and block them by group or one by one in robots.txt
- Content check — every page of a content type, a few at a time, against the same rules as the post audit the abilities return: nothing Google does not ask for is reported as a problem, each finding says whether Google, accessibility guidelines or our own judgement asks for it, and a check that cannot run says so
- WP-CLI — generate missing meta descriptions, import from other SEO plugins, validate product schema
- Bulk action — "Generate meta description" on the posts list
| URL | Content |
|---|---|
/sitemap.xml |
Index |
/sitemap-posts.xml |
Posts (paginates to -2, -3, …) |
/sitemap-pages.xml |
Pages (paginates) |
/sitemap-categories.xml |
Categories |
/sitemap-tags.xml |
Tags |
/sitemap-tax-{taxonomy}.xml |
Each public custom taxonomy with SEO fields, listed in the index while it has terms to list |
/sitemap-{cpt}.xml |
Each public custom post type (paginates) |
/sitemap_index.xml serves the same index, for Yoast compatibility, and the plugin rewrites the Sitemap: directive in robots.txt. Every page also announces the index in a Link: </sitemap.xml>; rel="sitemap" header (filter thatseoagent_sitemap_link_header). WordPress's own /wp-sitemap.xml is switched off while these are served, so search engines see one set.
A sitemap asks for its URLs to be indexed, so it lists no post marked Keep out of search results, no password-protected post and no attachment page. llms.txt leaves out the same posts.
Append .md to the URL of any published post or page:
curl https://example.com/my-post.md
curl https://example.com/about/team.md # hierarchical pages
curl https://example.com/2026/02/my-post.md # any permalink structureOr ask the page's own URL for Markdown, as HTTP content negotiation does:
curl -H 'Accept: text/markdown' https://example.com/my-postBrowsers never ask for it, so people keep getting the HTML. Both responses say Vary: Accept, and the Markdown one tells page caches not to store it.
A cache that answers before WordPress — a page cache plugin, a CDN — would still hand agents the stored HTML. AI index → Markdown for agents checks this from outside on demand and says which layer answered and what to change. Settings → Caches and CDN has the fixes: on Apache it can write a rule at the top of .htaccess that sends requests asking for Markdown to WordPress before any page cache plugin serves them (elsewhere it shows the lines to copy), and it gives the Cloudflare Cache Rules steps with links to Cloudflare's documentation.
An agent fetching the HTML pays for the navigation, sidebar, footer and scripts; the Markdown is only the content, typically 80–99% fewer tokens. The frontmatter carries the title, dates, author, permalink, excerpt, the same description the meta tags use, categories, tags and featured image.
X-Robots-Tag: noindexand a canonicalLinkheader keep search engines on the HTML page.Last-Modifiedis sent andIf-Modified-Sinceanswered with304.- Private, draft and password-protected posts follow the same rules as the HTML page.
- Cached in a transient per post (object-cache aware), invalidated when the post, its terms or its meta change. Needs pretty permalinks.
See docs/markdown for the details.
A catalog without WooCommerce — machinery, parts, a range of models — is usually a custom post type with its own taxonomies and meta. ThatSeoAgent does not guess which post types are catalogs: any theme or plugin that registers one declares it with thatseoagent_register_catalog(), and says where each product detail lives, on the thatseoagent_init action:
add_action( 'thatseoagent_init', function () {
thatseoagent_register_catalog( 'machine', array(
'brand_taxonomy' => 'machine_brand',
'category_taxonomy' => 'machine_type',
'properties' => fn ( WP_Post $post ) => my_theme_specs( $post->ID ),
'gallery' => '_machine_gallery',
'sku' => '_machine_sku',
) );
} );| Key | Takes | Schema |
|---|---|---|
brand_taxonomy |
a taxonomy of the post type | brand (Brand) |
category_taxonomy |
a taxonomy of the post type | category, as "Parent > Child" |
properties |
a meta key, or a callback that gets the post: a list of name/value pairs, a name => value map, or JSON of either | additionalProperty (PropertyValue) |
gallery |
a meta key, or a callback: attachment IDs, as a list or comma-separated | extra image entries |
sku, mpn, gtin |
a meta key, or a callback | sku, mpn, gtin |
Every key is optional. Name, description and featured image come from the post. Each entry is output as the page's mainEntity, instead of an Article.
The hook fires once per request, the first time anything asks for the catalogs, after init has begun: register the post type and its taxonomies on init before priority 20. A declaration outside the hook, of a post type that does not exist, or a second one of the same type is refused with _doing_it_wrong(); a key it does not know, or a detail mapped wrongly, is left out with the same notice and the rest kept. While WooCommerce is active its product types cannot be declared: WooCommerce marks them up itself. When the declarations change, the catalog file, llms.txt and the Products screen are rebuilt on their next request.
Without a theme or plugin that declares one, a site has no catalog: there is nothing to choose on the settings screen. See ADR 0003.
/catalog.jsonl gives agents the whole catalog as JSON Lines: each entry's Product markup, one per line, 100 per page (?page=2, announced with Link: rel="next"). Like llms.txt, it is for agents; search engines read the markup on each page.
Values are validated and dropped rather than output half-formed. ThatSeoAgent → Products lists what each product is missing, and wp thatseoagent validate-products checks the whole catalog. The markup carries no offers: a catalog declares no price, so there is nothing honest to put there. Google therefore shows no product rich result — that needs offers, a review or a rating — but the markup still describes each product to search engines and AI assistants.
/llms.txt opens with the site's about, contact and privacy pages, then lists the posts served as Markdown and the product catalogs — each catalog's 20 newest products, and a link to all of them in /catalog.jsonl — each entry linking to its .md version where there is one, with its description. It is a proposed convention, not a standard or a ranking factor. Regenerated when a post or the site identity changes; switch it off in the settings. A physical llms.txt in the site root takes precedence.
/llms-full.txt carries the content of those pages instead of links: each page with a Markdown version, in the same order, as its title, its URL and its Markdown, so an agent reads the site in one request. It is served and switched off with llms.txt, which links to it under ## Optional, and stops before 2 MB (filter thatseoagent_llms_full_max_bytes), ending with how many pages did not fit. A physical llms-full.txt takes precedence.
ThatSeoAgent → AI crawlers reads the robots.txt the site actually serves — the physical file in the site root if there is one, else the one WordPress builds with every plugin's edits — and shows, for each known crawler, whether it may read the site and which rule decides it. Check access now requests the homepage as each crawler, to catch a firewall, CDN or security plugin turning it away; it only runs when clicked.
The crawlers are grouped by what they do: search and answers (OAI-SearchBot, Claude-SearchBot, PerplexityBot, DuckAssistBot), visits asked for by a person (ChatGPT-User, Claude-User, Perplexity-User, Meta-ExternalFetcher) and training (GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, Meta-ExternalAgent, Amazonbot, CCBot, Bytespider). Googlebot, Bingbot and Applebot are shown but never blocked from here.
In Settings → AI crawlers, allow or block each group, with exceptions crawler by crawler. Blocking adds one group with Disallow: / to the virtual robots.txt; allowing writes nothing, because a crawler named in its own group stops following the site's * rules. Nothing is written until something is blocked, or while the site discourages search engines. With a physical robots.txt the rules cannot be served, and the screen gives the lines to paste instead.
The bulletin warns when robots.txt keeps search crawlers out, when a physical file ignores the chosen rules, or when another plugin writes crawler rules too. Blocking training is a choice, never a warning.
The plugin calls no service of its own and has no paid tier. It sends data to a third party only through settings you fill in:
- IndexNow — with an API key set, publishing or updating a post queues a background request to
https://api.indexnow.org/indexnowcontaining your site host, the key, the key file's URL and the URL of the post. Clearing the key stops these requests. The plugin also serves the{key}.txtverification file IndexNow requires. - Analytics and tags — with a Google Analytics 4 or Google Ads ID set, every front-end page loads
https://www.googletagmanager.com/gtag/js, and visitors' browsers send Google what that tag collects. Code pasted in the head, body or footer boxes is printed as written, and sends whatever it sends. Clearing the fields removes them.
The checks request the site's own pages, never another site: the AI crawler access check asks for the homepage as each crawler and for robots.txt, the Markdown check asks for one post as an agent and as a browser (these two run on demand and once a week), and the link report reads the homepage and asks up to 40 internal addresses it does not recognize whether they exist.
One class per file under includes/, grouped by concept and loaded by includes/autoload.php (an explicit class map: add a line there for a new class). ThatSeoAgent is the composition root: it calls each module's register(), and once after activation or a change of version, declared catalogs or stepping aside, it flushes the rewrite rules, purges the published files' caches and deletes the pre-3.0.0 catalog option. GLOSSARY.md defines the terms used below.
| Folder | Module | Responsibility |
|---|---|---|
includes/ |
ThatSeoAgent |
Composition root: which modules run, and when |
ThatSeoAgent_Settings |
Gathers each module's option (setting()) and registers it, with a schema, for the form and the REST API |
|
ThatSeoAgent_Memo |
Every per-request cache: forget_post() after each post in a loop, reset() to read the site again |
|
ThatSeoAgent_Loopback |
Every request the checks make to the site itself, through the WordPress HTTP API's filters | |
content/ |
ThatSeoAgent_Content |
The single answer to "what is this post's content?" |
ThatSeoAgent_Description |
The single answer to "what description does this post get?" | |
ThatSeoAgent_FAQ, ThatSeoAgent_FAQ_Section |
Reads content into sections; FAQ extraction | |
ThatSeoAgent_Post_Seo |
Per-post SEO fields: which post types get them, storage, sanitization and slashing | |
ThatSeoAgent_Structure |
How a post is built, as facts for an agent to judge | |
ThatSeoAgent_Image |
The image a page is represented by, for sharing and for the schema | |
ThatSeoAgent_Primary_Term |
The category that names a post where only one fits: the breadcrumb trail, article:section and the Product markup's category | |
ThatSeoAgent_Term_Seo |
Per-term SEO fields — title, description and noindex of a category, tag, brand or product category archive — on the term screens, in the head and in the sitemap | |
ThatSeoAgent_Sample_Content |
WordPress's sample post and page, while still published | |
head/ |
ThatSeoAgent_Meta |
<head> meta tags and canonical |
ThatSeoAgent_Title |
The single answer to "what title does this post show in search results?": the <title>, og:title, the editor's preview |
|
ThatSeoAgent_Schema |
JSON-LD graph | |
ThatSeoAgent_Breadcrumbs |
The breadcrumb trail: the BreadcrumbList, and the breadcrumbs a theme prints | |
indexing/ |
ThatSeoAgent_Indexing |
The single answer to "may search engines index this?": robots meta, and what the sitemaps and llms.txt may list |
ThatSeoAgent_Pagination |
Paginated listings and posts: page numbers, their URLs, rel="prev"/rel="next" |
|
ThatSeoAgent_Attachment_Redirect |
Attachment pages lead to their file | |
ThatSeoAgent_Crawl_Cleanup |
What nobody needs to crawl: shortlinks, RSD, the generator, extra feeds, spam searches | |
site/ |
ThatSeoAgent_Identity |
Who the site is: the settings, and the Person or Organization node and the X handle they make |
ThatSeoAgent_Homepage |
Homepage title and description settings | |
ThatSeoAgent_Default_Author |
The author credited on posts without one | |
ThatSeoAgent_Author_Profile |
An author's job title and profiles elsewhere, in the user profile | |
ThatSeoAgent_Trust_Pages |
The about, contact and privacy pages the bulletin looks for | |
ThatSeoAgent_New_Types |
Public content types the site owner has not looked at yet | |
ThatSeoAgent_Verification |
The verification tags of search engine consoles, on the homepage | |
catalog/ |
ThatSeoAgent_Product |
Product catalogs: their declarations, the Product node, validation |
ThatSeoAgent_Product_Report |
How complete the catalog is: summary and per-product report | |
ThatSeoAgent_Catalog_Feed |
The catalog as JSON Lines, one Product per line, for agents | |
sitemap/ |
ThatSeoAgent_Sitemap |
Sitemap routes and rendering (returns XML strings) |
ThatSeoAgent_Robots |
The Sitemap: directive and the blocked AI crawlers in robots.txt |
|
crawlers/ |
ThatSeoAgent_AI_Crawlers |
The known AI crawlers, the site owner's choices and the lines they add to robots.txt |
ThatSeoAgent_Crawler_Access |
Who can read the site: the served robots.txt read per crawler, and the on-demand access check | |
ThatSeoAgent_Robots_Parser |
Reads robots.txt as a crawler does (RFC 9309) | |
markdown/ |
ThatSeoAgent_Markdown |
A post as Markdown with YAML frontmatter |
ThatSeoAgent_Markdown_Endpoint |
The .md URLs and the rel="alternate" link |
|
ThatSeoAgent_Markdown_Cache |
Per-post Markdown cache and its invalidation | |
ThatSeoAgent_Markdown_Check |
Whether agents asking for Markdown get it: the on-demand check from outside | |
ThatSeoAgent_Markdown_Htaccess |
The .htaccess rule that keeps page caches away from Markdown requests | |
ThatSeoAgent_Cache_Settings |
Settings → Caches and CDN: the .htaccess rule and the Cloudflare steps | |
ThatSeoAgent_Llms |
llms.txt | |
ThatSeoAgent_Llms_Full |
llms-full.txt: the full text of the pages llms.txt lists | |
audit/ |
ThatSeoAgent_Audit |
The SEO audit of a post, and site scans |
ThatSeoAgent_Audit_Run |
The batched content check and its last results | |
ThatSeoAgent_Duplicates |
Pages that share a title or a description | |
ThatSeoAgent_Links |
How the pages link to each other: orphan pages and broken links | |
bulletin/ |
ThatSeoAgent_Bulletin |
The site's bulletin: gathers each checking module's bulletin() — its observations and warnings — ranks the warnings and words the headline |
ThatSeoAgent_Checks |
The access check's and the Markdown check's last two results, and their weekly run | |
ThatSeoAgent_Readings |
What the dashboard shows beside it: SEO field counts, the public files served | |
admin/ |
ThatSeoAgent_App |
The ThatSeoAgent screen: navigation, views, where each action leads, level colors, styles, scripts |
ThatSeoAgent_Icons |
The screen's inline SVG icons | |
ThatSeoAgent_Meta_Box |
The SEO fields in the post editor | |
ThatSeoAgent_Bulk_Descriptions |
The "Generate meta description" bulk action | |
ThatSeoAgent_Dashboard_Widget |
The bulletin on the WordPress dashboard | |
views/ |
The screen's templates | |
rest/ |
ThatSeoAgent_REST |
Registers the screen's controllers (thatseoagent/v1) |
ThatSeoAgent_REST_Controller |
Shared by every controller: namespace, permission, uncached responses | |
ThatSeoAgent_REST_Bulletin, _Preferences, _Audit, _Llms, _Crawlers, _Markdown |
One controller per resource | |
tooling/ |
ThatSeoAgent_CLI |
WP-CLI commands |
ThatSeoAgent_Abilities |
Abilities API registration: posts and terms | |
ThatSeoAgent_Site_Abilities |
Abilities API registration: settings and site reports | |
ThatSeoAgent_Importer |
Import from Yoast SEO, Rank Math, All in One SEO | |
integrations/ |
ThatSeoAgent_Compat |
Stepping aside while another SEO plugin is active |
ThatSeoAgent_WooCommerce |
What WooCommerce marks up itself: its products and their breadcrumbs | |
ThatSeoAgent_IndexNow |
IndexNow key, verification file and submission | |
ThatSeoAgent_Tracking |
Analytics and tags: the Google tag for GA4 and Google Ads, and code for the head, body and footer | |
ThatSeoAgent_MCP |
The plugin's own MCP server, when the Lean MCP plugin is active |
Title and description
| Filter | Purpose |
|---|---|
thatseoagent_document_title |
Override the title entirely (receives context and post) |
thatseoagent_title |
The resolved title, in the <title> and the meta tags alike (receives context and post) |
thatseoagent_title_separator |
Title separator (default |) |
thatseoagent_description |
The resolved description (receives context and post) |
thatseoagent_description_filler_patterns |
Intro-filler regexes skipped when generating |
Context is one of home, single, archive, taxonomy, search, author, date, 404, other. The post is the one whose title or description it is, null on a listing. For a post the filters run wherever its title or description is used — the head, the markup, the Markdown version, llms.txt, the editor, the content check — not only while its page is served, so branch on the post rather than on conditional tags like is_page().
Social
| Filter | Purpose |
|---|---|
thatseoagent_og_title |
og:title, over the resolved title (receives context) |
thatseoagent_og_site_name |
og:site_name (default the site name) |
thatseoagent_og_locale |
og:locale (default get_locale()) |
thatseoagent_og_type |
og:type of the current view: product, article, profile or website (receives context) |
thatseoagent_og_image_size |
Image size for Open Graph and Twitter; '' (default) takes the largest size under 2 MB (receives the attachment ID) |
thatseoagent_twitter_handle |
twitter:site handle (default the site identity's X handle; '' omits the tag) |
thatseoagent_twitter_repeat_open_graph |
Also print twitter:title, twitter:description and twitter:image, which X otherwise reads from Open Graph (off) |
thatseoagent_default_image |
Image URL for a page with none of its own, after the site identity's default sharing image |
Schema
A post's graph is ThatSeoAgent_Schema::for_post( $post ), the same inside its page's request and outside it — the get-post-seo ability returns it — so the filters that receive the post should branch on it rather than on conditional tags like is_singular().
| Filter | Purpose |
|---|---|
thatseoagent_primary_entity |
'person' or 'organization' — decides the publisher |
thatseoagent_website_schema |
WebSite node |
thatseoagent_organization_schema |
Organization node |
thatseoagent_person_schema |
Person node |
thatseoagent_webpage_schema |
WebPage node (receives the post) |
thatseoagent_breadcrumb_schema |
BreadcrumbList node (receives the post, null on a listing) |
thatseoagent_breadcrumb_trail |
The breadcrumb trail, for the schema and the visible breadcrumbs (receives the post, null on a listing) |
thatseoagent_breadcrumb_home |
Name of the homepage crumb (default "Home", translated) |
thatseoagent_main_taxonomy |
Taxonomy a post type's primary category is taken from (receives the post type) |
thatseoagent_article_post_types |
Post types that get an Article node (default post) |
thatseoagent_schema_image_size |
Image size of the Article image and the page's primary image (default full) |
thatseoagent_schema_graph |
The complete @graph before output (receives the post, null on any other view) |
thatseoagent_faq_schema_enabled |
Disable FAQ schema per post |
thatseoagent_faq_pairs |
The extracted Q&A pairs |
thatseoagent_faq_numbered_enabled |
Opt in to numbered-heading FAQs (off) |
thatseoagent_faq_thematic_enabled |
Opt in to thematic FAQs (off) |
thatseoagent_author_schema |
Person node of a post author |
thatseoagent_listing_page_schema |
CollectionPage / ProfilePage node of an archive |
thatseoagent_product_post_types |
Post types marked up as products |
thatseoagent_product_schema |
Product node |
thatseoagent_product_properties |
Specifications before they become PropertyValues |
Both FAQ opt-ins are off by default: they synthesise questions that do not appear on the page, which conflicts with Google's requirement that marked-up content be visible.
Indexing and crawling
| Filter | Purpose |
|---|---|
thatseoagent_noindex |
Whether the current page gets noindex (receives context); the sitemaps and llms.txt still follow the SEO fields |
thatseoagent_adjacent_links |
Print rel="prev"/rel="next" on paginated pages (default on) |
thatseoagent_redirect_attachment_pages |
Redirect attachment pages to their file (default on) |
thatseoagent_spam_search |
Whether a search is treated as spam (receives the search terms) |
thatseoagent_term_seo_taxonomies |
Taxonomies whose terms get SEO fields; the custom ones among them get a sitemap |
thatseoagent_trust_page_slugs |
Slugs that name the about, contact and privacy pages, by kind |
Sitemaps and admin
thatseoagent_sitemap_entries (the index listing) · thatseoagent_sitemap_link_header (the Link: rel="sitemap" header on every page, default on) · thatseoagent_meta_box_post_types
Other SEO plugins and llms.txt
thatseoagent_other_seo_plugin (return '' to keep ThatSeoAgent's output on) · thatseoagent_woocommerce_states_breadcrumbs (return false to keep ThatSeoAgent's BreadcrumbList on WooCommerce's pages, for a theme that prints none) · thatseoagent_ai_crawlers (the known crawlers and their groups) · thatseoagent_llms_txt_post_types · thatseoagent_llms_txt_limit · thatseoagent_llms_txt_catalog_limit (products per catalog, default 20) · thatseoagent_llms_txt · thatseoagent_llms_full_txt (the generated llms-full.txt) · thatseoagent_llms_full_max_bytes (default 2 MB)
Actions
thatseoagent_init (declare product catalogs, see Product catalogs) · thatseoagent_sitemap_index (echo extra <sitemap> entries into the index; prefer the thatseoagent_sitemap_entries filter)
Markdown
| Filter | Purpose |
|---|---|
thatseoagent_markdown_post_types |
Post types served as Markdown (default post, page) |
thatseoagent_markdown_frontmatter |
The frontmatter fields |
thatseoagent_markdown_html |
The HTML converted to Markdown (page builders) |
thatseoagent_markdown_include_custom_fields |
Opt in to custom fields in the frontmatter (off) |
thatseoagent_markdown_custom_fields |
The custom fields included |
thatseoagent_markdown_cache_duration |
Cache lifetime in seconds (default one hour) |
thatseoagent_markdown_alternate_link |
Print the rel="alternate" link to the .md URL (default on) |
thatseoagent_markdown_negotiation |
Answer Accept: text/markdown at the post's own URL (default on; receives the post); the .md URL works either way |
Custom fields are off by default: post meta not registered with show_in_rest is not public, and plugins routinely keep private data in it.
// Custom description for a specific page
add_filter( 'thatseoagent_description', function ( $desc, $context, $post ) {
return $post && 'special' === $post->post_name ? 'Custom description' : $desc;
}, 10, 3 );
// No SEO fields on a post type that is never public on its own
add_filter( 'thatseoagent_meta_box_post_types', function ( $types ) {
return array_diff( $types, array( 'testimonial' ) );
} );
// Site-specific intro filler to skip when generating descriptions
add_filter( 'thatseoagent_description_filler_patterns', function ( $patterns ) {
$patterns[] = '/welcome to our blog/i';
return $patterns;
} );
// Extra sitemaps in the index
add_filter( 'thatseoagent_sitemap_entries', function ( $entries ) {
$entries[] = array( 'loc' => home_url( '/custom.xml' ), 'lastmod' => null );
return $entries;
} );Registered on wp_abilities_api_init:
| Ability | Description | Capability |
|---|---|---|
thatseoagent/get-sitemap-urls |
Every sitemap URL the site publishes | manage_options |
thatseoagent/get-post-seo |
SEO of a post as its page publishes it: title, description, canonical, noindex, sharing image, primary terms, JSON-LD | edit_post |
thatseoagent/update-post-seo |
Update title, description, noindex, sharing image and primary terms; returns warnings (may be cut, shared with another page) | edit_post |
thatseoagent/audit-post-seo |
Audit one post, 0–100 score, and its structure as facts | edit_post |
thatseoagent/scan-seo-issues |
Scan many posts — one type or any, published or any status, one issue type — worst first, with each issue in full and next_offset to go on |
manage_options |
thatseoagent/generate-descriptions |
Save the generated description of up to 100 posts that have none | edit_post per post |
thatseoagent/list-term-seo |
Terms of every taxonomy with SEO fields, with what their archive publishes; filter by what is missing | manage_categories |
thatseoagent/get-term-seo |
SEO of a term's archive | edit_term |
thatseoagent/update-term-seo |
Update a term archive's title, description and noindex | edit_term |
thatseoagent/get-seo-settings |
The plugin's settings (identity, homepage, verification, crawlers…), what each does and its schema, and the declared catalogs | manage_options |
thatseoagent/update-seo-settings |
Change one setting, through its schema and sanitizer; tracking also needs unfiltered_html |
manage_options |
thatseoagent/get-duplicates |
Pages sharing a title or a written description | manage_options |
thatseoagent/get-link-report |
Orphan pages, broken internal links, navigation that leads nowhere | manage_options |
thatseoagent/get-site-bulletin |
The site's bulletin: level, warnings with where to fix them, observations | manage_options |
A post or term that does not exist, or has no SEO fields (a revision, an attachment, a post in the trash), is answered with why rather than a permissions error.
The audit applies the content check's rules: titles and descriptions that may be cut or that another page shares, a missing description, links search engines cannot follow, alt text — telling missing alt from the empty alt of decorative images — headings as accessibility, internal links, orphan pages and broken links as our own judgement, and, on catalog entries, their Product markup. Each finding carries its source, and checks that could not run come back in not_measured.
It also returns structure: how the post is built, as facts with no verdict — its headings in order, lists, tables, quotes, question-and-answer blocks, figures and percentages, paragraph and word counts, its first 150 words, its dates and the URL of its Markdown version. Nobody publishes how AI assistants choose what to cite, so the plugin scores none of it; an agent reviewing the site reads these facts, and the Markdown, and draws its own conclusions.
Every option is also registered with show_in_rest, so administrators can read and update them at /wp/v2/settings.
Optional. The fourteen abilities are registered with the WordPress Abilities API whether or not an MCP server exists. The MCP server is created only while the Lean MCP plugin is active, and Lean MCP is not publicly available yet; without it nothing below applies, and the abilities stay available to anything that calls the Abilities API.
With Lean MCP active, the abilities are also the tools of a dedicated MCP server, thatseoagent, whatever the theme. As tools the slash becomes a hyphen: thatseoagent-update-post-seo.
At https://<site>/wp-json/lean-mcp/thatseoagent, with the application password of an editor or administrator (edit_others_posts); anyone else gets a 401 or 403. Each tool also checks its own capability.
claude mcp add --transport http thatseoagent \
https://<site>/wp-json/lean-mcp/thatseoagent \
--header "Authorization: Basic $(printf 'USER:APPLICATION PASSWORD' | base64)"wp thatseoagent generate-descriptions [--post-type=post] [--batch-size=50] [--limit=0] [--dry-run]
wp thatseoagent import --from=<yoast|rankmath|aioseo> [--post-type=<types>] [--identity] [--overwrite] [--dry-run]
wp thatseoagent validate-products [--post-type=<type>] [--all] [--format=<table|csv|json>]generate-descriptionswrites a meta description for published posts that lack one, using the same rule the front end applies.importcopies titles and descriptions — and with--identity, the site's Person or Organization, name, logo and social profiles — from another SEO plugin, resolving its template variables. Values with unknown variables, and titles equal to the default, are skipped; existing values are kept unless--overwrite.validate-productslists catalog entries whose Product markup has errors or warnings.
The admin screen is styled with Tailwind CSS v4 and made interactive with Alpine.js. The compiled stylesheet (assets/build/admin.css) and Alpine itself (assets/vendor/alpine.min.js, pinned in package.json) are committed; only changing the templates, assets/src/admin.css or the Alpine version needs Node:
pnpm install
pnpm run build # Alpine into assets/vendor, the fonts into assets/fonts, then the CSS
pnpm run watch:css # while editing templatesThe screen's components live in assets/admin/app.js and register on alpine:init. Every view is server-rendered first and keeps working without scripts; the components start from the state printed into the page (window.thatSeoAgent), so nothing is fetched on load. Because Tailwind's utilities are !important, use x-show.important on elements that also carry a display utility.
REST endpoints for the screen, all administrators-only, under thatseoagent/v1: GET /bulletin, POST /preferences, GET /audit, POST /audit/runs, POST|DELETE /audit/runs/{token}, POST /llms, POST /crawlers/probe, POST /markdown/check, POST|DELETE /markdown/htaccess. Settings are saved through core's /wp/v2/settings.
Tailwind scans includes/admin/, includes/crawlers/, the Caches and CDN settings and assets/admin/app.js only, so the output holds just the classes they use. Colors are named by role (bg-paper, bg-sheet, text-ink-2, border-rule, text-met, bg-level-yellow…) and resolve to CSS variables that switch between the Day and Night editions. The screen wears the That SEO Agent brand (see DESIGN.md). Space Grotesk and Space Mono are self-hosted from assets/fonts/ (SIL Open Font License); pnpm run vendor:fonts copies them again from npm, should they need updating.
The HTML-to-Markdown library, league/html-to-markdown, ships in vendor-prefixed/ with its namespace rewritten to ThatSeoAgent\Dependencies\ by Strauss, so another plugin loading its own copy cannot conflict. vendor-prefixed/ is committed; installing the plugin needs no Composer.
Strauss runs as a .phar, not as a Composer package: its dependencies clash with Pest's. The .phar is not committed; before the first composer install, download it to bin/strauss.phar:
mkdir -p bin && curl -fL -o bin/strauss.phar https://github.com/BrianHenryIE/strauss/releases/download/0.30.0/strauss.pharTo update the library:
composer update league/html-to-markdown # Strauss runs on post-update-cmd
git add vendor-prefixed/ composer.lockPublishing a release on GitHub builds thatseoagent.zip with pnpm release and attaches it to the release (.github/workflows/release.yml). The release's tag, 3.0.0 or v3.0.0, must match the Version: in thatseoagent.php; otherwise the workflow fails and attaches nothing.
Tests are written with Pest, in four suites. tests/Unit runs on the plugin's classes alone, with no WordPress. The other three run inside a disposable WordPress started with wp-env (Docker), where the plugin is active:
tests/WordPresscalls the plugin in-process.pageAt()serves a URL up to the template and reads the<head>it prints. Each test runs inside a database transaction that is rolled back afterwards, so nothing it writes reaches the next one. No HTTP request leaves the site: a test answers the ones it expects withfakeHttp(), and any other request fails it.tests/Httpasks the site's web server withfetch(), for the responses that end the request (sitemaps, Markdown, llms.txt, the MCP server) and their headers.tests/Clirunswp thatseoagent …withwpCli(), as a person would.
The web server and WP-CLI cannot see an uncommitted transaction, so the Http and Cli tests write for real and Fixtures undoes it after each one. tests/mu-plugin.php, which wp-env loads into the test site only, gives them switches for situations a test cannot set up from its own process, such as another SEO plugin being active.
composer test # Unit suite; the WordPress tests skip themselves
pnpm env:start # Start the WordPress for the tests (http://localhost:8894)
pnpm test:wordpress # WordPress, Http and Cli suites
pnpm env:stop
composer analyse # PHPStan, level 5, with phpstan-baseline.neon
composer lint # Pint, checking the code style (pint.json)
composer format # Pint, fixing itThe MCP server's tests need Lean MCP active in the test site, and skip themselves without it; Lean MCP is not publicly available yet. With a copy of it, wp-env mounts it from a local .wp-env.override.json, not committed, that points at that copy:
{
"plugins": [".", "/path/to/lean-mcp"]
}Run pnpm env:start again after creating it.
Ships with Spanish (es_ES) and Uruguayan Spanish (es_UY). To add a language, copy languages/thatseoagent.pot to languages/thatseoagent-<locale>.po, translate it and compile both the .mo and the .json that carries the Breadcrumbs block's editor strings (assets/blocks/breadcrumbs.js):
wp i18n make-mo languages/thatseoagent-<locale>.po
wp i18n make-json languages/thatseoagent-<locale>.po --no-purgeDeleting the plugin removes its options, post meta, term meta, user meta (the screen's edition and author profiles) and transients, unschedules the queued IndexNow submissions and the weekly checks, on every site of a multisite network, and takes its block out of .htaccess. Deactivating leaves your data intact.
ThatSeoAgent began as a fork of Lean SEO 1.9.0, by Sarai Chinwag for Extra Chill, released under the GPL. It has since been rewritten and extended; the original copyright is kept in LICENSE.
Bundled: Alpine.js (MIT), league/html-to-markdown (MIT), Space Grotesk and Space Mono (SIL Open Font License), icons from Lucide (ISC).
License: GPL-2.0-or-later Author: Angel Cruz