Sensors Server

基于 MCP（Model Context Protocol） 的神策分析数据服务，让 AI 助手通过自然语言直接查询和分析神策平台中的用户行为数据。

功能概览

工具	说明
get_sensors_config	获取当前神策配置信息（调试用）
verify_sensors_config	验证 API 连通性和认证有效性
list_events_all	获取项目中的全部事件列表
list_event_tags	获取事件标签分类信息
get_event_properties	获取指定事件的属性定义
list_event_properties_all	获取所有事件的属性列表
query_segmentation_report	事件分析查询（次数、人数、维度拆分、筛选过滤）

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制 .env.example 为 .env，填写你的神策分析配置：

cp .env.example .env

SA_URL=https://your-sensors-analytics-url
SA_PROJECT=your_project_name
SA_API_KEY=your_api_key
SA_API_SECRET=your_api_secret  # 可选

API Key 在神策后台「项目管理 → 数据接口」中获取。

3. 编译与启动

# 编译
npm run build

# 生产模式
npm start

# 开发模式（直接运行 TypeScript，改完代码重启即可）
npm run dev

接入 MCP 客户端

QoderWork / Claude Desktop

在 MCP 设置中添加 Server，配置启动命令：

{
  "mcpServers": {
    "sensors": {
      "command": "node",
      "args": ["/path/to/SensorsMCPServer/dist/index.js"],
      "env": {
        "SA_URL": "https://your-sensors-analytics-url",
        "SA_PROJECT": "your_project_name",
        "SA_API_KEY": "your_api_key"
      }
    }
  }
}

MCP Server 使用 stdio 协议通信，由客户端启动和管理进程，无需手动运行。

调试

推荐使用 MCP Inspector 进行调试：

npx @modelcontextprotocol/inspector node dist/index.js

启动后访问 http://localhost:6274，可以手动调用工具、查看请求和响应。

使用示例

接入 MCP 客户端后，直接用自然语言提问即可：

查询上月左侧菜单点击事件的次数和人数

web_workgroup_nav_menu_cli 事件有哪些属性？

查询上月左侧菜单点击情况，按用户和菜单名拆分

AI 会自动探索事件元数据、构建查询参数、调用 API 并解读结果。

项目结构

src/
├── index.ts                 # MCP Server 入口，工具注册与请求路由
├── config.ts                # 环境变量配置管理
└── tools/
    ├── event-meta.ts        # 事件列表与标签查询
    ├── property-meta.ts     # 事件属性查询
    └── segmentation.ts      # 事件分析报告查询

技术栈

• 运行环境：Node.js（ES2022+）
• 开发语言：TypeScript 5.x
• MCP SDK：@modelcontextprotocol/sdk ^0.6.0
• 通信协议：stdio
• API 规范：神策分析 OpenAPI v3
• 认证方式：Header 认证（api-key + sensorsdata-project）

License

ISC