ts-guoguo-mcp-server/QUICKSTART.md

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

# 快速启动指南

## 1. 安装和构建

```bash
# 安装依赖
npm install

# 构建项目
npm run build
```

## 2. 测试服务器

```bash
# 查看帮助信息
node dist/index.js --help

# 使用模拟数据启动服务器进行测试
node dist/index.js --use-mock
```

## 3. 配置Claude Desktop

1. 找到Claude Desktop配置文件路径：
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. 编辑配置文件，添加以下内容：

```json
{
  "mcpServers": {
    "guoguo-shipping": {
      "command": "node",
      "args": [
        "/完整/路径/到/项目/dist/index.js",
        "--use-mock"
      ]
    }
  }
}
```

⚠️ **重要**: 将 `/完整/路径/到/项目/` 替换为你项目的实际绝对路径。

3. 重启Claude Desktop

## 4. 验证安装

1. 打开Claude Desktop
2. 查看是否出现🔌插件图标
3. 尝试使用以下提示词测试：

```
帮我查询地址簿
```

```
帮我创建一个寄件订单，从北京寄到上海，包裹是文件，重量0.5kg，尺寸30x20x5cm
```

```
查询最近的订单列表
```

## 5. 使用真实API

如果你有真实的API访问权限，可以这样配置：

```json
{
  "mcpServers": {
    "guoguo-shipping": {
      "command": "node",
      "args": [
        "/完整/路径/到/项目/dist/index.js"
      ],
      "env": {
        "SHIPPING_API_BASE_URL": "https://your-api-endpoint.com/",
        "SHIPPING_API_TOKEN": "your_real_api_token",
        "SHIPPING_USE_MOCK": "false"
      }
    }
  }
}
```

## 故障排除

### 问题：Claude Desktop中看不到插件图标

**解决方案：**
1. 确认配置文件路径正确
2. 确认JSON格式正确（可以使用在线JSON验证器）
3. 确认可执行文件路径是绝对路径
4. 重启Claude Desktop

### 问题：服务器启动失败

**解决方案：**
1. 运行 `npm run build` 确保项目已构建
2. 运行 `node dist/index.js --help` 测试服务器是否能启动
3. 检查Node.js版本（需要18.0.0或以上）

### 问题：工具调用失败

**解决方案：**
1. 使用 `--use-mock` 参数测试
2. 检查API配置是否正确
3. 查看Claude Desktop的开发者工具日志

## 开发模式

如果你想修改代码：

```bash
# 开发模式（自动重编译）
npm run dev

# 或者手动构建
npm run build
```

修改代码后需要：
1. 重新构建项目 (`npm run build`)
2. 重启Claude Desktop