Skip to content
Helpblogger
HelperSEO
Main site

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.

Updated Oct 23, 2026 11 min read

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#

  1. Requirements
  2. Architecture at a glance
  3. Hooks reference
  4. Shortcodes
  5. Sitemap and rewrite rules
  6. AI integration
  7. Helpblogger connection and Google data
  8. MCP endpoint
  9. AJAX endpoints
  10. Settings and storage
  11. Scheduled events
  12. Recipes
  13. Troubleshooting
  14. Support and resources

1. Requirements#

ItemRequirement
WordPress6.0 or newer
PHP7.4 or newer (8.x recommended)
cURLRequired for outbound API calls
Helpblogger SDKVersion 3.4 or newer, for AI and Google features
Google accountOnly 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:

ConstantPurpose
HELPERSEO_VERSIONPlugin version string
HELPERSEO_PLUGIN_FILEAbsolute path to the main plugin file
HELPERSEO_PLUGIN_DIRPlugin directory path, with trailing slash
HELPERSEO_PLUGIN_URLPlugin directory URL, with trailing slash
HELPERSEO_PLUGIN_BASEPlugin basename

Important classes:

ClassResponsibility
HelperSEO_OptionsRead and write plugin settings with get() and set()
HelperSEO_AIAI generation, alt text, link suggestions, scoring
HelperSEO_ConnectHelpblogger connection (SDK wrapper)
HelperSEO_Google_BrokerCalls the Google broker through the connection
HelperSEO_Search_ConsoleSearch Console reports and per-page stats
HelperSEO_AnalyticsGA4 property picker and Measurement ID lookup
HelperSEO_MCPMCP REST endpoint
HelperSEO_SitemapXML sitemaps and the [helperseo_sitemap] shortcode
HelperSEO_RedirectsRedirect 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#

HookTypeArgumentsWhen it fires
helperseo_loadedActionnoneAfter all HelperSEO classes are initialized
helperseo_activatedActionnoneOn plugin activation
helperseo_deactivatedActionnoneOn plugin deactivation
helperseo_settings_savedAction$section, $raw_dataAfter any settings section is saved

3.2 Post and term actions#

HookTypeArgumentsWhen it fires
helperseo_save_post_metaAction$post_idAfter HelperSEO saves its meta box fields for a post
helperseo_save_term_metaAction$term_idAfter HelperSEO saves term SEO fields
helperseo_meta_box_afterAction$postInside the editor meta box, after the built-in tabs

3.3 Meta box and editor filters#

HookTypeArgumentsReturns
helperseo_meta_box_post_typesFilter$post_types (array)Post types that show the meta box
helperseo_meta_box_tabsFilter$tabs, $postTabs shown in the meta box
helperseo_analysis_checksFilter$checks, $content, $keyword, $post_idThe list of on-page analyzer checks. Add, remove, or reorder checks here

3.4 Frontend SEO output filters#

HookTypeArgumentsReturns
helperseo_titleFilter$raw, $sepThe document title for archives and general pages
helperseo_singular_titleFilter$title, $post, $sepThe document title for single posts and pages
helperseo_meta_descriptionFilter$descThe meta description tag content
helperseo_meta_keywordsFilter$keywordsThe meta keywords content
helperseo_meta_robotsFilter$robots_contentThe robots meta directive
helperseo_canonical_urlFilter$canonicalThe canonical URL
helperseo_schema_graphsFilter$graphsThe JSON-LD graph array before output
helperseo_breadcrumbsFilter$crumbsBreadcrumb items

3.5 Sitemap, robots, and redirect filters#

HookTypeArgumentsReturns
helperseo_sitemap_index_xmlFilter$xmlThe sitemap index XML string
helperseo_sitemap_serveAction$type, $pageFires before a sitemap page is served
helperseo_after_pingAction$sitemapFires after the sitemap is pinged to search engines
helperseo_robots_txtFilter$default or $custom, $publicThe robots.txt content
helperseo_redirect_targetFilter$target, $rowThe destination of a redirect rule before it is followed
HookTypeArgumentsWhen it fires
helperseo_link_scan_completeAction$new_foundAfter a link scan finds new internal link opportunities
helperseo_dedupe_enabledFiltertrue (default)Return false to turn off duplicate-post detection
helperseo_known_seo_conflictsFilterarray of plugin conflictsAdd 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.

HookTypeArguments
helperseo_after_import_yoastAction$imported
helperseo_after_import_rankmathAction$imported
helperseo_after_import_aioseoAction$imported
helperseo_import_{plugin}FilterImport result, or a WP_Error for unknown plugins

3.8 AI and MCP hooks#

HookTypeArgumentsReturns
helperseo_ai_request_bodyFilter$bodyThe JSON body sent to the AI service. Use it to add a feature tag or change parameters
helperseo_ai_responseFilter$text, $promptThe AI reply text before it is shown or saved
helperseo_mcp_register_addonsActionnoneFires when the MCP server loads. Register extra tools here
helperseo_register_routesAction$namespaceFires when REST routes are registered. Add routes under the HelperSEO namespace

3.9 Example: change the meta description#

PHP
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#

