🚀 包裹跟踪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令牌
- 访问 17track.net。
- 注册一个账户。
- 导航至API部分。
- 生成你的API令牌。
- 将其添加到
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许可证。
🤝 贡献指南
- 分叉仓库。
- 创建功能分支。
- 进行更改。
- 提交拉取请求。
📞 支持
- 若遇到与MCP协议相关的问题，请查看 MCP文档。
- 若遇到与17track.net API相关的问题，请访问 17track.net API文档。
- 若遇到与本实现相关的问题，请在仓库中创建一个issue。
📝 更新日志
v1.0.0
- 初始版本发布。
- 具备基本的包裹跟踪功能。
- 支持自动和手动检测承运商。
- 包含错误处理和日志记录功能。