HelperSEO
Developer documentation for HelperSEO, a WordPress SEO plugin with AI writing tools, Google Search Console and Google Analytics 4 reporting, and a Model Context Protocol (MCP) endpoint.
Developer documentation for HelperSEO, a WordPress SEO plugin with AI writing tools, Google Search Console and Google Analytics 4 reporting, and a Model Context Protocol (MCP) endpoint.
This guide covers what developers need to extend, integrate, or debug HelperSEO: the hooks it fires, the filters you can change, the REST and AJAX surface, the Helpblogger connection, and where data is stored.
Contents#
- Requirements
- Architecture at a glance
- Hooks reference
- Shortcodes
- Sitemap and rewrite rules
- AI integration
- Helpblogger connection and Google data
- MCP endpoint
- AJAX endpoints
- Settings and storage
- Scheduled events
- Recipes
- Troubleshooting
- Support and resources
1. Requirements#
| Item | Requirement |
|---|---|
| WordPress | 6.0 or newer |
| PHP | 7.4 or newer (8.x recommended) |
| cURL | Required for outbound API calls |
| Helpblogger SDK | Version 3.4 or newer, for AI and Google features |
| Google account | Only for Search Console, Analytics, and the optional Instant Index feature |
HelperSEO works without a Helpblogger connection. Meta fields, sitemaps, schema, redirects, breadcrumbs, and the on-page analyzer do not need one. AI writing, Search Console reporting, and GA4 reporting do.
2. Architecture at a glance#
HelperSEO loads its classes from includes/. Admin screens live in admin/views/. The main plugin file is helperseo.php, which defines these constants:
| Constant | Purpose |
|---|---|
HELPERSEO_VERSION | Plugin version string |
HELPERSEO_PLUGIN_FILE | Absolute path to the main plugin file |
HELPERSEO_PLUGIN_DIR | Plugin directory path, with trailing slash |
HELPERSEO_PLUGIN_URL | Plugin directory URL, with trailing slash |
HELPERSEO_PLUGIN_BASE | Plugin basename |
Important classes:
| Class | Responsibility |
|---|---|
HelperSEO_Options | Read and write plugin settings with get() and set() |
HelperSEO_AI | AI generation, alt text, link suggestions, scoring |
HelperSEO_Connect | Helpblogger connection (SDK wrapper) |
HelperSEO_Google_Broker | Calls the Google broker through the connection |
HelperSEO_Search_Console | Search Console reports and per-page stats |
HelperSEO_Analytics | GA4 property picker and Measurement ID lookup |
HelperSEO_MCP | MCP REST endpoint |
HelperSEO_Sitemap | XML sitemaps and the [helperseo_sitemap] shortcode |
HelperSEO_Redirects | Redirect rules and permalink migration |
3. Hooks reference#
HelperSEO exposes filters (change a value) and actions (run code at a point in the lifecycle). Use add_filter() and add_action() from your own plugin or theme. Priority and accepted arguments follow WordPress defaults unless noted.
3.1 Lifecycle actions#
| Hook | Type | Arguments | When it fires |
|---|---|---|---|
helperseo_loaded | Action | none | After all HelperSEO classes are initialized |
helperseo_activated | Action | none | On plugin activation |
helperseo_deactivated | Action | none | On plugin deactivation |
helperseo_settings_saved | Action | $section, $raw_data | After any settings section is saved |
3.2 Post and term actions#
| Hook | Type | Arguments | When it fires |
|---|---|---|---|
helperseo_save_post_meta | Action | $post_id | After HelperSEO saves its meta box fields for a post |
helperseo_save_term_meta | Action | $term_id | After HelperSEO saves term SEO fields |
helperseo_meta_box_after | Action | $post | Inside the editor meta box, after the built-in tabs |
3.3 Meta box and editor filters#
| Hook | Type | Arguments | Returns |
|---|---|---|---|
helperseo_meta_box_post_types | Filter | $post_types (array) | Post types that show the meta box |
helperseo_meta_box_tabs | Filter | $tabs, $post | Tabs shown in the meta box |
helperseo_analysis_checks | Filter | $checks, $content, $keyword, $post_id | The list of on-page analyzer checks. Add, remove, or reorder checks here |
3.4 Frontend SEO output filters#
| Hook | Type | Arguments | Returns |
|---|---|---|---|
helperseo_title | Filter | $raw, $sep | The document title for archives and general pages |
helperseo_singular_title | Filter | $title, $post, $sep | The document title for single posts and pages |
helperseo_meta_description | Filter | $desc | The meta description tag content |
helperseo_meta_keywords | Filter | $keywords | The meta keywords content |
helperseo_meta_robots | Filter | $robots_content | The robots meta directive |
helperseo_canonical_url | Filter | $canonical | The canonical URL |
helperseo_schema_graphs | Filter | $graphs | The JSON-LD graph array before output |
helperseo_breadcrumbs | Filter | $crumbs | Breadcrumb items |
3.5 Sitemap, robots, and redirect filters#
| Hook | Type | Arguments | Returns |
|---|---|---|---|
helperseo_sitemap_index_xml | Filter | $xml | The sitemap index XML string |
helperseo_sitemap_serve | Action | $type, $page | Fires before a sitemap page is served |
helperseo_after_ping | Action | $sitemap | Fires after the sitemap is pinged to search engines |
helperseo_robots_txt | Filter | $default or $custom, $public | The robots.txt content |
helperseo_redirect_target | Filter | $target, $row | The destination of a redirect rule before it is followed |
3.6 Internal links and maintenance#
| Hook | Type | Arguments | When it fires |
|---|---|---|---|
helperseo_link_scan_complete | Action | $new_found | After a link scan finds new internal link opportunities |
helperseo_dedupe_enabled | Filter | true (default) | Return false to turn off duplicate-post detection |
helperseo_known_seo_conflicts | Filter | array of plugin conflicts | Add or remove plugins that HelperSEO warns about |
3.7 Import hooks#
HelperSEO can import SEO data from other plugins. These hooks fire after an import completes.
| Hook | Type | Arguments |
|---|---|---|
helperseo_after_import_yoast | Action | $imported |
helperseo_after_import_rankmath | Action | $imported |
helperseo_after_import_aioseo | Action | $imported |
helperseo_import_{plugin} | Filter | Import result, or a WP_Error for unknown plugins |
3.8 AI and MCP hooks#
| Hook | Type | Arguments | Returns |
|---|---|---|---|
helperseo_ai_request_body | Filter | $body | The JSON body sent to the AI service. Use it to add a feature tag or change parameters |
helperseo_ai_response | Filter | $text, $prompt | The AI reply text before it is shown or saved |
helperseo_mcp_register_addons | Action | none | Fires when the MCP server loads. Register extra tools here |
helperseo_register_routes | Action | $namespace | Fires when REST routes are registered. Add routes under the HelperSEO namespace |
3.9 Example: change the meta description#
add_filter( 'helperseo_meta_description', function ( $desc ) {
if ( is_singular( 'product' ) ) {
return $desc . ' Free shipping on orders over $50.';
}
return $desc;
} );3.10 Example: tag AI requests#
add_filter( 'helperseo_ai_request_body', function ( $body ) {
$body['feature'] = 'my-theme-helperseo';
return $body;
} );4. Shortcodes#
| Shortcode | Output | Attributes |
|---|---|---|
[helperseo_breadcrumbs] | Breadcrumb trail for the current page | Uses the helperseo_breadcrumbs filter |
[helperseo_sitemap] | HTML sitemap page content | Output follows the sitemap settings |
Example:
[helperseo_breadcrumbs]5. Sitemap and rewrite rules#
HelperSEO serves XML sitemaps through rewrite rules. The main index is at:
/sitemap.xmlSitemap pages are generated per post type and taxonomy. After changing a sitemap setting, the plugin flushes rewrite rules when needed. If a sitemap returns 404, open Settings, then Permalinks, and save once.
Robots output is controlled by the helperseo_robots_txt filter, which runs on the generated robots.txt content.
6. AI integration#
AI features call the Helpblogger AI service through the Helpblogger connection. Each request is a single POST to the AI response endpoint with a model ID, the message list, and a feature tag.
6.1 Calling the AI service from your own code#
Use HelperSEO_AI::call() for a plain text completion:
$text = HelperSEO_AI::call(
'Write a 150 character meta description for an article about container gardening.',
'You are a concise SEO copywriter.',
30
);
if ( is_wp_error( $text ) ) {
error_log( $text->get_error_message() );
} else {
echo esc_html( $text );
}Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
$prompt | string | required | The user request |
$system | string | built-in SEO assistant prompt | System instruction |
$timeout | int | 30 | Seconds before the request gives up |
Returns the reply text as a string, or a WP_Error on failure.
6.2 Checking whether AI is ready#
if ( HelperSEO_AI::is_configured() ) {
// AI is enabled, a model is selected, and a connection or API key exists.
}6.3 Authentication#
AI calls use one of two credentials:
- The Helpblogger connection, when the site has the
aiscope. This is preferred. - A manual API key, saved in AI settings. This is the fallback.
Your code does not need to pick one. HelperSEO_AI::call() chooses the credential.
7. Helpblogger connection and Google data#
HelperSEO uses Helpblogger Connect (HB Connect) for AI and Google data. The site connects once. The site owner then links a Google account on helpblogger.ng. No Google Cloud project is needed on the site.
7.1 Scopes#
| Scope | Gives access to |
|---|---|
ai | AI generation and the model list |
google:searchconsole | Search Console sites and search analytics |
google:ga4 | GA4 properties and reports |
7.2 Connection object#
$api = HelperSEO_Connect::api(); // The connection object, or null
HelperSEO_Connect::is_available(); // True when the connection exists
HelperSEO_Connect::can_call( 'ai' ); // True when calls work and the scope is granted
HelperSEO_Connect::has_scope( 'google:ga4' );The connection comes from one of two sources:
- A connection injected by the Helpblogger platform, read through the global
hb_connect_api()function. This is used when the plugin is distributed through the platform. - A connection built from
includes/connect-config.php. This file defines two constants,HELPERSEO_CONNECT_PRODUCT_IDandHELPERSEO_CONNECT_SECRET. The values come from the Helpblogger admin. Do not commit real secret values to a public repository.
7.3 Calling Google data directly#
Use HelperSEO_Google_Broker::request(). It takes the HTTP method, a path relative to /connect/google, and an arguments array:
$data = HelperSEO_Google_Broker::request( 'POST', '/searchconsole/query', [
'site_url' => 'https://example.com/',
'dimensions' => [ 'query' ],
'row_limit' => 25,
] );
if ( ! is_wp_error( $data ) ) {
$rows = $data['rows'] ?? [];
}Helper methods:
| Method | Purpose |
|---|---|
HelperSEO_Google_Broker::status() | Linked Google accounts and granted scopes. Cached for 5 minutes |
HelperSEO_Google_Broker::google_linked( 'searchconsole' ) | True when the site has the scope and the owner has linked Search Console |
HelperSEO_Google_Broker::google_linked( 'ga4' ) | True when the site has the scope and the owner has linked GA4 |
7.4 Search Console query filters#
HelperSEO_Search_Console::query() accepts an optional filter array. Each filter needs a dimension and an expression:
$data = HelperSEO_Search_Console::query(
[ 'page' ], // dimensions
28, // days back
1, // row limit
[ [ 'dimension' => 'page', 'expression' => 'https://example.com/my-post/' ] ]
);Allowed filter dimensions: query, page, country, device, date.
8. MCP endpoint#
HelperSEO exposes an MCP-compatible REST endpoint so AI assistants can read and edit SEO data on the site.
| Item | Value |
|---|---|
| Namespace | helperseo/v1 |
| Route | /mcp |
| Full URL | https://your-site.example/wp-json/helperseo/v1/mcp |
Authentication is required. Open the MCP settings screen in the HelperSEO admin for the current authentication method and setup steps.
8.1 Built-in tools#
Tools are grouped by area. Names are the identifiers an MCP client sends.
| Area | Tools |
|---|---|
| Posts | list_posts, get_post_content, get_post_seo, analyze_post, update_post, update_post_content, create_post |
| Categories and terms | get_categories, get_category_seo, create_category, update_category, get_term_seo |
| Homepage and site | get_homepage_seo, update_homepage_seo, get_site_seo_overview, get_full_site_audit, get_settings |
| Links and redirects | get_post_links, get_internal_link_report, get_broken_links, get_redirects, get_redirect_chains, create_redirect |
| Content quality | get_thin_content_posts, get_score_history, get_money_post_boost_plan |
| Keywords | get_keyword_ideas |
| Crawl and indexing | get_crawl_stats, get_sitemap_status, get_instant_index_status, get_instant_index_log, update_instant_index_settings |
| Search Console | search_console, search_console_connected, get_search_console_data |
| Products | get_product_seo |
| Skills | list_skills, get_skill |
To add your own tool, hook helperseo_mcp_register_addons and register it through the MCP server object.
9. AJAX endpoints#
HelperSEO admin screens call WordPress AJAX actions. Each action checks a nonce named helperseo_nonce and a capability. Front-end code should not call these directly.
Examples:
| Action | Purpose | Capability |
|---|---|---|
helperseo_gsc_sites | List Search Console properties | manage_options |
helperseo_gsc_select_site | Save the selected property | manage_options |
helperseo_gsc_report | Query and page search reports | manage_options |
helperseo_gsc_page_stats | Per-URL stats for the editor | edit_posts |
helperseo_ga_properties | List GA4 properties | manage_options |
helperseo_ga_select_property | Save the GA4 property and Measurement ID | manage_options |
helperseo_ai_refresh_models | Refresh the AI model list | manage_options |
If you add an admin screen that calls HelperSEO data, use the same nonce and capability checks.
10. Settings and storage#
Settings are stored as one option array and read through HelperSEO_Options:
$model = HelperSEO_Options::get( 'ai.hbng_model', '' );
HelperSEO_Options::set( 'search_console.site_url', 'https://example.com/' );Common keys:
| Key | Meaning |
|---|---|
ai.enable | AI features on or off |
ai.hbng_model | Selected AI model ID |
ai.hbng_api_key | Manual API key (fallback only) |
search_console.site_url | Selected Search Console property |
search_console.analytics_property | Selected GA4 property ID |
search_console.analytics_property_name | Display name of the GA4 property |
webmaster.ga4_id | GA4 Measurement ID used for the gtag output |
Option keys may change between versions. Read them through HelperSEO_Options::get() rather than reading the raw option.
Additional data lives in the custom table {prefix}helperseo_ai_models, which caches the AI model list.
11. Scheduled events#
HelperSEO registers these WP-Cron events:
| Event | Frequency | Purpose |
|---|---|---|
helperseo_ping_search_engines | Daily | Pings search engines about the sitemap |
helperseo_internal_link_scan_daily | Daily, first run after 10 minutes | Scans for internal link opportunities |
helperseo_link_scan_hourly | Hourly, first run after 5 minutes | Checks for broken links |
helperseo_process_permalink_migration | One time, when a migration is queued | Updates permalinks after a structure change |
If your host disables WP-Cron, run these from a system cron job.
12. Recipes#
12.1 Add an SEO check to the analyzer#
add_filter( 'helperseo_analysis_checks', function ( $checks, $content, $keyword, $post_id ) {
$checks[] = [
'id' => 'has_video',
'label' => 'Contains a video embed',
'pass' => ( strpos( $content, '<iframe' ) !== false ),
'weight' => 5,
];
return $checks;
}, 10, 4 );Check the analyzer source in includes/ for the exact array shape your version expects before shipping.
12.2 Add JSON-LD to every product page#
add_filter( 'helperseo_schema_graphs', function ( $graphs ) {
if ( is_singular( 'product' ) ) {
$graphs[] = [
'@type' => 'Product',
'name' => get_the_title(),
];
}
return $graphs;
} );12.3 Change the title separator on archives#
add_filter( 'helperseo_title', function ( $raw, $sep ) {
if ( is_archive() ) {
return $raw . ' ' . $sep . ' Our Store';
}
return $raw;
}, 10, 2 );12.4 Turn off duplicate-post detection#
add_filter( 'helperseo_dedupe_enabled', '__return_false' );12.5 Run code after an import#
add_action( 'helperseo_after_import_yoast', function ( $imported ) {
error_log( 'Imported ' . (int) $imported . ' posts from Yoast.' );
} );13. Troubleshooting#
| Problem | Likely cause | Fix |
|---|---|---|
| Sitemap returns 404 | Rewrite rules not flushed | Open Settings, then Permalinks, and save |
| AI shows "Connect Helpblogger or add an API key" | No connection and no key | Connect from the AI settings screen, or add a key |
| AI shows "Connect Helpblogger (SDK 3.4 or newer)" | Old SDK | Reinstall the SDK from helpblogger.ng/sdk/install |
| Search Console shows "Owner has not linked Google" | The site owner has not linked a Google account | Link it at helpblogger.ng under Account, then Google Connections |
| Search Console property list is empty | The Google account has no verified properties | Verify the site in Google Search Console |
| GA4 Measurement ID is empty | The property has no web data stream | Create a web stream in GA4, then select the property again |
| Meta descriptions do not change | Another SEO plugin also outputs meta tags | Turn off the other plugin's meta output. HelperSEO warns about known conflicts |
| Cron events do not run | WP-Cron disabled or traffic is low | Use a system cron job that calls wp-cron.php |
For debugging, enable WP_DEBUG and WP_DEBUG_LOG on a staging site. HelperSEO writes errors to the standard WordPress debug log.
14. Support and resources#
| Resource | Link |
|---|---|
| Documentation | Use this page |
| Support | Helpblogger support, through your account on helpblogger.ng |
| Connection help | helpblogger.ng/admin/docs/connect for the connection guide |
| Google data help | helpblogger.ng/admin/docs/google-connect for Search Console and GA4 details |
When you report a bug, include your WordPress version, PHP version, HelperSEO version, and the SDK version shown in the AI settings screen.
Version of this document follows the HelperSEO release it describes. Check the plugin changelog for changes between releases.