VTEX IO MCP

io.github.commentemeappPublished by GitHub account commentemeappv0.2.0Updated Oct 30, 2026

Scaffold VTEX IO apps, Node services and GraphQL, look up Store Framework block props, search docs

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local MCP server that helps an assistant scaffold VTEX IO apps, Node services and GraphQL, and look up Store Framework blocks, VTEX docs and REST APIs.

What you can do
  • Scaffold VTEX IO apps with manifest.json and builder folders, plus Node services with routes and event handlers and GraphQL schemas with typed resolvers
  • Look up Store Framework block props and examples, and generate validated JSONC snippets for blocks.jsonc
  • Search 391 VTEX documentation files and 10 official courses by keyword, and read a full concept by ID
  • Look up VTEX REST API references for catalog, orders, checkout, Master Data, logistics, pricing and other APIs
  • Expose read-only resources for the concept and course indexes and their full documents
When to use it
Useful when building or extending a VTEX IO storefront or backend and you want the assistant to generate boilerplate, check block props, or answer questions from bundled VTEX documentation without leaving the editor.
Requirements
Runs locally over stdio via npx (Node 18 or later); no installation needed, though a global npm install is also possible. No credentials, API keys or environment variables are required, and it makes no external API calls.
Before you install
Generated scaffolds and JSONC snippets are written into your project by the assistant, so review them before committing. The bundled knowledge is read-only at runtime and nothing is downloaded, but it is a snapshot of VTEX docs and courses, so it may lag behind current VTEX releases; only a small set of blocks is covered today.

Installation

In SourceWeft

  1. Open VTEX IO MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[vtex-io-mcp · Servidor MCP para desarrollar en VTEX IO: Store Framework, React, Node, GraphQL y Admin.]

vtex-io-mcp

Servidor MCP para desarrollar en VTEX IO: Store Framework, React, Node, GraphQL y Admin.

[npm] [node] [licencia]

Instalación

bash
claude mcp add vtex-io -- npx -y @commenteme/vtex-io-mcp

El cliente MCP corre el servidor con npx, así que no hace falta instalar nada. Requiere Node >= 18. Para Claude Desktop, Cursor, VS Code y Windsurf, mira Clientes MCP.

Uso rápido

Reinicia el cliente y pide lo que necesitas. El asistente elige la herramienta:

  • "Crea una app VTEX IO llamada product-reviews con los builders react, node, graphql y store"
  • "Que props acepta el flex-layout.row? Dame un ejemplo con dos columnas"
  • "Genera un servicio Node con una ruta pública GET /_v/order/:orderId y un handler para order.created"
  • "Arma el esquema GraphQL con una query productReviews(productId: ID!) y una mutation addReview"
  • "Busca en la documentación como funcionan las CSS Handles"
  • "Que endpoints tiene la API de Master Data?"

Que incluye

  • Scaffolding de apps VTEX IO: manifest.json y carpetas para cualquier combinación de builders.
  • Backend listo para empezar: servicio Node con service.json, clients, rutas HTTP y handlers de eventos; esquema GraphQL con resolvers tipados.
  • Store Framework: props, ejemplos y JSONC validado para los blocks del catálogo.
  • Documentación en el editor: 391 documentos de VTEX y 10 cursos oficiales, con búsqueda por palabras clave.
  • Local y sin credenciales: todo el conocimiento va en el paquete. No llama a APIs externas ni pide claves.

Funciona con Claude Code, Claude Desktop, Cursor, VS Code, Windsurf y cualquier cliente MCP por stdio.

Documentación

Clientes MCP

Claude Code. Para compartirlo con el equipo en un repositorio, agrega --scope project al comando de Instalación: la configuración queda en .mcp.json.

Claude Desktop, en claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Cursor, en ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto). Windsurf, en ~/.codeium/windsurf/mcp_config.json:

json
{  "mcpServers": {    "vtex-io": {      "command": "npx",      "args": ["-y", "@commenteme/vtex-io-mcp"]    }  }}

VS Code, en .vscode/mcp.json:

