Magento2 MCP - Catalog Tools

This is a sub-module for the Magento2 MCP module

Catalog-domain MCP tools for Magebit_Mcp. Exposes catalog products and
categories — paginated reads, single-entity reads with field-resolver-driven
shape, and writes (create / update / delete) wired through Magento service
contracts.

Each tool is a thin wrapper over the corresponding Magento service contract
(ProductRepositoryInterface, CategoryRepositoryInterface,
CategoryListInterface, StockRegistryInterface,
CategoryManagementInterface). Read responses are composed from field
resolvers that 3rd-party modules can extend; writes go through the same
repositories the admin UI uses, so server-side validation and reindex hooks
fire identically.

Install

composer require magebitcom/magento2-mcp-catalog-tools
bin/magento module:enable Magebit_McpCatalogTools
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Tool catalog

Products (read)

Categories (read)

Products (write)

Write tools require the global magebit_mcp/general/allow_writes flag and
the token's own allow_writes flag to be 1. All writes require explicit
confirmation so MCP clients prompt before firing.

Stock (write)

catalog.product.create also accepts qty / is_in_stock so a new product
lands sellable in one call.

These stock tools target stores with Multi-Source Inventory (MSI) disabled.
They write Magento's legacy single-stock tables via StockRegistryInterface,
which is the whole inventory model on an MSI-free store.

If MSI is enabled, use
Magebit_McpInventoryTools
instead — inventory.source_item.set addresses a specific source, whereas a
legacy write resolves to the default source only. With that module installed,
every result row from catalog.product.stock.set on a multi-source store
carries a warning saying exactly that. Without it the check assumes
single-source and stays quiet; the seam is
Magebit\McpCatalogTools\Api\SingleSourceModeCheckerInterface.

One MSI quirk worth knowing: while MSI is installed it forces min_qty to 0
on read whenever backorders are enabled (AdaptMinQtyToBackordersPlugin), so a
stored threshold reads back as zero. Without MSI the stored value is returned
as written.

Media (write)

The image type is detected from the decoded bytes, never from the supplied
filename — a payload that doesn't decode as a real image is rejected, and the
stored extension is derived from the sniffed type. Filenames are stripped of
path components before use.

Which types are accepted is decided by Magento's own
Magento\Framework\Api\ImageContentValidator, the same service the gallery
save uses, so a store that widens that allowlist through di.xml widens this
tool with it. Out of the box that means JPEG, PNG and GIF — not WebP.

Known Magento behaviour: catalog.product.media.update goes through
ProductAttributeMediaGalleryManagementInterface::update(), which re-copies the
image file on every call (photo.jpg becomes photo_1.jpg, then
photo_1_1.jpg). The gallery entry keeps its id and points at the newest file;
the previous file is left on disk. This is Magento's behaviour, not this
module's — budget for it if you script bulk metadata updates.

types assigns image roles (image, small_image, thumbnail,
swatch_image). Each role belongs to one image at a time, so assigning it here
removes it from whichever image held it before.

Request size. Base64 inflates a file by roughly a third, and the MCP
endpoint caps request bodies at 256 KB by default. For real product photos raise
Stores → Configuration → Magebit → MCP Server → Max Request Body (KB) (an
8 MB image needs about 11000) and raise the matching web-server limit —
nginx client_max_body_size or Apache LimitRequestBody — otherwise the upload
is rejected before Magento sees it.

Categories (write)

Every write tool also implements Magebit\Mcp\Api\UnderlyingAclAwareInterface
with Magento_Catalog::products / Magento_Catalog::categories as the
underlying Magento admin resource, so they block calls from admins who
wouldn't be allowed to perform the same action in the admin UI.

Upgrade notes

• Global-scope writes by default. catalog.product.create /
  catalog.product.update and catalog.category.create /
  catalog.category.update now save attribute values at global/default
  scope, matching REST /all/V1/products. Previously, calling these tools
  from the frontend area silently wrote store-view override rows instead of
  updating the default value. catalog.product.update gained an optional
  store_code argument (a store view code, or "all"/omitted for global)
  for intentional store-view overrides; catalog.category.update keeps its
  existing integer store_id argument for the same purpose (categories are
  always created at global scope — there is no store-scoped
  catalog.category.create). Override rows created by earlier versions of
  these tools are not repaired automatically — reapply the desired value at
  global scope (or the correct store view) if you need to clean one up.
  catalog.product.get reads the resolved store view, so a pre-existing
  store-view override row will still mask a newly written global value when
  reading back — such overrides are not repaired automatically.
• catalog.category.get reads true admin scope by default. Without a
  store_id, the tool now reads at admin/default scope as documented. One
  consequence: the products.product_ids slice always lists every product
  assigned to the category, not a store-view-filtered subset — pass
  exclude: ["products"] if you don't need it.
• catalog.product.list has a new has_special_price filter — boolean,
  presence-only (it does not evaluate special_from_date /
  special_to_date).
• catalog.product.get has a new variants slice for configurable
  products: id, sku, name, price, special_price, and status for each child.

Extending

See docs/EXTENDING.md for:

• adding a new field to any tool response via ProductFieldResolverInterface
  / CategoryFieldResolverInterface;
• adding a new filter to catalog.product.list / catalog.category.list
  via ProductFilterTranslatorInterface /
  CategoryFilterTranslatorInterface;
• the ACL layering rules for custom write tools.

License

Released under the MIT License.

Magebit - Full-service e-commerce agency

magebit.com