Skip to main content
Glama

AI Customer Service MCP Server

by yakir-Yang

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唯一订单标识
用户idstring用户标识
手机号string用户手机号
设备idstring设备标识
租借位置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或联系开发团队。

-
security - not tested
F
license - not found
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A customer service MCP server that enables order lookup by phone number and store location queries by coordinates. Supports Excel data import and provides comprehensive customer service tools for order management and store information retrieval.

  1. 功能特性
    1. 系统要求
      1. 环境安装
        1. Ubuntu 20.04 安装指南
        2. Docker安装(推荐用于生产环境)
        3. 其他Linux发行版
      2. 快速开始
        1. 1. 安装依赖
        2. 2. 测试功能
        3. 3. 启动服务器
        4. 4. 配置MCP客户端
      3. 可用工具
        1. 1. 订单查询工具 (query_order)
        2. 2. 网点查询工具 (query_stores)
      4. 数据管理
        1. 数据文件位置
        2. 数据格式
        3. 更新数据
      5. 项目结构
        1. 开发说明
          1. 添加新工具
          2. 自定义数据源
        2. 错误处理
          1. 性能优化
            1. 故障排除
              1. 常见问题及解决方案
              2. 日志和调试
              3. 获取帮助
            2. 许可证
              1. 支持

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/yakir-Yang/mcp_demo'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server