内容
# 大商MCP服务器
一个全面的模型上下文协议（MCP）服务器，用于BigCommerce REST API集成。该服务器为AI助手提供了通过三个强大的工具与BigCommerce商店交互的能力：
- 🛍️ **产品管理**：获取所有产品，并具有高级筛选功能
- 👥 **客户管理**：检索和筛选客户，并具有全面的搜索选项
- 📦 **订单管理**：访问订单，并具有客户-产品关系功能
## ✨ 功能
- ✅ 与MCP兼容的服务器，内置工具发现
- ✅ 所有端点都具有增强的筛选功能
- ✅ 通过订单历史记录实现客户-产品关联
- ✅ 全面的错误处理和验证
- ✅ 支持Docker生产部署
- ✅ 与Claude Desktop、Cline等MCP客户端兼容
## 🚦 快速入门
### ⚙️ 前提条件
- [Node.js（需v18+，推荐v20+）](https://nodejs.org/)
- [npm（包含在Node中）](https://www.npmjs.com/)
- 具有API凭证的BigCommerce商店
### 📥 安装和设置
**1. 克隆并安装依赖项**
```sh
git clone https://github.com/isaacgounton/bigcommerce-api-mcp.git
cd bigcommerce-api-mcp
npm install
```
**2. 配置BigCommerce凭证**
在项目根目录中创建一个`.env`文件：
```env
BIGCOMMERCE_STORE_HASH=您的商店哈希值
BIGCOMMERCE_API_KEY=您的API密钥
```
**如何获取BigCommerce凭证：**
1. 进入BigCommerce管理面板
2. 导航到 **高级设置** > **API账户**
3. 创建一个新的API账户，权限范围包括：
- **产品**：只读或修改
- **订单**：只读或修改
- **客户**：只读或修改
4. 将 **商店哈希值** 和 **访问令牌** 复制到您的`.env`文件
### 🔧 可用工具
**`get_all_products`**
- 从BigCommerce商店检索产品
- 参数：`store_Hash`（必填）
**`get_all_customers`**
- 使用高级选项搜索和筛选客户
- 参数：`store_Hash`（必填）
- 可选筛选器：`email`、`name`、`company`、`phone`、`customer_group_id`、`limit`、`page`、`date_created`、`date_modified`
**`get_all_orders`**
- 访问具有客户-产品关系数据的订单
- 参数：`store_Hash`（必填）
- 可选筛选器：`customer_id`、`email`、`status_id`、`min_id`、`max_id`、`limit`、`page`
- ✨ **特殊功能**：使用`customer_id`筛选以查看与特定客户关联的所有产品
## 🔗 客户端集成
### 💬 Claude Desktop
**步骤 1**：获取node和mcpServer.js的绝对路径：
```sh
which node
# 示例输出：/usr/bin/node
realpath mcpServer.js
# 示例输出：/home/user/bigcommerce-api-mcp/mcpServer.js
```
**步骤 2**：打开Claude Desktop → **设置** → **开发者** → **编辑配置**，并添加：
```json
{
"mcpServers": {
"bigcommerce": {
"command": "/usr/bin/node",
"args": ["/absolute/path/to/your/mcpServer.js"],
"env": {
"BIGCOMMERCE_STORE_HASH": "您的商店哈希值",
"BIGCOMMERCE_API_KEY": "您的API密钥"
}
}
}
}
```
**步骤 3**：重启Claude Desktop。在MCP部分查找“bigcommerce”旁边的绿色圆形图标。
### Cline（VS Code扩展）
**步骤 1**：在VS Code中安装Cline扩展
**步骤 2**：打开VS Code设置并搜索“Cline MCP”
**步骤 3**：添加您的MCP服务器配置：
```json
{
"cline.mcp.servers": {
"bigcommerce": {
"command": "node",
"args": ["/absolute/path/to/mcpServer.js"],
"env": {
"BIGCOMMERCE_STORE_HASH": "您的商店哈希值",
"BIGCOMMERCE_API_KEY": "您的API密钥"
}
}
}
}
```
### 🤖 其他MCP客户端
对于任何MCP兼容的客户端，请使用以下连接详细信息：
- **命令**：`node`
- **参数**：`["/path/to/mcpServer.js"]`
- **环境变量**：
- `BIGCOMMERCE_STORE_HASH`
- `BIGCOMMERCE_API_KEY`
## 🐳 Docker部署
### 快速开始
**1. 构建Docker镜像：**
```sh
docker build -t bigcommerce-mcp .
```
**2. 使用环境变量运行：**
```sh
docker run -i --rm \
-e BIGCOMMERCE_STORE_HASH=您的商店哈希值 \
-e BIGCOMMERCE_API_KEY=您的API密钥 \
bigcommerce-mcp
```
### 与Claude Desktop结合使用Docker
更新Claude Desktop配置以使用Docker：
```json
{
"mcpServers": {
"bigcommerce": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "BIGCOMMERCE_STORE_HASH=您的商店哈希值",
"-e", "BIGCOMMERCE_API_KEY=您的API密钥",
"bigcommerce-mcp"
]
}
}
}
```
### Docker Compose（生产环境）
创建一个`docker-compose.yml`文件：
```yaml
version: '3.8'
services:
bigcommerce-mcp:
build: .
environment:
- BIGCOMMERCE_STORE_HASH=${BIGCOMMERCE_STORE_HASH}
- BIGCOMMERCE_API_KEY=${BIGCOMMERCE_API_KEY}
restart: unless-stopped
```
然后运行：
```sh
docker-compose up -d
```
## 🧪 测试
### 本地测试
在本地测试服务器以确保其正常工作：
```sh
# 测试工具发现
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}' | node mcpServer.js
# 测试工具调用
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_all_products","arguments":{"store_Hash":"您的商店哈希值"}},"id":2}' | node mcpServer.js
```
### Postman集成（可选）
您还可以使用Postman Desktop进行测试：
1. 下载 [Postman Desktop](https://www.postman.com/downloads/)
2. 创建一个新的MCP请求，类型为`STDIO`
3. 将命令设置为：`node /absolute/path/to/mcpServer.js`
4. 在连接AI客户端之前测试您的工具
## 🛠️ 高级用法
### 服务器模式
**标准stdio模式（默认）：**
```sh
node mcpServer.js
```
**带有服务器发送事件的HTTP模式：**
```sh
node mcpServer.js --sse
```
**可流式HTTP模式：**
```sh
node mcpServer.js --streamable-http
```
### 环境变量
所有BigCommerce凭证都可以通过环境变量提供：
```bash
export BIGCOMMERCE_STORE_HASH="您的商店哈希值"
export BIGCOMMERCE_API_KEY="您的API密钥"
node mcpServer.js
```
## 🔍 工具示例
### 查找与客户关联的产品
```javascript
// 使用get_all_orders和customer_id筛选器
{
"name": "get_all_orders",
"arguments": {
"store_Hash": "您的商店哈希值",
"customer_id": "3"
}
}
```
### 按电子邮件搜索客户
```javascript
// 使用get_all_customers和email筛选器
{
"name": "get_all_customers",
"arguments": {
"store_Hash": "您的商店哈希值",
"email": "customer@example.com"
}
}
```
## 🤝 贡献
欢迎贡献！请随时提交拉取请求。
## 📄 许可证
该项目在MIT许可证下获得许可。
## 🆘 支持与问题
- 🐛 **问题**：[GitHub Issues](https://github.com/isaacgounton/bigcommerce-api-mcp/issues)
- 💬 **讨论**：[GitHub Discussions](https://github.com/isaacgounton/bigcommerce-api-mcp/discussions)
- 📖 **MCP文档**：[Model Context Protocol](https://modelcontextprotocol.io/)
- 🏪 **BigCommerce API文档**：[BigCommerce API Reference](https://developer.bigcommerce.com/docs/rest-management)
## 🚀 下一步
该MCP服务器为BigCommerce集成提供了一个坚实的基础。可能的增强功能包括：
- 额外的BigCommerce API端点（类别、品牌等）
- 用于实时更新的Webhook支持
- 高级筛选和搜索功能
- 多商店支持
- 产品修改工具（创建/更新/删除）
---
**为MCP社区打造 ❤️ **
