使用说明

电商售后支持助手 🤖

一个为电子商务平台打造的智能AI客服助手，构建于 模型上下文协议（MCP） 用于动态功能发现和 OpenAI GPT-4（注：GPT-4是OpenAI开发的第四代大型语言模型，此处为直接翻译，未添加额外解释） 用于自然语言理解。

🌟 概述

这个项目实现了一个完整的售后支持聊天机器人系统，通过自然对话帮助客户管理订单。该系统使用MCP（可能是指某种中间件或通信协议）从后端服务中动态发现可用功能，从而无需硬编码函数定义即可实现系统的可扩展性和可维护性。

主要特点

🔍 动态功能发现自动从MCP服务器发现可用操作
🤖 通用参数收集函数调用前收集所需参数的通用规则
💬 对话式人工智能使用OpenAI GPT-4进行自然语言处理
📝 基于会话的历史记录在交互过程中保持对话上下文
🌐 现代网页用户界面使用React和TypeScript实现带实时更新的界面
🐳 完全支持 Docker容器化微服务架构
**🔄 启用CORS（跨源资源共享）**浏览器友好的API，具备适当的CORS配置

🏗️ 建筑学

┌─────────────────────────────────────────────────────────────┐
│                       Chat UI (React)                        │
│                    http://localhost:3000                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ REST API
┌───────────────────────────▼─────────────────────────────────┐
│                    Chat API (Spring Boot)                    │
│              OpenAI Integration + MCP Client                 │
│                    http://localhost:8082                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP Protocol
┌───────────────────────────▼─────────────────────────────────┐
│              Order API MCP Server (Spring Boot)              │
│              Dynamic Tool Discovery + Execution              │
│                    http://localhost:8081                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ REST API
┌───────────────────────────▼─────────────────────────────────┐
│                Order API (Spring Boot)                       │
│                   Order Management CRUD                      │
│                    http://localhost:8080                     │
└─────────────────────────────────────────────────────────────┘

🚀 快速入门

先决条件

Docker 与 Docker Compose
OpenAI API密钥

1. 设置您的OpenAI API密钥

export OPENAI_API_KEY="your-openai-api-key-here"

2. 启动所有服务

docker-compose up -d

3. 访问聊天界面

打开您的浏览器并导航至： http://localhost:3000 翻译为中文是：“本地主机上的3000端口”。不过，在中文语境中，我们通常直接说网址或地址，而不特别翻译其含义，所以也可以直接表述为“http://localhost:3000（本地主机3000端口）”。但简化的说法就是“http://localhost:3000”

4. 开始聊天

试试这些例子：

“给我看看我的订单”
“我想取消我的订单”（如果您有多个订单，助手会询问是哪一个）
“取消订单号1”
“订单2的状况如何？”

📦 组件

1. 聊天用户界面 (React + TypeScript)

一个现代、响应式的聊天界面，具备：

实时消息更新
对话历史记录显示
会话管理
函数调用指示器
精美的动画

位置: chat-ui/ 港口3000 技术栈React 18、TypeScript、Vite、Axios

2. 聊天API （Spring Boot）

基于人工智能的聊天机器人后端，其功能包括：

与OpenAI GPT-4集成
每次会话保持对话历史记录
动态发现MCP工具
应用通用参数收集规则
处理浏览器访问的CORS（跨域资源共享）

位置： chat-api/ 港口8082 技术栈Java 17，Spring Boot 3.2.0，WebClient

关键特性：

通用提示规则在调用任何函数之前，自动收集所有必需的参数
动态工具发现在运行时从MCP服务器构建OpenAI函数定义
会话管理在多次交互中保持对话上下文

3. 订单API MCP服务器（Spring Boot）

将订单管理操作作为AI可调用工具暴露的MCP服务器：

位置： order-api-mcp/ 港口8081 技术栈Java 17，Spring Boot 3.2.0

可用工具：

get_all_orders - 获取所有订单
get_order_by_id - 通过ID获取特定订单
create_order - 创建一个新订单
update_order - 更新现有订单
cancel_order - 取消订单

每个工具都包含用于参数验证的JSON模式。

4. 订单API （Spring Boot）

核心订单管理REST API，具备：

订单的CRUD操作
Bean验证
异常处理
Swagger 文档
内存数据存储

位置： order-api/ 港口8080 技术栈Java 17，Spring Boot 3.2.0，OpenAPI 3

🎯 工作原理

动态功能发现流程

工具发现聊天API向MCP服务器查询可用工具
模式解析将MCP工具定义转换为OpenAI函数格式
运行时绑定OpenAI动态接收函数定义
参数收集通用规则确保收集所有必需的参数
函数执行MCP客户端调用相应的MCP工具
响应处理AI将结果格式化为自然对话形式

通用参数集合

该系统使用 通用规则 而不是功能特定的指令：

1. Collect ALL required parameters before calling any function
2. NEVER assume values - always ask the user explicitly
3. When multiple options exist, ALWAYS ask user to specify
4. For ambiguous requests:
   a) First list available options
   b) Then ask user to make specific choice
5. Only call functions with complete parameters

这种方法使系统 可扩展的 - 任何新的MCP功能都能自动受益于这些规则，而无需更新系统提示。