json
{  "servers": {    "vtex-io": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@commenteme/vtex-io-mcp"]    }  }}

Otros clientes. Cualquiera con transporte stdio sirve: el comando es npx y los argumentos, -y @commenteme/vtex-io-mcp. Si prefieres instalación global, npm install -g @commenteme/vtex-io-mcp y usa vtex-io-mcp como comando.

El servidor está en el Official MCP Registry como io.github.commentemeapp/vtex-io-mcp.

Herramientas

La entrada src/index.ts conecta el servidor por stdio: el cliente inicia el proceso y habla por la entrada y salida estándar, sin abrir puerto HTTP. Las nueve herramientas se registran en src/tools/index.ts.

Apps y backend

herramientaparámetrosque hace
scaffold-vtex-appappName, vendor, builders, version?, description?Genera manifest.json y las carpetas de los builders elegidos: store, react, node, graphql, styles, messages, admin, pixel, docs.
scaffold-node-serviceappName, vendor, routes?, events?, memory?, timeout?Genera node/index.ts, service.json, clients y middlewares. Cada ruta lleva name, path, method y public; cada evento, name, sender y keys.
scaffold-graphqlappName, vendor, queries?, mutations?Genera schema.graphql y los resolvers en TypeScript, con argumentos, tipo de retorno y descripción.

Store Framework

herramientaparámetrosque hace
lookup-block-propsblockNameDevuelve descripción, props y ejemplos de un block.
add-blockblockName, blockId?, props?, children?Genera un fragmento JSONC para blocks.jsonc y valida las props contra el esquema del block.

Blocks disponibles hoy: rich-text, info-card, flex-layout.row, flex-layout.col, shelf, image.

Documentación

herramientaparámetrosque hace
search-conceptsquery, maxResults?Busca por palabras clave en los 391 documentos y devuelve resultados ordenados con extractos.
explain-conceptconceptDevuelve el documento completo de un concepto por su ID.
search-coursesquery, courseId?Busca en los cursos oficiales de VTEX IO y devuelve extractos con contexto.
lookup-vtex-apiapiReferencia REST de una API de VTEX: catalog, orders, checkout, master-data, logistics, pricing, intelligent-search, session, headless-cms, promotions, payments-gateway, license-manager.

Resources

URIcontenido
vtex://conceptsÍndice de los documentos, agrupados por prefijo.
vtex://concepts/{conceptId}Documento completo de un concepto.
vtex://coursesÍndice de los cursos, con título, descripción y número de pasos.
vtex://courses/{id}Contenido completo de un curso: onboarding, basic-blocks, layout-blocks, styles-course, store-block, service-course, calling-commerce-apis, admin, content-workflow, store-performance.

Hoja de ruta

  • Mas blocks de Store Framework: layouts (slider-layout, tab-layout, responsive-layout, stack-layout, condition-layout, modal-layout, disclosure-layout), producto (product-summary, product-images, product-price, sku-selector, buy-button), búsqueda, header, footer, minicart y login
  • Referencia de todos los builders en data/builders/ (hoy: store y node)
  • Herramientas de Store Framework: validate-blocks, create-page-template
  • Herramientas de React: generate-react-component, add-css-handles, create-graphql-query
  • Herramientas de backend: add-route-handler, add-event-handler, create-client, add-graphql-field
  • Herramientas de manifiesto: add-builder, add-dependency, add-policy, generate-manifest
  • Scaffolding de apps Admin y Pixel
  • Resources vtex://builders/{name} y vtex://api/{client} con los clients de @vtex/api
  • Prompts MCP para escenarios comunes: home, PDP, servicio REST, app fullstack, app Admin
  • Scripts de ingestión para actualizar data/ desde los cursos y los README de vtex-apps

Estructura

text
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├── resources/        # vtex://concepts y vtex://courses└── knowledge/        # carga y búsqueda sobre data/data/├── blocks/           # un JSON por block + _index.json├── builders/         # referencia por builder├── concepts/         # documentación en Markdown└── courses/          # cursos en Markdown + _index.jsonassets/               # header del README (no va en el paquete npm)

Desarrollo

bash
git clone https://github.com/commentemeapp/vtex-io-mcp.gitcd vtex-io-mcpnpm installnpm run buildnpm run inspect

npm run inspect abre el MCP Inspector sobre build/index.js para llamar cada herramienta y leer los resources sin cliente. Para probar la versión local en un cliente, apunta el comando a la build en vez de npx:

bash
claude mcp add vtex-io-local -- node /ruta/a/vtex-io-mcp/build/index.js
comandoque hace
npm run buildCompila TypeScript en build/ y marca el binario como ejecutable.
npm run devCompilación en modo watch.
npm run lintVerificación de tipos (tsc --noEmit).
npm run inspectAbre el MCP Inspector sobre el servidor compilado.

Agregar una herramienta

  1. Crea src/tools/<nombre>.ts exportando el esquema zod (<nombre>Schema) y la función que devuelve el contenido.
  2. Regístrala en src/tools/index.ts con server.tool(nombre, descripción, esquema, función). La descripción es lo que el modelo lee para decidir cuando usarla: di que hace y con que ejemplos.
  3. Si necesita conocimiento nuevo, agrega los archivos en data/ y cárgalos desde src/knowledge/.
  4. npm run build y pruébala en el Inspector.

Convenciones

  • TypeScript con módulos ESM; Prettier sin punto y coma y con comillas simples.
  • Conventional Commits.
  • El conocimiento es 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 que sale de dev y el PR va contra dev. Después de probar localmente, dev se promueve a main con merge de la rama completa (sin qa desde el 30/10/2026). El CI corre lint y build en Node 18, 20 y 22.

Para publicar, sube la versión en package.json y CHANGELOG.md y empuja un tag v*: el workflow publish.yml compila, publica en npm con provenance, crea el GitHub Release y publica el server.json en el MCP Registry. Los cambios de cada versión están en CHANGELOG.md.

Contribuir · Licencia

Abre un issue o un PR contra dev. MIT.

Hecho por commente.me · [email protected]

Source: README.md at commit 6eb200e

Tools

9

lookup-block-props

Look up the props, description, and usage examples for any VTEX IO Store Framework block (e.g. rich-text, flex-layout.row, shelf, image, info-card)

ParametersblockNamerequired

add-block

Generate a JSONC snippet for a VTEX IO block ready to paste into blocks.jsonc. Validates props against the block schema.

ParameterspropsblockIdchildrenblockNamerequired

scaffold-vtex-app

Generate a complete VTEX IO app scaffold with manifest.json and all folder structures for the selected builders (store, react, node, graphql, styles, messages, admin, pixel)

ParametersvendorrequiredappNamerequiredversionbuildersrequireddescription

scaffold-node-service

Generate a complete Node.js service scaffold for VTEX IO including index.ts, service.json, clients, and middleware handlers for specified routes and events

ParameterseventsmemoryroutesvendorrequiredappNamerequiredtimeout

scaffold-graphql

Generate a GraphQL schema and resolver files for a VTEX IO app, including schema.graphql and TypeScript resolver stubs for queries and mutations

ParametersvendorrequiredappNamerequiredqueriesmutations

search-courses

Search for a term across all VTEX IO official courses (basic-blocks, layout-blocks, styles-course, store-block, service-course, admin, calling-commerce-apis, content-workflow, store-performance). Returns excerpts with surrounding context.

ParametersqueryrequiredcourseId

explain-concept

Get full documentation for a VTEX concept by exact ID (e.g. "vtex-io-builders", "vtex-io-css-handles", "vtex-io-service-json"). Use search-concepts to find the right ID first.

Parametersconceptrequired

search-concepts

Search across 391 VTEX documentation files by keywords. Returns ranked results with excerpts. Use this to find concepts before calling explain-concept.

ParametersqueryrequiredmaxResults

lookup-vtex-api

Look up VTEX REST API reference (endpoints, auth, request/response models) for any VTEX API: catalog, orders, checkout, master-data, logistics, pricing, intelligent-search, session, headless-cms, promotions, payments-gateway, license-manager

Parametersapirequired

Version history

1
  1. v0.2.0LatestOct 30, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts