包裹跟踪MCP服务器
一个模型上下文协议（MCP）服务器，使AI代理能够使用FedEx、UPS、DHL和OnTrac API跟踪包裹。该服务器提供标准化的跟踪工具，可供任何兼容MCP的AI代理或应用程序使用。
快速开始
要运行MCP服务器，请执行以下操作：
python -m src要使用Claude Desktop进行配置，请将以下内容添加到MCP设置中：
{
"mcpServers": {
"tracking-rate-mcp": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/TrackingRateMCP"
}
}
}特性
- 🚚 联邦快递包裹追踪：通过OAuth2身份验证和自动刷新进行实时跟踪
- 📦 UPS包裹追踪：使用OAuth2授权流提供完整的跟踪支持
- 🟡 DHL包裹追踪：使用OAuth2客户端凭据流进行DHL电子商务跟踪
- 🟠 OnTrac包裹跟踪：具有API密钥认证的区域运营商跟踪
- 🤖 MCP协议：通过模型上下文协议为AI代理提供标准接口
- ⚡ 批处理：一次最多可追踪30个联邦快递包裹、10个UPS包裹或10个DHL包裹
- 🔄 自动重试：速率限制和网络故障的自动重试逻辑
- 📝 丰富的日志记录：具有可配置级别的全面日志记录
- 🔒 安全认证：具有自动刷新功能的OAuth2令牌管理
- 🎯 类型安全：完整的Pydantic模型验证和类型提示
安装
- 克隆存储库:
git clone
cd TrackingRateMCP- 创建并激活虚拟环境 （如CLAUDE.md中所述）：
python -m venv venv_linux
source venv_linux/bin/activate # On Linux/macOS
# or
venv_linux\\Scripts\\activate # On Windows- 安装依赖项:
pip install -r requirements.txt- 设置环境变量:
cp .env.example .env
# Edit .env with your API credentials环境配置
创建一个 .env 文件基于 .env.example 具有以下设置：
所需的环境变量
# FedEx Configuration (Production)
FEDEX_CLIENT_ID=your_fedex_client_id
FEDEX_CLIENT_SECRET=your_fedex_client_secret
FEDEX_SANDBOX=false
# UPS Configuration
UPS_CLIENT_ID=your_ups_client_id
UPS_CLIENT_SECRET=your_ups_client_secret
UPS_REDIRECT_URI=http://localhost:8000/callback
UPS_SANDBOX=false
# DHL Configuration
DHL_CLIENT_ID=your_dhl_client_id
DHL_CLIENT_SECRET=your_dhl_client_secret
DHL_SANDBOX=true
# OnTrac Configuration
ONTRAC_API_KEY=your_ontrac_api_key
ONTRAC_ACCOUNT_NUMBER=your_ontrac_account_number
ONTRAC_SANDBOX=false
# MCP Configuration
MCP_TRANSPORT=stdio
LOG_LEVEL=INFO可选环境变量
# Custom timeout settings
REQUEST_TIMEOUT=30
TOKEN_REFRESH_BUFFER=60API密钥设置
联邦快递API设置
- 访问 FedEx开发者门户
- 创建帐户和新项目
- 获取您的客户端ID和客户端密码
- 启用生产访问以进行实时跟踪
UPS API设置
- 访问 UPS开发人员门户
- 创建帐户和新应用程序
- 获取您的客户端ID和客户端密码
- 无需额外的OAuth设置-使用客户端凭据流
DHL API设置
- 访问 DHL开发者门户
- 为DHL电子商务创建帐户和新应用程序
- 获取您的客户端ID和客户端密码
- 使用OAuth2客户端凭据流
OnTrac API设置
- OnTrac需要一个活动帐户和API密码
- 获取API访问权限：
- 联系ont@ontrac.com请求API密码 - 在电子邮件请求中包含您的OnTrac帐号 - 等待OnTrac发出您的API密码
- 出于测试目的：
- API文件显示账户 37 带密码 testpass - 这些是示例凭据，可能不起作用
- 使用查询参数身份验证(
pw参数）
用法
作为MCP服务器（推荐）
启动MCP服务器以与AI代理一起使用：
python -m srcMCP服务器支持多种AI平台：
- 克劳德桌面：通过配置提供原生MCP支持
- 微软复制品工作室：通过自定义连接器（请参阅下面的集成指南）
- GitHub Copilot：通过MCP扩展
- 任何兼容MCP的客户端：使用标准MCP协议
通过添加到MCP配置中，使用Claude Desktop进行配置：
{
"mcpServers": {
"tracking-rate-mcp": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/TrackingRateMCP"
}
}
}Microsoft Copilot Studio集成
此MCP服务器可以与Microsoft Copilot Studio集成，以在您的Copilot代理中启用包跟踪功能。
先决条件
- 启用预览功能的Microsoft Copilot Studio帐户
- Azure订阅（用于部署）
- 启用“尽早获取新功能”的Power Apps环境
- 定制连接器的基本知识
部署选项
选项1：使用公共URL进行本地开发
- 在本地启动MCP服务器:
python -m src- 暴露您的本地服务器 使用隧道服务：
- 使用ngrok： ngrok http 8000 - 使用VS代码：使用“端口”选项卡公开转发端口8000 - 注意公共URL（例如。， https://abc123.ngrok.io)
选项2：部署到Azure
- 为Azure部署准备MCP服务器:
- 创建一个 requirements.txt 所有依赖项 - 添加一个 app.py 或Azure应用服务的类似入口点 - 为API凭据配置环境变量
- 部署到Azure应用服务:
# Using Azure CLI
az webapp up --name tracking-mcp-server --resource-group your-rg --runtime "PYTHON:3.11"- 配置环境变量 在Azure门户中：
- 导航到您的应用程序服务 - 转到配置→ 应用程序设置 - 添加所有必需的API密钥和设置
创建自定义连接器
- 导航到Power Apps （make.powerapps.com）
- 创建新的自定义连接器:
- 转到数据→ 自定义连接器→ 新的自定义连接器 - 选择“从空白创建”
- 配置连接器:
- 一般信息:
- 主机：您的服务器URL（不含https://） - 基本URL: / - 方案：HTTPS
- 安全:
- 身份验证类型：无身份验证（或根据需要配置）
- 定义:
- 添加操作：“调用MCP” - 请求： - 动词：POST - 网址： /mcp - 添加OpenAPI扩展：
x-ms-agentic-protocol: mcp-streamable-1.0- 导入OpenAPI规范:
swagger: '2.0'
info:
title: Package Tracking MCP
description: MCP server for package tracking via FedEx, UPS, DHL, and OnTrac
version: 1.0.0
host: your-server.azurewebsites.net
basePath: /
schemes:
- https
paths:
/mcp:
post:
summary: Package Tracking MCP Server
x-ms-agentic-protocol: mcp-streamable-1.0
operationId: InvokeMCP
responses:
'200':
description: Success- 测试并创建连接器
添加到Copilot工作室
- 打开您的Copilot Studio代理
- 导航到操作:
- 点击“+添加操作” - 搜索您的自定义连接器 - 选择“包裹跟踪MCP”
- 配置操作:
- MCP工具将被自动发现 - 可用工具： - track_fedex_package - track_ups_package - track_dhl_package - track_ontrac_package - 以及每个运营商的验证工具
- Copilot Studio中的测试:
- 使用测试窗格 - 尝试：“追踪联邦快递包裹123456789012” - 代理应使用MCP服务器获取跟踪信息
故障排除
- “MCP服务器没有响应”：确保您的服务器可公开访问
- “身份验证失败”：检查环境变量中的API凭据
- “工具未出现”：验证OpenAPI规范是否包括
x-ms-agentic-protocol - 预览功能：确保您的环境启用了预览功能
安全考虑
- 使用Azure密钥保管库存储API凭据
- 在Copilot Studio和MCP服务器之间实现正确的身份验证
- 考虑生产部署的IP限制或API管理
- 监控使用情况以防止API速率限制问题
作为HTTP服务器（可选）
启动HTTP服务器以进行REST API访问：
python -m src.server命令行接口
该软件包包括一个用于测试和开发的CLI：
基本包裹跟踪
# Track a FedEx package
python main.py --fedex 123456789012
# Track a UPS package
python main.py --ups 1Z12345E0123456789
# Track a DHL package
python main.py --dhl GM60511234500000001
# Track an OnTrac package
python main.py --ontrac C10000012345678
# Track multiple packages
python main.py --fedex 123456789012 987654321098
python main.py --ups 1Z12345E0123456789 1Z12345E9876543210
python main.py --dhl GM60511234500000001 GM60511234500000002
python main.py --ontrac C10000012345678 D10000012345678验证和测试
# Validate tracking numbers without tracking
python main.py --validate --fedex 123456789012
python main.py --validate --ups 1Z12345E0123456789
python main.py --validate --dhl GM60511234500000001
python main.py --validate --ontrac C10000012345678
# Run test mode with sample tracking numbers
python main.py --test-mode
# Start MCP server
python main.py --server与AI代理集成
Pydantic AI代理示例
from pydantic_ai import Agent
from mcp import Client
# Configure MCP client to use tracking server
mcp_client = Client("stdio", command=["python", "-m", "src.server"])
# Create agent with tracking capabilities
agent = Agent(
"gpt-4",
tools=[mcp_client],
system_prompt="You can track packages using FedEx and UPS."
)
# Use the agent
result = await agent.run("Track FedEx package 123456789012")可用的MCP工具
服务器向AI代理公开以下工具：
track_fedex_package(tracking_number: str)-跟踪单个FedEx包裹track_multiple_fedex_packages(tracking_numbers: List[str])-跟踪多个FedEx包裹validate_fedex_tracking_number(tracking_number: str)-验证FedEx跟踪号格式track_ups_package(tracking_number: str)-跟踪单个UPS包track_multiple_ups_packages(tracking_numbers: List[str])-跟踪多个UPS包裹validate_ups_tracking_number(tracking_number: str)-验证UPS跟踪号格式track_dhl_package(tracking_number: str)-追踪单个DHL包裹track_multiple_dhl_packages(tracking_numbers: List[str])-追踪多个DHL包裹validate_dhl_tracking_number(tracking_number: str)-验证DHL跟踪号格式track_ontrac_package(tracking_number: str)-跟踪单个OnTrac包track_multiple_ontrac_packages(tracking_numbers: List[str])-跟踪多个OnTrac包validate_ontrac_tracking_number(tracking_number: str)-验证OnTrac跟踪号格式
可用MCP资源
tracking://server/info-服务器功能和配置tracking://carriers/{carrier}/capabilities-运营商特定功能
项目结构
TrackingRateMCP/
├── src/
│ ├── __init__.py # Package initialization
│ ├── server.py # Main MCP server implementation
│ ├── models.py # Pydantic models for tracking data
│ ├── config.py # Configuration and environment management
│ ├── auth/
│ │ ├── __init__.py # Auth package init
│ │ ├── fedex_auth.py # FedEx OAuth token management
│ │ ├── ups_auth.py # UPS OAuth token management
│ │ ├── dhl_auth.py # DHL OAuth token management
│ │ └── ontrac_auth.py # OnTrac API key authentication
│ ├── tracking/
│ │ ├── __init__.py # Tracking package init
│ │ ├── fedex_tracker.py # FedEx tracking implementation
│ │ ├── ups_tracker.py # UPS tracking implementation
│ │ ├── dhl_tracker.py # DHL tracking implementation
│ │ ├── ontrac_tracker.py # OnTrac tracking implementation
│ │ └── base_tracker.py # Abstract tracking interface
│ └── tools/
│ ├── __init__.py # Tools package init
│ ├── fedex_tools.py # FedEx MCP tools
│ ├── ups_tools.py # UPS MCP tools
│ ├── dhl_tools.py # DHL MCP tools
│ └── ontrac_tools.py # OnTrac MCP tools
├── tests/ # Comprehensive test suite
├── venv_linux/ # Virtual environment
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
├── .env.example # Environment variables template
├── README.md # This documentation
└── main.py # CLI entry point for testing测试
运行综合测试套件：
# Activate virtual environment
source venv_linux/bin/activate
# Run all tests with coverage
pytest tests/ -v --cov=src --cov-report=term-missing
# Run specific test modules
pytest tests/test_models.py -v
pytest tests/test_fedex_auth.py -v
pytest tests/test_fedex_tracking.py -v
# Run with detailed output
pytest tests/ -v -s发展
代码质量
该项目包括在中配置的代码质量工具 pyproject.toml:
# Format and lint code
ruff check src/ tests/ --fix
# Type checking
mypy src/ tests/
# Run all quality checks
ruff check src/ tests/ --fix && mypy src/ tests/添加新运营商
要添加对其他运营商的支持：
- 在中创建身份验证模块
src/auth/ - 实施跟踪服务扩展
BaseTracker - 在中创建MCP工具
src/tools/ - 在中注册工具
src/server.py - 添加综合测试
API文档
跟踪结果模型
class TrackingResult(BaseModel):
tracking_number: str # Package tracking number
carrier: TrackingCarrier # Shipping carrier (fedex/ups/dhl/ontrac)
status: TrackingStatus # Current package status
estimated_delivery: Optional[datetime] # Estimated delivery time
delivered_at: Optional[datetime] # Actual delivery time
events: List[TrackingEvent] # Tracking history
origin: Optional[PackageLocation] # Origin location
destination: Optional[PackageLocation] # Destination location
delivery_address: Optional[str] # Delivery location
service_type: Optional[str] # Shipping service type
weight: Optional[str] # Package weight
reference_numbers: List[str] # Reference numbers
error_message: Optional[str] # Error details if tracking failed跟踪状态值
in_transit-包裹正在运输中out_for_delivery-包裹已准备好发货delivered-包裹已送达exception-发生交付异常pending-包裹处理待定not_found-找不到跟踪号label_created-已创建发货标签unknown-状态未知error-发生跟踪错误
故障排除
常见问题
- 身份验证失败:
- 在中验证API凭据 .env 文件 - 检查是否使用了正确的沙盒/生产端点 - 确保UPS的OAuth流程已完成 - OnTrac：“无效用户名或密码”错误表示： - 您需要联系ont@ontrac.com用于API访问 - 在请求中包含您的帐号 - 文档中的测试证书可能不起作用
- 跟踪失败:
- 验证跟踪号格式 - 检查API费率限制 - 验证网络连接
- MCP集成问题:
- 确保MCP客户端配置正确 - 检查服务器日志以获取详细的错误信息 - 验证MCP客户端中的工具注册
日志记录
启用调试日志记录以进行详细的故障排除：
LOG_LEVEL=DEBUG查看日志以了解特定的错误详细信息和API响应信息。
费率限制和最佳实践
联邦快递API
- 每个请求最多30个跟踪号码
- 令牌每60分钟过期一次（自动刷新）
- 遵守速率限制，避免429个错误
UPS API
- 对每个跟踪号的单独请求
- OAuth令牌的有效期可能更长
- 实现重试的指数回退
DHL API
- 每个请求最多10个跟踪号
- OAuth令牌基于API设置过期
- 支持批量和单独跟踪
OnTrac API
- 不支持批处理跟踪（使用并发请求）
- API密钥身份验证（无令牌过期）
- 专注于美国西部各州的区域性航空公司
最佳实践
- 尽可能使用批量跟踪
- 缓存结果以最小化API调用
- 实施适当的错误处理
- 监控API的使用情况和成本
贡献
- 遵循以下项目结构和编码约定
CLAUDE.md - 使用pytest为新功能添加单元测试
- 根据需要更新文档
- 在提交更改之前，确保所有测试都通过
- 使用类型提示和Pydantic模型进行验证
许可证
该项目旨在教育和发展。使用跟踪功能时，请确保遵守联邦快递和UPS API的服务条款。
支持
对于问题和疑问：
- 检查上面的故障排除部分
- 查看测试文件以获取使用示例
- 检查日志文件以获取详细的错误信息