微信扫一扫article
README
🚀 Medusa.js文档MCP服务器
这是一个强大的模型上下文协议（MCP）服务器，它能让你的AI助手立即访问全面的Medusa.js v2文档，具备智能搜索功能和实时协助，可优化开发工作流程。
📅 最新文档日期：2025年9月 | 📊 覆盖章节数：2105+ | 📦 文件大小：4.7MB
✨ 主要特性
| 🎯 特性 | 📝 描述 | 🚀 优势 | |------------|----------------|-------------| | 🔍 智能搜索 | 对2105+个文档章节进行模糊搜索 | 即使使用部分或不精确的查询也能找到答案 | | 📖 精确检索 | 按标题或路径获取确切章节 | 即时访问特定文档 | | 📋 完整浏览 | 列出所有可用章节并支持过滤 | 发现新特性和功能 | | ⚡ 极速响应 | 由TypeScript驱动，性能优化 | 即时响应，无延迟 | | 📦 零配置 | 包含文档，无需外部依赖 | 开箱即用 | | 🔄 实时更新 | 始终提供最新的Medusa v2文档 | 掌握最新特性和最佳实践 |
📋 前提条件
- 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中设置支付？"
- 使用
search_docs并输入查询"payment setup" - 获取关于支付模块和提供商的相关章节
- 使用
get_section深入了解特定支付提供商的设置
场景2："有哪些工作流特性可用？"
- 使用
list_sections并指定类别"workflows" - 浏览可用的工作流文档
- 使用
get_section阅读特定的工作流实现指南
场景3："我需要购物车功能方面的帮助"
- 使用
search_docs并输入查询"cart module" - 查找与购物车相关的章节和API
- 访问详细的购物车实现示例
🔧 技术细节
开发脚本
# 带热重载的开发服务器
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）
🐛 故障排除
未找到服务器
- 配置更改后重启你的AI助手
- 确保文件路径是绝对路径，而不是相对路径
- 验证
dist/index.js文件是否存在（运行npm run build）
文档未加载
- 验证
MEDUSA_DOCS_PATH是否指向正确的文件 - 检查文件权限（应该是可读的）
- 确保文件存在且不为空
权限错误
# 修复文件权限
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：在开发者工具中检查扩展日志
🤝 贡献
- 分叉仓库
- 创建一个功能分支 (
git checkout -b feature/amazing-feature) - 进行更改
- 如有需要，更新
config.json中的配置 - 构建并测试 (
npm run build) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 打开一个拉取请求
📄 许可证
本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。
🙏 致谢
- Model Context Protocol 由Anthropic提供
- Medusa.js 电子商务平台
- Fuse.js 提供模糊搜索功能
📞 支持
- 🐛 问题反馈：GitHub Issues
- 💬 讨论交流：GitHub Discussions
- 📧 邮件联系：通过GitHub联系
⭐ 如果这个仓库对你的Medusa开发工作流程有帮助，请给它加星！