Medusa.js Documentation MCP Server

🚀 Medusa.js文檔MCP服務器

這是一個強大的模型上下文協議（MCP）服務器，它能讓你的AI助手立即訪問全面的Medusa.js v2文檔，具備智能搜索功能和實時協助，可優化開發工作流程。

📅 最新文檔日期：2025年9月 | 📊 覆蓋章節數：2105+ | 📦 文件大小：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. 文檔就緒！

✅ 無需額外設置！ 倉庫中包含全面的Medusa.js v2文檔（4.7MB，2025年9月），位於 ./docs/medusa-docs.txt。

可選：使用你自己的文檔文件：

# 如有需要，替換為你自己的文檔
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"
      }
    }
  }
}

💻 使用示例

基礎用法

🔍 智能搜索示例

💬 "在Medusa文檔中搜索支付提供商"
💬 "查找關於Medusa工作流的信息"
💬 "查找購物車模塊文檔"
💬 "如何實現自定義運輸方式？"
💬 "給我展示身份驗證示例"

📖 特定章節檢索

💬 "獲取關於API路由的章節"
💬 "給我展示模塊文檔"
💬 "檢索工作流示例"
💬 "我需要管理員自定義指南"
💬 "展示產品目錄設置"

📋 瀏覽可用內容

💬 "列出所有可用的文檔章節"
💬 "給我展示文檔中的類別"
💬 "有哪些文檔章節可用？"
💬 "瀏覽與工作流相關的文檔"
💬 "文檔中記錄了哪些支付集成？"

🌟 高級用法模式

💬 "比較Medusa中不同的支付提供商"
💬 "逐步指導我設置一個完整的電子商務商店"
💬 "模塊和插件有什麼區別？"
💬 "給我展示分步的工作流實現"

高級用法

MCP服務器提供3個強大的工具來訪問Medusa.js文檔：

🔍 1. search_docs - 智能文檔搜索

功能：使用模糊匹配智能搜索2105+個文檔章節 適用場景：當你不知道確切的章節名稱時查找相關信息

參數：

• 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 - 瀏覽所有可用內容

功能：列出所有2105+個可用的文檔章節 適用場景：發現可用的文檔或按類別瀏覽

參數：

• 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 由Anthropic提供
• Medusa.js 電子商務平臺
• Fuse.js 提供模糊搜索功能

📞 支持

• 🐛 問題反饋：GitHub Issues
• 💬 討論交流：GitHub Discussions
• 📧 郵件聯繫：通過GitHub聯繫

⭐ 如果這個倉庫對你的Medusa開發工作流程有幫助，請給它加星！