yszl-mcp/README.md

Scenic Area Tourist Flow Query Server with official MCP SDK

# 景区实时客流查询服务器 (MCP)

一个符合 Model Context Protocol 规范的景区客流查询服务。

## 功能特点

- 通过NPX快速安装运行
- 完全支持MCP标准的stdio通信协议
- 实现实时客流查询
- 实现实时累计客流统计
- 实现每日客流统计
- 实现游客来源省份分布
- 实现游客性别分布
- 实现游客年龄分布
- 通过环境变量轻松配置

## 快速开始

### 环境变量配置

在使用之前，请确保设置以下必要的环境变量：

```env
# API 配置（必需）
ACCOUNT=你的账号
APP_SECRET=你的密钥

# 服务器配置（可选）
PORT=3000
NODE_ENV=development

# MCP配置（必需）
MCP_MODE=stdio
```

### 在Cursor中使用

在Cursor配置中添加以下配置：

```json
{
  "mcpServers": {
    "touristflow": {
      "command": "npx",
      "args": [
        "-y",
        "yszl-mcp@latest"
      ],
      "env": {
        "ACCOUNT": "你的账号",
        "APP_SECRET": "你的密钥",
        "MCP_MODE": "stdio"
      }
    }
  }
}
```

## MCP协议实现

本服务实现了MCP的stdio通信协议，支持以下消息类型：

- `init`: 服务初始化时发送的消息，包含工具描述
- `ping`/`pong`: 心跳检测
- `tool_call`: 工具调用请求
- `tool_result`: 工具执行结果

输入消息示例:
```json
{"type": "ping"}
```

```json
{
  "type": "tool_call",
  "id": "123",
  "name": "TouristFlow",
  "args": {"scId": "景区ID"}
}
```

## 配置

运行服务器前，请设置API凭证：

1. 创建`.env`文件，参考`.env.example`
2. 填写API凭证：
   - `ACCOUNT`: 账户名或ID（必需）
   - `APP_SECRET`: 用于生成签名的应用密钥（必需）

## 工具说明

服务提供以下工具：

### TouristFlow - 查询实时客流

输入参数：
```json
{
  "scId": "景区ID"
}
```

### CumulativeTouristFlow - 查询实时累计客流

输入参数：
```json
{
  "scId": "景区ID"
}
```

### DailyTouristFlow - 查询每日客流统计

输入参数：
```json
{
  "scId": "景区ID",
  "day": "20221030"
}
```

### ProvinceOrigin - 查询游客来源省份分布

输入参数：
```json
{
  "scId": "景区ID",
  "day": "20221030"
}
```

### GenderPortrait - 查询游客性别分布

输入参数：
```json
{
  "scId": "景区ID",
  "day": "20221030"
}
```

### AgePortrait - 查询游客年龄分布

输入参数：
```json
{
  "scId": "景区ID",
  "day": "20221030"
}
```

## 测试

使用提供的测试脚本：

```bash
node test-tool.js
```

## 安装

```bash
npm install yszl-mcp
```

## 使用方法

### 作为命令行工具使用

```bash
ACCOUNT=your_account APP_SECRET=your_secret npx -y yszl-mcp
```

或者创建 .env 文件后运行：
```bash
npx -y yszl-mcp
```

### 作为模块导入使用

```javascript
import { TouristFlowTool } from 'yszl-mcp';

const tool = new TouristFlowTool();
const result = await tool.execute({ scId: '景区ID' });
console.log(result);
```

## 可用工具

- TouristFlow: 实时客流查询
- CumulativeTouristFlow: 累计客流查询
- DailyTouristFlow: 日客流查询
- ProvinceOrigin: 游客来源地分布
- GenderPortrait: 性别画像
- AgePortrait: 年龄画像

## 许可证

ISC