# WukongMCP — 听云悟空平台 MCP Server

基于 [听云 (Tingyun) RUM REST API](https://wukongdoc.tingyun.com/ty-doc/docs/api/RUM/App/) 的 MCP Server，让 AI 助手直接查询听云全平台（App / Browser / MiniProgram）监测数据。

## 快速开始

### 1. 获取 Access Token

登录 [悟空平台](https://wukong2.tingyun.com)，鼠标悬浮左下角账户 → **账户管理** → **API** → 生成 `accessToken`（永久有效）。

### 2. 设置环境变量

```bash
# 必填：听云平台地址 + App 端 accessToken
export TINGYUN_HOST="wukong2.tingyun.com"
export TINGYUN_ACCESS_TOKEN="你的App端accessToken"

# 可选：Browser Web 端鉴权（如需查询 Web 端数据）
export TINGYUN_API_KEY="你的api_key"
export TINGYUN_AUTH="你的auth签名"
```

### 3. 编译 & 运行

```bash
npm install
npm run build
node dist/index.js          # 手动启动（stdio JSON-RPC）
```

### 4. 注册到 Reasonix

在 `reasonix.toml` 中添加：

```toml
[[plugins]]
name    = "tingyun"
command = "node"
args    = ["dist/index.js"]
```

## 可用 Tools（13 个）

| Tool | 用途 |
|------|------|
| **tingyun_get_app_list** | 获取 Mobile App 列表（返回 mobileAppId） |
| **tingyun_adhoc_query** | 🔥 核心通用查询引擎 — 覆盖 16 种数据源，支持任意 metrics × dimensions × filters 组合 |
| **tingyun_get_app_performance** | 应用整体性能概览：体验评分、行业对比、性能指标列表 |
| **tingyun_get_exception_metrics** | 崩溃/卡顿/OOM/错误：TOP 分布、信息卡片、异常列表、趋势 |
| **tingyun_get_ux_metrics** | 用户体验：页面/操作/启动的 TOP 分布、列表、趋势、追踪 |
| **tingyun_get_user_metrics** | 用户统计：新增/活跃/启动/时长/日活/月活/TOP 分布 |
| **tingyun_get_version_metrics** | 版本分布：各版本启动趋势、设备趋势、性能对比 |
| **tingyun_get_network_metrics** | 网络请求：丢包率、关键请求、百分位、域名列表、网络延迟、探测任务 |
| **tingyun_get_trace_detail** | 单点追踪：崩溃/卡顿/启动/操作/页面/错误请求的详细堆栈和上下文 |
| **tingyun_manage_log_tasks** | 日志回捞：创建/修改/查询日志回捞任务，获取收集列表 |
| **tingyun_get_protocol_extension** | 协议扩展：自定义 span 耗时/失败率/分布图/分位图/异常详情 |
| **tingyun_get_web_metrics** | Browser Web 端 RUM 数据 |
| **tingyun_get_mp_metrics** | 小程序 (MiniProgram) RUM 数据 |

## 示例对话

**Q**: 帮我看看 app_test 过去 24 小时的崩溃率和趋势
→ AI 先调 `tingyun_get_app_list` 获取 mobileAppId，再调 `tingyun_get_exception_metrics(type=crash, query=card + trend_rate)`

**Q**: 最近 1 小时网络请求最慢的 TOP5 域名是哪些？
→ `tingyun_get_network_metrics(query=domain_list, timePeriod=60)`

**Q**: 分析一下昨天崩溃最多的设备型号
→ `tingyun_adhoc_query(datasource=APP_EXCEPTION_DATA, metrics=[crashCount], dimensions=[manufacturerModelId], timePeriod=1440)`

## 技术栈

- TypeScript + Node.js
- `@modelcontextprotocol/sdk` — MCP 协议层
- `zod` — 参数校验
- `undici` — HTTP 客户端