Medusa.js Documentation MCP Server

🚀 Medusa.js Documentation MCP Server

強力なモデルコンテキストプロトコル（MCP）サーバーです。このサーバーを使用すると、AIアシスタントがスマート検索機能とリアルタイムアシスタンスを備えた包括的なMedusa.js v2ドキュメントに即座にアクセスでき、開発ワークフローを向上させることができます。

📅 最新ドキュメント: 2025年9月 | 📊 カバレッジ: 2,105以上のセクション | 📦 サイズ: 4.7MB

✨ 主な機能

📋 前提条件

• Node.js 18以上
• npm または yarn
• MCPをサポートする AIアシスタント：
  • Claude Code (CLI) ✅ テスト済み、動作確認済み
  • Kilo Code ✅ テスト済み、動作確認済み
  • Cursor
  • Windsurf
  • またはMCP互換のクライアント

📦 インストール

1. リポジトリのクローンとセットアップ

# リポジトリをクローンする
git clone https://github.com/Alexcs24/Medusa.js-Documentation-MCP-Server
cd Medusa.js-Documentation-MCP-Server

# 依存関係をインストールする
npm install

# TypeScriptコードをビルドする
npm run build

2. ドキュメントの準備完了！

✅ 追加のセットアップは必要ありません！ リポジトリには、./docs/medusa-docs.txtにある包括的なMedusa.js v2ドキュメント（4.7MB、2025年9月）が含まれています。

オプション：独自のドキュメントファイルを使用する場合：

# 必要に応じて、独自のドキュメントで置き換える
export MEDUSA_DOCS_PATH="/absolute/path/to/your/custom-docs.txt"

3. AIアシスタントの設定

🟢 Claude Code CLI ✅ テスト済み、動作確認済み

グローバル設定（推奨）：

# グローバル設定ファイルを作成または編集する
nano ~/.claude/claude_code_config.json

以下の設定を追加します：

{
  "mcpServers": {
    "medusa-docs": {
      "command": "node",
      "args": ["/absolute/path/to/Medusa.js-Documentation-MCP-Server/dist/index.js"],
      "env": {
        "MEDUSA_DOCS_PATH": "/absolute/path/to/Medusa.js-Documentation-MCP-Server/docs/medusa-docs.txt"
      }
    }
  }
}

プロジェクト固有の設定：

# Medusaプロジェクトのルートディレクトリで
mkdir -p .claude
cp claude_code_config.json .claude/mcp.json
# パスをプロジェクトに対して相対的に編集する

Cursor IDE

Cursorの設定ファイル（settings.json）に追加します：

{
  "mcp": {
    "mcpServers": {
      "medusa-docs": {
        "command": "node",
        "args": ["/absolute/path/to/Medusa.js-Documentation-MCP-Server/dist/index.js"],
        "env": {
          "MEDUSA_DOCS_PATH": "/absolute/path/to/docs/medusa-docs.txt"
        }
      }
    }
  }
}

Windsurf

windsurf-mcp-config.jsonを作成または編集します：

{
  "mcpServers": {
    "medusa-docs": {
      "command": "node",
      "args": ["/absolute/path/to/Medusa.js-Documentation-MCP-Server/dist/index.js"],
      "env": {
        "MEDUSA_DOCS_PATH": "/absolute/path/to/docs/medusa-docs.txt"
      }
    }
  }
}

💻 使用例

基本的な使用法

設定後、AIアシスタントを再起動し、自然言語を使用して対話します。

🔍 スマート検索の例

💬 "Medusaのドキュメントで支払いプロバイダーを検索する"
💬 "Medusaのワークフローに関する情報を探す"
💬 "カートモジュールのドキュメントを検索する"
💬 "カスタム配送方法を実装するにはどうすればいいですか？"
💬 "認証の例を見せて"

📖 特定のセクションの取得

💬 "APIルートに関するセクションを取得する"
💬 "モジュールのドキュメントを見せて"
💬 "ワークフローの例を取得する"
💬 "管理者のカスタマイズガイドが必要です"
💬 "商品カタログのセットアップを表示する"

