人群分析 MCP | 产品方案
一、产品定位
为业务方的 AI Agent 提供定义人群、评估表现、刻画画像三个环节的标准化底层工具协议。
核心闭环架构
人群 Tool Group
这群人是谁？
留存 Tool Group
留存表现如何？
画像 Tool Group
长什么样？
三个 Group 共享同一个语义层、鉴权体系，物理上属于同一个 MCP Server。
二、全局演示：一次完整的人群分析闭环
业务背景：春节活动上线7天后，运营想搞清楚活动是否拉动了留存，以及是否有值得跟进的异常亚群。
三、能力范围
V1 核心能力全景图
人群 Tool Group
留存 Tool Group
画像 Tool Group
语义层字典 (API)
四、核心对象：segment_id
它是已被物化（真实计算出用户列表）的人群唯一标识。Agent不直接传递百万明细，只传递枢纽口令。
上游条件生产
自然语言条件
大基数异步执行
segment_id
下游组装消费
五、MCP 工具集
5.1 人群 Tool Group
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
create_segment
按复杂行为、属性组合或名单直传，创建并真实物化人群列表实体。
get_segment_status
针对超大基数人群的创建任务，执行后台轮询以获取计算进度。
get_segment
查询已有人群的元数据，确认筛选条件是否发生漂移或修改。
list_segments
搜索当前项目组的历史人群，减少重复圈人计算，支持复用 ID。
update_segment
传 segment_id，基于最新底层明细数据触发一次人群重新计算。
💬 整合交互示例：定位卡新手关的玩家
5.2 留存 Tool Group
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
analyze_retention
执行任意目标的留存计算，支持连续 N 日曲线与经典点位，最多支持 2 维交叉拆分。
预设留存类型
无需 Agent 拼写起止事件名称，直接调用枚举类型：
- new_user 注册 → 登录
- payment 首充 → 登录
- active 登录 → 登录
- custom 自定义留存事件
💬 整合交互示例：首充用户的 D1~D30 连续复充曲线
5.3 画像 Tool Group
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
profile_segment
对传入的 segment_id 进行深度解剖，输出包含直方分布和分位数指标的用户画像。
💬 整合交互示例：解剖"活跃但不付费"人群
5.4 语义层字典
语义层不是分析工具，而是三个 Tool Group 共享的基础设施。它让大模型能真正"懂"业务数据。
list_user_attributeslist_eventslist_event_attributes核心字典表结构定义
| 字段名 (Field) | 数据类型 | 业务含义 & MCP 约束规则 |
|---|---|---|
| name | string | 属性英文唯一代号（如 vip_level） |
| display_name | string | 前端展示中文名（如 VIP等级） |
| data_type | enum | 枚举限制：string | number | boolean | date | enum |
| applicable_in | array | 防幻觉 圈定该字段可用于哪些工具，如 [segment_filter, profile_dimension] |
| supported_operators | array | 防幻觉 限制大模型可使用的计算符，如 [eq, neq, gt, between] |
| enum_values | array | 若数据为枚举，提供大模型可填入的值映射字典 [{value: "iOS", label: "苹果"}] |
| is_default_profile | boolean | 是否作为 profile_segment 工具的默认分析维度 |
| 字段名 (Field) | 数据类型 | 业务含义 & MCP 约束规则 |
|---|---|---|
| name | string | 埋点事件底层代号（如 activity_join） |
| display_name | string | 事件前端展示中文名（如 参与活动） |
| description | string | 详细口径与触发时机描述，供 Agent 做自然语言语义理解匹配 |
| applicable_in | array | 防幻觉 指定可用模块，如 [segment_filter, retention_start] |
| has_attributes | boolean | 指引 Agent 是否需要继续调取 list_event_attributes 探查参数 |
| sub_events | array | 级联下钻的子事件字典，用于同一事件的多实例区分（如具体哪个活动） |
| 字段名 (Field) | 数据类型 | 业务含义 & MCP 约束规则 |
|---|---|---|
| event_name | string | 绑定的父事件代号（如 payment） |
| name | string | 参数字段英文标识（如 pay_amount） |
| supported_operators | array | 防幻觉 针对此参数可用的算子，如 [gt, lt, between] |
| enum_values | array | 若参数为枚举型，提供键值映射约束 |
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
list_user_attributes
检索当前底表支持的所有用户属性枚举，杜绝胡乱拼写字段。
list_events
根据人类指令的关键字，寻找底层对应的事件真实代号与子集。
list_event_attributes
查阅特定事件所附带的详细参数字段体系（如金额、渠道）。