AI Abilities / MCP API

This developer note documents the BricksMembers AI Abilities / MCP runtime. The module exposes guarded WordPress Abilities API records for external MCP clients, plus BricksMembers catalogs, provider status, dry-run plans, commit routing, and audit history.

The feature does not own chat, model selection, agent memory, prompt orchestration, or AI provider credentials. External MCP clients own that layer. BricksMembers owns the safe ability surface.

Runtime Owners

• AiAbilitiesFeatureRegistrar owns feature-local hook registration.
• AiAbilityRegistry owns WordPress Abilities API categories, ability records, labels, schemas, permission callbacks, execute callbacks, and MCP-public metadata.
• AiCapabilityCatalogBuilder owns read-only catalogs for site context, modules, admin surfaces, domains, Bricks primitives, REST route families, automations, template assistant entries, and help context.
• AiSettingsService owns brm_ai_mcp_settings, brm_ai_operation_plans, and brm_ai_ability_audit_log.
• AiMutationGuard owns read/write/destructive permission checks and blocked mutation responses.
• AiOperationPlanner owns dry-run plan envelopes, per-feature direct-write routing, expiry, commit routing, and plan cleanup after successful commits.
• AiContentAbilityService and AiContentCommitService own generic WordPress content, media, term, featured-image, and ACF value ability execution.
• AiCourseSetupAbilityService and AiCourseSetupCommitService own course/setup workflow planning and commit routing.
• FallbackBricksProvider and FallbackBricksMutationService own guarded fallback Bricks reads, dry-run plans, and commits when no richer Bricks provider is selected.
• AiAuditLogService owns audit retention and secret redaction.

Bootstrap

1. ModuleRegistry::is_active( 'ai_abilities' ) gates the feature.
2. BootstrapCoordinator::boot_modules() calls AiAbilitiesFeatureRegistrar::boot().
3. The registrar wires admin-post handlers, ability categories, and ability records.
4. Categories register on wp_abilities_api_categories_init.
5. Abilities register on wp_abilities_api_init.

Do not call wp_register_ability() outside the WordPress Abilities API hook. The registry intentionally returns early when the Abilities API is not available.

Settings Contract

The module option is brm_enable_ai_abilities. The settings option is brm_ai_mcp_settings. Defaults are fail-closed:

• enable_catalog_abilities = false
• enable_write_abilities = false
• enable_destructive_abilities = false
• require_bulk_dry_run = true
• max_batch_items = 50
• allowed_post_types = []
• allow_ai_content_generation = false
• allow_connected_video_assignment = false
• preferred_bricks_provider = auto
• public_mcp_read = false
• public_mcp_write = false
• audit_log_retention_days = 30
• enable_fallback_bricks_provider = true
• fallback_requires_full_dry_run = true
• fallback_allow_whole_content_replace = false
• direct_write_features = [] as internal normalized storage for the MCP Access dry-run switches

Ability Registration Rules

• Catalog abilities register only when the module, mcp_access_enabled, and enable_catalog_abilities are enabled.
• Write/planning abilities register only when mcp_access_enabled and enable_write_abilities are enabled.
• Read permissions use AiMutationGuard::current_user_can_read_catalogs().
• Write permissions use AiMutationGuard::writes_allowed().
• MCP-public read metadata follows public_mcp_read.
• MCP-public write metadata follows public_mcp_write.
• MCP-public metadata never replaces the WordPress ability permission_callback.

Ability Surface

The current V1 surface registers 63 BricksMembers abilities under the bricksmembers/ namespace.

Catalog And Help

site-context-get, module-status-get, admin-surface-map-get, admin-module-setup-catalog-get, domain-catalog-get, bricks-catalog-get, bricks-filter-sources-catalog-get, dynamic-tags-catalog-get, form-actions-catalog-get, conditions-catalog-get, template-assistant-catalog-get, headless-rest-route-catalog-get, automation-catalog-get, provider-status-get, help-context-get, and mcp-setup-guide-get.

