ts-guoguo-mcp-server/README.md

裹裹寄件服务MCP Server - TypeScript版本，基于Model Context Protocol的寄件服务集成工具

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

[![npm version](https://badge.fury.io/js/ts-guoguo-mcp-server.svg)](https://badge.fury.io/js/ts-guoguo-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)

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

## 功能特性

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

## 安装

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

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

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

### 方式二：从源码安装

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

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build
```

## 使用方法

### 命令行使用

如果全局安装：
```bash
# 查看帮助
ts-guoguo-mcp --help

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

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

如果本地安装：
```bash
# 查看帮助
npx @jiadun/ts-guoguo-mcp-server --help

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

### 从源码启动

```bash
# 启动服务器
npm start

# 开发模式
npm run dev

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

### 环境变量

```bash
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的配置文件中添加：

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

#### 使用全局安装的包

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

#### 使用源码

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

### 使用MCP Inspector调试

#### 使用npm包

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

#### 使用源码

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

## 可用工具

### 1. query_address_book
查询用户的地址簿信息

**参数:**
- `search_key` (可选): 搜索关键词

**示例:**
```json
{
  "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提供完整的类型安全：

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

### 错误处理

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

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

### 模拟数据

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

```bash
npm start -- --use-mock
```

## 快速开始

1. **安装包**
   ```bash
   npm install -g @jiadun/ts-guoguo-mcp-server
   ```

2. **配置Claude Desktop**
   ```json
   {
     "mcpServers": {
       "guoguo-shipping": {
         "command": "ts-guoguo-mcp",
         "args": ["--use-mock"]
       }
     }
   }
   ```

3. **重启Claude Desktop并测试**
   ```
   帮我查询地址簿
   ```

## 版本更新

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

## 许可证

MIT License

## 贡献

欢迎提交 Pull Request 和 Issue！

- GitHub: [https://github.com/jiadun/ts-guoguo-mcp-server](https://github.com/jiadun/ts-guoguo-mcp-server)
- Issues: [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** - 参数验证