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: via54-social-roi

权限

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