adobe-commerce-docs-mcp

Adobe Commerce Docs MCP サーバー

AI アシスタントから公式の Adobe Commerce / Magento ドキュメントに直接アクセスできる MCP（Model Context Protocol） サーバーです。Adobe Experience League のサイトマップをインデックス化し、AI コーディングアシスタント内からドキュメントページを検索、閲覧、読み込むためのツール、リソース、プロンプトを提供します。

---

特長

• 10 個のツール — 検索、ページの読み込み、セクションの閲覧、長いページの一部セクションの取得、関連ドキュメントの検索、コード例の抽出、ページの目次の取得、エラーの検索、複数クエリ検索、更新
• 構造化されたツール出力 — 各ツールは、人が読みやすい Markdown とともに、型付けされた structuredContent（JSON Schema の outputSchema）を返すため、クライアントは結果をプログラムから解析できます
• ツールのアノテーション — すべてのツールで readOnlyHint／openWorldHint／idempotentHint を宣言しているため、MCP クライアントは安全な読み取り専用操作で確認の手間を減らせます
• MCP リソース — セクションの読み取りごとに最大 300 件に制限された、セクションやドキュメントページ用の参照可能な commerce:// URI。コンテキストを安全に保ちます
• MCP プロンプト — トラブルシューティング、コードレビュー、アップグレード、概念の説明に使える再利用可能なワークフロー
• BM25 検索 — IDF による重み付けと文書長の正規化で関連度順に並べた結果
• 同義語の展開 — graphql で gql も、cloud で ece も、module で extension も検索されるほか、40 件以上に対応
• あいまい検索 — chekout → checkout、catlog → catalog のようなタイプミスにも対応
• スマートな切り詰め — 文の途中ではなく、見出しの境界で切り詰めます
• 即時のコールドスタート — パッケージに同梱されたサイトマップのスナップショットからインデックスを作成し、バックグラウンドで最新情報に更新します。最初のクエリへの応答時に、ライブサイトマップの取得を待つ必要はありません
• 永続キャッシュ — サイトマップ（24 時間）とページコンテンツ（7 日間）のディスクキャッシュで、再起動後も保持されます
• HTTP トランスポート — Streamable HTTP を使ったリモート／チーム向けのデプロイには --http フラグを使用
• Docker 対応 — コンテナー化したデプロイ向けのマルチステージ Dockerfile
• 設定可能 — すべての設定を環境変数で調整可能
• 設定不要 — MCP 設定に 1 行追加するだけで使えます

---

ツール

search_adobe_commerce_docs

同義語の展開とあいまい検索に対応した、BM25 順位付けの検索です。

パラメーター	型	必須	説明
query	string	はい	検索キーワード（例："graphql product query"、"checkout configuration"）
limit	number	いいえ	返す結果の最大数（1～50、デフォルト：15）
section	string	いいえ	セクションのスラッグで絞り込み（利用可能なセクションを参照）

get_doc_content

ドキュメントページの全文を、整形済みの Markdown として取得します。

パラメーター	型	必須	説明
url	string	はい	検索結果にあるドキュメントページの完全な URL

get_code_examples

ドキュメントページからコードブロックのみを抽出します。前後の文章を含まないフェンス付きコードスニペットを返すため、ページ全体を取得するよりもトークンを大幅に節約できます。

パラメーター	型	必須	説明
url	string	はい	ドキュメントページの完全な URL

get_page_toc

ページの見出し階層（目次）を取得します。ページ全体のコンテンツを取得する前に、構成を把握するのに便利です。

パラメーター	型	必須	説明
url	string	はい	ドキュメントページの完全な URL

get_doc_section

見出し名（大文字と小文字を区別せず、部分一致）を指定して、ページのセクションを1つだけ取得します。ネストされたサブ見出しも含まれます。get_doc_content でページ全体を取得すると、必要なセクションに到達する前に長いページが切り詰められてしまう場合に使用します。まず get_page_toc で見出し名を確認してください。

