Shopify MCP Proxy & Mock Server (ShopifyMCPMockShop)

Shopify MCP Proxy & Mock Server（ShopifyMCPMockShop）

このプロジェクトは、Shopify の Storefront API へのインテリジェントなブリッジ兼プロキシとして機能する Model Context Protocol（MCP）サーバーを実装しています。実際のストアの認証情報がなくても安全に開発やテストを行えるよう、mock.shop を独自にサポートしています。

サーバーは 標準入力／出力（stdio） で通信するため、Claude Desktop や Cursor などのクライアントとのローカル統合に適しています。

開発の動機

汎用 AI 開発ツールや既製の MCP サーバーは、多くの機能をうたっていても、透明性、安全機構（明示的な ToolAnnotations など）、安定性、または制御された開発やテストに必要な特定の機能が不足していることがあります。特に、急速に進化する Shopify のような API を扱う場合にその傾向があります。

このプロジェクトは、次のような信頼性の高いオープンソースの Shopify MCP サーバーが必要だったことから生まれました。

• 安全性を優先： mock.shop と緊密に統合し、ライブストアに影響を与えることなく、リスクのない開発と正確なテストを可能にする重要なサンドボックスを提供します。
• 透明性と制御を重視： 使用される API バージョンやアクションが及ぼす可能性のある影響（readonly、destructive などの ToolAnnotations による）も含め、Shopify API とのやり取りがどのように行われるかを、開発者（およびその AI パートナー）が正確に把握できるようにします。
• 特定のニーズに対応： 情報提供に特化したツールやクローズドソースの商用製品では満たされないニーズに応え、Shopify の開発ワークフローに合わせた安全な実行エンジンを提供します。

このプロジェクトの目標は、意図的なガードレールと明確な運用コンテキストを備えたツールを利用していることを確認しながら、開発者が Shopify 関連のタスクで AI の支援を安心して活用できるようにすることです。

アーキテクチャ

システム概要

ShopifyMCPMockShop サーバーは、MCP プロトコルの処理と Shopify API の統合を明確に分離する、多層アーキテクチャを採用しています。

データフロー

このシーケンス図は、ユーザーの操作から API の応答まで、一般的なリクエストがシステムを通過する流れを示しています。

ツール階層

MCP サーバーは、Shopify のリソースタイプごとに整理された包括的なツールを公開します。

ローカルでのセットアップと実行

このサーバーは、スタンドアロンの Node.js スクリプトです。

1. リポジトリをクローンします：

   git clone https://github.com/ramakay/ShopifyMockMCP.git
   cd ShopifyMCPMockShop
   

2. 依存関係をインストールします：

   npm install
   

3. サーバーをビルドします：

   npm run build
   

   これにより、TypeScript コードが dist ディレクトリ内の JavaScript（dist/server.js）にコンパイルされます。

4. 環境を設定します（任意 — 実際のストアを使用する場合）：

   • mock.shop の代わりに実際の Shopify ストアへ接続する場合は、サーバーを実行する前に次の環境変数を設定してください（たとえば、export を使用するか、クライアントが読み込む .env ファイルに設定します）。
     • SHOPIFY_STORE：ストアのドメイン（例：your-store.myshopify.com）。実際のストアを使用する場合は必須です。
     • SHOPIFY_ACCESS_TOKEN：Storefront API のアクセストークン。実際のストアを使用する場合は必須です。
     • SHOPIFY_VERSION：特定の Storefront API バージョンを指定する場合に設定します（例：2025-04）。指定しない場合は、最新の安定版が使用されます。
   • 注： mock.shop（SHOPIFY_STORE が設定されていない場合のデフォルト）を使用する際、環境変数は不要です。
   • 注： Admin API の機能は現在無効ですが、今後のアップデートで対応する予定です。設定変数（USE_ADMIN_API、ADMIN_ACCESS_TOKEN、ADMIN_VERSION）は現在使用されません。

