# Sensors MCP Server

基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 的神策分析数据服务，让 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. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

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

```bash
cp .env.example .env
```

```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. 编译与启动

```bash
# 编译
npm run build

# 生产模式
npm start

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

## 接入 MCP 客户端

### QoderWork / Claude Desktop

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

```json
{
  "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](https://github.com/modelcontextprotocol/inspector) 进行调试：

```bash
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