jlwainwright
服务介绍
Shiplogic MCP 服务器
这是一个模型上下文协议（MCP）服务器，提供与Shiplogic运输API的无缝集成。使用MCP SDK和TypeScript构建，以确保类型安全并提升开发体验。
演示
bash
与Claude的示例对话：
用户: "查询从开普敦到约翰内斯堡2.5公斤包裹的运费"
Claude: "我将为您查询运费..."
[使用工具: get_shipping_rates]
结果: 经济服务 - R95 (2-3天送达)
用户: "预订经济服务"
Claude: "正在创建发货单..."
[使用工具: create_shipment]
结果: 发货单已创建！追踪号: QR4FVL
功能
- 🚚 获取运费 - 计算两地之间的运输成本
- 📦 创建发货单 - 预订发货单并自动跟踪
- 🔍 追踪包裹 - 实时追踪发货状态
- ❌ 取消发货单 - 在需要时取消预订
- ➕ 可选服务 - 获取特殊服务的附加费率
- 📚 地址簿管理 - 存储和管理常用地址
安装
前提条件
- Node.js 18+
- npm 或 yarn
- Shiplogic API 密钥（在 shiplogic.com 获取）
快速开始
-
克隆并安装：
bash
git clone https://github.com/jlwainwright/shiplogic-mcp.git
cd shiplogic-mcp
npm install -
配置环境变量：
bash
cp .env.example .env编辑 .env 并添加您的 Shiplogic API 密钥
-
构建服务器：
bash
npm run build
使用方法
与Claude桌面版配合使用
将以下内容添加到您的Claude桌面配置中：
json
{
"mcpServers": {
"shiplogic": {
"command": "node",
"args": ["/absolute/path/to/shiplogic-mcp/dist/index.js"],
"env": {
"SHIPLOGIC_API_KEY": "your_api_key_here"
}
}
}
}
通过MCP Inspector测试
使用MCP Inspector测试服务器：
bash
npm run inspect
独立运行
直接运行服务器：
bash
npm run dev
可用工具
get_shipping_rates
计算两个地址之间的运费。
typescript
{
collection_address: {
street_address: string,
city: string,
code: string,
country?: string,
type?: "residential" | "business"
},
delivery_address: {
street_address: string,
city: string,
code: string,
country?: string,
type?: "residential" | "business"
},
parcels: [{
length: number, // cm
width: number, // cm
height: number, // cm
weight: number, // kg
description?: string
}],
declared_value?: number
}
create_shipment
创建带有跟踪的新发货单。
typescript
{
service_level_code: string, // 例如："ECO"
collection_address: { /* 同上 / },
delivery_address: { / 同上 / },
parcels: [{ / 同上 */ }],
collection_contact: {
name: string,
mobile_number?: string,
email?: string
},
delivery_contact: {
name: string,
mobile_number?: string,
email?: string
},
customer_reference?: string,
mute_notifications?: boolean
}
track_shipment
通过参考编号追踪发货单。
typescript
{
tracking_number: string
}
cancel_shipment
取消现有的发货单。
typescript
{
tracking_reference: string
}
get_opt_in_rates
获取可选附加服务的费率。
typescript
{
collection_address: { /* 地址对象 / },
delivery_address: { / 地址对象 */ }
}
add_address_to_book
向账户地址簿中添加一个地址。
typescript
{
account_id: number,
address: {
street_address: string,
city: string,
code: string,
country?: string,
type?: "residential" | "business",
company?: string
},
name?: string, // 此地址条目的名称
type?: "collection" | "delivery" // 地址类型
}### get_address_book
从账户的地址簿中检索地址。
typescript
{
account_id: number,
type?: "collection" | "delivery" // 可选，按类型过滤
}
remove_address_from_book
从账户的地址簿中移除一个地址。
typescript
{
account_id: number,
address_id: number
}
配置
环境变量：
| 变量 | 描述 | 是否必需 | 默认值 |
|---|---|---|---|
SHIPLOGIC_API_KEY |
您的Shiplogic API密钥 | 是 | - |
SHIPLOGIC_API_URL |
API基础URL | 否 | https://api.shiplogic.com |
开发
项目结构
shiplogic-mcp-official/
├── src/
│ └── index.ts # 主服务器实现
├── dist/ # 编译后的JavaScript（生成）
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
脚本
npm run build- 编译TypeScriptnpm run dev- 构建并运行npm run inspect- 使用MCP Inspector运行
测试
bash
使用MCP Inspector运行
npm run inspect
在另一个终端中测试工具
curl -X POST http://localhost:3000/tools/list
API参考
此服务器与Shiplogic API v2集成。有关详细的API文档，请参阅：
许可证
MIT许可证 - 查看LICENSE文件
贡献
- 分叉仓库
- 创建您的功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 打开Pull Request
支持
- 🐛 问题：GitHub Issues
- 📧 电子邮件：your.email@example.com
- 📚 文档：Wiki
- ☕ 支持我的工作：Buy Me a Coffee
如果您觉得这个项目有帮助，请考虑支持我的工作。您的支持有助于我投入更多时间进行开源开发，并为社区创造更好的工具。
致谢
- 使用Model Context Protocol SDK构建
- 由Shiplogic API提供支持
由Jacques Wainwright用❤️制作