WordPress Content, ACF, And Content Fields

wp-post-upsert, wp-post-bulk-upsert, wp-term-upsert, wp-media-sideload, wp-featured-image-set, wp-cpt-catalog-get, wp-taxonomy-catalog-get, acf-catalog-get, acf-values-get, acf-values-set, content-fields-catalog-get, content-fields-values-get, content-fields-values-set-plan, and content-fields-acf-import-plan.

Content Fields abilities are service-backed by the Content Fields runtime. Catalog and value reads use the Content Fields definition/value owners; value write plans commit through ContentFieldValueService; and ACF import planning is migration analysis only, not an ACF bridge or fake ACF runtime.

Post upsert meta is restricted to plain custom fields: protected meta keys and BricksMembers/Bricks canonical keys (_brm_*, brm_*, _bricks_*) are rejected with a per-key warning, and term assignments are restricted to registered taxonomies. wp-media-sideload only accepts public http(s) URLs; loopback, private, and reserved addresses are rejected at plan and commit time.

Course And Site Setup

course-outline-plan, course-scaffold-create, course-content-generate, course-assets-match, course-assets-assign, course-bricks-pages-plan, course-bricks-pages-create, course-automations-plan, course-automations-create, admin-module-setup-plan, and setup-plan-commit.

Fallback Bricks Provider

bricks-provider-status-get, bricks-setup-check, bricks-content-get, bricks-content-plan, bricks-content-patch, bricks-content-set, bricks-content-insert, bricks-content-remove, bricks-template-list, bricks-template-create, bricks-template-conditions-get, bricks-template-conditions-set, bricks-global-classes-list, bricks-global-classes-upsert, bricks-variables-list, bricks-variables-upsert, bricks-color-palette-list, bricks-color-palette-upsert, bricks-theme-styles-list, bricks-theme-styles-upsert, bricks-components-list, and bricks-components-upsert.

Mutation Contract

Write abilities create dry-run plans by default. The commit ability consumes a valid plan_id. The admin UI exposes broad dry-run switches in MCP Access; internally those switches normalize to direct_write_features so concrete write operations can commit immediately through the same canonical service path when dry-run is off. Explicit plan abilities still return plans.

Dry-run is a plan/commit checkpoint and audit boundary, not an absolute human-approval guarantee. If an external MCP client is configured to auto-approve the planning ability and the commit ability, the client can still continue without a human stopping between those calls. When direct write is enabled for a feature, the concrete ability skips the plan and returns direct-write warnings in the mutation response.

Structure-aware content writes use the same canonical mutation owner as the BricksMembers structure editor. When wp-post-upsert, wp-post-bulk-upsert, or course setup payloads include structure_id and level_index, commits route through StructureItemMutationService. Course content and video assignment updates also use that service for existing structured posts. The response result reports recompute_queued, spm_scheduled, progress_scheduled, and drip_scheduled so MCP clients know that structure paths, progress projections, and drip unlocks have been queued for refresh.

Mutation responses use the shared response keys:

• dry_run
• plan_id
• summary
• changes
• warnings
• affected_objects
• result
• rollback_hint
• admin_urls

Plans are stored in brm_ai_operation_plans with an expiry. Successful non-blocked commits remove the plan. Invalid or expired plans fail closed.

Admin Module Setup

AiAdminModuleSetupAbilityService exposes an admin-module setup catalog for every surface in AdminRouteRegistry::get_surface_map(). Each surface includes its label, page slug, admin URL, module gate, route kind, required MCP abilities, explicit setup blueprint, known frontend Bricks resources, and warnings for unsupported deep settings writes.

admin-module-setup-plan accepts surface IDs or module IDs and creates a dry-run plan. setup-plan-commit enables known module flags through ModuleRegistry option owners and clears the module cache. It must not write arbitrary module settings, payment secrets, group internals, instructor scopes, or domain data without a surface-specific canonical service-backed ability.