PHP
add_filter( 'helperseo_ai_request_body', function ( $body ) {
    $body['feature'] = 'my-theme-helperseo';
    return $body;
} );

4. Shortcodes#

ShortcodeOutputAttributes
[helperseo_breadcrumbs]Breadcrumb trail for the current pageUses the helperseo_breadcrumbs filter
[helperseo_sitemap]HTML sitemap page contentOutput follows the sitemap settings

Example:

Text
[helperseo_breadcrumbs]

5. Sitemap and rewrite rules#

HelperSEO serves XML sitemaps through rewrite rules. The main index is at:

Text
/sitemap.xml

Sitemap 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:

PHP
$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:

ParameterTypeDefaultDescription
$promptstringrequiredThe user request
$systemstringbuilt-in SEO assistant promptSystem instruction
$timeoutint30Seconds 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#

PHP
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:

  1. The Helpblogger connection, when the site has the ai scope. This is preferred.
  2. 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#

ScopeGives access to
aiAI generation and the model list
google:searchconsoleSearch Console sites and search analytics
google:ga4GA4 properties and reports

7.2 Connection object#

PHP
$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:

  1. 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.
  2. A connection built from includes/connect-config.php. This file defines two constants, HELPERSEO_CONNECT_PRODUCT_ID and HELPERSEO_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:

PHP
$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:

MethodPurpose
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:

PHP
$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.

ItemValue
Namespacehelperseo/v1
Route/mcp
Full URLhttps://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.

AreaTools
Postslist_posts, get_post_content, get_post_seo, analyze_post, update_post, update_post_content, create_post
Categories and termsget_categories, get_category_seo, create_category, update_category, get_term_seo
Homepage and siteget_homepage_seo, update_homepage_seo, get_site_seo_overview, get_full_site_audit, get_settings
Links and redirectsget_post_links, get_internal_link_report, get_broken_links, get_redirects, get_redirect_chains, create_redirect
Content qualityget_thin_content_posts, get_score_history, get_money_post_boost_plan
Keywordsget_keyword_ideas
Crawl and indexingget_crawl_stats, get_sitemap_status, get_instant_index_status, get_instant_index_log, update_instant_index_settings
Search Consolesearch_console, search_console_connected, get_search_console_data
Productsget_product_seo
Skillslist_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:

ActionPurposeCapability
helperseo_gsc_sitesList Search Console propertiesmanage_options
helperseo_gsc_select_siteSave the selected propertymanage_options
helperseo_gsc_reportQuery and page search reportsmanage_options
helperseo_gsc_page_statsPer-URL stats for the editoredit_posts
helperseo_ga_propertiesList GA4 propertiesmanage_options
helperseo_ga_select_propertySave the GA4 property and Measurement IDmanage_options
helperseo_ai_refresh_modelsRefresh the AI model listmanage_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:

PHP
$model = HelperSEO_Options::get( 'ai.hbng_model', '' );
HelperSEO_Options::set( 'search_console.site_url', 'https://example.com/' );

Common keys:

KeyMeaning
ai.enableAI features on or off
ai.hbng_modelSelected AI model ID
ai.hbng_api_keyManual API key (fallback only)
search_console.site_urlSelected Search Console property
search_console.analytics_propertySelected GA4 property ID
search_console.analytics_property_nameDisplay name of the GA4 property
webmaster.ga4_idGA4 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:

EventFrequencyPurpose
helperseo_ping_search_enginesDailyPings search engines about the sitemap
helperseo_internal_link_scan_dailyDaily, first run after 10 minutesScans for internal link opportunities
helperseo_link_scan_hourlyHourly, first run after 5 minutesChecks for broken links
helperseo_process_permalink_migrationOne time, when a migration is queuedUpdates 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#

PHP
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#

PHP
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#

PHP
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#

PHP
add_filter( 'helperseo_dedupe_enabled', '__return_false' );

12.5 Run code after an import#

PHP
add_action( 'helperseo_after_import_yoast', function ( $imported ) {
    error_log( 'Imported ' . (int) $imported . ' posts from Yoast.' );
} );

13. Troubleshooting#

ProblemLikely causeFix
Sitemap returns 404Rewrite rules not flushedOpen Settings, then Permalinks, and save
AI shows "Connect Helpblogger or add an API key"No connection and no keyConnect from the AI settings screen, or add a key
AI shows "Connect Helpblogger (SDK 3.4 or newer)"Old SDKReinstall the SDK from helpblogger.ng/sdk/install
Search Console shows "Owner has not linked Google"The site owner has not linked a Google accountLink it at helpblogger.ng under Account, then Google Connections
Search Console property list is emptyThe Google account has no verified propertiesVerify the site in Google Search Console
GA4 Measurement ID is emptyThe property has no web data streamCreate a web stream in GA4, then select the property again
Meta descriptions do not changeAnother SEO plugin also outputs meta tagsTurn off the other plugin's meta output. HelperSEO warns about known conflicts
Cron events do not runWP-Cron disabled or traffic is lowUse 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#

ResourceLink
DocumentationUse this page
SupportHelpblogger support, through your account on helpblogger.ng
Connection helphelpblogger.ng/admin/docs/connect for the connection guide
Google data helphelpblogger.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.