AI智能客服MCP Server

这是一个基于Model Context Protocol (MCP) 的AI智能客服系统核心服务器，提供订单查询和网点查询功能。

功能特性

• ✅ 支持标准MCP协议，与MCP客户端通过SSE进行通信
• ✅ 提供订单查询工具：根据手机号查询订单详情
• ✅ 提供网点查询工具：根据经纬度查询附近网点信息
• ✅ 支持Excel数据文件导入
• ✅ 内置示例数据，开箱即用
• ✅ 支持与腾讯智能体开放平台ADP集成

系统要求

• 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. 安装依赖

npm install

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)

根据手机号查询用户的订单详情。

输入参数：

• phone (string): 用户手机号

返回信息：

• 手机号
• 订单号
• 租借位置
• 租借状态
• 是否允许停止计费
• 设备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	支付方式

更新数据

1. 替换 data/ 目录下的Excel文件
2. 重启MCP Server
3. 数据将自动重新加载

项目结构

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                 # 项目文档

开发说明

添加新工具

1. 在 src/tools/ 目录下创建新的工具文件
2. 实现工具类，包含静态方法 execute(args, dataManager)
3. 在 src/tools/index.js 中导出新工具
4. 在 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

获取帮助

如果遇到其他问题，可以：

1. 查看项目日志文件
2. 检查系统日志：journalctl -u your-service
3. 在GitHub上提交Issue
4. 联系技术支持团队

许可证

MIT License

支持

如有问题或建议，请提交Issue或联系开发团队。