Magento Graphql Docs MCP

🚀 Magento 2 GraphQL Documentation MCP Server

このローカルのSTDIO MCPサーバーは、ローカルのMarkdownファイルからMagento 2 GraphQL APIのドキュメントを検索および取得するツールを提供します。

📖 セットアップが初めてですか？ SETUP.mdを参照して、ステップバイステップのクイックスタートガイドを確認してください。

✨ 主な機能

• ドキュメント検索：350ページ以上のGraphQLドキュメントに対する全文検索
• 完全なドキュメントの取得：メタデータ付きの完全なドキュメントを取得
• GraphQL要素の検索：クエリ、ミューテーション、タイプ、インターフェースを検索
• 要素の詳細を取得：サンプル付きの完全なスキーマ要素定義を表示
• カテゴリの閲覧：ドキュメントの階層（スキーマ、開発、使用方法、チュートリアル）をナビゲート
• チュートリアルのアクセス：ステップバイステップの学習パス（例：チェックアウトワークフロー）を取得
• コード例の検索：GraphQL、JSON、JavaScriptの実行可能なコード例を検索
• 関連ドキュメントの発見：関連するドキュメントを自動的に検索
• オフライン操作：ローカルのMarkdownファイルを使用して完全にオフラインで動作
• 高速起動：ドキュメントファイルが変更された場合のみ再インデックス化（5秒未満）

🔧 仕組み

1. 解析：起動時に、サーバーはYAMLフロントマター付きのMarkdownファイルを解析します。
2. 抽出：メタデータ、コードブロック、およびGraphQLスキーマ要素を抽出します。
3. インデックス化：FTS5全文検索インデックス付きでSQLiteにデータを格納します。
4. 検索：ドキュメント、コード、およびスキーマに対するインテリジェントな検索を提供します。

🚀 クイックスタート

ステップ1：ドキュメントリポジトリのクローン

MCPサーバーは、Adobe Commerce GraphQLドキュメントのMarkdownファイルにアクセスする必要があります。公式リポジトリをクローンします。

# commerce-webapiリポジトリをクローン
git clone https://github.com/AdobeDocs/commerce-webapi.git

# GraphQLドキュメントは以下の場所にあります。
# commerce-webapi/src/pages/graphql/

ステップ2：ドキュメントパスの設定

ドキュメントパスを構成するには、2つのオプションがあります。

オプションA：シンボリックリンクの使用（推奨） プロジェクトディレクトリにシンボリックリンクを作成します。

cd magento-graphql-docs-mcp
ln -s /path/to/commerce-webapi/src/pages/graphql data

オプションB：環境変数の使用 MAGENTO_GRAPHQL_DOCS_PATH環境変数を設定します。

export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"

これを永続的にするには、シェルプロファイル（~/.bashrc、~/.zshrcなど）に追加します。

echo 'export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"' >> ~/.zshrc
source ~/.zshrc

ステップ3：ドキュメントアクセスの確認

ドキュメントパスにアクセスできることを確認します。

# シンボリックリンクを使用している場合
ls -la data/

# 環境変数を使用している場合
ls -la $MAGENTO_GRAPHQL_DOCS_PATH/

# 以下のようなファイルが表示されるはずです。
# - index.md
# - release-notes.md
# - schema/ (ディレクトリ)
# - tutorials/ (ディレクトリ)
# - develop/ (ディレクトリ)

ステップ4：MCPサーバーのインストール

cd magento-graphql-docs-mcp
pip install -e .

（オプション）Dockerでのビルドと実行

Dockerを使用する場合は、イメージをビルドし、ドキュメントパスを/dataにマウントします（またはMAGENTO_GRAPHQL_DOCS_PATHを別の場所に設定します）。

docker build -t magento-graphql-docs-mcp -f docker/Dockerfile .
docker run --rm -it \
  -v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \
  magento-graphql-docs-mcp

自動取得のフォールバック：ドキュメントをマウントしない場合、コンテナは起動時にそれらをクローンできます。これはMAGENTO_GRAPHQL_DOCS_AUTO_FETCHで制御します（デフォルト：true）。

# コンテナにドキュメントをクローンさせる（/tmp/commerce-webapi/src/pages/graphqlを使用）
docker run --rm -it magento-graphql-docs-mcp

# 自動取得を無効にする；マウントまたは事前設定されたMAGENTO_GRAPHQL_DOCS_PATHが必要
docker run --rm -it \
  -e MAGENTO_GRAPHQL_DOCS_AUTO_FETCH=false \
  -v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \
  magento-graphql-docs-mcp

