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 クライアントをご覧ください。

クイックスタート

クライアントを再起動して、必要なことを依頼してください。アシスタントがツールを選択します。

• "react、node、graphql、store の builders を使って、product-reviews という名前の VTEX IO アプリを作成して"
• "flex-layout.row はどのような props を受け取りますか？2 カラムの例を見せて"
• "公開ルート GET /_v/order/:orderId と order.created 用のハンドラーを備えた Node サービスを生成して"
• "productReviews(productId: ID!) クエリと addReview mutation を含む GraphQL スキーマを作成して"
• "CSS Handles の仕組みをドキュメントで調べて"
• "Master Data API にはどのようなエンドポイントがありますか？"

含まれる機能

• VTEX IO アプリのスキャフォールディング：任意の builders の組み合わせに対応する manifest.json とフォルダーを生成します。
• すぐに使えるバックエンド：service.json、clients、HTTP ルート、イベントハンドラーを備えた Node サービスと、型付き resolvers を備えた GraphQL スキーマ。
• Store Framework：カタログの blocks 用の props、例、検証済み JSONC。
• エディター内のドキュメント：VTEX のドキュメント 391 件と公式コース 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 として公式 MCP レジストリに登録されています。

ツール

エントリーポイントの src/index.ts は、stdio 経由でサーバーに接続します。クライアントがプロセスを起動し、HTTP ポートを開かずに標準入力と標準出力で通信します。9 つのツールは src/tools/index.ts に登録されています。

アプリとバックエンド

ツール	パラメーター	動作
scaffold-vtex-app	appName, vendor, builders, version?, description?	manifest.json と、選択した builders のフォルダー（store、react、node、graphql、styles、messages、admin、pixel、docs）を生成します。
scaffold-node-service	appName, vendor, routes?, events?, memory?, timeout?	node/index.ts、service.json、clients、middlewares を生成します。各ルートには 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 フラグメントを生成し、props を block のスキーマに照らして検証します。

現在利用できる Blocks：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 の Blocks を追加：レイアウト（slider-layout、tab-layout、responsive-layout、stack-layout、condition-layout、modal-layout、disclosure-layout）、商品（product-summary、product-images、product-price、sku-selector、buy-button）、検索、ヘッダー、フッター、ミニカート、ログイン
• data/builders/ 内の全 builders のリファレンス（現在は 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
• マニフェストツール：add-builder、add-dependency、add-policy、generate-manifest
• Admin および Pixel アプリのスキャフォールディング
• @vtex/api の clients を使う Resources vtex://builders/{name} と vtex://api/{client}
• 一般的なシナリオ向けの 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	ウォッチモードでコンパイルします。
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 でテストします。

規約

• ESM モジュールを使用した TypeScript を使います。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 を作成して、MCP Registry に server.json を公開します。各バージョンの変更内容は CHANGELOG.md に記載されています。

貢献・ライセンス

issue を作成するか、dev に対して PR を作成してください。 MIT。

---

commente.me 制作 · [email protected]