5. 実行： このサーバーは、stdio 設定を使用して MCP クライアント（Claude Desktop や Cursor など）から自動的に起動されることを想定しています。npm run start を手動で実行する必要はありません。詳しくは以下の「使用方法」セクションを参照してください。

Cursor または Claude Desktop での使用

MCP クライアント（Cursor、Claude Desktop）を設定し、stdio 経由でこのサーバーを起動します。各設定ファイルに次のようなエントリを追加してください。

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json（または同様のファイル）

{
  "mcpServers": {
    // ... other servers ...
    "shopify-mcp": {
      "command": "node",
      "args": [
        "/full/path/to/ShopifyMCPMockShop/dist/server.js"
      ],
      "env": {
        // Only needed if connecting to a REAL store:
        // "SHOPIFY_STORE": "your-store.myshopify.com",
        // "SHOPIFY_ACCESS_TOKEN": "your-storefront-token",
        // "SHOPIFY_VERSION": "2025-04"
      },
      "disabled": false,
      "alwaysAllow": []
    }
    // ... other servers ...
  }
}

重要：

• /full/path/to/ShopifyMCPMockShop を、リポジトリをクローンした場所の絶対パスに置き換えてください。
• 実際のストアに接続する場合に限り、env 変数を含めてください。
• 設定を変更した後、クライアント（Cursor／Claude Desktop）を再起動してください。

利用可能なツール

この MCP サーバーは現在、Shopify Storefront API を操作するためのツールを提供しています。

ツール名	説明	API
getShopInfo	ショップの基本情報（名前、説明、通貨）を取得します。	Storefront
getProductById	指定した ID の商品を取得します。includeImages が true の場合、JSON の詳細情報と最初の画像（75px）を base64 の ImageContentBlock として返します。	Storefront
findProducts	ページネーション／並べ替えに対応して商品を検索／フィルタリングします。	Storefront
getCollectionById	指定した ID のコレクションを取得します。オプションで商品を含めることもできます。	Storefront
findCollections	ページネーション／並べ替えに対応してコレクションを検索／フィルタリングします。	Storefront
cartCreate	新しいショッピングカートを作成します。	Storefront
cartLinesAdd	既存のショッピングカートに商品明細を追加します。	Storefront
cartLinesUpdate	既存のショッピングカートの商品明細（数量など）を更新します。	Storefront
cartLinesRemove	既存のショッピングカートから商品明細を削除します。	Storefront
getCart	ID を指定して、既存のショッピングカートの詳細を取得します。	Storefront

（注：getCustomerById や createProduct などの Admin API ツールは今後の更新で追加する予定で、現在は無効になっています。）

サーバーの機能を確認する

サーバーが正しくビルドされていることを確認し、MCP クライアントに通知する正確な機能を確認するには、package.json で定義されている inspect スクリプトを使用できます。

# Ensure you have run 'npm install' and 'npm run build' first
# Run this from the project root directory
npm run inspect

このコマンドはコンパイル済みのサーバー（node dist/server.js）を実行し、標準入力経由で標準の mcp/capabilities リクエストを送信します。サーバーはこのリクエストを処理し、機能（利用可能なツール、リソーステンプレート、サーバー情報を含む）を JSON レスポンスとして標準出力に出力するため、ターミナルで確認できます。これは、デバッグやサーバーが通知する機能の確認に役立ちます。

既知の問題

• インライン画像のレンダリング： Claude Desktop や Cursor などのクライアントでは現在、ImageContentBlock（includeImages が true の場合に getProductById が使用）がメインのテキストレスポンス内ではなく、その下の別の UI ブロックに表示されます。テキストブロック内で Markdown または HTML の画像タグを使用する方法も試しましたが、これらのクライアントではインライン表示されませんでした。

今後の予定

• Admin API ツール（getCustomerById、createProduct など）を再統合してテストする。
• Admin API の認証情報（USE_ADMIN_API、ADMIN_ACCESS_TOKEN、ADMIN_VERSION）の設定オプションを追加する。
• テスト用フレームワークを実装する。
• クライアントのサポートが改善された場合に、リソースの処理方法を検討する。

ライセンス

MIT ライセンス