寄件服务MCP Server
提供寄件订单管理、地址簿查询等功能的Model Context Protocol (MCP) Server，支持通过HTTP API对接远程寄件服务。
功能特性
🏠 地址簿管理
- 查询用户保存的地址簿数据
- 支持关键词搜索（姓名、电话、地址）
- 标识默认地址
📦 寄件订单管理
- 创建新的寄件订单
- 分页查询订单列表
- 查询订单详细信息
- 支持多种服务类型（标准/快速/经济）
- 订单状态追踪
🔍 高级查询
- 按日期范围过滤订单
- 按订单状态过滤
- 分页浏览订单列表
- 完整物流追踪记录
🌐 API集成
- 支持HTTP API对接真实寄件服务
- 灵活的配置管理（命令行参数/环境变量）
- Mock模式用于开发和测试
- 完善的错误处理和重试机制
安装
使用 uvx（推荐）
# 直接运行，无需安装
uvx guoguo-mcp-server --help
# 如果遇到包未找到的问题，可以指定索引
uvx --index-url https://pypi.org/simple/ guoguo-mcp-server --help
使用 pip
pip install guoguo-mcp-server
注意: 新发布的包可能需要几分钟时间在各个 PyPI 镜像中同步。如果遇到包未找到的错误，请稍等片刻再试，或使用 pip 安装后直接使用命令。
使用方法
配置API参数
方法1: 通过命令行参数
# 使用真实API
guoguo-mcp-server --api-url https://api.sf-express.com --token your_access_token --no-mock
# 或使用 uvx
uvx guoguo-mcp-server --api-url https://api.sf-express.com --token your_access_token --no-mock
# 使用模拟数据（开发测试）
guoguo-mcp-server --use-mock
方法2: 通过环境变量
export SHIPPING_API_BASE_URL="https://api.sf-express.com"
export SHIPPING_API_TOKEN="your_access_token"
export SHIPPING_USE_MOCK="false"
guoguo-mcp-server
方法3: 在Claude Desktop中配置
使用 uvx（推荐，无需预安装）:
{
"mcpServers": {
"guoguo-mcp-server": {
"command": "uvx",
"args": [
"guoguo-mcp-server",
"--api-url", "https://api.sf-express.com",
"--token", "your_access_token",
"--no-mock"
]
}
}
}
使用已安装的包:
{
"mcpServers": {
"guoguo-mcp-server": {
"command": "guoguo-mcp-server",
"args": [
"--api-url", "https://api.sf-express.com",
"--token", "your_access_token",
"--no-mock"
]
}
}
}
使用模拟模式（开发测试）:
{
"mcpServers": {
"guoguo-mcp-server": {
"command": "uvx",
"args": [
"guoguo-mcp-server",
"--use-mock"
]
}
}
}
开发模式运行
# 使用模拟数据（默认）
guoguo-mcp-server --use-mock
# 使用 uvx（无需安装）
uvx guoguo-mcp-server --use-mock
# 使用 mcp 开发工具
mcp dev guoguo-mcp-server -- --use-mock
生产模式运行
# 连接真实API
guoguo-mcp-server \
--api-url https://api.your-shipping-provider.com \
--token your_production_token \
--no-mock
# 或使用 uvx
uvx guoguo-mcp-server \
--api-url https://api.your-shipping-provider.com \
--token your_production_token \
--no-mock
工具列表
1. 地址簿查询 (query_address_book)
查询用户的地址簿信息
参数:
search_key (可选): 搜索关键词，可以搜索姓名、电话或地址
返回:
{
"status": "success",
"total_count": 4,
"addresses": [
{
"name": "张三",
"phone": "13800138000",
"address": "北京市朝阳区中关村大街1号",
"is_default": true
}
]
}
2. 创建寄件订单 (create_shipping_order)
创建新的寄件订单
参数:
sender_name: 寄件人姓名sender_phone: 寄件人电话sender_address: 寄件人地址receiver_name: 收件人姓名receiver_phone: 收件人电话receiver_address: 收件人地址package_type: 物品类型package_weight: 重量(kg)package_size: 尺寸(长x宽x高,cm)service_type: 服务类型(标准/快速/经济)
返回:
{
"status": "success",
"order_id": "SF2024003",
"estimated_cost": 18.4,
"estimated_delivery": "2024-01-15 14:30:00",
"pickup_time": "24小时内安排取件"
}
3. 查询订单列表 (list_shipping_orders)
分页查询寄件订单列表
参数:
page_size: 每页数量（默认10）page_number: 页码，从1开始（默认1）start_date: 开始日期(YYYY-MM-DD格式)end_date: 结束日期(YYYY-MM-DD格式)status: 订单状态过滤
返回:
{
"status": "success",
"orders": [...],
"pagination": {
"total_count": 2,
"total_pages": 1,
"current_page": 1,
"page_size": 10,
"has_next": false,
"has_prev": false
}
}
4. 查询订单详情 (get_order_detail)
获取订单详细信息
参数:
order_id: 订单号detail_level: 详情级别(basic/full)
返回:
{
"status": "success",
"order_info": {
"order_id": "SF2024001",
"status": "已签收",
"create_time": "2024-01-13 10:30:00",
"service_type": "快速"
},
"sender_info": {...},
"receiver_info": {...},
"package_info": {...},
"tracking_history": [...]
}
订单状态说明
- 待取件: 订单已创建，等待快递员取件
- 运输中: 包裹正在运输途中
- 派送中: 包裹已到达目的地，正在派送
- 已签收: 包裹已成功签收
- 已退回: 包裹已退回寄件人
- 已取消: 订单已取消
服务类型说明
- 标准: 48小时送达，费用标准
- 快速: 24小时送达，费用1.5倍
- 经济: 72小时送达，费用0.8倍
开发
项目结构
guoguo-mcp-server/
├── src/
│ └── guoguo_mcp/
│ └── __init__.py # 主服务器代码
├── requirements.txt # Python依赖
├── pyproject.toml # 项目配置
├── test_client.py # 测试客户端
├── run_server.py # 启动脚本
└── README.md # 说明文档
代码说明
服务器使用了以下主要组件：
- FastMCP: MCP协议的Python实现
- 数据模型: 使用dataclass定义订单、地址等数据结构
- 枚举类型: 定义订单状态和服务类型
- 模拟数据: 内存中存储示例数据，实际应用中可替换为数据库
扩展功能
可以进一步扩展的功能：
- 集成真实的快递API
- 添加数据库持久化
- 实现用户认证
- 添加订单状态更新功能
- 集成支付功能
- 添加物流追踪API
许可证
MIT License
贡献
欢迎提交Issue和Pull Request来改进这个项目。