magebitcom / magento2-mcp-hyva-commerce-tools
Hyvä Commerce 1.4 MCP tools for Magebit_Mcp: Hyvä CMS, Menu Builder, Media Gallery and Media Optimization, Form Builder, Email & Newsletter Templates, Store Credit, Linked Products, Category Merchandiser, AI Worker monitoring, Advanced Admin Permissions and Hyvä Admin Dashboard widgets
Package info
github.com/magebitcom/magento2-mcp-hyva-commerce-tools
Type:magento2-module
pkg:composer/magebitcom/magento2-mcp-hyva-commerce-tools
Requires
- php: >=8.1
- hyva-themes/commerce-module-admin-dashboard: ^2.0
- hyva-themes/commerce-module-admin-dashboard-api: ^3.0
- hyva-themes/commerce-module-cms: ^1.3
- magebitcom/magento2-mcp-module: ^1.3
- magento/framework: ^103.0
Requires (Dev)
None
Suggests
- hyva-themes/commerce-module-advanced-admin-permissions: ^1.0: hyva_admin_perm.* reads; MCP callers get their union/deny roles in Hyvä checks
- hyva-themes/commerce-module-ai-worker: ^1.0: enables the hyva_ai.* job monitoring tools
- hyva-themes/commerce-module-category-merchandiser: ^1.0: enables the hyva_merch.* tools
- hyva-themes/commerce-module-cms-ai-translations: ^1.0.2: enables hyva_cms.translation.*
- hyva-themes/commerce-module-email-templates: ^1.0: enables the hyva_email.* tools
- hyva-themes/commerce-module-form-builder: ^1.0: enables the hyva_form.* tools
- hyva-themes/commerce-module-image-editor: ^1.1: reports Image Editor backups in hyva_media.image.get
- hyva-themes/commerce-module-linked-products: ^1.0: enables the hyva_linked.* tools
- hyva-themes/commerce-module-media-gallery: ^1.0 (installed with commerce-module-cms 1.3): enables the hyva_media.asset/trash/folder/sync tools and asset ids in content
- hyva-themes/commerce-module-media-optimization: ^1.1: enables the hyva_media.optimization.* tools
- hyva-themes/commerce-module-menu-builder: ^1.1: enables the hyva_menu.* tools and the menu health widget
- hyva-themes/commerce-module-store-credit: ^1.0.1: enables the hyva_store_credit.* tools
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-04 10:24:59 UTC
README
Hyvä Commerce 1.4 MCP tools for Magebit_Mcp. Exposes Hyvä CMS
content and the other Hyvä Commerce modules as MCP tools, and adds Hyvä Admin Dashboard widgets that show MCP activity
and content health.
Contents
- What this module gives you
- Requirements
- Install
- Concepts
- Safety model
- ACL
- Store scope
- Delete tools
- Optional features
- Hyvä Commerce 1.4 coverage
- Tool catalog
- Prompts
- Dashboard widgets
- Notes on Hyvä behaviour
- Upgrade notes
- Development
- License
What this module gives you
- Hyvä CMS pages and blocks: drafts, versions, components, scheduling, AI translations, Page Builder migration, import and export
- Menu Builder menus and menu items
- Media Gallery assets, image usage and Media Optimization
- Form Builder forms
- Email and newsletter templates
- Store Credit balances
- Linked Products groups
- Category Merchandiser product positions
- Read-only tools for AI Worker and Advanced Admin Permissions
- Admin Dashboard views and widgets
- Content audits, three MCP prompts and seven dashboard widgets
See Hyvä Commerce 1.4 coverage for the tools each Hyvä module gets.
Content writes are drafts. They go through the same Hyvä service the Liveview editor uses
(Hyva\CmsLiveviewEditor\Model\Provider). Only the publish tools make content live: hyva_cms.publish,
hyva_menu.publish, hyva_form.form.publish and hyva_email.*.publish.
Requirements
magebitcom/magento2-mcp-module(Magebit_Mcp)^1.3- Hyvä Commerce 1.4:
- Hyvä CMS 1.3 with Media Gallery (
hyva-themes/commerce-module-cms) - Hyvä Admin Dashboard (
hyva-themes/commerce-module-admin-dashboard,hyva-themes/commerce-module-admin-dashboard-api)
- Hyvä CMS 1.3 with Media Gallery (
These Hyvä modules are optional and detected at runtime. Each one enables the tools listed in Hyvä Commerce 1.4 coverage. Optional features explains what happens when one is missing.
hyva-themes/commerce-module-menu-builderhyva-themes/commerce-module-media-optimizationhyva-themes/commerce-module-image-editorhyva-themes/commerce-module-form-builderhyva-themes/commerce-module-email-templateshyva-themes/commerce-module-store-credithyva-themes/commerce-module-linked-productshyva-themes/commerce-module-category-merchandiserhyva-themes/commerce-module-cms-ai-translationshyva-themes/commerce-module-ai-workerhyva-themes/commerce-module-advanced-admin-permissions
Removing Menu Builder also removes Hyvä's CMS dashboard widgets.
hyva-themes/commerce-module-admin-dashboard-cms-widgets requires commerce-module-menu-builder, both in composer and
in a constructor (RecentlyEditedHyvaCmsMenus). Remove the widgets package too, or setup:di:compile fails. This
module requires neither package: Menu Builder is only a composer suggestion.
Install
composer require magebitcom/magento2-mcp-hyva-commerce-tools bin/magento module:enable Magebit_McpHyvaCommerceTools bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush
Concepts
| Term | What it is |
|---|---|
| Draft | Unpublished Hyvä content. The storefront keeps showing the published version until a publish tool or a scheduled release makes the draft live. |
| Settings | Magento fields of a page, block or menu (title, active flag, store views, meta), passed as settings. They are not drafted and apply immediately. |
| Content type | The entity_type argument of the shared CMS tools: cms_page, cms_block or menu. |
| Hyvä verb | A per-type permission from Hyvä's ContentTypeAuthorization: view, save, publish, delete, version_history, export, scheduling, schedule_save, schedule_cancel. For example, publish on a page is Hyva_Cms::page_publish. |
| Preview | The dry-run reply of a call that needs "confirm": true and did not pass it. Nothing is written. |
Safety model
- Write gate. Write tools need the global write switch and a token with writes.
- Drafts first. Content tools save drafts; only publish tools and scheduled releases make a draft live.
- Explicit confirm. The calls in the confirm table return a preview until called with
"confirm": true. Publish tools need no confirm: publishing is their purpose, and they go live on the first call. - Three ACL checks. The tool resource, the Hyvä resource and, for tools with
entity_type, the Hyvä verb for that type. See ACL. - Store scope. A role restricted by Hyvä Advanced Admin Permissions is held to its websites and store views. See Store scope.
Write gate
Every write tool needs both switches:
- the global Allow Write Tools setting (
magebit_mcp/general/allow_writes); - the write flag on the calling token.
Every write tool also sets confirmationRequired. tools/list sends it to clients as the destructiveHint
annotation.
Drafts and live settings
These tools save a draft (saveContent(..., publish: false)) and a version-history entry:
- page, block and menu tools;
- migration and import tools;
- image replace and alt-text tools.
The storefront changes only after hyva_cms.publish or a scheduled release.
Publishing a menu also activates it: Hyvä Menu Builder sets is_active when it publishes
(MenuProvider::saveContent()), and the publish reply reports the flag after publishing. Publishing a page or block
leaves its active flag as it is; an inactive one stays hidden, and the reply's note names the update call.
settings are different: they are Magento fields and apply at once. A settings change that affects the live
storefront therefore needs "confirm": true (see the next section).
Confirm and previews
Without "confirm": true these calls write nothing and return a preview instead.
| Call | Needs "confirm": true |
|---|---|
hyva_cms.page.create / hyva_cms.block.create with is_active=true |
Always. The preview shows what would go live. An inactive create never needs it, whatever its identifier and store views: an inactive page or block is not served. |
settings: active flag, store views, URL key or identifier |
Always. |
settings: any other field |
Only on an active page, block or menu. A menu's preview_url_key never needs it: it only picks the page the editor previews the menu on. |
| Replacing a draft | hyva_cms.draft.create and hyva_cms.import when the current draft has unpublished changes; hyva_cms.migration.convert_to_draft when a Hyvä draft already exists. |
| Removing a menu item that has children | Always, also through hyva_menu.update / hyva_cms.draft.update operations that remove or replace one. The preview lists the children and children_count. |
hyva_media.image.replace |
Only with scope=global. |
hyva_media.optimization.clear |
Only with all_images=true (clears every optimized image). |
hyva_media.asset.move, hyva_media.asset.trash |
Always. |
hyva_store_credit.balance.credit, hyva_store_credit.balance.debit |
Always. |
hyva_linked.group.save |
Always. Without it the tool only validates and shows the result. |
hyva_merch.category.positions_set |
Always. |
hyva_cms.page.delete, hyva_cms.block.delete, hyva_menu.delete |
Always; an entity in use also needs "force": true. See Delete tools. |
A call that changes settings writes nothing without confirm, not even the draft part of the call. Its preview lists
each change with its storefront effect.
Every preview has the same keys:
| Key | Content |
|---|---|
dry_run, confirmation_required |
Both true. |
action |
The action the call would take, e.g. delete_cms_page. |
affected |
Always a list: one entry per item that would change, or sample paths when clearing every optimized image. |
total |
Every item that would change. |
details |
Only when there is context that is not an item, e.g. in_use (always a boolean; trash adds in_use_count) for trash and the delete tools, target_folder for move, menu_id and children_count for a menu item removal, not_editable_usages for a global image replace (an affected entity's own usages sit on its affected entry, so each entity is listed once). |
hint |
What confirming does, e.g. that a replaced image is a draft until hyva_cms.publish. |
Refusals
Hyvä's save refusals come back as soft errors with a status:
| Status | When | What to do |
|---|---|---|
| 422 | A provider refuses content, or Hyvä's content guard rejects it (3 MB, 5000 components, depth 50). field_errors lists the problems per component uid and field. |
Fix the fields and call again. |
| 409 | The draft changed since you read it. Pass base_version_uid to the update tools to get this check. |
Reload and re-apply your change. Never resubmit old content. |
| 403 | Hyvä refuses a permission, or the role's store scope excludes the entity (audit summary {"error": "out_of_scope"}; a missing permission is status_403). |
Grant the permission (see Role setup), or work in the role's own store views (see Store scope). |
ACL
Every tool has its own resource under System → MCP → MCP Tools → Hyvä Commerce Tools, named
Magebit_McpHyvaCommerceTools::tool_<tool_name_with_underscores>.
A call passes three checks, all against the token's admin role:
| # | Check | Applies to | Catalog column |
|---|---|---|---|
| 1 | The tool's own resource. | tools/list and tools/call |
— |
| 2 | The Hyvä resource the tool is listed with, e.g. Hyva_Cms::page_view. A role without it does not see the tool. |
tools/list and tools/call |
Listed with |
| 3 | For tools that take entity_type: the Hyvä verb for that type. For example, hyva_cms.publish on a page needs Hyva_Cms::page_publish, on a menu Hyva_MenuBuilder::menu_publish. |
tools/call |
Checked per call |
Tools with entity_type in tools/list. tools/list has no arguments, so it cannot check the verb per type.
These tools are listed for a role that holds their verb on at least one content type ("the verb on any type" in the
catalog). A call on a type the role lacks is refused with -32004. A role with only the view verbs therefore does not
see the draft, publish, import, restore and schedule tools, or hyva_cms.migration.convert_to_draft.
Version history needs its own verb. Reading a version also needs the type's version_history verb:
| Argument | Tools |
|---|---|
fields with versions |
hyva_cms.page.get, hyva_cms.block.get, hyva_menu.get |
version_id |
Preview, publish and schedule create (hyva_cms.* and hyva_menu.*) |
source=version |
hyva_cms.draft.create |
include_versions |
hyva_cms.export |
A get without fields returns versions: null to a caller without that permission.
Hyvä's own checks see the MCP caller. Hyvä 1.4 also checks permissions inside its own services, e.g. version restore. While a tool runs, the module gives Magento authorization the MCP caller's role, so those checks see the same role.
Role setup
Give a role the Hyvä permissions that match what the agent should do. Existing roles are not migrated from
Magento_Backend::content.
| Agent should… | Grant (besides the MCP tool resources) |
|---|---|
| read pages, blocks, menus, images | Hyva_Cms::cms, Hyva_Cms::page_view, Hyva_Cms::block_view, Hyva_MenuBuilder::menu_view, Hyva_MediaGallery::media + asset_view |
| see version history | + Hyva_Cms::page_version_history, Hyva_Cms::block_version_history, Hyva_MenuBuilder::menu_version_history |
| create and edit drafts | + Hyva_Cms::page_save, Hyva_Cms::block_save, Hyva_MenuBuilder::menu_save |
| publish | + Hyva_Cms::page_publish, Hyva_Cms::block_publish, Hyva_MenuBuilder::menu_publish |
| schedule | + *_scheduling, *_schedule_save, *_schedule_cancel |
| export / import | + *_export / *_save and Hyva_Cms::transfer (Transfer Center) |
| delete pages, blocks, menus | see Delete tools |
| clear optimized images | + Hyva_MediaGallery::asset_save |
| manage Media Gallery files | + Hyva_MediaGallery::asset_save (move), asset_delete (trash, restore), folder_save |
| forms | Hyva_FormBuilder::form_view, form_save, form_publish, form_version_history |
| emails and newsletters | Hyva_EmailTemplates::email_template_* / newsletter_template_* (view, save, publish) |
| translate CMS content | + Hyva_CmsAiTranslations::translate (and *_save to write the draft) |
| store credit | Hyva_StoreCredit::balance_view; balance_adjust to credit or debit |
| linked product groups | Hyva_LinkedProducts::group_view; group_save to change them |
| reorder category products | Magento_Catalog::categories (not for website-restricted roles: positions are global) |
| monitor AI Worker | Hyva_AiWorker::manage (own jobs), ::jobs (all jobs, usage, errors), ::config (status) |
| read admin permissions | Magento_User::acl_users; Hyva_AdvancedAdminPermissions::audit for the audit log |
| list dashboard views and widgets | Hyva_AdminDashboardFramework::dashboard |
A role without Hyva_Cms::cms sees none of the Hyvä CMS, menu or media tools.
Store scope
Hyvä Advanced Admin Permissions restricts an admin role to some websites or store views. Hyvä's scope guards run only
in the admin and the web API, not on the /mcp route. The module therefore applies the MCP admin's restriction itself.
Rules per entity
| Entity | Read | Change |
|---|---|---|
| CMS pages, blocks, menus, forms | Outside the role's store views: hidden from the lists, and refused by every tool that reads one (status 403). | Outside the role's store views: refused (status 403). Changing one, or its store views, needs every store view it is assigned to. |
| Email and newsletter templates, linked product groups, category positions | Allowed. They belong to no store view. | Refused for a restricted role. |
| Store credit | Checked against the customer's website. | Checked against the customer's website. Hyvä's own store credit services do not check scope. |
| Media Gallery files, folders, trash, sync status | Not scoped. | Not scoped. |
Menus and forms are scoped by their store views although the Hyvä admin does not scope them.
Store view 0 (All Store Views)
- Changing or creating needs every store view. Store view 0 counts as all of them, as in the Hyvä admin. A restricted role can read an "All Store Views" page, block or menu, but can neither change it there nor create one there.
- Re-assigning is judged by the store views it enters. This covers
settings.store_idsonhyva_cms.page.update,hyva_cms.block.updateandhyva_menu.update, as Hyvä Advanced Admin Permissions judges the admin save:- moving the entity into the role's own store views is allowed (giving up store view 0 is not giving up a foreign store view);
- dropping a store view outside the role is refused.
Tools that skip or hide content outside the role
| Tool | Behaviour | Hidden count |
|---|---|---|
hyva_media.image.replace, hyva_media.image.update_alt |
Skip content outside the role. | — |
hyva_cms.schedule.cancel, hyva_menu.schedule.cancel |
Refuse items of content outside the role. | — |
hyva_cms.schedule.list, hyva_cms.schedule.detect_conflicts, the conflicts hyva_cms.schedule.create and hyva_menu.schedule.create return |
Hide items and conflicts of content outside the role, including content that no longer exists. | items_hidden_by_permissions, conflicts_hidden_by_permissions |
hyva_form.delivery.audit without a form |
Audits only the role's forms. | forms_hidden_by_permissions |
hyva_cms.migration.scan |
Lists only the role's pages and blocks. | — |
hyva_menu.find_usage |
Leaves out the design configuration scopes the role may not open: Default, websites it does not fully hold, other store views. | usages_hidden_by_permissions |
hyva_menu.category.import |
Keeps to the role's category roots. Without a store_id it reads in the menu's first store view the role may read. |
— |
Usage lists, previews and audits
These leave out content outside the role, as Hyvä's guards do:
hyva_media.image.find_usage,hyva_media.image.list,hyva_media.image.validate,hyva_media.asset.resolve;- the
hyva_media.asset.moveandhyva_media.asset.trashpreviews; - the
usagefield ofhyva_media.image.get,hyva_cms.block.getandhyva_menu.get; hyva_menu.find_usage;- the
hyva_commerce.audit.*,hyva_media.audit*andhyva_menu.audit_allaudits; - the forms lens of
hyva_commerce.audit.overview.
What is left out, counted in *_hidden_by_permissions:
- pages, blocks, menus and widget instances outside the role's store views;
- products outside the role's websites;
- categories outside the category trees of the role's store views.
Exceptions:
- An image or menu used only outside the role still counts as used.
- A product assigned to no website stays listed, as in the Hyvä admin.
published_urls and the store rows of previews (preview links, is_assigned, e.g. in hyva_menu.create and
hyva_cms.preview) list only the role's store views, and count the rest in stores_hidden_by_permissions.
Not filtered by scope
- Media Gallery files, folders, trash and sync status. The Hyvä Media Gallery has no scope, and the core MCP module leaves data without a store assignment unscoped too. The media tool descriptions and, for a restricted admin, the Media Health notice say that media files are shared by all websites.
- Configuration values: menu placements, email assignments in
hyva_email.audit.coverage, store credit websites inhyva_commerce.audit.overview. - Email and newsletter templates.
- The MCP audit log. See Store scope in widgets for what the MCP Activity widget shows a restricted admin.
Delete tools
hyva_cms.page.delete, hyva_cms.block.delete and hyva_menu.delete each delete one page, block or menu.
- Same path as the admin. They use the repository the admin delete action uses: Magento's page or block repository in the admin area, Hyvä's menu repository for menus.
- Hyvä data goes with it. Hyvä drafts, version history and Tailwind CSS are deleted too, as in the admin (foreign
keys with
ON DELETE CASCADE). - Scheduled releases stay. Releases that name the entity are not removed, as in the admin.
To remove a single menu item use hyva_menu.item.remove. To remove media files, hyva_media.asset.trash moves them to
the Media Gallery trash.
Permissions
| Tool | Tool resource | Admin delete permissions |
|---|---|---|
hyva_cms.page.delete |
Tool: Delete CMS Pages via MCP | Magento_Cms::page_delete (the admin page Delete action) and Hyva_Cms::page_delete |
hyva_cms.block.delete |
Tool: Delete CMS Blocks via MCP | Magento_Cms::block (Magento has no separate block delete permission) and Hyva_Cms::block_delete |
hyva_menu.delete |
Tool: Delete Hyvä Menus via MCP | Hyva_MenuBuilder::menu_delete |
- The tool resources sit under MCP Tools → Hyvä Commerce Tools. The module grants them to no role. Only a role with All resources (Administrators) has them without being given them.
- The core checks the tool resource and the "Listed with" resource on
tools/listandtools/call. - The page and block tools check both admin delete permissions again and refuse with status 403.
- They are write tools, so the write gate applies.
- Store scope is as for any change: every store view the entity is assigned to must be the role's, and store view 0 needs all of them.
Confirm and force
| Call | Entity not in use | Entity in use (in_use: true) |
|---|---|---|
No confirm (with or without force) |
Preview | Preview that says force is needed (details.force_required, hint) |
"confirm": true |
Deleted | Refused: soft error, status 409, naming the usages and returning them in usage |
"confirm": true, "force": true |
Deleted | Deleted |
The preview is the standard one:
action:delete_cms_page,delete_cms_blockordelete_menu;affected: the entity with its store views andin_use;details.usage: where it is still used (see Usage keys).
A forced delete answers deleted: true with:
forced: true;- the usages that broke, in
usage(the preview's report); - a hint that those references are now broken.
The audit summary records forced too.
Usage keys
details.usage has used, total and one list per place. The list keys differ per type: they are the keys the
find-usage tools already return, so they are not unified.
| Tool | List keys in details.usage |
|---|---|
hyva_cms.page.delete |
store_config (home / 404 / cookies page configuration), links (links in Hyvä CMS content and menu items) |
hyva_cms.block.delete |
hyva_content (Hyvä CMS components), magento_content (widget directives in Magento content), widget_instances |
hyva_menu.delete |
design_config (header/footer design configuration), hyva_cms_content and magento_cms_content (menu widgets in content), widget_instances, layout_and_templates; also identifier, as hyva_menu.find_usage |
For a role restricted to some websites, usages_hidden_by_permissions counts the usages it may not see.
The page and block tools also check menus when the role may not view them (Hyva_MenuBuilder::menu_view). Those
usages are not listed; usages_hidden_by_permissions counts them, and they still set used, so force is needed.
Optional features
Tools for an optional Hyvä module stay registered when that module is missing, disabled, or not allowed for the token's admin role. What an agent sees depends on the module:
| Hyvä module missing or disabled | Effect |
|---|---|
| Menu Builder, Media Optimization, Media Gallery, Form Builder, Email Templates, Store Credit, Linked Products, AI Worker | Their tools are hidden from tools/list. A call to a hidden tool is refused by the core (-32004). The status tools stay listed (below). |
| Category Merchandiser, CMS AI Translations, Advanced Admin Permissions, the AI providers, the Tailwind compiler | Their tools stay listed and answer "not installed" per call. |
The status tools stay listed:
hyva_menu.statusandhyva_media.statusreport the feature withavailable: falseandacl_allowed: null(no ACL verdict for a feature that is not there).hyva_store_credit.statusandhyva_ai.worker.statusanswer that the module is not installed.hyva_commerce.audit.overviewlists every module.
A call that reaches such a tool answers with a soft error (isError: true) instead of failing:
{"available": false, "feature": "menu_builder", "reason": "Hyvä Menu Builder is installed but disabled (Hyva_MenuBuilder).", "hint": "Run bin/magento module:enable Hyva_MenuBuilder and setup:upgrade."}
Call hyva_commerce.audit.overview, hyva_menu.status or hyva_media.status first to see what the store supports.
Hyvä Commerce 1.4 coverage
Hyvä Commerce 1.4.0 (hyva-themes/commerce 1.4.0) and what this module offers for each part. Counts are tools.
| Module (version) | Tools | Notes |
|---|---|---|
| Hyvä CMS 1.3.1 (Liveview editor, Connect, Admin Styles) | hyva_cms.* (29, without translation.* and tailwind.status) |
Pages, blocks, drafts, versions, scheduling, components, export/import, PageBuilder migration, preview, permission.check; per-type verbs from ContentTypeAuthorization |
| CMS AI Translations 1.0.2 | hyva_cms.translation.* (2) |
Status per store view; run returns proposals and can write the draft, never publishes |
| Menu Builder 1.1.0 | hyva_menu.* (21) |
Includes publish, delete, versions and schedules (1.1 per-verb permissions) |
| Media Gallery 1.0.0 | hyva_media.asset.*, trash.*, folder.create, sync.status, audit.literal_urls (9) |
Asset ids in content (imageOptions.id), move, trash/restore, sync drift, literal-URL audit |
| Media Optimization 1.1.0 | hyva_media.optimization.* (5) |
Unchanged in 1.4 |
| Image usage and audits (CMS + Media Gallery) | hyva_media.image.*, hyva_media.audit_*, hyva_media.status (10) |
Find, replace and fix images across CMS content and menus |
| Form Builder 1.0.1 | hyva_form.* (9) |
Forms, drafts, publish, versions, delivery audit (recipients, webhook) |
| Email & Newsletter Templates 1.0.0 | hyva_email.* (14) |
Transactional emails and newsletters: drafts, publish, render preview, test send, coverage audit |
| Store Credit 1.0.1 | hyva_store_credit.* (5) |
Balances, history, credit/debit with preview and idempotency key. Its GraphQL API is for shoppers and has no admin use here |
| Linked Products 1.0.0 | hyva_linked.* (4) |
Groups, validation with storefront warnings, save with page cache refresh |
| Category Merchandiser 1.0.0 | hyva_merch.category.* (2) |
Reorder only. The Enterprise package is not installed. Reports when another module (ElasticSuite) owns storefront sorting |
| AI Worker 1.0.0 and AI Worker CMS 1.0.0 | hyva_ai.* (5, without provider.status) |
Monitoring only (status, jobs, usage, errors); AI Worker CMS jobs show in hyva_ai.job.list. No generation by design |
AI providers 1.3.0 (magento2-module-ai 1.3.1 with the Anthropic, DeepL, Gemini and OpenAI modules) |
hyva_ai.provider.status (1) |
Which providers are configured and their models, plus whether CMS AI Translation is ready to run. API keys are never read or shown |
| CMS Tailwind compiler 1.0.x and JIT bridge 1.0.3 | hyva_cms.tailwind.status (1) |
Compiler daemon health, daemon management, compilation strategy and compiler version, with a hint when new CMS content is not being compiled. Read only: no start, stop or restart |
| Advanced Admin Permissions 1.0.0 | hyva_admin_perm.* (2) |
Read only (effective permissions, audit log). Scope restrictions are applied by the module itself, see Store scope |
| Admin Dashboard 2.0.3 (+ API 3.0.1, CMS widgets, CrUX history widget) | hyva_dashboard.* (3) + widgets |
Views and widget types as the caller sees them; MCP activity and content health widgets |
| Audits | hyva_commerce.audit.* (4) |
audit.overview adds one health line per 1.4 module |
Not covered, on purpose
| Module (version) | Why |
|---|---|
Admin Theme (commerce-theme-adminhtml 1.1.1, commerce-module-admin-theme 1.0.1) |
Visual admin theme only; nothing for an agent to read or change |
| Commerce Module 1.0.6 | Shared base and branding fixes (logo); no data of its own |
| Image Editor 1.1.0 | Interactive in-browser editor; its saved edits show in hyva_media.image.get |
| CMS Google Maps 1.0.0 | Only a CMS component; listed and validated by hyva_cms.component.list / schema / validate |
Tool catalog
Tool names. The tables use the canonical dotted names (hyva_cms.page.get). On the wire, tools/list shows them
with underscores (hyva_cms_page_get); tools/call accepts both forms.
Columns.
- Mode:
readorwrite. Write tools need the write gate. - Listed with: the Hyvä or Magento resource the role needs to see and call the tool (ACL check 2).
-means none. - Checked per call: the Hyvä verb checked against the call's arguments (ACL check 3).
entity_type → publishmeans thepublishverb for the content type inentity_type. "The verb on any type" in Listed with means the role needs that verb on at least one content type.
Hyvä CMS
| Tool | Mode | Listed with | Checked per call (Hyvä verb) | What it does |
|---|---|---|---|---|
hyva_cms.block.create |
write | Hyva_Cms::block_save |
copy_from.entity_type → view | Create Hyvä CMS Block |
hyva_cms.block.get |
read | Hyva_Cms::block_view |
fields with versions → version_history | Get Hyvä CMS Block |
hyva_cms.block.list |
read | Hyva_Cms::block_view |
List Hyvä CMS Blocks | |
hyva_cms.block.delete |
write | Hyva_Cms::block_delete + Magento_Cms::block |
Delete Hyvä CMS Block (own resource Delete CMS Blocks via MCP; confirm-gated) | |
hyva_cms.block.update |
write | Hyva_Cms::block_save |
Update Hyvä CMS Block | |
hyva_cms.component.list |
read | Hyva_Cms::cms |
List Hyvä CMS Components | |
hyva_cms.component.schema |
read | Hyva_Cms::cms |
Get Hyvä CMS Component Schema | |
hyva_cms.component.validate |
read | the verb on any type | entity_type → view | Validate Hyvä CMS Components |
hyva_cms.draft.create |
write | the verb on any type | entity_type → save (+ version_history for source=version) | Create Hyvä CMS Draft |
hyva_cms.draft.update |
write | the verb on any type | entity_type → save | Update Hyvä CMS Draft |
hyva_cms.export |
read | the verb on any type | entity_type → export (+ version_history with include_versions) + Hyva_Cms::transfer |
Export Hyvä CMS Content |
hyva_cms.import |
write | the verb on any type | entity_type → save + Hyva_Cms::transfer |
Import Hyvä CMS Content |
hyva_cms.migration.analyze |
read | the verb on pages or blocks | entity_type → view | Analyze Legacy CMS Content |
hyva_cms.migration.convert_to_draft |
write | the verb on pages or blocks | entity_type → save | Convert Legacy CMS Content to Draft |
hyva_cms.migration.scan |
read | the verb on pages or blocks | entity_type → view | Scan Legacy CMS Content (at most limit items, default 50, max 500; summary.total counts all) |
hyva_cms.page.create |
write | Hyva_Cms::page_save |
copy_from.entity_type → view | Create Hyvä CMS Page |
hyva_cms.page.get |
read | Hyva_Cms::page_view |
fields with versions → version_history | Get Hyvä CMS Page |
hyva_cms.page.list |
read | Hyva_Cms::page_view |
List Hyvä CMS Pages | |
hyva_cms.page.delete |
write | Hyva_Cms::page_delete + Magento_Cms::page_delete |
Delete Hyvä CMS Page (own resource Delete CMS Pages via MCP; confirm-gated) | |
hyva_cms.page.update |
write | Hyva_Cms::page_save |
Update Hyvä CMS Page | |
hyva_cms.permission.check |
read | - |
Check Hyvä CMS Permissions | |
hyva_cms.preview |
read | the verb on any type | entity_type → view (+ version_history with version_id) | Preview Hyvä CMS Content |
hyva_cms.publish |
write | the verb on any type | entity_type → publish (+ version_history with version_id) | Publish Hyvä CMS Content |
hyva_cms.schedule.cancel |
write | the verb on any type | entity_type → schedule_cancel | Cancel Hyvä CMS Schedule |
hyva_cms.schedule.create |
write | the verb on any type | entity_type → schedule_save (+ version_history with version_id) | Schedule Hyvä CMS Content |
hyva_cms.schedule.detect_conflicts |
read | the verb on any type | entity_type → scheduling | Detect Hyvä CMS Schedule Conflicts |
hyva_cms.schedule.list |
read | the verb on any type | entity_type → scheduling | List Hyvä CMS Schedules |
hyva_cms.tailwind.status |
read | Magento_Config::config_system |
Hyvä CMS Tailwind Status (compiler daemon health, strategy; hint when classes are not compiled) | |
hyva_cms.translation.run |
write | the verb on any type | entity_type → view + Hyva_CmsAiTranslations::translate |
Run Hyvä CMS AI Translation |
hyva_cms.translation.status |
read | the verb on any type | entity_type → view | Hyvä CMS Translation Status |
hyva_cms.version.list |
read | the verb on any type | entity_type → version_history | List Hyvä CMS Versions |
hyva_cms.version.restore |
write | the verb on any type | entity_type → save + version_history | Restore Hyvä CMS Version |
Hyvä Menu Builder (optional)
| Tool | Mode | Listed with | Checked per call (Hyvä verb) | What it does |
|---|---|---|---|---|
hyva_menu.audit_all |
read | Hyva_MenuBuilder::menu_view |
Audit All Hyvä Menus | |
hyva_menu.category.import |
write | Hyva_MenuBuilder::menu_save |
Import Categories into Hyvä Menu | |
hyva_menu.category.sync_preview |
read | Hyva_MenuBuilder::menu_view |
Preview Category Import into Hyvä Menu | |
hyva_menu.create |
write | Hyva_MenuBuilder::menu_save |
Create Hyvä Menu | |
hyva_menu.find_usage |
read | Hyva_MenuBuilder::menu_view |
Find Hyvä Menu Usage | |
hyva_menu.get |
read | Hyva_MenuBuilder::menu_view |
fields with versions → version_history | Get Hyvä Menu |
hyva_menu.item.add |
write | Hyva_MenuBuilder::menu_save |
Add Hyvä Menu Item | |
hyva_menu.item.remove |
write | Hyva_MenuBuilder::menu_save |
Remove Hyvä Menu Item | |
hyva_menu.item.update |
write | Hyva_MenuBuilder::menu_save |
Update Hyvä Menu Item | |
hyva_menu.list |
read | Hyva_MenuBuilder::menu_view |
List Hyvä Menus | |
hyva_menu.preview |
read | Hyva_MenuBuilder::menu_view |
version_id → version_history | Preview Hyvä Menu |
hyva_menu.publish |
write | Hyva_MenuBuilder::menu_publish |
entity_type → publish (+ version_history with version_id) | Publish Hyvä Menu |
hyva_menu.render_check |
read | Hyva_MenuBuilder::menu_view |
Check Hyvä Menu Rendering | |
hyva_menu.schedule.cancel |
write | Hyva_MenuBuilder::menu_schedule_cancel |
entity_type → schedule_cancel | Cancel Hyvä Menu Schedule |
hyva_menu.schedule.create |
write | Hyva_MenuBuilder::menu_schedule_save |
entity_type → schedule_save (+ version_history with version_id) | Schedule Hyvä Menu |
hyva_menu.status |
read | Hyva_Cms::cms |
Menu Builder Status | |
hyva_menu.delete |
write | Hyva_MenuBuilder::menu_delete |
Delete Hyvä Menu (own resource Delete Hyvä Menus via MCP; confirm-gated) | |
hyva_menu.update |
write | Hyva_MenuBuilder::menu_save |
Update Hyvä Menu | |
hyva_menu.validate |
read | Hyva_MenuBuilder::menu_view |
Validate Hyvä Menu | |
hyva_menu.version.list |
read | Hyva_MenuBuilder::menu_version_history |
entity_type → version_history | List Hyvä Menu Versions |
hyva_menu.version.restore |
write | Hyva_MenuBuilder::menu_save |
entity_type → save + version_history | Restore Hyvä Menu Version |
Hyvä Media (optimization tools need Hyva_MediaOptimization)
| Tool | Mode | Listed with | Checked per call (Hyvä verb) | What it does |
|---|---|---|---|---|
hyva_media.asset.move |
write | Hyva_MediaGallery::asset_save |
Move Media Gallery Assets | |
hyva_media.asset.resolve |
read | Hyva_MediaGallery::asset_view |
Resolve Media Gallery Asset | |
hyva_media.asset.search |
read | Hyva_MediaGallery::asset_view |
Search Media Gallery Assets | |
hyva_media.asset.trash |
write | Hyva_MediaGallery::asset_delete |
Trash Media Gallery Assets | |
hyva_media.audit.literal_urls |
read | Hyva_MediaGallery::asset_view |
Audit Literal Media URLs | |
hyva_media.audit_all |
read | Hyva_MediaGallery::asset_view |
Audit Storefront Media | |
hyva_media.audit_cms |
read | Hyva_MediaGallery::asset_view |
Audit Hyvä CMS Media | |
hyva_media.audit_menu |
read | Hyva_MediaGallery::asset_view |
Audit Menu Media | |
hyva_media.folder.create |
write | Hyva_MediaGallery::folder_save |
Create Media Gallery Folder | |
hyva_media.image.find_usage |
read | Hyva_MediaGallery::asset_view |
Find Media Image Usage | |
hyva_media.image.get |
read | Hyva_MediaGallery::asset_view |
Get Media Image | |
hyva_media.image.list |
read | Hyva_MediaGallery::asset_view |
List Media Images | |
hyva_media.image.replace |
write | Hyva_MediaGallery::asset_view + save on any type |
entity_type → save | Replace Media Image |
hyva_media.image.update_alt |
write | Hyva_MediaGallery::asset_view + save on any type |
entity_type → save | Update Media Image Alt Text |
hyva_media.image.validate |
read | Hyva_MediaGallery::asset_view |
Validate Media Image | |
hyva_media.optimization.clear |
write | Hyva_MediaGallery::asset_save |
Clear Optimized Images | |
hyva_media.optimization.config_get |
read | Magento_Cms::config_cms |
Get Media Optimization Config | |
hyva_media.optimization.config_validate |
read | Magento_Cms::config_cms |
Validate Media Optimization Config | |
hyva_media.optimization.preview_picture |
read | Hyva_MediaGallery::asset_view |
Preview Responsive Picture | |
hyva_media.optimization.status |
read | Hyva_MediaGallery::asset_view |
Media Optimization Status for Image | |
hyva_media.status |
read | Hyva_MediaGallery::asset_view |
Media Optimization Status | |
hyva_media.sync.status |
read | Hyva_MediaGallery::asset_view |
Media Gallery Sync Status | |
hyva_media.trash.list |
read | Hyva_MediaGallery::asset_view |
List Media Gallery Trash | |
hyva_media.trash.restore |
write | Hyva_MediaGallery::asset_delete |
Restore Media Gallery Trash |
Hyvä Form Builder
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_form.delivery.audit |
read | Hyva_FormBuilder::form_view |
Audit Hyvä Form Delivery |
hyva_form.form.create |
write | Hyva_FormBuilder::form_save |
Create Hyvä Form |
hyva_form.form.get |
read | Hyva_FormBuilder::form_view |
Get Hyvä Form |
hyva_form.form.list |
read | Hyva_FormBuilder::form_view |
List Hyvä Forms |
hyva_form.form.publish |
write | Hyva_FormBuilder::form_publish |
Publish Hyvä Form |
hyva_form.form.update_draft |
write | Hyva_FormBuilder::form_save |
Update Hyvä Form Draft |
hyva_form.form.validate |
read | Hyva_FormBuilder::form_view |
Validate Hyvä Form |
hyva_form.version.list |
read | Hyva_FormBuilder::form_version_history |
List Hyvä Form Versions |
hyva_form.version.restore |
write | Hyva_FormBuilder::form_save |
Restore Hyvä Form Version |
Hyvä Email & Newsletter Templates
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_email.audit.coverage |
read | Hyva_EmailTemplates::email_template_view |
Audit Hyvä Email Coverage |
hyva_email.newsletter.create_draft |
write | Hyva_EmailTemplates::newsletter_template_save |
Create Hyvä Newsletter Template |
hyva_email.newsletter.get |
read | Hyva_EmailTemplates::newsletter_template_view |
Get Hyvä Newsletter Template |
hyva_email.newsletter.list |
read | Hyva_EmailTemplates::newsletter_template_view |
List Hyvä Newsletter Templates |
hyva_email.newsletter.preview |
read | Hyva_EmailTemplates::newsletter_template_view |
Preview Hyvä Newsletter Template |
hyva_email.newsletter.publish |
write | Hyva_EmailTemplates::newsletter_template_publish |
Publish Hyvä Newsletter Template |
hyva_email.newsletter.update_draft |
write | Hyva_EmailTemplates::newsletter_template_save |
Update Hyvä Newsletter Template Draft |
hyva_email.template.create_draft |
write | Hyva_EmailTemplates::email_template_save |
Create Hyvä Email Template |
hyva_email.template.get |
read | Hyva_EmailTemplates::email_template_view |
Get Hyvä Email Template |
hyva_email.template.list |
read | Hyva_EmailTemplates::email_template_view |
List Hyvä Email Templates |
hyva_email.template.preview |
read | Hyva_EmailTemplates::email_template_view |
Preview Hyvä Email Template |
hyva_email.template.publish |
write | Hyva_EmailTemplates::email_template_publish |
Publish Hyvä Email Template |
hyva_email.template.send_test |
write | Hyva_EmailTemplates::email_template_save |
Send Hyvä Email Template Test (an outbound write: needs Save draft, although the Hyvä admin button needs only View) |
hyva_email.template.update_draft |
write | Hyva_EmailTemplates::email_template_save |
Update Hyvä Email Template Draft |
Hyvä Store Credit
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_store_credit.balance.credit |
write | Hyva_StoreCredit::balance_adjust |
Credit Store Credit |
hyva_store_credit.balance.debit |
write | Hyva_StoreCredit::balance_adjust |
Debit Store Credit |
hyva_store_credit.balance.get |
read | Hyva_StoreCredit::balance_view |
Get Store Credit Balance |
hyva_store_credit.history.list |
read | Hyva_StoreCredit::balance_view |
List Store Credit History |
hyva_store_credit.status |
read | Hyva_StoreCredit::balance_view |
Hyvä Store Credit Status |
Hyvä Linked Products
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_linked.group.get |
read | Hyva_LinkedProducts::group_view |
Get Linked Product Group |
hyva_linked.group.list |
read | Hyva_LinkedProducts::group_view |
List Linked Product Groups |
hyva_linked.group.save |
write | Hyva_LinkedProducts::group_save |
Save Linked Product Group |
hyva_linked.group.validate |
read | Hyva_LinkedProducts::group_view |
Validate Linked Product Group |
Hyvä Category Merchandiser
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_merch.category.positions_get |
read | Magento_Catalog::categories |
Get Category Product Order |
hyva_merch.category.positions_set |
write | Magento_Catalog::categories |
Reorder Category Products |
Hyvä AI (monitoring)
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_ai.error.list |
read | Hyva_AiWorker::jobs |
List Hyvä AI Worker Errors |
hyva_ai.job.get |
read | Hyva_AiWorker::manage |
Get Hyvä AI Worker Job |
hyva_ai.job.list |
read | Hyva_AiWorker::manage |
List Hyvä AI Worker Jobs |
hyva_ai.provider.status |
read | Hyva_Ai::config |
Hyvä AI Provider Status (providers configured or not, CMS translation readiness; API keys never shown) |
hyva_ai.usage.summary |
read | Hyva_AiWorker::jobs |
Hyvä AI Worker Token Usage |
hyva_ai.worker.status |
read | Hyva_AiWorker::config |
Hyvä AI Worker Status |
Hyvä Advanced Admin Permissions (read only)
| Tool | Mode | Listed with | What it does |
|---|---|---|---|
hyva_admin_perm.audit.list |
read | Hyva_AdvancedAdminPermissions::audit |
List Admin Role Assignment Audit |
hyva_admin_perm.effective.get |
read | Magento_User::acl_users |
Get Effective Admin Permissions |
Audits and dashboard
| Tool | Mode | Listed with | Checked per call (Hyvä verb) | What it does |
|---|---|---|---|---|
hyva_commerce.audit.cms |
read | the verb on any type | entity_type → view | Audit Hyvä CMS Content |
hyva_commerce.audit.media |
read | Hyva_MediaGallery::asset_view |
Audit Hyvä Commerce Media | |
hyva_commerce.audit.menu |
read | Hyva_MenuBuilder::menu_view |
Audit Hyvä Commerce Menus (accepts max_kb and limit) |
|
hyva_commerce.audit.overview |
read | - |
Audit Hyvä Commerce Installation | |
hyva_dashboard.view.list |
read | Hyva_AdminDashboardFramework::dashboard |
List Hyvä Dashboard Views | |
hyva_dashboard.widget.list |
read | Hyva_AdminDashboardFramework::dashboard |
List Hyvä Dashboard Widgets | |
hyva_dashboard.widget.refresh |
write | Hyva_AdminDashboardFramework::dashboard |
Refresh Dashboard Widget Data |
Prompts
| Prompt | Writes | What it does |
|---|---|---|
hyva_cms.landing_page_draft |
yes | Builds a campaign landing page as a draft from a short brief, validates it and returns the preview link. |
hyva_menu.health_check |
no | Checks every menu for broken links, disabled targets and empty sections, in plain language. |
hyva_media.audit_report |
no | Reports heavy images, missing alt text, missing files and WebP/AVIF setup. |
Dashboard widgets
The widgets are in the category Magebit / AI / MCP, registered through
Hyva\AdminDashboardFramework\Model\Config\Widget\Converter.
- ACL. Each widget has its own resource under Dashboard → Magebit / AI / MCP Widgets.
- Cache. Each widget caches its data for 300 s and reuses the same services as the audit tools.
- CSP. Templates are static markup with no Alpine state, so they are CSP-safe.
| Widget | Shows |
|---|---|
magebit_mcp_activity_widget |
MCP calls, failures, writes, AI-generated drafts, publish/live/destructive actions, and a link to the MCP audit log. See How MCP Activity counts calls. |
magebit_content_health_widget |
Missing alt text, broken images, invalid/disabled components, unpublished drafts, schedule problems, legacy pages |
magebit_menu_health_widget |
Menus with broken links, disabled targets, empty columns, placement, last MCP menu actions |
magebit_media_health_widget |
Oversized images, missing alt, broken references, missing WebP/AVIF, optimization and engine status |
magebit_campaign_calendar_widget |
Upcoming and recent scheduled releases, homepage/menu changes, conflicts |
magebit_migration_status_widget |
Hyvä vs Page Builder/WYSIWYG pages, complexity, converted drafts waiting |
magebit_campaign_asset_readiness_widget |
Media and link problems in the content of pending scheduled items |
hyva_dashboard.widget.refresh clears a widget's cached data by type or instance, for every viewer of the instance.
How MCP Activity counts calls
- Writes: every registered write tool.
- AI-generated drafts: this module's tools that only save drafts. These are
create_draft,update_draft,convert_to_draft,update_alt, and create/update/add/run on pages, blocks, drafts, menus, menu items, forms and translations. - Publish, live and destructive actions: every other write tool. This covers publish, delete, trash, remove, clear,
restore, import, replace, cancel, move, flush, reset, disable, and immediate changes such as
system.config.set, the core CMS tools, category positions or store credit. - Dry runs and confirmation previews are not counted.
Store scope in widgets
- The widgets apply the logged-in admin's store scope, with a separate widget cache entry per restriction.
- The MCP audit log has no store scope. The MCP Activity widget (which needs
Magebit_Mcp::mcp_audit) therefore shows a restricted admin only their own MCP calls, and an unrestricted admin every admin's calls. - Menu Health and Media Health show MCP activity and the audit log link only with
Magebit_Mcp::mcp_audit.
Notes on Hyvä behaviour
- Scheduling. Hyvä scheduled releases are one-way: there is no end date.
hyva_cms.schedule.detect_conflictsreports ano_fallbackinfo when nothing restores the previous content after a campaign. - Schedule list cap.
hyva_cms.schedule.listwith a status other thanpendinglists the newest releases first and reads at most the newest 1000 items. It reportstruncated: truewhen it cut; the release cut by the cap is left out, so no release is partial.total_releasescounts releases within the items read. Pending is never capped. - Tailwind CSS. JIT Tailwind CSS for content is compiled by the Liveview editor in the browser. Content written over MCP can use classes that are not compiled yet for the theme.
- Admin area for saves. Page and block saves run in an emulated
adminhtmlarea. In the frontend area, where/mcpruns, Hyvä'sPlugin\Model\Page::afterGetContentfails for a page without an id. - Published URLs. Hyvä's page provider reports a page's address as
published_urlin every store view, active or not, and its menu provider marks a menu assigned (is_assigned: true) in every store view.published_urlsleaves out, and preview store rows givepublished_url: nullfor, an inactive entity and a store view it is not assigned to; for a menu, that is decided by the menu's own store views. - Component links.
hyva_cms.component.validatewarns (invalid_link) about link field values with neithertypeandvaluenor a non-emptysrc, such as{"url": "..."}. They render an empty href. - Image ids. Hyvä writers outside the editor must call
ImageIdBackfiller::backfill()themselves (Provider::saveContentdoes not). The draft tools do, so images keep their Media Gallery asset id. - Trash and asset ids. Trashing deletes the Media Gallery asset row, so a restored file can come back with a new
asset id. Check content that used the old id with
hyva_media.audit.literal_urls(stale_asset_id). - Optimized image cleanup.
hyva_media.optimization.clearalso removes conversions of resized variants (converted/resized/<hash>), which Hyvä's own cleaner leaves behind. - Category import.
hyva_menu.category.importleaves out new subcategories of a category whose menu item lies outside the targeted roots, and lists them inskipped_outside_targets(id,name). - Email fields that are not drafted. An email template's subject and preheader, and a newsletter's sender, change
sent emails at once. The email update tools say so and report
live_change. - AI translation. Hyvä's AI translation joins texts with line breaks and splits the answer on line breaks.
hyva_cms.translation.runcollapses line breaks in HTML and skips plain multi-line texts, so translations never land on the wrong field. - Store credit idempotency. Hyvä's ledger returns the earlier entry when an idempotency key is reused, even for another customer or amount. The tools tell a replay from a clash (409).
- Store credit switches. Hyvä's balance services ignore the enabled flag and never email. The tools refuse websites where store credit is off, and can notify the customer.
- Linked Products cache. Hyvä's group saver cleans no cache.
hyva_linked.group.saverefreshes the product pages of old and new members. - Category positions. Positions only reach the storefront when Magento's own catalog search sorts category pages. With ElasticSuite installed (as on the demo), it sorts by its own positions; the merchandiser tools say so.
- Dashboard services. Several Hyvä Admin Dashboard services (view model, widget instance repository, widget auth) need the admin session or adminhtml-only configuration. The dashboard tools therefore read views and widgets through the explicit-id services, the widget configuration and the instance table.
Upgrade notes
Since 0.0.1 (breaking for custom gateways and for clients that parse replies)
Api\Adapter\MenuGatewayInterface has a new method delete(int $menuId): void, used by hyva_menu.delete.
- Projects that keep the module's
MenuGatewayneed no change. - Projects that replace the module's preference for this interface in their own
di.xmlmust add the method. Otherwise PHP stops with a fatal error when the class is loaded.
Three reply shapes changed. Clients that read them must switch:
- Confirm previews have one envelope:
affectedis always a list and context sits indetails. In 0.0.1hyva_media.asset.trashhadaffected.assetsandaffected.in_use,hyva_media.asset.movehadaffected.assetsandaffected.target_folder, andhyva_media.image.replace(scope=global) hadaffected.hyva_entities. Now the items areaffected[]and the context isdetails.*(e.g.details.in_use,details.target_folder).hyva_media.optimization.clear(all_images) had its counts andmodeas the onlyaffectedentry; nowaffectedlists sample paths,totalcounts every file and the counts andmodeare indetails. hyva_media.asset.trash:in_useis a boolean, in the preview (details.in_use) and in the confirmed reply, as in the delete tools. In 0.0.1 it was the number of assets still in use (preview:affected.in_use). Read that number fromin_use_count(preview:details.in_use_count).hyva_media.image.replace(scope=global) preview lists each entity once. In 0.0.1 every usage that is not changed was inaffected.not_editable_usages. Now the usages of an entity that is changed sit on that entity'saffected[]row asnot_editable_usages, anddetails.not_editable_usageskeeps only entities that are not changed at all. Read both to get every usage. The confirmed reply'snot_changedstill lists all of them.
Development
vendor/bin/phpstan analyse app/code/Magebit/McpHyvaCommerceTools -c app/code/Magebit/McpHyvaCommerceTools/phpstan.neon vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Magebit/McpHyvaCommerceTools/Test/Unit vendor/bin/phpcs --standard=Magento2 --extensions=php,phtml app/code/Magebit/McpHyvaCommerceTools
Optional Hyvä code stays behind adapters. Only Model/Adapter/* reference Hyva\MenuBuilder\* /
Hyva\MediaOptimization\*. Tools depend on the Api/Adapter/*GatewayInterface contracts, wired to generated proxies,
so the real gateway is built only after the feature check.
CI (.github/workflows/ci.yml) runs PHPStan and the unit tests. It needs four repository secrets:
| Secret | Value |
|---|---|
MAGENTO_AUTH_USER, MAGENTO_AUTH_PASS |
repo.magento.com keys |
HYVA_PACKAGIST_URL |
The Hyvä Commerce Private Packagist URL, https://hyva-themes.repo.packagist.com/<project>/ |
HYVA_PACKAGIST_TOKEN |
Its token |
phpcs warnings. phpcs reports warnings only for:
- the static value helpers (
Model/Util/Cast,Model/Tool/Schema/EntityTargetnamed constructors, mirroring the core'sPagination::maxPageSize()); - a few string and path functions (
pathinfo,html_entity_decode,rawurldecode,getimagesize,addcslashes).
License
Released under the MIT License.
Magebit - Full-service e-commerce agency