kdniao-mcp 1.0.2
快递鸟MCP服务 - 提供快递物流查询的MCP协议服务
Requires Python: >=3.9
Keywords: express, kdniao, logistics, mcp, 快递鸟, 物流查询

# 快递鸟物流服务 - KDNiao Logistics MCP Service

由快递鸟(www.kdniao.com)提供技术支持的MCP（Model Context Protocol）服务，为AI助手提供专业的物流查询、单号识别、时效预估和地址解析功能。

## 服务提供商

本服务由 **快递鸟(www.kdniao.com)** 提供技术支持，快递鸟是国内领先的物流信息服务提供商，为开发者提供专业、稳定、高效的物流API服务。

## 功能特性

### 核心功能
- **物流轨迹查询**：支持100+快递公司的实时物流轨迹查询，自动识别单号所属快递公司
- **智能单号识别**：自动识别快递单号对应的快递公司，支持一个单号匹配多家快递公司
- **时效预估**：预估快递配送时间和路线，支持发货前和发货后两种场景
- **智能地址解析**：智能解析完整地址信息，拆分省市区街道、姓名、电话等信息

### 技术特性
- **异步架构**：基于FastMCP框架，支持高并发异步处理
- **多传输协议**：支持stdio和SSE两种MCP传输方式
- **完善的错误处理**：统一的异常处理机制和详细的错误信息
- **高性能HTTP客户端**：使用httpx异步客户端，支持连接池、重试机制和超时控制
- **灵活的配置系统**：支持环境变量和配置文件多种配置方式
- **完整的日志系统**：基于loguru的结构化日志，支持文件轮转和多种输出格式
- **品牌标识**：所有响应都包含快递鸟品牌标识和服务信息

## 系统要求

- Python 3.9+
- 快递鸟API账户（EBusinessID和AppKey）

## 安装配置

### 1. 安装依赖

#### 方式一：从源码安装

```bash
git clone <repository-url>
cd mcptrae
pip install -r requirements.txt
```

#### 方式二：使用pip安装（如果已发布到PyPI）

```bash
pip install kdnmcp
```

### 2. 配置环境变量

复制环境变量模板：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的快递鸟API配置：

```env
# 快递鸟API配置
KDNIAO_EBUSINESS_ID=your_ebusiness_id
KDNIAO_APP_KEY=your_app_key
KDNIAO_REQ_URL=https://api.kdniao.com/api/dist

# MCP服务配置
MCP_SERVER_NAME=kdniao-mcp
MCP_SERVER_VERSION=1.0.0
MCP_TRANSPORT=stdio
MCP_HOST=localhost
MCP_PORT=8000

# 日志配置
LOG_LEVEL=INFO
LOG_FORMAT=text
LOG_TO_FILE=true
LOG_FILE_PATH=logs/kdniao-mcp.log
LOG_MAX_SIZE=10MB
LOG_BACKUP_COUNT=5

# 协议配置
PROTOCOL_VERSION=2024-11-05
PROTOCOL_IMPLEMENTATION_NAME=kdniao-mcp
PROTOCOL_IMPLEMENTATION_VERSION=1.0.0

# 请求配置
REQUEST_TIMEOUT=30
REQUEST_MAX_RETRIES=3
REQUEST_RETRY_DELAY=1.0
```

### 3. 获取快递鸟API密钥

