Adobe Commerce MCP

Adobe Commerce MCP

Servidor MCP para desarrollar en PHP sobre Adobe Commerce: documentación oficial, archivos de configuración, CLI, Web API y scaffolding de módulos, sin red y sin credenciales.

adobe-commerce-mcp es un servidor Model Context Protocol para quien escribe módulos de Adobe Commerce (Magento Open Source) y Adobe Commerce en PaaS o en servidor propio: di.xml, plugins, observers, layout, db_schema.xml, webapi.xml y el resto del día a día en PHP. La documentación oficial viaja dentro del paquete; el servidor no abre conexiones, no pide login y no escribe en disco. Funciona con Claude Code, Claude Desktop, Cursor, VS Code, Windsurf y cualquier cliente MCP con transporte stdio.

Por qué existe

El MCP oficial de Adobe, @adobe-commerce/commerce-extensibility-tools, cubre el desarrollo con App Builder (comandos aio). Para usarlo hay que iniciar sesión en Adobe IMS (aio auth login), también para buscar documentación; su licencia es propietaria (EULA), y una de sus herramientas envía el historial de la conversación a Adobe. Si desarrollas con App Builder, ese es el servidor que corresponde.

Para el desarrollo en PHP (módulos, di.xml, layout, db_schema.xml, webapi.xml) no hay un servidor oficial. Este cubre ese caso con la documentación pública de Adobe, licencia MIT, sin cuenta y sin red.

Características

Versión del código: 0.1.0, según package.json. La entrada src/index.ts conecta el servidor por stdio, y las diez herramientas se registran en src/tools/index.ts.

• Documentación oficial offline: 1.896 páginas de cuatro repositorios de AdobeDocs, con búsqueda BM25 por secciones. Cada resultado trae título, URL pública y ruta en el repositorio de origen.
• Archivos de configuración: qué es cada uno, dónde va (carpeta y área), la URN del XSD cuando la documentación la da y las páginas que lo explican.
• CLI y Web API: los 147 comandos de bin/magento (2.4.9) con sus opciones, 614 endpoints REST del esquema OpenAPI y 225 queries y mutations de GraphQL.
• Scaffolding: módulo, plugin, observer, controller y tabla de db_schema.xml. Las herramientas devuelven los archivos (ruta y contenido) para que el cliente los escriba, y cada archivo dice de qué página de la documentación se adaptó.
• Local y sin credenciales: nada se descarga ni se envía; todo el conocimiento está en data/.

Instalación

El cliente MCP ejecuta el servidor bajo demanda con npx, así que no hace falta instalarlo. Requiere Node >= 18.

Claude Code

claude mcp add adobe-commerce -- npx -y adobe-commerce-mcp

Para compartirlo con el equipo en un repositorio, usa --scope project: la configuración queda en .mcp.json.

Claude Desktop, Cursor y Windsurf

En claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json o .cursor/mcp.json (Cursor) y ~/.codeium/windsurf/mcp_config.json (Windsurf):

{
  "mcpServers": {
    "adobe-commerce": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-mcp"]
    }
  }
}

VS Code

En .vscode/mcp.json:

{
  "servers": {
    "adobe-commerce": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "adobe-commerce-mcp"]
    }
  }
}

Otros clientes

Cualquier cliente con transporte stdio sirve: el comando es npx y los argumentos, -y adobe-commerce-mcp. Con una instalación global (npm install -g adobe-commerce-mcp), el comando es adobe-commerce-mcp.

Uso

Después de reiniciar el cliente, pide lo que necesitas en lenguaje natural y el asistente elige la herramienta:

• "Crea el módulo Acme_Reviews que dependa de Magento_Catalog"
• "Agrega un plugin after a Magento\Catalog\Model\Product::getName"
• "¿Dónde va el system.xml y cuál es su XSD?"
• "Crea la tabla acme_review con clave foránea a catalog_product_entity"
• "¿Qué opciones tiene bin/magento setup:static-content:deploy?"
• "¿Qué argumentos recibe la mutation addProductsToCart?"

Herramientas

Documentación y referencia

Scaffolding

Las herramientas de scaffolding devuelven también structuredContent con files (path, content, source) y notes. Las rutas son relativas a la raíz de la instalación (app/code/<Vendor>/<Module> por defecto). La herramienta no ve el módulo: si el archivo ya existe, el nodo nuevo se fusiona con lo que hay, y las notas lo avisan.

Resources

De dónde vienen los datos

Todo sale de los repositorios públicos de documentación de Adobe, en el commit indicado en data/fonte.json:

Quedaron fuera las notas de versión, las más de 900 páginas de parches del Quality Patches Tool, las herramientas de monitoreo en la nube y la referencia de GraphQL de versiones anteriores. El código y los XSD del repositorio magento/magento2 no se usan: su licencia (OSL-3.0) no es compatible con la MIT de este paquete. Los templates de scaffolding se adaptaron de los ejemplos de la documentación.

Las licencias de las fuentes van en data/licenses/ y el detalle, en NOTICE. Este proyecto no está afiliado a Adobe ni cuenta con su respaldo.

Estructura

src/
├── index.ts            # entry point del binario (stdio)
├── server.ts           # McpServer: registra tools y resources
├── tools/              # una herramienta por archivo, registradas en tools/index.ts
├── scaffold/           # validación de nombres y formato de los archivos generados
├── resources/          # adobe-commerce://docs, config-files y sources
└── knowledge/          # carga de data/ y búsqueda BM25
scripts/
├── ingerir.ts          # genera data/ a partir de los clones de AdobeDocs
├── catalogo-config.ts  # catálogo de archivos de configuración, con sus fuentes
├── probar-mcp.mjs      # arranca el servidor por stdio y comprueba las herramientas
└── rastros.mjs         # busca rutas locales, correos personales y nombres de clientes
data/                   # generado: docs, cli.json, webapi/, config-files.json, licencias
test/                   # node --test sobre el build

Desarrollo

Desde una copia del repositorio:

npm install
npm run check

Para probar la versión local en un cliente, apunta el comando a la build:

claude mcp add adobe-commerce-local -- node /ruta/a/adobe-commerce-mcp/build/index.js

Actualizar la documentación

1. Clona en una misma carpeta AdobeDocs/commerce-php, commerce-frontend-core, commerce-webapi y commerce-operations.en (un clon superficial alcanza).
2. npm run ingerir -- <carpeta>. El script solo lee los archivos de texto; nada de los clones se ejecuta.
3. La ingestión falla si una entrada del catálogo de configuración cita una página que no existe o una URN que no aparece en sus fuentes.
4. npm run check y commit de data/: el paquete lo necesita.

Convenciones

• TypeScript con módulos ESM; Prettier sin punto y coma y con comillas simples.
• Las descripciones de las herramientas van en inglés: es lo que el modelo lee para elegirlas.
• Conventional Commits.
• El conocimiento es de solo lectura en tiempo de ejecución: nada se escribe en disco ni se descarga.

Ramas y publicación

El trabajo nace en una rama salida de dev y el PR va contra dev. De ahí se promueve a qa y, después de probar, a main, siempre con merge de la rama completa. El CI corre npm run check en Node 18, 20 y 22.

Para publicar, actualiza la versión en package.json, server.json y CHANGELOG.md y sube un tag v*: el workflow publish.yml corre el gate, publica en npm con provenance, crea el GitHub Release y publica server.json en el MCP Registry.

Changelog

Ver CHANGELOG.md.

Licencia

MIT. Los datos de data/ conservan las licencias de sus fuentes (Apache-2.0 y MIT); ver NOTICE.

Hecho con amor y café por commente.me