📋 利用可能なコンテンツの閲覧

💬 "すべての利用可能なドキュメントセクションをリスト表示する"
💬 "ドキュメントのカテゴリを見せて"
💬 "利用可能なドキュメントセクションは何ですか？"
💬 "ワークフロー関連のドキュメントを閲覧する"
💬 "どの支払い統合がドキュメント化されていますか？"

🌟 高度な使用パターン

💬 "Medusaで異なる支払いプロバイダーを比較する"
💬 "完全な電子商取引ストアのセットアップを案内して"
💬 "モジュールとプラグインの違いは何ですか？"
💬 "ワークフローの実装をステップバイステップで見せて"

高度な使用法

MCPサーバーは、Medusa.jsドキュメントにアクセスするための3つの強力なツールを提供します。

🔍 1. search_docs - スマートなドキュメント検索

機能：ファジーマッチングを使用して2,105以上のドキュメントセクションをインテリジェントに検索します。 最適なシナリオ：正確なセクション名を知らない場合に関連情報を見つけるのに最適です。

パラメーター：

• query (文字列、必須)：検索クエリ
• limit (数値、オプション)：返す最大結果数（デフォルト: 5）

✨ 使用例：

{
  "name": "search_docs",
  "arguments": {
    "query": "workflow payment providers",
    "limit": 3
  }
}

返り値：ワークフローエンジンモジュール、タイムアウト設定、およびインメモリワークフローの設定

📖 2. get_section - 正確なセクションの取得

機能：タイトルまたはパスで正確なドキュメントセクションを取得します。 最適なシナリオ：存在する特定のトピックに関する詳細情報を取得するのに最適です。

パラメーター：

• identifier (文字列、必須)：正確なセクションタイトルまたはパス

✨ 使用例：

{
  "name": "get_section",
  "arguments": {
    "identifier": "Debug Workflows"
  }
}

返り値：デバッグアプローチとテクニックを含む完全なセクション内容

📋 3. list_sections - すべての利用可能なコンテンツの閲覧

機能：2,105以上の利用可能なドキュメントセクションをリスト表示します。 最適なシナリオ：利用可能なドキュメントを発見したり、カテゴリ別に閲覧したりするのに最適です。

パラメーター：

• category (文字列、オプション)：特定のカテゴリでセクションをフィルタリングする

✨ 使用例：

{
  "name": "list_sections",
  "arguments": {
    "category": "workflows"
  }
}

返り値：ワークフロー関連のドキュメントセクションの完全なリスト

🚀 実際の使用例

シナリオ1： "Medusaで支払いを設定するにはどうすればいいですか？"

1. search_docsを使用して、クエリ "payment setup"を指定します。
2. 支払いモジュールとプロバイダーに関する関連セクションを取得します。
3. get_sectionを使用して、特定の支払いプロバイダーの設定を詳しく調べます。

シナリオ2： "利用可能なワークフロー機能は何ですか？"

1. list_sectionsを使用して、カテゴリ "workflows"を指定します。
2. 利用可能なワークフロードキュメントを閲覧します。
3. get_sectionを使用して、特定のワークフロー実装ガイドを読みます。

シナリオ3： "カート機能について助けが必要です"

1. search_docsを使用して、クエリ "cart module"を指定します。
2. カート関連のセクションとAPIを見つけます。
3. 詳細なカート実装例にアクセスします。

🔧 技術詳細

開発用スクリプト

# ホットリロード付きの開発サーバーを起動する
npm run dev

# ウォッチモード（変更時に自動再起動）
npm run watch

# TypeScriptをビルドする
npm run build

# 本番サーバーを起動する
npm run start

テスト

MCPサーバーを手動でテストします：

# サーバーを起動する
node dist/index.js

# 別のターミナルで、MCPリクエストを送信する
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

デバッグモード

# デバッグログを有効にする
DEBUG=1 node dist/index.js

# または環境変数を使用する
MEDUSA_DOCS_PATH="/path/to/docs.txt" DEBUG=1 node dist/index.js

