vtex-io-mcp
An offline MCP server that scaffolds VTEX IO apps and backends, helps build Store Framework blocks, and searches bundled VTEX documentation — no credentials needed.
Scaffold full apps (
scaffold-vtex-app): generatemanifest.jsonplus folders for any mix ofstore,react,node,graphql,styles,messages,admin,pixel,docs.Scaffold Node services (
scaffold-node-service):node/index.ts,service.json, clients and middleware for custom HTTP routes (public or private) and event handlers, with memory/timeout settings.Scaffold GraphQL (
scaffold-graphql):schema.graphqland typed TypeScript resolvers for queries and mutations, including args, return types and descriptions.Work with Store Framework blocks (
lookup-block-props,add-block): inspect props/examples for blocks likerich-text,info-card,flex-layout.row/col,shelf,image, and generate validated JSONC snippets forblocks.jsoncwith ids, props and children.Search documentation (
search-concepts,explain-concept): keyword search across 391 VTEX docs with ranked excerpts, then pull a full document by concept ID.Search courses (
search-courses): find terms across 10 official VTEX IO courses (onboarding, blocks, styles, store block, services, admin, commerce APIs, content workflow, performance), optionally scoped to one course.Look up REST APIs (
lookup-vtex-api): reference endpoints, auth and models for catalog, orders, checkout, master-data, logistics, pricing, intelligent-search, session, headless-cms, promotions, payments-gateway and license-manager.Resources: browse
vtex://concepts,vtex://concepts/{conceptId},vtex://courses,vtex://courses/{id}.Local and credential-free: runs over stdio, knowledge is read-only inside the package, no external API calls.
Provides tools for developing VTEX IO apps, including scaffolding apps with various builders (store, react, node, graphql, admin, etc.), generating Node services and GraphQL schemas, looking up Store Framework block props, adding blocks to blocks.jsonc, and searching VTEX documentation and official courses.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vtex-io-mcp What props does the product-summary block accept?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