パラメーター	型	必須	説明
url	string	はい	ドキュメントページの完全な URL
heading	string	はい	検索する見出しテキスト（例："tunnel"、"SSH Tunnel Setup"）

get_related_docs

ドキュメントツリー内の同じセクションにある、関連ページや兄弟ページを検索します。

パラメーター	型	必須	説明
url	string	はい	ドキュメントページの完全な URL
limit	number	いいえ	関連ページの最大数（1～30、デフォルト：10）

lookup_error_code

ナレッジベースでエラーコードまたはメッセージを検索します。すぐに回答できるよう、最上位の検索結果を自動取得します。

パラメーター	型	必須	説明
error	string	はい	エラーコードまたはメッセージ（例："MDVA-43395"、"Unable to serialize value"）

multi_page_search

1回の呼び出しで複数のクエリを検索します。重複を除いた結果を返すため、複数の観点から調査する際の往復を減らせます。

パラメーター	型	必須	説明
queries	string[]	はい	検索クエリの配列（1～5件）
limit_per_query	number	いいえ	クエリごとの結果の最大数（1～20、デフォルト：5）
section	string	いいえ	すべてのクエリに適用するセクションの任意のフィルター

list_doc_sections

利用可能なすべてのドキュメントセクションとページ数を一覧表示します。パラメーターはありません。

refresh_sitemap

キャッシュされたサイトマップデータを強制的に更新し、ディスク上のページコンテンツキャッシュ（ページごとに個別にキャッシュされ、最大7日間保持されます）を消去します。これにより、以降に取得するページが古い内容ではなく最新の内容になります。パラメーターはありません。

利用可能なセクション

section パラメーターには、次のスラッグを使用します。

セクションのスラッグ	説明
commerce-admin	管理パネル、カタログ、顧客、注文、ストア設定
commerce-operations	インストール、アップグレード、設定、CLI ツール、パッチ
commerce-cloud-service	クラウドインフラストラクチャ、デプロイ、環境
commerce-on-cloud	クラウドアーキテクチャ、CLI／ブランチ、CDN と Fastly VCL、開発ツールと連携機能
commerce-merchant-services	Live Search、Product Recommendations、Payment Services
commerce-channels	Amazon Sales Channel、Channel Manager
commerce-knowledge-base	トラブルシューティング記事と既知の問題
commerce-learn	チュートリアルと動画ガイド
commerce-business-intelligence	レポートと分析

---

リソース

MCP リソースを使うと、AI クライアントはツール呼び出しを行わずに URI 経由でデータを直接参照できます。

URI	説明
commerce://sections	ページ数を含むすべてのドキュメントセクション
commerce://stats	サーバーの状態：バージョン、稼働時間、インデックスサイズ
commerce://docs/{section}	セクション内のすべてのページを参照（自動補完に対応）

---

プロンプト

MCP プロンプトは、すべての MCP クライアント（Cursor、Claude Desktop、VS Code、Windsurf など）で使用できる再利用可能なワークフローです。

プロンプト	引数	説明
troubleshoot-commerce-error	error_message	ナレッジベースを検索し、根本原因、解決策、予防策を提示します
explain-commerce-concept	topic	公式ドキュメントに基づき、コード例とベストプラクティスを交えて概念を説明します
commerce-code-review	code	公式の Commerce コーディング規約に照らして PHP／XML／JS コードをレビューします
commerce-upgrade-guide	from_version, to_version	互換性を損なう変更とロールバック計画を含むアップグレードのチェックリストを生成します

Cursor のクイックセットアップ

オプション A：自動セットアップスクリプト（Linux / macOS）

ターミナルで次のコマンドを 1 つ実行します。

