寄件服务MCP Server

提供寄件订单管理、地址簿查询等功能的Model Context Protocol (MCP) Server，支持通过HTTP API对接远程寄件服务。

功能特性

🏠 地址簿管理

• 查询用户保存的地址簿数据
• 支持关键词搜索（姓名、电话、地址）
• 标识默认地址

📦 寄件订单管理

• 创建新的寄件订单
• 分页查询订单列表
• 查询订单详细信息
• 支持多种服务类型（标准/快速/经济）
• 订单状态追踪

🔍 高级查询

• 按日期范围过滤订单
• 按订单状态过滤
• 分页浏览订单列表
• 完整物流追踪记录

🌐 API集成

• 支持HTTP API对接真实寄件服务
• 灵活的配置管理（命令行参数/环境变量）
• Mock模式用于开发和测试
• 完善的错误处理和重试机制

安装

使用 uv（推荐）

uv init shipping-mcp-server
cd shipping-mcp-server
uv add "mcp[cli]>=1.0.0"

使用 pip

pip install "mcp[cli]>=1.0.0"

使用方法

配置API参数

方法1: 通过命令行参数

# 使用真实API
python src/guoguo_mcp/__init__.py --api-url https://api.sf-express.com --token your_access_token --no-mock

# 使用模拟数据（开发测试）
python src/guoguo_mcp/__init__.py --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"
python src/guoguo_mcp/__init__.py

方法3: 在Claude Desktop中配置

{
  "mcpServers": {
    "guoguo-shipping": {
      "command": "python",
      "args": [
        "/path/to/guoguo_mcp/src/guoguo_mcp/__init__.py",
        "--api-url", "https://api.sf-express.com",
        "--token", "your_access_token",
        "--no-mock"
      ],
      "env": {
        "PATH": "/path/to/venv/bin:/usr/bin:/bin"
      }
    }
  }
}

开发模式运行

# 使用模拟数据（默认）
python src/guoguo_mcp/__init__.py

# 使用 mcp 开发工具
mcp dev src/guoguo_mcp/__init__.py -- --use-mock

# 使用 uv
uv run python src/guoguo_mcp/__init__.py --use-mock

生产模式运行

# 连接真实API
python src/guoguo_mcp/__init__.py \
  --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来改进这个项目。