プロジェクト構造

Medusa.js-Documentation-MCP-Server/
├── src/
│   └── index.ts              # メインのMCPサーバー実装
├── dist/                     # コンパイルされたJavaScript（自動生成）
├── docs/
│   └── medusa-docs.txt       # 完全なMedusa v2ドキュメント（4.7MB, 2025年9月）
├── config.json               # サーバーの設定
├── example-docs.txt          # ドキュメントの例の形式
├── claude_code_config.json   # Claude Codeの設定例
├── package.json              # Node.jsの依存関係
├── tsconfig.json            # TypeScriptの設定
├── .gitignore               # Gitの無視ルール
├── LICENSE                  # MITライセンス
└── README.md                # このファイル

設定

すべてのサーバー設定は、config.jsonでカスタマイズできます：

{
  "searchDefaults": {
    "maxResults": 5,           # 検索結果のデフォルト数
    "threshold": 0.4,          # 検索感度（0-1、値が低いほど厳格）
    "minMatchCharLength": 3    # 検索マッチングの最小文字数
  },
  "listDefaults": {
    "maxSections": 50          # list_sectionsで表示される最大セクション数
  },
  "server": {
    "name": "medusa-docs-mcp",
    "version": "1.0.0"
  },
  "documentation": {
    "previewLength": 500,      # 検索結果のコンテンツプレビューの長さ
    "fallbackPaths": [         # ドキュメントファイルを検索するパス
      "docs/medusa-docs.txt",
      "llms-full.txt",
      "../llms-full.txt",
      "../../llms-full.txt",
      "/home/claude/llms-full.txt"
    ]
  }
}

🔧 設定のカスタマイズ

• より多くの検索結果：searchDefaults.maxResultsを増やします。
• より厳格な検索：searchDefaults.thresholdを下げます（0.2 = 非常に厳格、0.8 = 非常に緩い）。
• より長いプレビュー：documentation.previewLengthを増やします。
• より多くのリスト項目：listDefaults.maxSectionsを増やします。

環境変数

• MEDUSA_DOCS_PATH：ドキュメントファイルの絶対パス
• DEBUG：デバッグログを有効にする（1またはtrueに設定）

トラブルシューティング

サーバーが見つからない場合

1. 設定変更後、AIアシスタントを再起動します。
2. ファイルパスが絶対パスであることを確認します。
3. dist/index.jsファイルが存在することを確認します（npm run buildを実行）。

ドキュメントが読み込まれない場合

1. MEDUSA_DOCS_PATHが正しいファイルを指していることを確認します。
2. ファイルのパーミッションを確認します（読み取り可能である必要があります）。
3. ファイルが存在し、空でないことを確認します。

パーミッションエラー

# ファイルのパーミッションを修正する
chmod 644 /path/to/docs/medusa-docs.txt
chmod +x /path/to/Medusa.js-Documentation-MCP-Server/dist/index.js

接続問題のデバッグ

# MCPサーバーを手動でテストする
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | MEDUSA_DOCS_PATH="/path/to/docs.txt" node dist/index.js

AIアシスタントのMCPログを確認します：

• Claude Code CLI：表示 → 出力 → MCPログ
• Cursor IDE：開発者ツール → コンソール
• Windsurf：開発者ツールで拡張機能のログを確認する

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更を加えます。
4. 必要に応じて、config.jsonの設定を更新します。
5. ビルドしてテストします (npm run build)。
6. 変更をコミットします (git commit -m 'Add amazing feature')。
7. ブランチにプッシュします (git push origin feature/amazing-feature)。
8. プルリクエストを開きます。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSEファイルを参照してください。

🙏 謝辞

• Model Context Protocol by Anthropic
• Medusa.js コマースプラットフォーム
• Fuse.js ファジー検索機能

📞 サポート

• 🐛 問題報告：GitHub Issues
• 💬 ディスカッション：GitHub Discussions
• 📧 メール：GitHubを通じて連絡してください

⭐ このリポジトリがMedusaの開発ワークフローに役立つ場合は、スターをつけてください！