1. 访问 [快递鸟官网](https://www.kdniao.com/)
2. 注册账户并实名认证
3. 在管理后台获取 `EBusinessID` 和 `AppKey`
4. 将密钥填入 `.env` 文件

## 使用方法

### 方式一：通过MCP客户端使用（推荐）

在MCP客户端配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "kdniao-mcp": {
      "command": "python",
      "args": ["-m", "kdnmcp"],
      "cwd": "/path/to/mcptrae",
      "env": {
        "KDNIAO_EBUSINESS_ID": "your_ebusiness_id_here",
        "KDNIAO_APP_KEY": "your_app_key_here"
      }
    }
  }
}
```

### 方式二：直接启动MCP服务器

#### 使用Python模块启动

**Stdio模式**（推荐用于AI助手集成）：
```bash
python -m kdnmcp
# 或
python -m kdnmcp --transport stdio
```

**SSE模式**（推荐用于Web集成）：
```bash
python -m kdnmcp --transport sse --port 8000
```

**调试模式**：
```bash
python -m kdnmcp --transport stdio --debug
```

#### 使用主脚本启动

```bash
python main.py --transport stdio
python main.py --transport sse --port 8000
python main.py --transport stdio --debug
```

## 可用工具

### 1. 物流轨迹查询 (track_logistics)

查询快递包裹的实时物流轨迹信息，支持自动识别快递公司。

**参数：**
- `shipper_code` (string): 快递公司编码（如：SF、YTO、ZTO等）
- `logistic_code` (string, 必需): 快递单号
- `mobile` (string, 可选): 寄件人或收件人手机号/座机号后四位（部分快递公司需要）

**特殊说明：**
- 如果不传递 `shipper_code`，系统会自动识别单号所属快递公司
- 顺丰快递查询时建议提供 `mobile` 参数以提高查询成功率

**示例：**
```json
{
  "shipper_code": "SF",
  "logistic_code": "SF1234567890",
  "mobile": "1234"
}
```

### 2. 单号识别 (recognize_logistics_code)

自动识别快递单号对应的快递公司，一个单号可能匹配多家快递公司。

**参数：**
- `logistic_code` (string, 必需): 快递单号

**示例：**
```json
{
  "logistic_code": "1234567890123"
}
```

### 3. 时效预估 (estimate_delivery_time)

预估快递配送时间和路线信息，支持发货前和发货后两种场景。

**参数：**
- `shipper_code` (string, 必需): 快递公司编码
- `send_province` (string, 必需): 发件省份
- `send_city` (string, 必需): 发件城市
- `send_area` (string, 必需): 发件区县
- `receive_province` (string, 必需): 收件省份
- `receive_city` (string, 必需): 收件城市
- `receive_area` (string, 必需): 收件区县
- `logistic_code` (string, 可选): 快递单号（有单号时查询发货后时效）
- `send_address` (string, 可选): 发件详细地址
- `receive_address` (string, 可选): 收件详细地址
- `catch_time` (string, 可选): 揽收时间（格式：YYYY-MM-DD HH:MM:SS）

**重要提示：**
- 如果参数不全，请将相应字段设置为None或空字符串，不要自行补充
- `send_area` 和 `receive_area` 为必填字段

**示例：**
```json
{
  "shipper_code": "SF",
  "send_province": "广东省",
  "send_city": "深圳市",
  "send_area": "南山区",
  "receive_province": "北京市",
  "receive_city": "北京市",
  "receive_area": "海淀区"
}
```

### 4. 智能地址解析 (parse_address)

智能解析完整地址信息，拆分为省市区街道、姓名、电话等信息。

**参数：**
- `content` (string, 必需): 待识别的完整地址

**重要说明：**
- 这个接口的能力是地址拆分，无法实现精准的地址补全功能
- 为提高准确率，地址必须包含城市名称，地址结构要完整、逐级清晰
- 不建议将输出结果直接用于下单，以免造成识别错误
- 地址解析由AI分析，请注意核对解析结果

**示例：**
```json
{
  "content": "张三 13800138000 北京市海淀区彩和坊路74号"
}
```

## 支持的快递公司

系统支持100+快递公司，主要包括：

| 快递公司 | 编码 | 轨迹查询 | 单号识别 | 时效预估 |
|---------|------|---------|---------|----------|
| 顺丰速运 | SF | ✅ | ✅ | ✅ |
| 圆通速递 | YTO | ✅ | ✅ | ✅ |
| 中通快递 | ZTO | ✅ | ✅ | ✅ |
| 申通快递 | STO | ✅ | ✅ | ✅ |
| 韵达速递 | YD | ✅ | ✅ | ✅ |
| 极兔速递 | JTSD | ✅ | ✅ | ✅ |
| 京东物流 | JD | ✅ | ✅ | ✅ |
| 邮政EMS | EMS | ✅ | ✅ | ✅ |
| 德邦快递 | DBL | ✅ | ✅ | ✅ |
| 百世快递 | HTKY | ✅ | ✅ | ✅ |

*完整的快递公司列表请参考 `models/kdniao_docs.py` 文件中的 `SHIPPER_CODES` 映射*

## 物流状态说明

### 物流状态码
- `0`: 暂无轨迹信息
- `1`: 已揽收
- `2`: 在途中
- `3`: 已签收
- `4`: 问题件
- `5`: 转寄

### 详细状态码
系统支持更详细的物流状态码，包括：
- `10`: 已下单
- `20`: 已揽收
- `30`: 运输中
- `40`: 派件中
- `50`: 已签收
- `60`: 异常
- `70`: 转寄

*完整的状态码说明请参考 `models/kdniao_docs.py` 文件*

## 错误处理

服务提供完善的错误处理机制，所有错误都会返回标准化的错误响应：

```json
{
  "success": false,
  "reason": "参数错误：快递公司编码无效",
  "error_code": "INVALID_SHIPPER_CODE",
  "service_provider": "快递鸟(www.kdniao.com)",
  "powered_by": "快递鸟提供技术支持"
}
```

### 常见错误码
- `INVALID_PARAMETER`: 参数无效
- `MISSING_PARAMETER`: 缺少必需参数
- `INVALID_SHIPPER_CODE`: 快递公司编码无效
- `INVALID_LOGISTIC_CODE`: 快递单号格式错误
- `API_REQUEST_FAILED`: API请求失败
- `NETWORK_ERROR`: 网络连接错误
- `TIMEOUT_ERROR`: 请求超时
- `AUTHENTICATION_FAILED`: API认证失败

## 项目架构

```
mcptrae/
├── kdnmcp/                 # 主包目录
│   ├── __init__.py        # 包初始化
│   ├── __main__.py        # 包入口点
│   ├── main.py            # 主启动脚本
│   └── server.py          # MCP服务器实现
├── tools/                 # MCP工具实现
│   ├── __init__.py
│   ├── tracking_tool.py   # 轨迹查询工具
│   ├── recognize_tool.py  # 单号识别工具
│   ├── timeline_tool.py   # 时效预估工具
│   └── address_parse_tool.py # 地址解析工具
├── utils/                 # 工具类
│   ├── __init__.py
│   ├── kdniao_client.py   # 快递鸟API客户端
│   ├── signature.py       # API签名生成
│   ├── logger.py          # 日志配置
│   └── credentials.py     # 凭证管理
├── models/                # 数据模型
│   ├── __init__.py
│   ├── kdniao_models.py   # API数据模型
│   └── kdniao_docs.py     # 快递公司和状态码映射
├── settings/              # 配置管理
│   ├── __init__.py
│   ├── config.py          # 配置类定义
│   └── app_config.py      # 应用配置聚合
├── docs/                  # 文档资源
│   ├── __init__.py
│   └── doc_provider.py    # 文档提供器
├── requirements.txt       # 依赖列表
├── pyproject.toml        # 项目配置
├── .env.example          # 环境变量模板
└── README.md             # 项目说明
```

## 日志记录

服务使用loguru提供强大的日志功能：

### 日志配置
- **日志级别**: DEBUG, INFO, WARNING, ERROR, CRITICAL
- **日志格式**: text（文本格式）, json（JSON格式）
- **输出方式**: 控制台输出 + 可选文件输出
- **日志轮转**: 按大小自动轮转（默认10MB）
- **备份数量**: 默认保留5个备份文件

### 日志文件
日志文件默认保存在 `logs/` 目录下：
- `kdniao-mcp.log`: 主日志文件
- 轮转文件: `kdniao-mcp.log.1`, `kdniao-mcp.log.2` 等

### 日志格式示例

**文本格式：**
```
2024-01-15 10:30:45.123 | INFO | kdnmcp.server:initialize:45 - MCP服务器初始化完成
```

**JSON格式：**
```json
{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "INFO",
  "logger": "kdnmcp.server",
  "function": "initialize",
  "line": 45,
  "message": "MCP服务器初始化完成"
}
```

## 性能优化

### HTTP客户端优化
- **异步HTTP客户端**: 使用httpx异步客户端提高并发性能
- **连接池**: 复用HTTP连接减少延迟
- **请求重试**: 自动重试失败的请求（默认最多3次）
- **超时控制**: 合理的超时设置避免长时间等待（默认30秒）
- **指数退避**: 重试时使用指数退避策略

### 内存和性能
- **异步架构**: 基于asyncio的异步处理
- **资源管理**: 自动管理HTTP连接和资源释放
- **错误隔离**: 单个请求失败不影响其他请求

## 开发调试

### 运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_tracking.py -v

# 运行测试并生成覆盖率报告
pytest tests/ --cov=kdnmcp --cov-report=html
```

