Parcel Tracking MCP

🚀 包裹跟蹤MCP服務器

這是一個基於Model Context Protocol (MCP)的服務器，藉助17track.net API實現包裹配送跟蹤功能。

✨ 主要特性

• 支持跟蹤多家快遞公司的包裹配送情況。
• 可自動識別快遞公司。
• 支持手動指定快遞公司。
• 採用TypeScript和MCP SDK構建。

📦 安裝指南

全局安裝

通過npm全局安裝該包：

npm install -g parcel-tracking-mcp-server

本地安裝

在本地安裝該包：

npm install parcel-tracking-mcp-server

📚 詳細文檔

配置

在工作目錄下創建一個config.json文件，並填入你的17track.net API令牌：

{
  "apiToken": "your-17track-api-token-here"
}

注意：服務器會在你運行命令的當前工作目錄中查找config.json文件。

獲取17track.net API令牌

1. 訪問 17track.net。
2. 註冊一個賬戶。
3. 導航到API部分。
4. 生成你的API令牌。
5. 將其添加到config.json文件中。

使用方法

運行服務器

• 全局安裝時：

parcel-tracking-mcp-server

• 本地安裝時：

npx parcel-tracking-mcp-server

• 作為項目依賴使用時：

node node_modules/parcel-tracking-mcp-server/dist/index.js

MCP客戶端配置

若要將此服務器與MCP客戶端（如Claude Desktop）配合使用，請將其添加到MCP配置中：

• 本地安裝時：

{
  "mcpServers": {
    "parcel-tracking": {
      "command": "npx",
      "args": ["parcel-tracking-mcp-server"]
    }
  }
}

• 全局安裝時：

{
  "mcpServers": {
    "parcel-tracking": {
      "command": "parcel-tracking-mcp-server"
    }
  }
}

可用工具

tracking-delivery

通過提供跟蹤號碼來跟蹤包裹配送情況。 參數：

• number（必填）：包裹的跟蹤號碼。
• carrier（選填）：包裹的快遞公司（默認為'auto'，即自動識別）。

示例：

// 自動識別快遞公司進行跟蹤
await trackingDelivery({
  number: "1234567890"
});

// 指定快遞公司進行跟蹤
await trackingDelivery({
  number: "1234567890",
  carrier: "ups"
});

支持的快遞公司

服務器支持自動識別快遞公司，你也可以手動指定。常見的快遞公司包括：

• UPS
• FedEx
• DHL
• USPS
• 中國郵政
• 更多公司（完整列表請查看17track.net文檔）

API響應格式

服務器以JSON格式返回跟蹤信息，包括：

• 跟蹤狀態
• 配送進度
• 時間戳
• 位置更新
• 快遞公司信息

錯誤處理

服務器具備全面的錯誤處理機制，可處理以下錯誤：

• API連接錯誤
• 無效的跟蹤號碼
• 缺少配置
• 網絡超時

開發

項目結構

├── index.ts          # 主服務器實現文件
├── config.json       # 配置文件（需自行創建）
├── package.json      # 依賴項和腳本
└── README.md         # 本文件

依賴項

• @modelcontextprotocol/sdk - 用於構建服務器的MCP SDK。
• zod - 模式驗證工具。
• node-fetch - HTTP請求工具（適用於較舊的Node.js版本）。

📄 許可證

本項目採用MIT許可證。

🤝 貢獻

1. 分叉該倉庫。
2. 創建一個功能分支。
3. 進行修改。
4. 提交拉取請求。

🆘 支持

若遇到以下相關問題：

• MCP協議：請查看 MCP文檔。
• 17track.net API：請訪問 17track.net API文檔。
• 本項目實現：請在倉庫中創建一個問題。

📝 變更日誌

v1.0.0

• 初始版本發佈。
• 具備基本的包裹跟蹤功能。
• 支持自動和手動識別快遞公司。
• 包含錯誤處理和日誌記錄功能。