AI导哈

包裹追踪MCP服务器

一个支持FedEx、UPS、DHL和OnTrac API的包裹追踪服务器，为AI代理提供标准化的追踪工具。

  • by GeigerAI
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 GeigerAI/TrackingMCP

使用说明

包裹跟踪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模型验证和类型提示

安装

  1. 克隆存储库:

    git clone <repository-url>
cd TrackingRateMCP

  2. 创建并激活虚拟环境 （如CLAUDE.md中所述）：

    python -m venv venv_linux
source venv_linux/bin/activate  # On Linux/macOS
# or
venv_linux\\Scripts\\activate     # On Windows

  3. 安装依赖项:

    pip install -r requirements.txt

  4. 设置环境变量:

    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=60

API密钥设置

联邦快递API设置

  1. 访问 FedEx开发者门户
  2. 创建帐户和新项目
  3. 获取您的客户端ID和客户端密码
  4. 启用生产访问以进行实时跟踪

UPS API设置

  1. 访问 UPS开发人员门户
  2. 创建帐户和新应用程序
  3. 获取您的客户端ID和客户端密码
  4. 无需额外的OAuth设置-使用客户端凭据流

DHL API设置

  1. 访问 DHL开发者门户
  2. 为DHL电子商务创建帐户和新应用程序
  3. 获取您的客户端ID和客户端密码
  4. 使用OAuth2客户端凭据流

OnTrac API设置

  1. OnTrac需要一个活动帐户和API密码
  2. 获取API访问权限：
    • 联系ont@ontrac.com请求API密码
    • 在电子邮件请求中包含您的OnTrac帐号
    • 等待OnTrac发出您的API密码
  3. 出于测试目的：
    • API文件显示账户 37 带密码 testpass
    • 这些是示例凭据，可能不起作用
  4. 使用查询参数身份验证(pw 参数）

用法

作为MCP服务器（推荐）

启动MCP服务器以与AI代理一起使用：

python -m src

MCP服务器支持多种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进行本地开发

  1. 在本地启动MCP服务器:

    python -m src

  2. 暴露您的本地服务器 使用隧道服务：

    • 使用ngrok： ngrok http 8000
    • 使用VS代码：使用“端口”选项卡公开转发端口8000
    • 注意公共URL（例如。， https://abc123.ngrok.io)
选项2：部署到Azure

  1. 为Azure部署准备MCP服务器:

    • 创建一个 requirements.txt 所有依赖项
    • 添加一个 app.py 或Azure应用服务的类似入口点
    • 为API凭据配置环境变量

  2. 部署到Azure应用服务:

    # Using Azure CLI
az webapp up --name tracking-mcp-server --resource-group your-rg --runtime "PYTHON:3.11"

  3. 配置环境变量 在Azure门户中：

    • 导航到您的应用程序服务
    • 转到配置→ 应用程序设置
    • 添加所有必需的API密钥和设置

创建自定义连接器

  1. 导航到Power Apps （make.powerapps.com）

  2. 创建新的自定义连接器:

    • 转到数据→ 自定义连接器→ 新的自定义连接器
    • 选择“从空白创建”

  3. 配置连接器:

    • 一般信息:

      • 主机：您的服务器URL（不含https://）
      • 基本URL: /
      • 方案：HTTPS

    • 安全:

      • 身份验证类型：无身份验证（或根据需要配置）

    • 定义:

      • 添加操作：“调用MCP”
      • 请求：
        • 动词：POST
        • 网址： /mcp
      • 添加OpenAPI扩展：
        x-ms-agentic-protocol: mcp-streamable-1.0

  4. 导入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

  5. 测试并创建连接器

添加到Copilot工作室

  1. 打开您的Copilot Studio代理

  2. 导航到操作:

    • 点击“+添加操作”
    • 搜索您的自定义连接器
    • 选择“包裹跟踪MCP”

  3. 配置操作:

    • MCP工具将被自动发现
    • 可用工具：
      • track_fedex_package
      • track_ups_package
      • track_dhl_package
      • track_ontrac_package
      • 以及每个运营商的验证工具

  4. 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/

添加新运营商

要添加对其他运营商的支持：

  1. 在中创建身份验证模块 src/auth/
  2. 实施跟踪服务扩展 BaseTracker
  3. 在中创建MCP工具 src/tools/
  4. 在中注册工具 src/server.py
  5. 添加综合测试

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 -发生跟踪错误

故障排除

常见问题

  1. 身份验证失败:

    • 在中验证API凭据 .env 文件
    • 检查是否使用了正确的沙盒/生产端点
    • 确保UPS的OAuth流程已完成
    • OnTrac：“无效用户名或密码”错误表示：
      • 您需要联系ont@ontrac.com用于API访问
      • 在请求中包含您的帐号
      • 文档中的测试证书可能不起作用

  2. 跟踪失败:

    • 验证跟踪号格式
    • 检查API费率限制
    • 验证网络连接

  3. MCP集成问题:

    • 确保MCP客户端配置正确
    • 检查服务器日志以获取详细的错误信息
    • 验证MCP客户端中的工具注册

日志记录

启用调试日志记录以进行详细的故障排除：

LOG_LEVEL=DEBUG

查看日志以了解特定的错误详细信息和API响应信息。

费率限制和最佳实践

联邦快递API

  • 每个请求最多30个跟踪号码
  • 令牌每60分钟过期一次（自动刷新）
  • 遵守速率限制，避免429个错误

UPS API

  • 对每个跟踪号的单独请求
  • OAuth令牌的有效期可能更长
  • 实现重试的指数回退

DHL API

  • 每个请求最多10个跟踪号
  • OAuth令牌基于API设置过期
  • 支持批量和单独跟踪

OnTrac API

  • 不支持批处理跟踪（使用并发请求）
  • API密钥身份验证（无令牌过期）
  • 专注于美国西部各州的区域性航空公司

最佳实践

  • 尽可能使用批量跟踪
  • 缓存结果以最小化API调用
  • 实施适当的错误处理
  • 监控API的使用情况和成本

贡献

  1. 遵循以下项目结构和编码约定 CLAUDE.md
  2. 使用pytest为新功能添加单元测试
  3. 根据需要更新文档
  4. 在提交更改之前，确保所有测试都通过
  5. 使用类型提示和Pydantic模型进行验证

许可证

该项目旨在教育和发展。使用跟踪功能时，请确保遵守联邦快递和UPS API的服务条款。

支持

对于问题和疑问：

  • 检查上面的故障排除部分
  • 查看测试文件以获取使用示例
  • 检查日志文件以获取详细的错误信息

相关 MCP