vtex-io-mcp
Servidor MCP para desarrollar en VTEX IO: Store Framework, React, Node, GraphQL y Admin.
Instalación
claude mcp add vtex-io -- npx -y @commenteme/vtex-io-mcpEl 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.
Related MCP server: Vibe Coder MCP Server
Uso rápido
Reinicia el cliente y pide lo que necesitas. El asistente elige la herramienta:
"Crea una app VTEX IO llamada
product-reviewscon 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/:orderIdy un handler paraorder.created""Arma el esquema GraphQL con una query
productReviews(productId: ID!)y una mutationaddReview""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.jsony 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, Codex, Cursor, Gemini CLI, GitHub Copilot, 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:
{
"mcpServers": {
"vtex-io": {
"command": "npx",
"args": ["-y", "@commenteme/vtex-io-mcp"]
}
}
}VS Code, en .vscode/mcp.json:
{
"servers": {
"vtex-io": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@commenteme/vtex-io-mcp"]
}
}
}Codex, con el CLI (queda en ~/.codex/config.toml):
codex mcp add vtex-io -- npx -y @commenteme/vtex-io-mcpO a mano, en ~/.codex/config.toml o en .codex/config.toml del proyecto:
[mcp_servers.vtex-io]
command = "npx"
args = ["-y", "@commenteme/vtex-io-mcp"]Gemini CLI, con el CLI (-s user lo deja en ~/.gemini/settings.json; sin -s, en .gemini/settings.json del proyecto):
gemini mcp add -s user vtex-io npx -y @commenteme/vtex-io-mcpGitHub Copilot CLI, en ~/.copilot/mcp-config.json o en .mcp.json del proyecto, con el mismo JSON de mcpServers de arriba. En VS Code, Copilot usa el .vscode/mcp.json.
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
herramienta | parámetros | que hace |
|
| Genera |
|
| Genera |
|
| Genera |
Store Framework
herramienta | parámetros | que hace |
|
| Devuelve descripción, props y ejemplos de un block. |
|
| Genera un fragmento JSONC para |
Blocks disponibles hoy: rich-text, info-card, flex-layout.row, flex-layout.col, shelf, image.
Documentación
herramienta | parámetros | que hace |
|
| Busca por palabras clave en los 391 documentos y devuelve resultados ordenados con extractos. |
|
| Devuelve el documento completo de un concepto por su ID. |
|
| Busca en los cursos oficiales de VTEX IO y devuelve extractos con contexto. |
|
| Referencia REST de una API de VTEX: catalog, orders, checkout, master-data, logistics, pricing, intelligent-search, session, headless-cms, promotions, payments-gateway, license-manager. |
Resources
URI | contenido |
| Índice de los documentos, agrupados por prefijo. |
| Documento completo de un concepto. |
| Índice de los cursos, con título, descripción y número de pasos. |
| Contenido completo de un curso: |
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 loginReferencia de todos los builders en
data/builders/(hoy:storeynode)Herramientas de Store Framework:
validate-blocks,create-page-templateHerramientas de React:
generate-react-component,add-css-handles,create-graphql-queryHerramientas de backend:
add-route-handler,add-event-handler,create-client,add-graphql-fieldHerramientas de manifiesto:
add-builder,add-dependency,add-policy,generate-manifestScaffolding de apps Admin y Pixel
Resources
vtex://builders/{name}yvtex://api/{client}con los clients de@vtex/apiPrompts 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 devtex-apps
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
├── 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.json
assets/ # header del README (no va en el paquete npm)Desarrollo
git clone https://github.com/commentemeapp/vtex-io-mcp.git
cd vtex-io-mcp
npm install
npm run build
npm run inspectnpm 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:
claude mcp add vtex-io-local -- node /ruta/a/vtex-io-mcp/build/index.jscomando | que hace |
| Compila TypeScript en |
| Compilación en modo watch. |
| Verificación de tipos ( |
| Abre el MCP Inspector sobre el servidor compilado. |
Agregar una herramienta
Crea
src/tools/<nombre>.tsexportando el esquema zod (<nombre>Schema) y la función que devuelve el contenido.Regístrala en
src/tools/index.tsconserver.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.Si necesita conocimiento nuevo, agrega los archivos en
data/y cárgalos desdesrc/knowledge/.npm run buildy pruébala en el Inspector.
Convenciones
TypeScript con módulos ESM; Prettier sin punto y coma y con comillas simples.
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 · hablecon@commente.me
Available Tools
9 toolsadd-blockA
Generate a JSONC snippet for a VTEX IO block ready to paste into blocks.jsonc. Validates props against the block schema.
Inputs: blockName (required), props, blockId, children.
explain-conceptA
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.
Inputs: concept (required).
lookup-block-propsA
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)
Inputs: blockName (required).
lookup-vtex-apiA
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
Inputs: api (required).
scaffold-graphqlA
Generate a GraphQL schema and resolver files for a VTEX IO app, including schema.graphql and TypeScript resolver stubs for queries and mutations
Inputs: vendor (required), appName (required), queries, mutations.
scaffold-node-serviceB
Generate a complete Node.js service scaffold for VTEX IO including index.ts, service.json, clients, and middleware handlers for specified routes and events
Inputs: vendor (required), appName (required), events, memory, +2 more.
scaffold-vtex-appB
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)
Inputs: vendor (required), appName (required), builders (required), version, +1 more.
search-conceptsA
Search across 391 VTEX documentation files by keywords. Returns ranked results with excerpts. Use this to find concepts before calling explain-concept.
Inputs: query (required), maxResults.
search-coursesA
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.
Inputs: query (required), courseId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: lookups for blocks vs APIs, separate scaffold generators for app, node, and GraphQL, and distinct search/explain tools for courses vs concepts. No two tools overlap in function.
All tool names follow a consistent verb_noun pattern (lookup, add, scaffold, search, explain) with clear domain nouns. Snake_case is used uniformly.
Nine tools is well-scoped for a VTEX IO development assistance server, covering reference lookup, code generation, and learning resources without unnecessary bloat.
The surface covers core workflows: discovering blocks/APIs, generating scaffolds, and accessing documentation. Minor gaps exist such as no tool for editing existing configurations or deploying, but these are not essential to the server's purpose.
Maintenance
Related MCP Connectors
Build, validate, test-run and publish AIOS workflows from Claude Code, Codex, Cursor or VS Code.
Tailor Platform for AI assistants: search, list and read the platform documentation.
Find, write, publish and check pages and API references in your DeveloperHub docs from an AI client
Search, read and install agent-ready React components, screens and blocks for AI products.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides AI-powered UI design, repo intelligence, and frontend code generation tools, enabling assistants to scaffold projects, generate and modify UI components, manage design tokens, and analyze repositories.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to research topics, analyze codebases, generate requirements and user stories, scaffold starter projects, and run multi-step development workflows through natural language.42 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to research topics, generate product requirements and user stories, map codebases, curate context, scaffold full-stack starter projects, and run multi-step development workflows.42 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables developers using agentic AI tools to scaffold applications and integration cards, retrieve API references and best-practice guidelines, inspect project metadata, validate manifests, and detect and fix framework-specific code issues.547 npmMIT