bash <(curl -sS https://raw.githubusercontent.com/jigarkkarangiya/adobe-commerce-docs-mcp/main/setup-cursor.sh)

リポジトリをクローン済みの場合は、次のコマンドを実行します。

bash setup-cursor.sh

スクリプトは次の処理を行います。

• Node.js 18+ がインストールされていることを確認します
• ~/.cursor/mcp.json を作成または更新します
• Cursor を再起動するよう案内します

オプション B：手動セットアップ（すべてのプラットフォーム — 3 ステップ）

前提条件

Node.js 18+ がインストールされている必要があります。次のコマンドを実行して確認してください。

node --version

インストールされていない場合は、nodejs.org からインストールしてください。

ステップ 1：Cursor で MCP 設定を開く

1. Cursor を開きます
2. 設定（左下の歯車アイコン、または Ctrl + , / Cmd + ,）に移動します
3. 左側のサイドバーで 「MCP」 をクリックします
4. 「+ Add new MCP server」 をクリックします

ステップ 2：サーバーを追加する

ダイアログが表示されます。次のように入力します。

項目	値
名前	adobe-commerce-docs
タイプ	command
コマンド	npx -y adobe-commerce-docs-mcp

「Add」 をクリックします。

ステップ 3：確認する

MCP の一覧に adobe-commerce-docs が 緑色の点（有効）とともに表示されます。

エージェントモードで任意のチャットを開き、次のように試してください。

「Adobe Commerce のドキュメントでチェックアウトの設定を検索して」

オプション C：設定ファイルを直接編集する

MCP 設定ファイルを開く（または作成する）には、次のパスを使用します。

OS	パス
Linux	~/.cursor/mcp.json
macOS	~/.cursor/mcp.json
Windows	%USERPROFILE%\.cursor\mcp.json

次の JSON を追加します（ファイルにほかのサーバーがすでに含まれている場合は、adobe-commerce-docs ブロックを既存の mcpServers オブジェクトにマージします）。

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-docs-mcp"]
    }
  }
}

保存したら Cursor を再起動します。

---

その他のツールのセットアップ

Claude Desktop

Claude Desktop の設定に追加します。

OS	設定パス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-docs-mcp"]
    }
  }
}

VS Code / GitHub Copilot

プロジェクトルートの .vscode/mcp.json に追加します。

{
  "servers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-docs-mcp"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-docs-mcp"]
    }
  }
}

---

使用例

接続したら、任意の AI チャットで自然に質問するだけです。

質問の例	実行される処理
「Adobe Commerce のドキュメントで GraphQL の商品クエリを検索して」	同義語展開を用いた BM25 ランク付け検索
「支払い方法のドキュメントページを取得して」	ページ全体をクリーンな Markdown として取得
「DI ドキュメントからコード例だけを表示して」	コードブロックのみを抽出します（トークンを節約）
「チェックアウトページの目次は？」	見出しの階層を返します
「この Cloud デプロイメントドキュメントに関連するページを見つけて」	ドキュメントツリー内の同階層のページを返します
「エラー MDVA-43395 を調べて」	ナレッジベースを検索し、最上位の検索結果を自動取得します
「REST API、GraphQL ミューテーション、Webhook を検索して」	1 回の呼び出しで複数のクエリを検索します
「カタログ価格ルールについて Commerce では何と説明されていますか？」	検索後、最も一致するページを読み込みます
「2.4.6 から 2.4.7 へのアップグレードを手伝って」	アップグレードガイドのプロンプトワークフローを使用します

---

仕組み

┌─────────────┐     ┌──────────────────────────┐     ┌─────────────────────────┐
│  AI Client   │────▶│  MCP Server (v2.0)        │────▶│  Adobe Experience League │
│  (Cursor,    │◀────│                          │◀────│  sitemap.xml + .md pages │
│   Claude,    │     │  10 Tools                │     │                         │
│   VS Code)   │     │  3 Resources             │     └─────────────────────────┘
│              │     │  4 Prompts               │
└─────────────┘     └──────────────────────────┘
                      │
                      ├─ BM25 search with synonym expansion + fuzzy matching
                      ├─ Pre-warms sitemap on startup
                      ├─ Fetches .md endpoints (native markdown)
                      ├─ Memory LRU cache: 100 pages, 1h TTL
                      ├─ Disk page cache: 7-day TTL (survives restarts)
                      └─ Disk sitemap cache: 24h TTL