ホスト側のDockerラッパー（STDIO）

提供されているラッパーを使用して、コンテナを実行し、MCPクライアントのSTDIN/STDOUTを転送します（TTYは追加されません）。

# リポジトリのルートから
./run-docker-mcp.sh

これが行うこと：

• magento-graphql-docs-mcpイメージが存在しない場合は自動的にビルドします。
• MAGENTO_GRAPHQL_DOCS_PATH（または./data）が存在する場合は/dataにマウントします；そうでない場合は自動取得に依存します。
• MCPクライアントのためにSTDIOをクリーンに保ちます；起動時に接続手順を表示します。
• MAGENTO_GRAPHQL_DOCS_AUTO_FETCHを尊重します（マウントされたパスが必要な場合はfalseに設定します）。

MCPクライアントコマンドをラッパーパスに設定します。例えばClaude Desktopの設定：

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "/absolute/path/to/run-docker-mcp.sh"
    }
  }
}

VS CodeのMCP設定

Dockerラッパーを使用したVS CodeのMCP設定の例：

{
  "servers": {
    "magento-webapi-docs": {
      "type": "stdio",
      "command": "/absolute/path/to/run-docker-mcp.sh"
    }
  }
}

サーバーエントリを追加した後、VS CodeのMCP/Toolsパネルを開き、magento-webapi-docsの「Start」を押して、コンテナベースのSTDIOサーバーを起動します。

Docker Compose（HTTP/SSE）

提供されているdocker-compose.ymlを使用して、HTTP/SSEでサーバーを実行します。

docker compose up --build

これはdocker/Dockerfileからビルドし、8765:8765をマッピングし、MAGENTO_GRAPHQL_DOCS_TRANSPORT=httpとMAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0を設定します。docker-compose.ymlのvolumesブロックのコメントを解除して、ローカルのドキュメントチェックアウトをバインドします；そうでない場合は、イメージがドキュメントを自動取得できます。ポート8765は一般的な8080の競合を避けるために選択されています；必要に応じて調整してください。

ステップ5：実行と確認

# サーバーを実行する（初回実行時は350のドキュメントを解析してインデックス化します）
magento-graphql-docs-mcp

# 別のターミナルで、検証テストを実行する
python3 tests/verify_parser.py
python3 tests/verify_db.py
python3 tests/verify_server.py

📦 インストール

必要条件

• Python 3.10以上
• Git（ドキュメントリポジトリをクローンするため）
• AdobeDocs/commerce-webapiからの350ページ以上のMagento 2 GraphQLドキュメントのMarkdownファイル

詳細なセットアップ

1. 両方のリポジトリをクローン

# ドキュメントソースをクローン
git clone https://github.com/AdobeDocs/commerce-webapi.git

# このMCPサーバーをクローン
cd magento-graphql-docs-mcp

2. ドキュメントパスを構成

サーバーは、ドキュメントを次の順序で探します（起動時にパスの検証が行われます）。

1. 環境変数 MAGENTO_GRAPHQL_DOCS_PATH（設定されている場合、パスが存在することを検証）
2. ./data/ディレクトリ（シンボリックリンクまたはプロジェクトルートにある.mdファイルを含むディレクトリ）
3. ../commerce-webapi/src/pages/graphql/（兄弟ディレクトリの自動検出）

有効なパスが見つからない場合、サーバーは3つのセットアップオプションを説明する有益なエラーメッセージで失敗します。

あなたのセットアップに最適な方法を選択します。

# 方法1：シンボリックリンク（開発に推奨）
ln -s ~/projects/commerce-webapi/src/pages/graphql data

# 方法2：環境変数（デプロイに推奨）
export MAGENTO_GRAPHQL_DOCS_PATH="$HOME/projects/commerce-webapi/src/pages/graphql"

# 方法3：commerce-webapiを兄弟ディレクトリとしてクローン
# magento-graphql-docs-mcp/
# commerce-webapi/
#   └── src/pages/graphql/

3. 依存関係のインストール

pip install -e .

これにより、以下がインストールされます。

• fastmcp - MCPサーバーフレームワーク
• sqlite-utils - データベース管理
• pydantic - データ検証
• python-frontmatter - YAMLフロントマター解析
• markdown-it-py - Markdown処理

💻 使用例

examples/ディレクトリには、すべてのMCPツールを実証する実用的な使用例が含まれています。

