ts-guoguo-mcp-server

裹裹寄件服务MCP Server (TypeScript版本)

一个基于Model Context Protocol (MCP)的寄件服务服务器，使用TypeScript开发，提供地址簿查询、订单创建、订单管理等功能。通过MCP协议，可以让AI助手（如Claude）直接调用寄件服务API。

功能特性

• 🚀 TypeScript实现 - 完整的类型安全和现代JavaScript特性
• 📮 地址簿管理 - 查询和搜索联系人地址信息
• 📦 订单创建 - 创建新的寄件订单，支持多种服务类型
• 📋 订单查询 - 分页查询订单列表，支持条件筛选
• 🔍 订单详情 - 获取详细的订单信息和物流追踪
• 🎭 Mock模式 - 内置模拟数据，便于开发和测试
• 🔧 配置灵活 - 支持命令行参数和环境变量配置

安装

方式一：从npm安装（推荐）

# 全局安装
npm install -g @jiadun/ts-guoguo-mcp-server

# 或本地安装
npm install @jiadun/ts-guoguo-mcp-server

方式二：从源码安装

# 1. 克隆项目
git clone https://github.com/jiadun/ts-guoguo-mcp-server.git
cd ts-guoguo-mcp-server

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

使用方法

命令行使用

如果全局安装：

# 查看帮助
ts-guoguo-mcp --help

# 使用模拟数据启动
ts-guoguo-mcp --use-mock

# 指定API配置
ts-guoguo-mcp --api-url https://your-api.com --token your-token

如果本地安装：

# 查看帮助
npx @jiadun/ts-guoguo-mcp-server --help

# 使用模拟数据启动
npx @jiadun/ts-guoguo-mcp-server --use-mock

从源码启动

# 启动服务器
npm start

# 开发模式
npm run dev

# 命令行选项
npm start -- --use-mock
npm start -- --help

环境变量

export SHIPPING_API_BASE_URL="https://pre-xg.cainiao.com/"
export SHIPPING_API_TOKEN="your_api_token"
export SHIPPING_API_TIMEOUT="30"
export SHIPPING_USE_MOCK="true"

MCP客户端配置

Claude Desktop

使用npm包（推荐）

在Claude Desktop的配置文件中添加：

{
  "mcpServers": {
    "guoguo-shipping": {
      "command": "npx",
      "args": [
        "@jiadun/ts-guoguo-mcp-server",
        "--use-mock"
      ]
    }
  }
}

使用全局安装的包

{
  "mcpServers": {
    "guoguo-shipping": {
      "command": "ts-guoguo-mcp",
      "args": ["--use-mock"]
    }
  }
}

使用源码

{
  "mcpServers": {
    "guoguo-shipping": {
      "command": "node",
      "args": ["/path/to/your/project/dist/index.js", "--use-mock"]
    }
  }
}

使用MCP Inspector调试

使用npm包

npx @modelcontextprotocol/inspector npx @jiadun/ts-guoguo-mcp-server --use-mock

使用源码

npx @modelcontextprotocol/inspector node dist/index.js --use-mock

可用工具

1. query_address_book

查询用户的地址簿信息

参数:

• search_key (可选): 搜索关键词

示例:

{
  "search_key": "张三"
}

2. create_shipping_order

创建新的寄件订单

参数:

• sender_name: 寄件人姓名
• sender_phone: 寄件人电话
• sender_address: 寄件人地址
• receiver_name: 收件人姓名
• receiver_phone: 收件人电话
• receiver_address: 收件人地址
• package_type: 物品类型
• package_weight: 重量(kg)
• package_size: 尺寸(长x宽x高,cm)
• service_type: 服务类型(标准/快速/经济)

3. list_shipping_orders

分页查询寄件订单列表

参数:

• page_size: 每页数量(默认10)
• page_number: 页码(默认1)
• start_date: 开始日期(YYYY-MM-DD)
• end_date: 结束日期(YYYY-MM-DD)
• status: 订单状态过滤

4. get_order_detail

获取订单详细信息

参数:

• order_id: 订单号
• detail_level: 详情级别(basic/full)

项目结构

src/
├── config/
│   └── api-config.ts      # API配置类
├── services/
│   ├── address-book.ts    # 地址簿服务
│   ├── order.ts          # 订单服务
│   └── shipping.ts       # 统一寄件服务
├── types/
│   └── index.ts          # 类型定义
├── utils/
│   ├── args-parser.ts    # 命令行参数解析
│   ├── http-client.ts    # HTTP客户端
│   └── logger.ts         # 日志工具
└── index.ts              # 主入口文件

开发指南

类型安全

项目使用TypeScript提供完整的类型安全：

interface CreateOrderRequest {
  sender_name: string;
  sender_phone: string;
  // ... 其他字段
}

错误处理

所有API调用都包含完整的错误处理：

try {
  const result = await shippingService.createOrder(request);
  return { status: "success", data: result };
} catch (error) {
  return { status: "error", message: error.message };
}

模拟数据

在开发和测试时可以使用内置的模拟数据：

npm start -- --use-mock

快速开始

• 安装包

  npm install -g @jiadun/ts-guoguo-mcp-server
  

• 配置Claude Desktop

  {
    "mcpServers": {
      "guoguo-shipping": {
        "command": "ts-guoguo-mcp",
        "args": ["--use-mock"]
      }
    }
  }
  

• 重启Claude Desktop并测试

  帮我查询地址簿
  

版本更新

v1.0.0

• ✅ 初始版本发布
• ✅ 支持地址簿查询、订单创建、订单列表、订单详情
• ✅ Mock模式支持
• ✅ TypeScript类型安全

许可证

MIT License

贡献

欢迎提交 Pull Request 和 Issue！

• GitHub: https://github.com/jiadun/ts-guoguo-mcp-server
• Issues: https://github.com/jiadun/ts-guoguo-mcp-server/issues

技术栈

• TypeScript - 主要开发语言
• Node.js - 运行环境
• @modelcontextprotocol/sdk - MCP官方SDK
• axios - HTTP客户端
• zod - 参数验证