Guoguo Mcp Python

电商 Python

🚀 寄件服务MCP Server

寄件服务MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，它提供了寄件订单管理、地址簿查询等功能，支持通过 HTTP API 对接远程寄件服务，为寄件业务的管理和操作提供了高效便捷的解决方案。

🚀 快速开始

寄件服务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 来改进这个项目。

0 条评论
分类：电商