1. 起動時に、パッケージに同梱されたサイトマップのスナップショット（npm 公開のたびに新たに生成）から即座にインデックスを作成し、その後バックグラウンドで Adobe Experience League から最新データを取得します。これにより、約 77MB のサイトマップをリアルタイムで取得する間、処理がブロックされることなくすぐに検索でき、数秒以内に完全な最新データへ自動修正されます。有効な 24 時間のディスクキャッシュがある場合は、この処理を省略してディスクから直接読み込みます。
2. BM25 スコアリング、同義語マッピング、ドキュメント頻度の統計を使用して転置インデックスを構築します
3. 検索時には、用語を同義語で展開し、誤字にはファジーマッチングで対応します
4. ページの内容を要求すると、ネイティブの .md 版を取得します（クリーンな Markdown のため、HTML の解析は不要です）
5. .md が利用できない場合は、HTML の取得と変換にフォールバックします
6. スマートな切り詰めにより、文の途中ではなく見出しの境界で切り詰めます
7. ページはディスク（7 日間）とメモリ（LRU、100 ページ、1 時間）にキャッシュされます

---

HTTP トランスポート

チーム／リモート環境にデプロイする場合は、サーバーを HTTP モードで実行します。

npm run start:http
# or
npx adobe-commerce-docs-mcp --http

これにより、ポート 3000 で Streamable HTTP サーバーが起動します（PORT 環境変数で変更できます）。

Docker

docker build -t adobe-commerce-docs-mcp .
docker run -p 3000:3000 adobe-commerce-docs-mcp

---

設定

すべての設定は環境変数で変更できます。

変数	デフォルト	説明
SITEMAP_URL	Adobe Experience League URL	サイトマップの取得元を上書きします
CACHE_DIR	~/.cache/adobe-commerce-docs-mcp	キャッシュディレクトリのパス
SITEMAP_CACHE_TTL_MS	86400000（24 時間）	サイトマップのキャッシュ有効期間
PAGE_CACHE_MAX	100	メモリ内 LRU キャッシュに保持するページの最大数
PAGE_CACHE_TTL_MS	3600000（1 時間）	メモリキャッシュ内のページの有効期間
PAGE_DISK_CACHE_TTL_MS	604800000（7 日間）	ディスクキャッシュ内のページの有効期間
MAX_CONTENT_LENGTH	15000	ページの応答あたりの最大文字数
MAX_CONCURRENT_FETCHES	5	サイトマップの同時取得数
PORT	3000	HTTP サーバーのポート（--http 使用時）
LOG_LEVEL	info	ログレベル：debug、info、warn、error

---

トラブルシューティング

MCP サーバーの起動に失敗する

• Node.js 18 以降がインストールされていることを確認します：node --version
• ターミナルでコマンドを手動で実行してテストします：

  npx -y adobe-commerce-docs-mcp
  

• 社内プロキシを使用している場合は、npm がレジストリにアクセスできることを確認します：

  npm config set registry https://registry.npmjs.org/
  

Cursor に緑色の点が表示されない

• MCP の設定で、サーバー名の横にある更新アイコンをクリックします
• Cursor を完全に再起動します
• Cursor の出力パネルでエラーメッセージを確認します

検索結果が「見つかりません」と表示される

• サイトマップは初回使用時に読み込まれます（数秒かかります）。少し待ってからもう一度お試しください。
• より広いキーワードを使用します。たとえば、"checkout multishipping step 3" ではなく "checkout" を使用します。
• 同義語の展開により、多くの別名が自動的に処理されます（gql → graphql、ece → cloud など）。
• 最新のデータを再読み込みするよう AI に refresh_sitemap の実行を依頼します

