美杜莎.js文档MCP服务器
项目介绍
🚀 Medusa.js 文档 MCP 服务器
一个强大的 模型上下文协议（MCP）服务器，能够即时访问 全面的 Medusa.js v2 文档，并具有智能搜索功能和实时协助，以增强开发工作流程。
📅 最新文档：2025年9月 | 📊 覆盖范围：2,105+ 部分 | 📦 大小：4.7MB
✨ 主要特性
| 🎯 特性 | 📝 描述 | 🚀 优势 |
|---|---|---|
| 🔍 智能搜索 | 在2,105+ 文档部分中进行模糊搜索 | 即使使用不完整或不精确的查询也能找到答案 |
| 📖 精确检索 | 通过标题或路径获取确切的部分 | 即时访问特定文档 |
| 📋 完整浏览 | 列出所有可用部分并进行过滤 | 发现新特性和能力 |
| ⚡ 雷电般快速 | 使用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="/绝对路径/到/您的/自定义文档.txt"
3. 配置您的AI助手
🟢 Claude Code CLI ✅ 已测试且运行正常
全局配置（推荐）：
# 创建或编辑全局配置
nano ~/.claude/claude_code_config.json
添加以下配置：
{
"mcpServers": {
"medusa-docs": {
"command": "node",
"args": ["/绝对路径/到/Medusa.js-Documentation-MCP-Server/dist/index.js"],
"env": {
"MEDUSA_DOCS_PATH": "/绝对路径/到/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": ["/绝对路径/到/Medusa.js-Documentation-MCP-Server/dist/index.js"],
"env": {
"MEDUSA_DOCS_PATH": "/绝对路径/到/docs/medusa-docs.txt"
}
}
}
}
}
Windsurf
创建或编辑 windsurf-mcp-config.json：
{
"mcpServers": {
"medusa-docs": {
"command": "node",
"args": ["/绝对路径/到/Medusa.js-Documentation-MCP-Server/dist/index.js"],
"env": {
"MEDUSA_DOCS_PATH": "/绝对路径/到/docs/medusa-docs.txt"
}
}
}
}
🎯 使用方法及自然语言示例
配置完成后，重启您的AI助手，并使用自然语言进行交互：
🔍 智能搜索示例
💬 "搜索Medusa文档中的支付提供商"
💬 "查找关于Medusa工作流的信息"
💬 "查阅购物车模块文档"
💬 "如何实现自定义运输方式？"
💬 "显示身份验证示例"
📖 特定部分检索
💬 "获取关于API路由的部分"
💬 "显示模块文档"
💬 "检索工作流示例"
💬 "我需要管理员定制指南"
💬 "展示产品目录设置"
📋 浏览可用内容
💬 "列出所有可用文档部分"
💬 "显示文档中的类别"
💬 "有哪些文档部分可用？"
💬 "浏览与工作流相关的文档"
💬 "哪些支付集成被记录了？"
🌟 高级使用模式
💬 "比较Medusa中的不同支付提供商"
💬 "引导我完成完整的电子商务商店设置"
💬 "模块和插件有什么区别？"
💬 "显示逐步的工作流实施"
🔧 可用的MCP工具
MCP服务器提供了3个强大的工具来访问Medusa.js文档：
🔍 1. search_docs - 智能文档搜索
功能：通过模糊匹配在2,105+ 文档部分中智能搜索 适用于：当不知道确切部分名称时寻找相关信息
参数：
query(字符串，必需): 您的搜索查询limit(数字，可选): 返回的最大结果数（默认：5）
✨ 示例用法：
{
"name": "search_docs",
"arguments": {
"query": "工作流支付提供商",
"limit": 3
}
}
返回：工作流引擎模块、超时配置以及内存工作流设置
📖 2. get_section - 精确部分检索
功能：通过标题或路径获取确切的文档部分 适用于：获取您知道存在的特定主题的详细信息
参数：
identifier(字符串，必需): 确切部分标题或路径
✨ 示例用法：
{
"name": "get_section",
"arguments": {
"identifier": "调试工作流"
}
}
返回：包含调试方法和技术的完整部分内容
📋 3. list_sections - 浏览所有可用内容
功能：列出所有2,105+ 可用文档部分 适用于：发现可用文档或按类别浏览
参数：
category(字符串，可选): 按特定类别筛选部分
✨ 示例用法：
{
"name": "list_sections",
"arguments": {
"category": "工作流"
}
}
返回：所有与工作流相关的文档部分列表
🚀 实际使用示例
场景1："如何在Medusa中设置支付？"
- 使用
search_docs和查询"支付设置" - 获取有关支付模块和提供商的相关部分
- 使用
get_section深入了解特定支付提供商的设置
场景2："有哪些工作流功能可用？"
- 使用
list_sections和类别"工作流" - 浏览可用的工作流文档
- 使用
get_section阅读特定工作流实施指南
场景3："我需要帮助处理购物车功能"
- 使用
search_docs和查询"购物车模块" - 查找与购物车相关的部分和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="/路径/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 /路径/to/docs/medusa-docs.txt
chmod +x /路径/to/Medusa.js-Documentation-MCP-Server/dist/index.js
调试连接问题
# 手动测试MCP服务器
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | MEDUSA_DOCS_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 '添加精彩功能') - 推送到分支 (
git push origin feature/amazing-feature) - 打开拉取请求
📝 许可证
该项目采用MIT许可证 - 详情见LICENSE文件。
🙏 致谢
📞 支持
⭐ 如果此仓库有助于您的Medusa开发工作流程，请给它点赞！