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

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

功能特点

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

快速开始

环境变量配置

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

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

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

# MCP配置（必需）
MCP_MODE=stdio

在Cursor中使用

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

{
  "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: 工具执行结果

输入消息示例:

{"type": "ping"}

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

配置

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

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

工具说明

服务提供以下工具：

TouristFlow - 查询实时客流

输入参数：

{
  "scId": "景区ID"
}

CumulativeTouristFlow - 查询实时累计客流

输入参数：

{
  "scId": "景区ID"
}

DailyTouristFlow - 查询每日客流统计

输入参数：

{
  "scId": "景区ID",
  "day": "20221030"
}

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

输入参数：

{
  "scId": "景区ID",
  "day": "20221030"
}

GenderPortrait - 查询游客性别分布

输入参数：

{
  "scId": "景区ID",
  "day": "20221030"
}

AgePortrait - 查询游客年龄分布

输入参数：

{
  "scId": "景区ID",
  "day": "20221030"
}

测试

使用提供的测试脚本：

node test-tool.js

安装

npm install yszl-mcp

使用方法

作为命令行工具使用

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

或者创建 .env 文件后运行：

npx -y yszl-mcp

作为模块导入使用

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