利用可能な例

1. 商品クエリ (examples/example_products.py)

• 商品ドキュメントを検索
• 商品GraphQLクエリとタイプを検索
• ProductInterfaceの詳細を探索
• 商品コード例を検索

2. 顧客クエリ (examples/example_customer.py)

• 顧客ドキュメントを検索
• 顧客ミューテーション（作成、更新）を検索
• 認証とトークンを探索
• 顧客住所操作を検索

3. カートとチェックアウト (examples/example_cart_checkout.py)

• カートドキュメントを検索
• チェックアウトワークフローチュートリアルを完了
• カートミューテーションとクエリを検索
• チェックアウトをステップバイステップで探索

例の実行

# 個々の例を実行
python3 examples/example_products.py
python3 examples/example_customer.py
python3 examples/example_cart_checkout.py

# または、すべての例を一度に実行
bash examples/run_all_examples.sh

詳細なドキュメントについては、examples/README.mdを参照してください。

📚 ドキュメント

1. search_documentation

キーワードを使用してドキュメントページを検索します。

パラメーター:

• queries: 1 - 3の短いキーワードクエリのリスト（例：["product", "cart"]）
• category: オプションのフィルター（schema, develop, usage, tutorials）
• subcategory: オプションのフィルター（products, cart, customer, など）
• content_type: オプションのフィルター（guide, reference, tutorial, schema）

例:

search_documentation(queries=["checkout"], category="tutorials")

2. get_document

ファイルパスで完全なドキュメントページを取得します。

パラメーター:

• file_path: ドキュメントへの相対パス（例："schema/products/queries/products.md"）

戻り値: メタデータ、フロントマター、およびMarkdown付きの完全なドキュメントコンテンツ。

3. search_graphql_elements

GraphQLクエリ、ミューテーション、タイプ、またはインターフェースを検索します。

パラメーター:

• query: 検索用語
• element_type: オプションのフィルター（query, mutation, type, interface, union）

例:

search_graphql_elements(query="products", element_type="query")

4. get_element_details

特定のGraphQL要素に関する完全な詳細を取得します。

パラメーター:

• element_name: 要素名（例："products", "createCustomer"）
• element_type: オプションのタイプフィルター

戻り値: フィールド、パラメーター、ソースドキュメント、およびコード例付きの完全な要素定義。

5. list_categories

ドキュメント数付きですべてのドキュメントカテゴリをリストします。

戻り値: 利用可能なすべてのドキュメント領域を示す階層的なカテゴリツリー。

6. get_tutorial

すべての手順を順番に含む完全なチュートリアルを取得します。

パラメーター:

• tutorial_name: チュートリアル名（例："checkout"）

戻り値: コード例と説明付きの順次のチュートリアル手順。

7. search_examples

トピックと言語でコード例を検索します。

パラメーター:

• query: 検索用語
• language: オプションの言語フィルター（graphql, json, javascript, php, bash）

例:

search_examples(query="add to cart", language="graphql")

8. get_related_documents

指定されたドキュメントに関連するドキュメントを検索します。

パラメーター:

• file_path: ソースドキュメントのファイルパス

戻り値: カテゴリとキーワードに基づく関連ドキュメント。

検証スクリプト

各コンポーネントを独立してテストします。

重要: すべてのテストはプロジェクトルートディレクトリから実行してください。

# プロジェクトルートに移動
cd magento-graphql-docs-mcp

# Markdownパーサーをテスト
python3 tests/verify_parser.py

# データベースの取り込みをテスト
python3 tests/verify_db.py

# MCPサーバーとすべての8つのツールをテスト
python3 tests/verify_server.py

# パフォーマンスベンチマークを実行
python3 tests/benchmark_performance.py

他のディレクトリからテストを実行すると、インポートエラーが発生します。

データベーススキーマ

サーバーは、次のテーブルを持つSQLiteを使用します。

• documents: FTS5インデックス付きのすべてのドキュメントページ
• code_blocks: ドキュメントからのコード例
• graphql_elements: FTS5インデックス付きで抽出されたGraphQLスキーマ要素
• metadata: 取り込み追跡

パフォーマンス

ベンチマークに基づく（python3 tests/benchmark_performance.pyを実行）：

