mcp-member-ops

会员运营 MCP 服务 —— 把会员数据能力暴露给 AI 客户端，同时管住三件事：谁能调、能看到什么、调用过什么。

pip install -e ".[dev]"
MCPOPS_ROLE=analyst mcpops serve

标准 MCP JSON-RPC over stdio，手写实现（约 200 行），不依赖 SDK。

三类原语

Tools（4 个）

Resources（2 个）

• mcpops://segments —— 五个人群的标准口径（high_value / at_risk / new / dormant / reactivated）

• mcpops://schema —— 可用表与字段，明确标注 phone 与 id_card 只返回脱敏值

Prompts（1 个）

• churn_review —— 流失复盘的提问模板，强制"数字必须来自工具返回"

Related MCP server: Marketing Agent Eval Harness

RBAC：按能力授权，不按接口

关键在于 get_member_profile 和 segment_summary 都是"读"，但风险差一个量级：一个返回聚合，一个返回行级明细。所以权限挂在能力上，而不是"读/写"上。

授权检查只有一处——Server._call_tool 里的 principal.require(name)。新增传输方式也绕不过去。

脱敏在返回层

printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_member_profile","arguments":{"member_id":"M000001"}}}' \
  | MCPOPS_ROLE=analyst mcpops serve

{
  "member_id": "M000001",
  "member_level": "金卡",
  "phone": "179****7525",
  "id_card": "1101**********0731",
  "orders_90d": 2,
  "masked_columns": ["phone", "id_card"]
}

masked_columns 是显式字段：客户端能知道"这里被处理过"，而不是以为拿到的是原值。

审计

每次调用一条 JSONL，成功和拒绝都记：

{"principal": "test-viewer", "role": "viewer", "method": "tools/call",
 "params": {"name": "get_member_profile", ...}, "ok": false,
 "detail": "role 'viewer' 无权调用 get_member_profile"}

拒绝记录和成功记录同样重要——只看成功日志，等于不知道谁在试探边界。

实测

python -m pytest    # 18 passed

快速开始

pip install -e ".[dev]"

mcpops list                                    # 看原语
mcpops call segment_summary --args '{"dimension":"member_level","month":"2026-09"}'
mcpops call get_member_profile --args '{"member_id":"M000001"}' --role analyst
MCPOPS_ROLE=viewer mcpops serve                # 只读角色跑服务

python -m pytest

接入 AI 客户端时，把 mcpops serve 配成 stdio server 即可。

设计取舍

为什么手写 JSON-RPC 而不装 MCP SDK？ SDK 会更省事，但也会把授权点推进框架的调用链里。这个项目要演示的是"权限必须只有一个闸门"，所以在 dispatch 里显式写一遍更清楚。协议本身只有 6 个方法，没有复杂到必须用库。

为什么角色从环境变量读，不做 OAuth？ OAuth 是部署问题，不是设计问题。演示需要的是"权限模型清楚"，而不是"登录流程完整"。真实部署应该由网关签发 token，服务端只信任网关传入的角色。

为什么任务写入单独文件，不写数据库？ 服务对仓库应当只读。写操作落在独立的 append-only 日志里，既留下痕迹，又不给服务一个能改主数据的连接。

边界

• 角色由环境变量指定，无认证流程；生产环境需网关签发身份

• 脱敏基于列名白名单，改列名需同步维护

• 不做限流与配额

• 审计日志为本地文件，无防篡改

• 数据为合成数据，phone / id_card 均为伪造

License

MIT