kdnmcp 1.0.2

快递鸟MCP服务 - 提供快递物流查询的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. 安装依赖

方式一：从源码安装

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

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

pip install kdnmcp

2. 配置环境变量

复制环境变量模板：

cp .env.example .env

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

# 快递鸟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. 访问 快递鸟官网
2. 注册账户并实名认证
3. 在管理后台获取 EBusinessID 和 AppKey
4. 将密钥填入 .env 文件

使用方法

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

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

{
  "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助手集成）：

python -m kdnmcp
# 或
python -m kdnmcp --transport stdio

SSE模式（推荐用于Web集成）：

python -m kdnmcp --transport sse --port 8000

调试模式：

python -m kdnmcp --transport stdio --debug

使用主脚本启动

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 参数以提高查询成功率

示例：

{
  "shipper_code": "SF",
  "logistic_code": "SF1234567890",
  "mobile": "1234"
}

2. 单号识别 (recognize_logistics_code)

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

参数：

• logistic_code (string, 必需): 快递单号

示例：

{
  "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 为必填字段

示例：

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

4. 智能地址解析 (parse_address)

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

参数：

• content (string, 必需): 待识别的完整地址

重要说明：

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

示例：

{
  "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 文件

错误处理

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

{
  "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格式：

{
  "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连接和资源释放
• 错误隔离: 单个请求失败不影响其他请求

开发调试

运行测试

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

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

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

代码质量检查

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

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

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

配置检查

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

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

调试模式

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

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

部署建议

生产环境部署

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

Docker部署

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

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. 启用调试模式

   python -m kdnmcp --transport stdio --debug
   

2. 查看详细日志

   tail -f logs/kdniao-mcp.log
   

3. 测试API连接

   python -c "from utils.kdniao_client import KDNiaoClient; client = KDNiaoClient(); print('API连接正常')"
   

4. 验证配置

   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相关问题，请联系快递鸟官方客服。

---

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