🛠️ 开发

在本地运行服务

聊天用户界面

cd chat-ui
npm install
npm run dev

聊天API

cd chat-api
mvn spring-boot:run

订单API MCP

cd order-api-mcp
mvn spring-boot:run

订单API

cd order-api
mvn spring-boot:run

重建 Docker 镜像

# Build all services
docker-compose build

# Or build individually
docker build -t order-api:latest ./order-api
docker build -t order-api-mcp:latest ./order-api-mcp
docker build -t chat-api:latest ./chat-api
docker build -t chat-ui:latest ./chat-ui

🧪 测试

测试聊天API

curl -X POST http://localhost:8082/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Show me my orders",
    "sessionId": "test-session-001"
  }'

测试MCP服务器

# List available tools
curl http://localhost:8081/mcp/tools

# Get all orders via MCP
curl -X POST http://localhost:8081/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_all_orders",
    "arguments": {}
  }'

测试订单API

# Get all orders
curl http://localhost:8080/api/orders

# Create order
curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "items": [{
      "itemName": "Laptop",
      "quantity": 1,
      "price": 999.99
    }],
    "totalAmount": 999.99,
    "status": "PENDING",
    "address": "123 Main St"
  }'

📊 容器管理

检查状态

docker-compose ps

查看日志

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f chat-api

停止服务

docker-compose down

重启服务

docker-compose restart

🔧 配置

环境变量

聊天API：

OPENAI_API_KEY您的OpenAI API密钥（必需）
MCP_SERVER_URLMCP服务器端点（默认：http://order-api-mcp:8081）

订单API MCP：

ORDER_API_URL订单API终端（默认：http://order-api:8080/api/orders）

聊天用户界面：

VITE_API_URL聊天API端点（默认：http://localhost:8082）

自定义 docker-compose.yml 文件

services:
  chat-api:
    environment:
      - OPENAI_API_KEY=your-key-here
      - MCP_SERVER_URL=http://order-api-mcp:8081
    ports:
      - "8082:8082"

📚 API 文档

订单API Swaggerhttp://localhost:8080/swagger-ui.html 翻译成中文是：“http://本地主机:8080/swagger-ui.html” 或者 “访问本地主机8080端口的Swagger UI页面”
订单API 开放API规范http://localhost:8080/v3/api-docs
聊天API健康状况http://localhost:8082/api/chat/health 翻译为中文是：“本地主机8082端口的聊天健康检查API”。不过，通常我们不会直接翻译这样的URL地址，而是根据上下文或用途来解释其意义。在这里，“localhost:8082”表示本地运行的服务，监听8082端口；“/api/chat/health”则可能是一个用于检查聊天服务健康状态的API接口路径

🎨 功能亮点

1. 动态工具发现

没有硬编码的函数定义。系统自动：

查询MCP服务器上的可用工具
解析工具模式和描述
生成OpenAI函数定义
在系统提示中更新功能列表

2. 通用参数收集

通用规则适用于所有功能：

避免对缺失参数做出假设
智能处理模糊请求
在询问选择之前列出选项
确保执行前数据完整

3. 对话历史

基于会话的内存：

在交互过程中保持上下文连贯性
记住之前的函数调用
提供连贯的多轮对话
每个用户的独立会话

4. 现代用户界面/用户体验（UI/UX）

美观的聊天界面，具备：

右侧用户消息（蓝色）
左侧（白色）为AI消息
加载指示器
函数调用徽章
流畅的动画
响应式设计

🐛 故障排除

CORS 错误

确保 chat-api has（在中文中，这个单词本身是英文中的一个动词，表示“有”的意思，直接翻译为中文即为“有”，但根据上下文，具体翻译可能有所不同） WebConfig.java 具有适当的CORS设置
检查浏览器控制台以查看具体的CORS问题
验证允许的来源包括 http://localhost:3000

OpenAI API 错误

验证 OPENAI_API_KEY 设置正确
检查API密钥是否拥有足够的信用额度
查看聊天API日志： docker logs chat-api-container

容器无法启动

# Check logs
docker-compose logs

# Check health status
docker inspect order-api-container | jq '.[0].State.Health'

# Restart specific service
docker-compose restart chat-api

端口冲突

# Find process using port
lsof -ti:8080

# Kill process
lsof -ti:8080 | xargs kill -9

🚧 路线图/发展蓝图

[ ] 添加身份验证和用户管理
[ ] 实现持久化数据库（PostgreSQL）
[ ] 添加更多MCP工具（发货、退货、退款）
[ ] 实施速率限制
[ ] 添加全面的测试覆盖率
[ ] 部署到生产环境
[ ] 添加监控和可观测性
[ ] 多语言支持

📝 许可证

麻省理工学院（MIT）

🤝 贡献

克隆该仓库
创建你的特性分支（git checkout -b feature/amazing-feature)
提交您的更改（git commit -m 'Add amazing feature')
推送到分支（git push origin feature/amazing-feature)
打开一个拉取请求

📞 联系我们

如有问题或疑问，请在GitHub上提交一个议题。

构建于 ❤️ 使用模型上下文协议、OpenAI GPT-4、Spring Boot 和 React