### 代码质量检查

```bash
# 代码格式化
black kdnmcp/ tools/ utils/ models/ settings/

# 代码风格检查
flake8 kdnmcp/ tools/ utils/ models/ settings/

# 类型检查
mypy kdnmcp/ tools/ utils/ models/ settings/
```

### 配置检查

```bash
# 检查配置文件
python -m kdnmcp --check-config

# 测试API连接
python -m kdnmcp --test-api
```

### 调试模式

```bash
# 启用调试模式
python -m kdnmcp --transport stdio --debug

# 查看详细日志
LOG_LEVEL=DEBUG python -m kdnmcp
```

## 部署建议

### 生产环境部署

1. **使用进程管理器**（如supervisor、systemd）
2. **配置日志轮转**（如logrotate）
3. **设置环境变量**（避免硬编码密钥）
4. **监控服务状态**（健康检查）
5. **配置防火墙**（仅开放必要端口）
6. **定期备份日志**（重要的业务日志）

### Docker部署

```dockerfile
FROM python:3.9-slim

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .
RUN pip install -r requirements.txt

# 复制源码
COPY . .

# 创建日志目录
RUN mkdir -p logs

# 设置环境变量
ENV PYTHONPATH=/app
ENV LOG_TO_FILE=true
ENV LOG_FILE_PATH=logs/kdniao-mcp.log

# 暴露端口（SSE模式）
EXPOSE 8000

# 启动命令
CMD ["python", "-m", "kdnmcp", "--transport", "sse", "--port", "8000"]
```

