AI智能客服MCP Server
这是一个基于Model Context Protocol (MCP) 的AI智能客服系统核心服务器，提供订单查询和网点查询功能。
功能特性
系统要求
Node.js 18.0.0 或更高版本
npm 或 yarn 包管理器
环境安装
Ubuntu 20.04 安装指南
快速安装（推荐）
我们提供了一个自动安装脚本，可以一键完成所有安装步骤：
# 下载并运行自动安装脚本
chmod +x install-ubuntu.sh
./install-ubuntu.sh
手动安装步骤
如果您希望手动控制安装过程，可以按照以下步骤操作：
1. 更新系统包
sudo apt update
sudo apt upgrade -y
2. 安装Node.js 18.x
方法一：使用NodeSource官方仓库（推荐）
# 添加NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
# 安装Node.js
sudo apt-get install -y nodejs
# 验证安装
node --version
npm --version
方法二：使用snap安装
# 安装Node.js
sudo snap install node --classic
# 验证安装
node --version
npm --version
方法三：使用nvm（Node Version Manager）
# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 重新加载shell配置
source ~/.bashrc
# 安装Node.js 18
nvm install 18
nvm use 18
nvm alias default 18
# 验证安装
node --version
npm --version
3. 安装必要的系统依赖
# 安装构建工具（用于编译native模块）
sudo apt-get install -y build-essential
# 安装Python（某些npm包需要）
sudo apt-get install -y python3 python3-pip
# 安装Git（如果需要从Git仓库安装依赖）
sudo apt-get install -y git
# 安装curl和wget（用于下载文件）
sudo apt-get install -y curl wget
4. 配置npm（可选但推荐）
# 设置npm全局安装路径（避免使用sudo）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# 添加到PATH环境变量
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 设置npm镜像源（加速下载）
npm config set registry https://registry.npmmirror.com
# 验证配置
npm config get registry
5. 安装项目依赖
# 进入项目目录
cd /path/to/mcp_test
# 安装项目依赖
npm install
# 如果遇到权限问题，可以尝试
npm install --unsafe-perm=true --allow-root
6. 设置启动脚本权限
# 给启动脚本添加执行权限
chmod +x start.sh
7. 验证安装
# 检查Node.js版本
node --version
# 检查npm版本
npm --version
# 检查项目依赖
npm list
# 测试启动（可选）
npm start
Docker安装（推荐用于生产环境）
如果您希望使用Docker部署，可以按照以下步骤操作：
1. 安装Docker
# Ubuntu 20.04安装Docker
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 添加Docker仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker
# 将当前用户添加到docker组（可选）
sudo usermod -aG docker $USER
2. 创建Dockerfile
FROM node:18-alpine
# 设置工作目录
WORKDIR /app
# 复制package.json和package-lock.json
COPY package*.json ./
# 安装依赖
RUN npm ci --only=production
# 复制源代码
COPY . .
# 暴露端口
EXPOSE 3000
# 启动命令
CMD ["npm", "start"]
3. 构建和运行Docker容器
# 构建Docker镜像
docker build -t ai-customer-service-mcp .
# 运行容器
docker run -d \
--name mcp-server \
-p 3000:3000 \
-v $(pwd)/data:/app/data \
ai-customer-service-mcp
# 查看容器状态
docker ps
# 查看日志
docker logs mcp-server
4. Docker Compose部署
快速启动（推荐）：
# 使用快速启动脚本
chmod +x docker-start.sh
./docker-start.sh
手动部署：
创建docker-compose.yml文件：
version: '3.8'
services:
mcp-server:
build: .
container_name: ai-customer-service-mcp
ports:
- "3000:3000"
volumes:
- ./data:/app/data
environment:
- NODE_ENV=production
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
启动服务：
# 启动服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
其他Linux发行版
CentOS/RHEL 8+:
# 安装Node.js
sudo dnf module install nodejs:18
# 或使用NodeSource仓库
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install -y nodejs
Debian 11+:
# 使用NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
快速开始
1. 安装依赖
2. 测试功能
# 快速测试（推荐）
node quick-test.js
# 完整测试（需要启动服务器）
./test-mcp-server.sh
# 查看测试指南
cat MANUAL_TEST_GUIDE.md
3. 启动服务器
# 使用启动脚本
./start.sh
# 或直接使用npm
npm start
# 开发模式（自动重启）
npm run dev
4. 配置MCP客户端
将以下配置添加到您的MCP客户端配置文件中：
{
"mcpServers": {
"ai-customer-service": {
"command": "node",
"args": ["src/server.js"],
"cwd": "/path/to/your/mcp_test",
"env": {
"NODE_ENV": "production"
}
}
}
}
可用工具
1. 订单查询工具 (query_order)
根据手机号查询用户的订单详情。
输入参数：
返回信息：
手机号
订单号
租借位置
租借状态
是否允许停止计费
设备ID
租借开始时间
持续时间
计费金额
支付方式
使用示例：
{
"name": "query_order",
"arguments": {
"phone": "17798762697"
}
}
2. 网点查询工具 (query_stores)
根据经纬度查询附近的网点信息。
输入参数：
latitude (number): 纬度 (-90 到 90)
longitude (number): 经度 (-180 到 180)
limit (number, 可选): 返回网点数量限制，默认10个
返回信息：
网点名称
状态
经纬度
详细地址
距离（公里）
营业时间
评分
联系电话
门店类型
使用示例：
{
"name": "query_stores",
"arguments": {
"latitude": 39.946613,
"longitude": 116.370503,
"limit": 5
}
}
数据管理
数据文件位置
门店数据：data/stores.xlsx
订单数据：data/orders.xlsx
数据格式
门店数据格式
字段名 | 类型 | 说明 |
网点名称 | string | 门店名称 |
状态 | string | 营业状态 |
经纬度 | string | 坐标信息 |
省份 | string | 所属省份 |
城市 | string | 所属城市 |
区/县 | string | 所属区县 |
详细地址 | string | 具体地址 |
经度 | number | 经度值 |
纬度 | number | 纬度值 |
门店类型 | string | 门店类型 |
开业时间 | string | 开业日期 |
营业时间 | string | 营业时间段 |
评分 | number | 门店评分 |
联系电话 | string | 联系电话 |
订单数据格式
字段名 | 类型 | 说明 |
订单号 | string | 唯一订单标识 |
用户id | string | 用户标识 |
手机号 | string | 用户手机号 |
设备id | string | 设备标识 |
租借位置 | string | 租借门店 |
租借开始时间 | string | 开始时间 |
退还时间 | string | 退还时间 |
持续时间/分钟 | number | 使用时长 |
归还网点 | string | 归还门店 |
计费 | number | 费用金额 |
租借状态 | string | 订单状态 |
支付方式 | string | 支付方式 |
更新数据
替换 data/ 目录下的Excel文件
重启MCP Server
数据将自动重新加载
项目结构
mcp_test/
├── src/
│ ├── server.js # MCP服务器主文件
│ ├── data-manager.js # 数据管理器
│ └── tools/
│ ├── index.js # 工具导出
│ ├── order-tool.js # 订单查询工具
│ └── store-tool.js # 网点查询工具
├── data/
│ ├── stores.xlsx # 门店数据
│ └── orders.xlsx # 订单数据
├── package.json # 项目配置
├── mcp-config.json # MCP配置示例
├── start.sh # 启动脚本
└── README.md # 项目文档
开发说明
添加新工具
在 src/tools/ 目录下创建新的工具文件
实现工具类，包含静态方法 execute(args, dataManager)
在 src/tools/index.js 中导出新工具
在 src/server.js 中注册新工具
自定义数据源
修改 src/data-manager.js 中的 loadStoresData() 和 loadOrdersData() 方法，支持其他数据源（如数据库、API等）。
错误处理
服务器包含完整的错误处理机制：
性能优化
数据预加载和缓存
高效的距离计算算法
内存优化的数据结构
故障排除
常见问题及解决方案
1. Node.js安装问题
问题： node: command not found
解决方案：
# 检查Node.js是否已安装
which node
# 如果未安装，重新安装
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# 检查PATH环境变量
echo $PATH
2. npm配置问题
问题： npm error 'timeout' is not a valid npm option
解决方案：
# 使用修复脚本
chmod +x fix-npm-config.sh
./fix-npm-config.sh
# 或手动修复
npm config delete timeout
npm config set fetch-timeout 60000
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000
3. npm权限问题
问题： EACCES: permission denied
解决方案：
# 方法1：使用npm配置全局路径
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 方法2：使用sudo（不推荐）
sudo npm install -g
# 方法3：使用nvm管理Node.js版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
4. 依赖安装失败
问题： npm ERR! peer dep missing
解决方案：
# 清理npm缓存
npm cache clean --force
# 删除node_modules和package-lock.json
rm -rf node_modules package-lock.json
# 重新安装
npm install
# 如果仍有问题，尝试使用yarn
npm install -g yarn
yarn install
5. 构建工具缺失
问题： gyp ERR! build error
解决方案：
# 安装构建工具
sudo apt-get install -y build-essential
# 安装Python开发工具
sudo apt-get install -y python3-dev
# 安装其他可能需要的工具
sudo apt-get install -y libssl-dev libffi-dev
6. 网络连接问题
问题： npm ERR! network timeout
解决方案：
# 设置npm镜像源
npm config set registry https://registry.npmmirror.com
# 或使用淘宝镜像
npm config set registry https://registry.npm.taobao.org
# 增加超时时间
npm config set fetch-timeout 60000
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000
# 使用代理（如果需要）
npm config set proxy http://proxy-server:port
npm config set https-proxy http://proxy-server:port
7. 端口占用问题
问题： EADDRINUSE: address already in use
解决方案：
# 查找占用端口的进程
sudo netstat -tulpn | grep :3000
# 或使用lsof
sudo lsof -i :3000
# 杀死占用端口的进程
sudo kill -9 <PID>
# 或使用不同的端口
PORT=3001 npm start
8. 内存不足问题
问题： JavaScript heap out of memory
解决方案：
# 增加Node.js内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
# 或在启动时指定
node --max-old-space-size=4096 src/server.js
# 检查系统内存
free -h
9. 文件权限问题
问题： Permission denied
解决方案：
# 检查文件权限
ls -la start.sh
# 添加执行权限
chmod +x start.sh
# 检查目录权限
ls -la
# 修改目录权限（如果需要）
chmod 755 /path/to/mcp_test
日志和调试
启用详细日志
# 设置调试模式
export DEBUG=*
npm start
# 或使用Node.js调试模式
node --inspect src/server.js
检查系统资源
# 检查CPU使用率
top
# 检查内存使用
free -h
# 检查磁盘空间
df -h
# 检查网络连接
netstat -tulpn
获取帮助
如果遇到其他问题，可以：
查看项目日志文件
检查系统日志：journalctl -u your-service
在GitHub上提交Issue
联系技术支持团队
许可证
MIT License
支持
如有问题或建议，请提交Issue或联系开发团队。