VTEX IO MCP

vtex-io-mcp

用于在 VTEX IO 中开发的 MCP 服务：Store Framework、React、Node、GraphQL 和 Admin。

安装

claude mcp add vtex-io -- npx -y vtex-io-mcp

MCP 客户端会通过 npx 运行服务，因此无需安装任何内容。需要 Node >= 18。对于 Claude Desktop、Cursor、VS Code 和 Windsurf，请参阅客户端 MCP。

快速上手

重启客户端，然后提出你的需求。助手会选择相应的工具：

• “创建一个名为 product-reviews 的 VTEX IO 应用，使用 react、node、graphql 和 store builders”
• “flex-layout.row 接受哪些 props？给我一个包含两列的示例”
• “生成一个 Node 服务，包含公开路由 GET /_v/order/:orderId，以及用于 order.created 的处理程序”
• “构建 GraphQL 架构，包含查询 productReviews(productId: ID!) 和 mutation addReview”
• “在文档中搜索 CSS Handles 的工作原理”
• “Master Data API 有哪些端点？”

包含内容

• VTEX IO 应用脚手架：为任意 builder 组合生成 manifest.json 和文件夹。
• 开箱即用的后端：Node 服务，包含 service.json、clients、HTTP 路由和事件处理程序；GraphQL 架构包含类型化 resolvers。
• Store Framework：目录中各个 block 的 props、示例和经过验证的 JSONC。
• 编辑器中的文档：391 篇 VTEX 文档和 10 门官方课程，可按关键词搜索。
• 本地运行，无需凭据：所有知识都包含在软件包中。不会调用外部 API，也不会要求提供密钥。

适用于 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf，以及任何使用 stdio 的 MCP 客户端。

文档

客户端 MCP

Claude Code。 要在仓库中与团队共享，请在安装命令中添加 --scope project：配置将保存在 .mcp.json 中。

Claude Desktop，配置文件为 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。Cursor，配置文件为 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）。Windsurf，配置文件为 ~/.codeium/windsurf/mcp_config.json：

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

VS Code，配置文件为 .vscode/mcp.json：

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

其他客户端。 任何支持 stdio 传输的客户端都可以使用：命令为 npx，参数为 -y vtex-io-mcp。如果倾向于全局安装，请运行 npm install -g vtex-io-mcp，并将 vtex-io-mcp 用作命令。

此服务已作为 io.github.zeluizr/vtex-io-mcp 收录在 Official MCP Registry 中。

工具

入口文件 src/index.ts 通过 stdio 连接服务：客户端启动进程，并通过标准输入和标准输出通信，无需打开 HTTP 端口。九个工具在 src/tools/index.ts 中注册。

应用与后端

工具	参数	作用
scaffold-vtex-app	appName、vendor、builders、version?、description?	生成 manifest.json 和所选 builder 的文件夹：store、react、node、graphql、styles、messages、admin、pixel、docs。
scaffold-node-service	appName、vendor、routes?、events?、memory?、timeout?	生成 node/index.ts、service.json、客户端和中间件。每条路由包含 name、path、method 和 public；每个事件包含 name、sender 和 keys。
scaffold-graphql	appName、vendor、queries?、mutations?	生成 schema.graphql 和 TypeScript resolvers，包含参数、返回类型和描述。

Store Framework

工具	参数	作用
lookup-block-props	blockName	返回 block 的描述、props 和示例。
add-block	blockName、blockId?、props?、children?	为 blocks.jsonc 生成 JSONC 片段，并根据 block 的 schema 验证 props。

当前可用的 block：rich-text、info-card、flex-layout.row、flex-layout.col、shelf、image。

文档

工具	参数	作用
search-concepts	query、maxResults?	在 391 篇文档中按关键词搜索，并返回按相关性排序、附带摘录的结果。
explain-concept	concept	根据概念 ID 返回完整文档。
search-courses	query、courseId?	在 VTEX IO 官方课程中搜索，并返回附带上下文的摘录。
lookup-vtex-api	api	VTEX API 的 REST 参考：catalog、orders、checkout、master-data、logistics、pricing、intelligent-search、session、headless-cms、promotions、payments-gateway、license-manager。

资源

URI	内容
vtex://concepts	按前缀分组的文档索引。
vtex://concepts/{conceptId}	概念的完整文档。
vtex://courses	课程索引，包含标题、描述和步骤数。
vtex://courses/{id}	课程的完整内容：onboarding、basic-blocks、layout-blocks、styles-course、store-block、service-course、calling-commerce-apis、admin、content-workflow、store-performance。

路线图

• 更多 Store Framework block：布局（slider-layout、tab-layout、responsive-layout、stack-layout、condition-layout、modal-layout、disclosure-layout）、产品（product-summary、product-images、product-price、sku-selector、buy-button）、搜索、header、footer、迷你购物车和登录
• data/builders/ 中所有 builder 的参考资料（当前：store 和 node）
• Store Framework 工具：validate-blocks、create-page-template
• React 工具：generate-react-component、add-css-handles、create-graphql-query
• 后端工具：add-route-handler、add-event-handler、create-client、add-graphql-field
• manifest 工具：add-builder、add-dependency、add-policy、generate-manifest
• Admin 和 Pixel 应用脚手架
• Resources vtex://builders/{name} 和 vtex://api/{client}，包含 @vtex/api 的客户端
• 面向常见场景的 MCP 提示词：主页、PDP、REST 服务、全栈应用、Admin 应用
• 用于从课程和 vtex-apps README 更新 data/ 的摄取脚本

结构

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)

开发

git clone https://github.com/zeluizr/vtex-io-mcp.git
cd vtex-io-mcp
npm install
npm run build
npm run inspect

npm run inspect 会在 build/index.js 上打开 MCP Inspector，无需客户端即可调用每个工具并读取资源。要在客户端中测试本地版本，请将命令指向构建产物，而不是 npx：

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

命令	作用
npm run build	将 TypeScript 编译到 build/，并将二进制文件标记为可执行。
npm run dev	以 watch 模式编译。
npm run lint	类型检查（tsc --noEmit）。
npm run inspect	在已编译的服务上打开 MCP Inspector。

添加工具

1. 创建 src/tools/<nombre>.ts，导出 zod 模式（<nombre>Schema）和用于返回内容的函数。
2. 在 src/tools/index.ts 中通过 server.tool(nombre, descripción, esquema, función) 注册。模型会读取描述来决定何时使用工具：说明工具的作用，并提供使用示例。
3. 如果需要新的知识，请将文件添加到 data/，并从 src/knowledge/ 加载。
4. 运行 npm run build，并在 Inspector 中测试。

约定

• 使用 TypeScript ESM 模块；Prettier 不加分号，使用单引号。
• Conventional Commits。
• 知识仅在运行时以只读方式使用：不会写入磁盘，也不会下载。

分支与发布

工作从 dev 分支创建新分支，PR 合并到 dev。之后依次合并到 qa 和（测试通过后）main，始终合并完整分支。CI 会在 Node 18、20 和 22 上运行 lint 和 build。

要发布，请更新 package.json 和 CHANGELOG.md 中的版本，并推送一个 v* 标签：publish.yml 工作流会进行编译、通过 provenance 发布到 npm、创建 GitHub Release，并将 server.json 发布到 MCP Registry。每个版本的更改记录在 CHANGELOG.md 中。

贡献 · 许可证

请提交 issue 或向 dev 提交 PR。 MIT。

---

由 commente.me 制作 · [email protected]