Skip to main content
Glama

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

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.

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-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, 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-mcp

O 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-mcp

GitHub 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

scaffold-vtex-app

appName, 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-service

appName, 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-graphql

appName, vendor, queries?, mutations?

Genera schema.graphql y los resolvers en TypeScript, con argumentos, tipo de retorno y descripción.

Store Framework

herramienta

parámetros

que hace

lookup-block-props

blockName

Devuelve descripción, props y ejemplos de un block.

add-block

blockName, 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

herramienta

parámetros

que hace

search-concepts

query, maxResults?

Busca por palabras clave en los 391 documentos y devuelve resultados ordenados con extractos.

explain-concept

concept

Devuelve el documento completo de un concepto por su ID.

search-courses

query, courseId?

Busca en los cursos oficiales de VTEX IO y devuelve extractos con contexto.

lookup-vtex-api

api

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

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

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 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:

claude mcp add vtex-io-local -- node /ruta/a/vtex-io-mcp/build/index.js

comando

que hace

npm run build

Compila TypeScript en build/ y marca el binario como ejecutable.

npm run dev

Compilación en modo watch.

npm run lint

Verificación de tipos (tsc --noEmit).

npm run inspect

Abre 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 · hablecon@commente.me

Available Tools

9 tools
add-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

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (lookup, add, scaffold, search, explain) with clear domain nouns. Snake_case is used uniformly.

    Tool Count5/5

    Nine tools is well-scoped for a VTEX IO development assistance server, covering reference lookup, code generation, and learning resources without unnecessary bloat.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT