Medusa Js Documentation MCP Server

🚀 Medusa.js文档MCP服务器

一个强大的 模型上下文协议（MCP）服务器 这使您的AI助手能够即时访问 全面的Medusa.js v2文档 具有智能搜索功能和实时辅助功能，可增强开发工作流程。

📅 最新文档：2025年9月|📊 覆盖：2105+节|📦 尺寸：470万桶

✨ 主要特点

📋 先决条件

• Node.js 18+
• npm 或 纱线
• AI助手 在MCP支持下：

- 克劳德代码（CLI） ✅ 测试和工作 - 基洛代码 ✅ 测试和工作 - 光标 - 帆板运动 - 或任何兼容MCP的客户端

🛠 安装

1.克隆和设置

# Clone the repository
git clone https://github.com/Alexcs24/Medusa.js-Documentation-MCP-Server
cd Medusa.js-Documentation-MCP-Server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

2.文件准备就绪！

✅ 无需额外设置！ 该存储库包括全面的Medusa.js v2文档（4.7MB，2025年9月），位于 ./docs/medusa-docs.txt.

可选的：使用您自己的文档文件：

# Replace with your own documentation if needed
export MEDUSA_DOCS_PATH="/absolute/path/to/your/custom-docs.txt"

3.配置您的AI助手

🟢 克劳德代码CLI✅ 测试和工作

全局配置 （推荐）：

# Create or edit global config
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"
      }
    }
  }
}

项目特定配置:

# In your Medusa project root
mkdir -p .claude
cp claude_code_config.json .claude/mcp.json
# Edit paths to be relative to your project

光标IDE

添加到光标设置(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-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助手并使用进行交互 自然语言:

🔍 智能搜索示例

💬 "Search Medusa docs for payment providers"
💬 "Find information about workflows in Medusa"
💬 "Look up cart module documentation"
💬 "How do I implement custom shipping methods?"
💬 "Show me authentication examples"

📖 特定章节检索

💬 "Get the section about API routes"
💬 "Show me the modules documentation"
💬 "Retrieve workflow examples"
💬 "I need the admin customization guide"
💬 "Display the product catalog setup"

📋 浏览可用内容

💬 "List all available documentation sections"
💬 "Show me categories in the docs"
💬 "What documentation sections are available?"
💬 "Browse workflow-related documentation"
💬 "What payment integrations are documented?"

🌟 高级使用模式

💬 "Compare different payment providers in Medusa"
💬 "Walk me through setting up a complete e-commerce store"
💬 "What's the difference between modules and plugins?"
💬 "Show me step-by-step workflow implementation"

🔧 可用的MCP工具

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: *“我如何在美杜莎设置付款？”*

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. 访问详细的购物车实施示例

🚧 发展

脚本

# Development server with hot reload
npm run dev

# Watch mode (auto-restart on changes)
npm run watch

# Build TypeScript
npm run build

# Start production server
npm run start

测试

手动测试MCP服务器：

# Start the server
node dist/index.js

# In another terminal, send MCP requests
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

调试模式

# Enable debug logging
DEBUG=1 node dist/index.js

# Or with environment variables
MEDUSA_DOCS_PATH="/path/to/docs.txt" DEBUG=1 node dist/index.js

📁 项目结构

Medusa.js-Documentation-MCP-Server/
├── src/
│   └── index.ts              # Main MCP server implementation
├── dist/                     # Compiled JavaScript (auto-generated)
├── docs/
│   └── medusa-docs.txt       # Complete Medusa v2 docs (4.7MB, Sep 2025)
├── config.json               # Server configuration settings
├── example-docs.txt          # Example documentation format
├── claude_code_config.json   # Example Claude Code config
├── package.json              # Node.js dependencies
├── tsconfig.json            # TypeScript configuration
├── .gitignore               # Git ignore rules
├── LICENSE                  # MIT License
└── README.md                # This file

⚙️ 配置

所有服务器设置都可以在中自定义 config.json:

{
  "searchDefaults": {
    "maxResults": 5,           // Default number of search results
    "threshold": 0.4,          // Search sensitivity (0-1, lower = more strict)
    "minMatchCharLength": 3    // Minimum characters for search matching
  },
  "listDefaults": {
    "maxSections": 50          // Maximum sections shown in list_sections
  },
  "server": {
    "name": "medusa-docs-mcp",
    "version": "1.0.0"
  },
  "documentation": {
    "previewLength": 500,      // Length of content preview in search results
    "fallbackPaths": [         // Paths to search for documentation file
      "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. 确保文件存在且不为空

权限错误

# Fix file permissions
chmod 644 /path/to/docs/medusa-docs.txt
chmod +x /path/to/Medusa.js-Documentation-MCP-Server/dist/index.js

调试连接问题

# Test MCP server manually
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | MEDUSA_DOCS_PATH="/path/to/docs.txt" node dist/index.js

检查AI助手的MCP日志：

• 克劳德代码CLI：查看→ 输出→ MCP日志
• 光标IDE：开发人员工具→ 控制台
• 帆板运动：检查开发人员工具中的扩展日志

🤝 贡献

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许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 模型上下文协议 通过Anthropic
• Medusa.js 商务平台
• Fuse.js 用于模糊搜索功能

📞 支持

• 🐛 问题:
• 💬 讨论:
• 📧 电子邮件：通过GitHub联系

______________________________________________________________________

⭐ 如果此仓库有助于您的Medusa开发工作流程，请将其标记为星号！