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开发工作流程有帮助，请给它加星！