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文档。
• 若遇到与本实现相关的问题，请在仓库中创建一个issue。

📝 更新日志

v1.0.0

• 初始版本发布。
• 具备基本的包裹跟踪功能。
• 支持自动和手动检测承运商。
• 包含错误处理和日志记录功能。