# AI智能客服MCP Server

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

## 功能特性

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

## 系统要求

- Node.js 18.0.0 或更高版本
- npm 或 yarn 包管理器

## 环境安装

### Ubuntu 20.04 安装指南

#### 快速安装（推荐）

我们提供了一个自动安装脚本，可以一键完成所有安装步骤：

```bash
# 下载并运行自动安装脚本
chmod +x install-ubuntu.sh
./install-ubuntu.sh
```

#### 手动安装步骤

如果您希望手动控制安装过程，可以按照以下步骤操作：

#### 1. 更新系统包

```bash
sudo apt update
sudo apt upgrade -y
```

#### 2. 安装Node.js 18.x

**方法一：使用NodeSource官方仓库（推荐）**

```bash
# 添加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安装**

```bash
# 安装Node.js
sudo snap install node --classic

# 验证安装
node --version
npm --version
```

**方法三：使用nvm（Node Version Manager）**

```bash
# 安装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. 安装必要的系统依赖

```bash
# 安装构建工具（用于编译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（可选但推荐）

```bash
# 设置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. 安装项目依赖

```bash
# 进入项目目录
cd /path/to/mcp_test

# 安装项目依赖
npm install

# 如果遇到权限问题，可以尝试
npm install --unsafe-perm=true --allow-root
```

#### 6. 设置启动脚本权限

```bash
# 给启动脚本添加执行权限
chmod +x start.sh
```

#### 7. 验证安装

```bash
# 检查Node.js版本
node --version

# 检查npm版本
npm --version

# 检查项目依赖
npm list

# 测试启动（可选）
npm start
```

### Docker安装（推荐用于生产环境）

如果您希望使用Docker部署，可以按照以下步骤操作：

#### 1. 安装Docker

```bash
# 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

```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容器

```bash
# 构建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部署

**快速启动（推荐）：**

```bash
# 使用快速启动脚本
chmod +x docker-start.sh
./docker-start.sh
```

**手动部署：**

创建`docker-compose.yml`文件：

```yaml
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
```

启动服务：

```bash
# 启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 其他Linux发行版

**CentOS/RHEL 8+:**

```bash
# 安装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+:**

```bash
# 使用NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 测试功能

```bash
# 快速测试（推荐）
node quick-test.js

# 完整测试（需要启动服务器）
./test-mcp-server.sh

# 查看测试指南
cat MANUAL_TEST_GUIDE.md
```

### 3. 启动服务器

```bash
# 使用启动脚本
./start.sh

# 或直接使用npm
npm start

# 开发模式（自动重启）
npm run dev
```

### 4. 配置MCP客户端

将以下配置添加到您的MCP客户端配置文件中：

```json
{
  "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
- 租借开始时间
- 持续时间
- 计费金额
- 支付方式

**使用示例：**
```json
{
  "name": "query_order",
  "arguments": {
    "phone": "17798762697"
  }
}
```

### 2. 网点查询工具 (query_stores)

根据经纬度查询附近的网点信息。

**输入参数：**
- `latitude` (number): 纬度 (-90 到 90)
- `longitude` (number): 经度 (-180 到 180)
- `limit` (number, 可选): 返回网点数量限制，默认10个

**返回信息：**
- 网点名称
- 状态
- 经纬度
- 详细地址
- 距离（公里）
- 营业时间
- 评分
- 联系电话
- 门店类型

**使用示例：**
```json
{
  "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`

**解决方案：**
```bash
# 检查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`

**解决方案：**
```bash
# 使用修复脚本
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`

**解决方案：**
```bash
# 方法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`

**解决方案：**
```bash
# 清理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`

**解决方案：**
```bash
# 安装构建工具
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`

**解决方案：**
```bash
# 设置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`

**解决方案：**
```bash
# 查找占用端口的进程
sudo netstat -tulpn | grep :3000

# 或使用lsof
sudo lsof -i :3000

# 杀死占用端口的进程
sudo kill -9 <PID>

# 或使用不同的端口
PORT=3001 npm start
```

#### 8. 内存不足问题

**问题：** `JavaScript heap out of memory`

**解决方案：**
```bash
# 增加Node.js内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 或在启动时指定
node --max-old-space-size=4096 src/server.js

# 检查系统内存
free -h
```

#### 9. 文件权限问题

**问题：** `Permission denied`

**解决方案：**
```bash
# 检查文件权限
ls -la start.sh

# 添加执行权限
chmod +x start.sh

# 检查目录权限
ls -la

# 修改目录权限（如果需要）
chmod 755 /path/to/mcp_test
```

### 日志和调试

#### 启用详细日志

```bash
# 设置调试模式
export DEBUG=*
npm start

# 或使用Node.js调试模式
node --inspect src/server.js
```

#### 检查系统资源

```bash
# 检查CPU使用率
top

# 检查内存使用
free -h

# 检查磁盘空间
df -h

# 检查网络连接
netstat -tulpn
```

### 获取帮助

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

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

## 许可证

MIT License

## 支持

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