初回の応答が遅い

• 最初のクエリではサイトマップの読み込みが行われます（約 2～5 秒）。以降のクエリはすぐに応答します。
• サイトマップは 24 時間、ページコンテンツは 7 日間ディスクにキャッシュされるため、再起動後の読み込みは速くなります。

---

開発

ソースから実行

git clone https://github.com/jigarkkarangiya/adobe-commerce-docs-mcp.git
cd adobe-commerce-docs-mcp
npm install
npm run build
npm start

開発モード（自動再読み込み）

npm run dev          # stdio transport
npm run dev:http     # HTTP transport

テストの実行

npm test

プロジェクト構成

adobe-commerce-docs-mcp/
├── src/
│   ├── index.ts          # MCP server: tools, resources, prompts, transport
│   ├── sitemap.ts        # Sitemap loading, BM25 search, synonyms, fuzzy matching
│   ├── content.ts        # Page fetching, markdown/HTML parsing, structured extraction
│   └── config.ts         # Environment variable configuration
├── tests/
│   ├── search.test.ts    # Search, Levenshtein, synonym expansion tests
│   └── content.test.ts   # Content extraction, TOC, smart truncation tests
├── dist/                 # Compiled JS (generated by `npm run build`)
├── .cursor/
│   ├── rules/            # Cursor auto-apply rules for this MCP
│   └── prompts/          # Cursor slash commands (/commerce-search, etc.)
├── .github/workflows/    # CI/CD: build, test, publish
├── Dockerfile            # Multi-stage Docker build for HTTP deployment
├── setup-cursor.sh       # One-command Cursor setup script
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

コントリビューション

1. リポジトリをフォークします
2. ブランチを作成します：git checkout -b my-feature
3. 変更を加えます
4. ビルドとテストを実行します：npm run build && npm test
5. コミットしてプッシュします
6. Pull Request を作成します

---

要件

• Node.js 18 以降

---

この MCP を見つける

レジストリ	リンク
npm	npmjs.com/package/adobe-commerce-docs-mcp
GitHub	github.com/jigarkkarangiya/adobe-commerce-docs-mcp
Official MCP Registry	io.github.jigarkkarangiya/adobe-commerce-docs-mcp — server.json を参照
Cursor	cursor.directory — adobe-commerce-docs で検索
mcp.so	mcp.so — adobe-commerce-docs で検索
Smithery	smithery.ai — adobe-commerce-docs で検索
Glama	glama.ai/mcp/servers — adobe commerce で検索

関連する MCP

• adobe-commerce-dev-docs-mcp — Adobe Commerce の開発者向けドキュメント（developer.adobe.com/commerce）
• aem-live-docs-mcp — AEM ／ Edge Delivery Services のドキュメント（aem.live）
• adobe-app-builder-docs-mcp — Adobe App Builder — サーバーレス、I/O Runtime、Commerce の拡張性
• adobe-api-mesh-docs-mcp — Adobe API Mesh — GraphQL ゲートウェイとソースハンドラー
• adobe-commerce-kb-mcp — Adobe Commerce サポートナレッジベース — トラブルシューティングとパッチ
• adobe-io-events-docs-mcp — Adobe I/O Events — Webhook、ジャーナリング、イベントプロバイダー

---

変更履歴

各リリースの新機能、修正、変更、改善については、CHANGELOG.md をご覧ください。

---

ライセンス

ソース公開 — All Rights Reserved

透明性と評価を目的として、ソースを公開しています。個人的、教育的、または社内での非営利目的に限り、変更を加えずにパッケージをインストールして実行できます。事前の書面による許可なく、変更、フォーク、再配布、商用利用を行うことはできません。利用条件の詳細については、LICENSE をご覧ください。

© 2026 Jigar Karangiya · LinkedIn