• 起動時間: 0.87秒（データが変更されていない場合） | 3 - 5秒（初回実行またはファイルが変更された場合）
• 検索速度: 平均5.5ミリ秒（FTS5直接: 0.7ミリ秒）
• ドキュメント取得: 8.2ミリ秒
• GraphQL要素検索: 3.4ミリ秒
• データベースサイズ: 350のドキュメントで約30MB
• インデックス化されたコンテンツ: 350のドキュメント、963のコードブロック、51のGraphQL要素

すべてのパフォーマンスターゲットを達成しました：起動時間<5秒 ✓、検索時間<100ミリ秒 ✓

例のクエリ

クエリ	ツール	結果
"商品をクエリするにはどうすればいいですか？"	search_documentation	商品クエリのドキュメント
"商品クエリの詳細を表示してください"	search_graphql_elements	商品クエリの定義
"完全なチェックアウトフロー"	get_tutorial	ステップバイステップのチェックアウトガイド
"カートミューテーションの例"	search_examples	動作するGraphQLカートの例
"すべてのB2Bドキュメント"	list_categories + search	B2Bスキーマのドキュメント

開発

プロジェクト構造

magento-graphql-docs-mcp/
├── magento_graphql_docs_mcp/
│   ├── __init__.py
│   ├── config.py          # 設定
│   ├── parser.py          # Markdown + GraphQLパーサー
│   ├── ingest.py          # データベースの取り込み
│   └── server.py          # 8つのツールを持つMCPサーバー
├── tests/
│   ├── verify_parser.py   # パーサーの検証
│   ├── verify_db.py       # データベースの検証
│   └── verify_server.py   # サーバーの検証
├── data/
│   └── (ドキュメントへのシンボリックリンク)
├── pyproject.toml
├── README.md
└── CLAUDE.md

アーキテクチャ

Markdownファイル (350)
    ↓
パーサー (フロントマター + コンテンツ + GraphQL抽出)
    ↓
SQLite (ドキュメント + コードブロック + graphql要素 + FTS5)
    ↓
FastMCPサーバー (STDIO経由の8つのツール)
    ↓
MCPクライアント (Claude, IDE, など)

利点

Webスクレイピングとの比較

• ✅ オフライン操作（ネットワーク不要）
• ✅ 高速起動（3 - 5秒 vs 30 - 60秒）
• ✅ ローカル制御（カスタムドキュメントで動作）
• ✅ HTML解析の複雑さがない

REST API MCPとの比較

• ✅ チュートリアルとガイドを含む（API仕様だけでない）
• ✅ コード例が検索可能
• ✅ 学習用の説明コンテンツがある
• ✅ チュートリアルワークフロー

独自機能

• 📚 350のドキュメントがインデックス化されている
• 🔍 8つの特殊な検索ツール
• 💡 チュートリアルサポート
• 📝 コード例の検索
• 🔗 関連ドキュメントの発見
• ⚡ 高速なFTS5検索
• 🎯 GraphQL対応の解析

トラブルシューティング

ドキュメントが見つからないエラー

エラー: FileNotFoundError: Documentation directory not found!

サーバーは現在、3つのセットアップ方法を示す有益なエラーメッセージを提供しています。

解決策:

1. ドキュメントリポジトリがクローンされていることを確認

git clone https://github.com/AdobeDocs/commerce-webapi.git

2. パスが正しいことを確認

# 環境変数を使用している場合
echo $MAGENTO_GRAPHQL_DOCS_PATH
ls -la $MAGENTO_GRAPHQL_DOCS_PATH

# シンボリックリンクを使用している場合
ls -la data/
# GraphQLドキュメントを指すシンボリックリンクが表示されるはずです

# 以下のような350以上のMarkdownファイルとディレクトリが表示されるはずです。
# - schema/
# - tutorials/
# - develop/
# - index.md

3. 正しいパスを設定する（1つの方法を選択）

# 方法1: 環境変数（デプロイに推奨）
export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"

# 方法2: シンボリックリンクを作成（開発に推奨）
cd magento-graphql-docs-mcp
ln -s /path/to/commerce-webapi/src/pages/graphql data
# 確認: ls -la data/ でシンボリックリンクが表示されるはずです

# 方法3: commerce-webapiを兄弟ディレクトリとしてクローン
# magento-graphql-docs-mcp/
# commerce-webapi/
#   └── src/pages/graphql/

4. セットアップを確認

# サーバーは起動時にパスを検証し、試行された方法を正確に表示します。
magento-graphql-docs-mcp
# パスが無効な場合、どの方法が試行されたかが表示されます。

サーバーが起動しない

