MCP 服务器

Shipping Service MCP Server

Provides a Model Context Protocol server for managing shipping orders and address book functionality with support for connecting to real shipping services via HTTP API.

README

寄件服务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               # 说明文档