### Docker Compose

```yaml
version: '3.8'

services:
  kdniao-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - KDNIAO_EBUSINESS_ID=${KDNIAO_EBUSINESS_ID}
      - KDNIAO_APP_KEY=${KDNIAO_APP_KEY}
      - LOG_LEVEL=INFO
      - MCP_TRANSPORT=sse
      - MCP_PORT=8000
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

## 故障排除

### 常见问题

1. **API认证失败**
   - 检查 `KDNIAO_EBUSINESS_ID` 和 `KDNIAO_APP_KEY` 是否正确
   - 确认快递鸟账户状态正常且有足够的API调用次数
   - 验证API签名生成是否正确

2. **网络连接问题**
   - 检查网络连接和防火墙设置
   - 确认快递鸟API服务地址可访问
   - 调整 `REQUEST_TIMEOUT` 和重试配置

3. **参数验证错误**
   - 检查快递公司编码是否在支持列表中
   - 验证快递单号格式是否正确
   - 确认所有必需参数都已提供

4. **服务启动失败**
   - 检查Python版本是否为3.9+
   - 验证所有依赖是否正确安装
   - 检查配置文件格式和环境变量
   - 查看详细错误日志

5. **MCP协议问题**
   - 确认MCP客户端版本兼容性
   - 检查传输协议配置（stdio/sse）
   - 验证JSON-RPC消息格式

### 调试步骤

1. **启用调试模式**
   ```bash
   python -m kdnmcp --transport stdio --debug
   ```

2. **查看详细日志**
   ```bash
   tail -f logs/kdniao-mcp.log
   ```

3. **测试API连接**
   ```bash
   python -c "from utils.kdniao_client import KDNiaoClient; client = KDNiaoClient(); print('API连接正常')"
   ```

4. **验证配置**
   ```bash
   python -m kdnmcp --check-config
   ```

### 获取帮助

- 查看日志文件获取详细错误信息
- 使用 `--debug` 模式获取更多调试信息
- 检查快递鸟官方文档和API状态
- 提交Issue时请附上相关日志和配置信息

## 许可证

MIT License

## 更新日志

### v1.0.0 (2024-01-XX)

- 初始版本发布
- 实现物流轨迹查询功能，支持自动识别快递公司
- 实现智能单号识别功能
- 实现时效预估功能，支持发货前后两种场景
- 实现智能地址解析功能
- 完整的MCP协议实现，支持stdio和SSE传输方式
- 基于FastMCP框架的异步架构
- 完善的错误处理和日志记录系统
- 灵活的配置管理和环境变量支持
- 高性能HTTP客户端，支持连接池和重试机制

## 技术支持

本服务由 **快递鸟(www.kdniao.com)** 提供技术支持。如有API相关问题，请联系快递鸟官方客服。

---

*快递鸟物流服务 - 让物流查询更简单、更智能*