エラー: ModuleNotFoundError: No module named 'magento_graphql_docs_mcp'

解決策: 開発モードでパッケージをインストールします。

cd magento-graphql-docs-mcp
pip install -e .

エラー: サーバーが起動したがすぐに終了する

解決策: Pythonバージョンを確認します（3.10以上が必要）。

python3 --version  # 3.10以上である必要があります

検索結果がない

問題: ドキュメントが存在するにもかかわらず、検索に結果が返されない

解決策:

1. より短く、シンプルなキーワードを使用

# 代わりに: "customer authentication token generation"
# 試す: ["customer", "token"]

# 代わりに: "how to add products to cart"
# 試す: ["cart", "add"]

2. データベースが作成されていることを確認

ls -la ~/.mcp/magento-graphql-docs/
# database.db（約30MB）が表示されるはずです

3. データがインデックス化されていることを確認

python3 tests/verify_db.py
# 350のドキュメント、963のコードブロック、51のGraphQL要素が表示されるはずです

4. データベースを再インデックス化

rm ~/.mcp/magento-graphql-docs/database.db
magento-graphql-docs-mcp  # すべてを解析して再インデックス化します

データベースエラー

エラー: sqlite3.OperationalError: database is locked

解決策: 別のプロセスがデータベースを使用しています。

# プロセスを見つけて終了
lsof ~/.mcp/magento-graphql-docs/database.db
kill <PID>

# または、単に削除して再作成
rm ~/.mcp/magento-graphql-docs/database.db
magento-graphql-docs-mcp

エラー: sqlite3.DatabaseError: database disk image is malformed

解決策: データベースが破損しています、再作成します。

rm -rf ~/.mcp/magento-graphql-docs/
magento-graphql-docs-mcp  # 最初から再作成します

パフォーマンスが遅い

問題: 初回起動に10秒以上かかる

解決策: これは正常です！初回実行時には350のファイルが解析されます。その後の実行は1秒未満です。

問題: 毎回の起動が遅い

解決策: ドキュメントの更新時間が変更されています。確認します。

# gitがファイルの時間を変更していないことを確認
cd /path/to/commerce-webapi
git status
git pull  # 必要に応じて最新版に更新

検証に失敗した

問題: verify_server.pyが接続エラーで失敗する

解決策:

# 依存関係がインストールされていることを確認
pip install -e ".[dev]"

# MCPクライアントライブラリを確認
pip list | grep mcp

# 個々の検証を再実行
python3 tests/verify_parser.py   # 解析をテスト
python3 tests/verify_db.py       # データベースをテスト
python3 tests/verify_server.py   # MCPサーバーをテスト

MCPクライアントの統合問題

問題: MCPクライアントが「サーバーが見つかりません」または「接続に失敗しました」と表示する

解決策:

1. コマンドが正しいことを確認

# コマンドを直接テスト
which magento-graphql-docs-mcp
# または
python3 -m magento_graphql_docs_mcp.server

2. MCP設定の環境変数を確認

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "magento-graphql-docs-mcp",
      "env": {
        "MAGENTO_GRAPHQL_DOCS_PATH": "/FULL/PATH/to/commerce-webapi/src/pages/graphql"
      }
    }
  }
}

重要: MCP設定では、絶対パスを使用し、~や相対パスを使用しないでください。

3. ログを確認

• Claude Desktop: ~/Library/Logs/Claude/ (macOS)
• サーバーに関連するエラーメッセージを探します。

ヘルプの取得

まだ問題が解決しない場合は：

1. すべての検証スクリプトを実行

python3 tests/verify_parser.py
python3 tests/verify_db.py
python3 tests/verify_server.py
python3 tests/benchmark_performance.py

2. セットアップを確認

# Pythonバージョン
python3 --version

# ドキュメントパス
echo $MAGENTO_GRAPHQL_DOCS_PATH
ls -la $MAGENTO_GRAPHQL_DOCS_PATH | head -20

# データベース
ls -la ~/.mcp/magento-graphql-docs/

# パッケージのインストール
pip show magento-graphql-docs-mcp

3. 上記のコマンドの出力を添えてGitHubのissueを作成

📄 ライセンス

MIT

コントリビューション

コントリビューションを歓迎します！提出する前に、すべての変更を検証スクリプトでテストしてください。

サポート

問題や質問がある場合は：

1. 検証スクリプトを実行して問題を診断します。
2. データベースの場所とパーミッションを確認します。
3. ドキュメントパスが正しいことを確認します。