金大哥 - parcel-tracking-mcp MCP 详情

article

README

🚀 包裹跟踪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

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

parcel-tracking-mcp