Shipping Service MCP Server

# 寄件服务MCP Server 提供寄件订单管理、地址簿查询等功能的Model Context Protocol (MCP) Server，支持通过HTTP API对接远程寄件服务。 ## 功能特性 ### 🏠 地址簿管理 - 查询用户保存的地址簿数据 - 支持关键词搜索（姓名、电话、地址） - 标识默认地址 ### 📦 寄件订单管理 - 创建新的寄件订单 - 分页查询订单列表 - 查询订单详细信息 - 支持多种服务类型（标准/快速/经济） - 订单状态追踪 ### 🔍 高级查询 - 按日期范围过滤订单 - 按订单状态过滤 - 分页浏览订单列表 - 完整物流追踪记录 ### 🌐 API集成 - 支持HTTP API对接真实寄件服务 - 灵活的配置管理（命令行参数/环境变量） - Mock模式用于开发和测试 - 完善的错误处理和重试机制 ## 安装 ### 使用 uvx（推荐） ```bash # 直接运行，无需安装 uvx guoguo-mcp-server --help # 如果遇到包未找到的问题，可以指定索引 uvx --index-url https://pypi.org/simple/ guoguo-mcp-server --help ``` ### 使用 pip ```bash pip install guoguo-mcp-server ``` > **注意**: 新发布的包可能需要几分钟时间在各个 PyPI 镜像中同步。如果遇到包未找到的错误，请稍等片刻再试，或使用 pip 安装后直接使用命令。 ## 使用方法 ### 配置API参数 #### 方法1: 通过命令行参数 ```bash # 使用真实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: 通过环境变量 ```bash 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（推荐，无需预安装）:** ```json { "mcpServers": { "guoguo-mcp-server": { "command": "uvx", "args": [ "guoguo-mcp-server", "--api-url", "https://api.sf-express.com", "--token", "your_access_token", "--no-mock" ] } } } ``` **使用已安装的包:** ```json { "mcpServers": { "guoguo-mcp-server": { "command": "guoguo-mcp-server", "args": [ "--api-url", "https://api.sf-express.com", "--token", "your_access_token", "--no-mock" ] } } } ``` **使用模拟模式（开发测试）:** ```json { "mcpServers": { "guoguo-mcp-server": { "command": "uvx", "args": [ "guoguo-mcp-server", "--use-mock" ] } } } ``` ### 开发模式运行 ```bash # 使用模拟数据（默认） guoguo-mcp-server --use-mock # 使用 uvx（无需安装） uvx guoguo-mcp-server --use-mock # 使用 mcp 开发工具 mcp dev guoguo-mcp-server -- --use-mock ``` ### 生产模式运行 ```bash # 连接真实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` (可选): 搜索关键词，可以搜索姓名、电话或地址 **返回:** ```json { "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`: 服务类型(标准/快速/经济) **返回:** ```json { "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`: 订单状态过滤 **返回:** ```json { "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) **返回:** ```json { "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来改进这个项目。