AiAdminSurfaceSetupBlueprintCatalog owns the explicit setup blueprint for each admin surface. The unit suite asserts that every runtime admin surface has a blueprint and that every referenced Bricks element, form action, query type, query control, filter source, condition, time condition, and dynamic tag family exists in the Bricks catalog. This makes AI/MCP drift a failing test instead of a documentation problem.

Provider Routing

The Bricks editing provider order for auto is Novamira when Novamira integration hooks or registered Novamira Bricks abilities are present, then the fallback Bricks provider.

The MCP adapter layer and the Bricks provider layer are separate. The WordPress MCP Adapter exposes public WordPress abilities through the default MCP server endpoint, while Novamira can own richer Bricks tree mutation when its Bricks abilities are registered. The fallback Bricks provider is not an MCP adapter; it is BricksMembers’ built-in conservative Bricks mutation provider behind the ability layer.

Supported MCP transport patterns are: direct connection to the WordPress MCP Adapter endpoint, the WordPress MCP Adapter endpoint through a local connector/proxy for desktop clients, Novamira’s integrated MCP bridge when its MCP abilities are registered, or another bridge that discovers and executes WordPress Abilities API records through the normal WordPress permission model. A copied agent prompt is only bootstrap instruction for the external agent after the MCP transport is connected.

BricksMembers does not ship a standalone MCP server. AiMcpSetupGuideBuilder exposes the admin setup guidance and mcp-setup-guide-get ability so users and connected agents can retrieve the required bridge options, endpoint hint, setup steps, and bootstrap prompt.

AiProviderStatusService reports WordPress Abilities API availability, WordPress MCP Adapter availability, WordPress Connectors/AI Client availability, Novamira status, fallback status, active provider choice, and warnings.

Fallback Bricks Rules

The fallback provider exposes the FallbackBricksConstructionContract through bricks-provider-status-get, bricks-setup-check, and bricks-catalog-get. MCP clients should read that contract before planning fallback Bricks page or template work.

• Fallback writes are dry-run-first.
• Whole-content replacement is disabled unless fallback_allow_whole_content_replace is explicitly enabled.
• Targeted patch, insert, and remove operations are preferred.
• Fallback writes preserve unknown Bricks JSON fields and operate on the current Bricks content meta key.
• Fallback writes must not mutate BricksMembers domain state directly.
• Generated trees must use section roots, containers for section width, blocks for real inner layout groups, and native Bricks/BRM elements instead of whole-page text/html/code dumps.
• Reusable component styling should use Bricks global classes, Bricks controls, saved settings, template JSON, or approved utility classes. Element ID styling and broad sitewide CSS dumps are not valid defaults.
• Agents must not invent dynamic tags, query controls, filter sources, conditions, form actions, video provider IDs, or checkout structures. Missing runtime surfaces should return warnings.

Security Rules

• Do not store AI provider API keys in BricksMembers.
• Do not expose secrets in ability input, output, warnings, or audit records.
• Use WordPress sanitizers and canonical services for writes.
• Do not route internal writes through public brm_* wrappers.
• Destructive writes must be separately enabled and must still pass capability checks.
• Video assignments must use real user-provided or connected-provider IDs/URLs. BricksMembers must not fabricate provider IDs.

Maintenance Rules

• Update docs/feature-maps/ai-abilities.md when ability ownership, bootstrap, provider routing, settings, or public ability contracts change.
• Keep new ability tests behavior-based. Avoid source-inspection tests unless they belong in the existing architecture contract suite.
• Run focused AI ability tests after registry, settings, guard, provider, planner, or commit changes.
• Run browser/admin tests when the AI settings/status/audit UI changes.
• Do not create a broad src/AI/ ownership area. Keep this feature under src/Modules/AiAbilities/.