AI导哈

客户订单分析服务器

一个基于FastAPI的MCP服务器，提供AI驱动的工具，用于查询客户和订单数据，支持客户分析和订单管理。

  • by JoaoToledoSE
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 joaotoledose/mcp-server

使用说明

MCP服务器-客户和订单分析

A. 模型上下文协议（MCP） 服务器实现，提供人工智能驱动的工具来查询客户和订单数据。这个基于FastAPI的服务器使LLM客户端能够通过三个用于客户分析和订单管理的专用工具访问结构化业务数据。

🚀 概述

此MCP服务器充当AI语言模型和业务数据之间的桥梁，允许LLM：

  • 按月统计客户订单
  • 按国家检索最近的客户
  • 计算客户终身价值和支出模式

服务器遵循模型上下文协议规范，使其与支持MCP集成的各种AI客户端和框架兼容。

✨ 特性

核心MCP工具

  1. 按客户和月份的订单计数 -随着时间的推移跟踪客户订购模式
  2. 按国家/地区列出的最新客户 -发现特定市场的新客户
  3. 客户总支出 -分析客户终身价值和消费行为

技术特性

  • FastAPI框架 -具有自动文档的高性能异步API
  • Pydantic验证 -具有自动验证功能的类型安全数据模型
  • JSON数据后端 -为客户和订单提供简单的基于文件的存储
  • 综合录井 -用于调试的完整请求/响应日志记录
  • 健康监测 -内置健康检查端点
  • CORS支持 -为web客户端启用了跨源请求

🏗️ 建筑

mcp-server/
├── main.py                     # FastAPI application entry point
├── requirements.txt            # Python dependencies
├── data/                       # JSON data files
│   ├── customers.json          # Customer records
│   └── orders.json             # Order transactions
├── src/                        # Source code
│   ├── models/                 # Data models and schemas
│   │   ├── schemas.py          # Pydantic models for validation
│   │   └── data_loader.py      # Data loading utilities
│   └── tools/                  # MCP tools implementation
│       └── mcp_tools.py        # Tool implementations
├── tests/                      # Test suite
├── llm_client/                 # Example LLM client implementation
└── docs/                       # Documentation

🛠️ 可用工具

1.获得订单、订单、客户和月份

统计给定日历月内特定客户的订单。

输入：

{
  "customerName": "John Doe",
  "isoMonth": "2025-03"
}

输出：

{
  "count": 2
}

2.按国家列出最近的客户

从特定国家获取最新的N个客户。

输入：

{
  "country": "USA",
  "limit": 5
}

输出：

{
  "customers": [
    {
      "id": 1,
      "name": "John Doe",
      "country": "USA",
      "joinedAt": "2025-01-15T10:30:00Z",
      "totalSpend": 1250.50,
      "orderCount": 3
    }
  ]
}

3.获取客户总额

计算客户的总支出和订单统计数据。

输入：

{
  "customerName": "John Doe"
}

输出：

{
  "customerName": "John Doe",
  "totalSpend": 1250.50,
  "orderCount": 3,
  "averageOrderValue": 416.83
}

🚦 快速开始

先决条件

  • Python 3.9+
  • pip或poetry用于依赖管理

安装

  1. 克隆存储库：
git clone <repository-url>
cd mcp-server
  1. 安装依赖项：
pip install -r requirements.txt
  1. 启动服务器：
python main.py

服务器将于启动 http://localhost:8000

生产部署

uvicorn main:app --host 0.0.0.0 --port 8000

📡 API终点

健康检查

  • 获取 / -基本健康检查
  • 获取 /health -详细的健康状况

MCP协议端点

  • 获取 /tools/list -列出可用的MCP工具
  • 发布 /tools/call -执行特定工具

示例用法

列出可用工具：

curl http://localhost:8000/tools/list

调用工具：

curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_order_count_by_customer_and_month",
    "arguments": {
      "customerName": "John Doe",
      "isoMonth": "2025-03"
    }
  }'

🧪 测试

运行测试套件：

pytest tests/

跑步覆盖：

pytest tests/ --cov=src --cov-report=html

🔧 配置

环境变量

  • HOST -服务器主机（默认值：0.0.0.0）
  • PORT -服务器端口（默认值：8000）
  • LOG_LEVEL -日志记录级别（默认值：INFO）

数据文件

服务器从JSON文件中读取 data/ 目录：

  • customers.json -带有id、姓名、国家、joined的客户记录
  • orders.json -带有id、customerId、customerName、日期、金额的订单记录

🤝 整合

LLM客户端示例

此存储库包括一个示例LLM客户端(llm_client/)演示了如何使用Mistral AI与MCP服务器集成。客户端：

  • 连接到MCP服务器
  • 使用Mistral AI进行自然语言处理
  • 根据用户问题自动调用相应的MCP工具
  • 返回具有真实数据的AI生成答案

与其他AI框架一起使用

该服务器与支持模型上下文协议的任何系统兼容，包括：

  • 克劳德桌面
  • 自定义AI应用程序
  • 其他MCP兼容框架

📚 文档

  • 安装指南 -详细的设置和使用说明
  • 建筑 -技术架构和设计决策
  • API文档 -交互式API文档（当服务器正在运行时）

🛡️ 错误处理

服务器提供全面的错误处理：

  • 400错误请求 -输入参数无效
  • 404未找到 -未知工具名称
  • 500内部服务器错误 -服务器端错误

所有错误均遵循MCP协议格式，并附有详细的错误消息。

🔄 发展

添加新工具

  1. 在中定义工具模式 src/tools/mcp_tools.py
  2. 执行工具逻辑
  3. 使用Pydantic模型添加输入验证
  4. 更新工具定义列表
  5. 添加综合测试

代码的风格

  • 遵循PEP 8指南
  • 全程使用类型提示
  • 为所有公共方法添加文档字符串
  • 保持测试覆盖率在80%以上

相关 MCP