AI导哈

忠诚度计划管理服务

Gameball MCP Server 是一个用于通过AI代理管理Gameball忠诚度计划配置的多租户服务器，每个请求都通过Gameball仪表板生成的个人访问令牌(PAT)进行身份验证。

  • by Ahmedelmonady
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Ahmedelmonady/gb-mcp

使用说明

游戏球MCP服务器

MCP（模型上下文协议）服务器，用于通过AI代理管理Gameball忠诚度计划配置。多租户——每个请求都使用从Gameball仪表板生成的个人访问令牌（PAT）进行身份验证。

设置

npm install
npm run build
npm start

服务器启动于 :8080 （用覆盖 PORT=...)并在以下位置暴露单个端点 POST /mcp.

认证

每个请求都必须包括呼叫者的PAT X-GB-Access-Token 头球MCP服务器将其传递给Gameball后端，Gameball后端验证令牌并应用附加的作用域规则。

POST /mcp HTTP/1.1
Content-Type: application/json
X-GB-Access-Token: gbpat_your_token_here

{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }

配置

环境变量 必填 说明
PORT 无 HTTP端口。默认为 8080.
GAMEBALL_BASE_URL 否 游戏球API基本URL。默认为 https://api.gameball.co.
CODEX_PATH 否 包含每个工具代码的本地目录 *.md 文档。未设置时，捆绑 build/tools/codex/ 使用服务器附带的。
CODEX_REPO 没有 codex文档仓库的Git URL。当设置为 CODEX_PATH，如果缺少，服务器将在启动时克隆到该路径中，否则将提取最新路径 CODEX_REF.
CODEX_REF 否 分支/标记/提交跟踪。默认为 main.
CODEX_WEBHOOK_PORT 没有 TCP端口 POST /admin/codex-sync.默认为 0 （残疾）。
CODEX_SYNC_KEY 否 需要启用 /admin/* webhook监听器。呼叫者必须发送匹配的 X-GB-Sync-Key 头球未设置时，侦听器不会启动。

价值观可以来自 docker run -e KEY=value, --env-file，或JSON加载器位于 src/environments/environment[.<NODE_ENV>].json。参见 技术_培训_测试.md 对于完整的配置模型和优先级规则。

工具代码

每个工具都附带了详细的参考文档 src/tools/codex/<tool>.md。这些文件是 未通过MCP暴露 --它们是通过codex管理端点出现的仅限操作员/管理员的工件（请参阅codex同步部分）。共享指令块({{> template_flow}}, {{> core_required}}, {{> update_flow}})定义见 src/tools/shared.ts 当管理文件端点为文档提供服务时，将其内联。

看 TOKEN_MEASURENT.md 如何衡量储蓄。

可用工具集

实用工具（7）

工具 说明
get_supported_languages 客户支持的语言，包括ID、代码、方向
get_collections 具有collectionId的产品集合用于限制规则
get_tags 标签、片段、带有ID和类型的RFM，用于受众定位
get_customer_attributes 使用键和数据类型自定义客户属性
get_events 带有元数据字段和ID的事件（触发器），用于创建活动
get_merchants 具有外部ID、名称和分支机构的商家
get_icons 徽章/图标库，用于选择奖励和等级的视觉效果

方案2

工具 说明
get_program_activation 检查忠诚度计划是否处于活动状态（GbEnabled）
toggle_program_activation 启用/禁用整个忠诚度计划

VIP等级（2）

工具 说明
get_tiers 列出带有ID、名称、顺序和分数阈值的VIP级别
get_tier_details 单层的完整细节——包括奖励配置、地区、图标

赎回选择权（6）

工具 说明
get_redemption_options 列出所有兑换规则（slim:id、姓名、类型、积分、isVisible）
get_redemption_option 按ID列出单个规则的完整详细信息
create_redemption_option 创建新规则（固定、百分比、免费送货、免费产品、自定义）
update_redemption_option 按ID更新现有规则
toggle_redemption_option_activation 按ID激活/停用规则
delete_redemption_option 按ID删除规则（受一般规则保护）

奖励活动（16）

模板第一流：调用 get_campaign_template 首先，只修改用户想要的字段，然后调用相应的分组创建工具。

工具 说明
get_campaign_template 按类型名称获取种子模板。返回具有所有默认值的完整对象。
get_reward_campaigns 使用分页+仪表板奇偶校验过滤器列出活动
get_reward_campaigns_count 与筛选器匹配的活动总数
get_reward_campaigns_stats 列出活动，并预先汇总每个活动的成就计数
get_reward_campaign 按ID列出单个活动的完整详细信息
get_reward_campaign_customers 列出特定活动的成就记录
get_reward_campaign_customers_count 特定活动的成就记录计数
create_game_campaign 游戏活动：SpinTheWheel、SlotMachine、ScratchAndWin、测验、火柴卡、捕手、TicTacToe、太空射击、拼图、TapTheTarget、DrivingGame
create_event_campaign 事件触发的活动：基于事件、SpendingMilestone
create_date_campaign 日期触发的活动：基于日期（生日、加入日期、自定义属性）
create_mission 任务活动：非连续任务
create_calendar_campaign 日历活动：每天父容器+子活动
create_newsletter 通讯订阅活动（必须创建非活动）
update_reward_campaign 按ID更新现有活动
toggle_reward_campaign_activation 按ID激活/停用活动
delete_reward_campaign 按ID删除活动和所有子实体

小部件设置（5）

总是打电话 get_widget_settings 首先，更新使用AutoMapper合并，因此空值会擦除现有值。

工具 说明
get_widget_settings 完整的小部件配置：品牌、常规、访客、功能切换
update_widget_style 更新品牌：颜色、主题、字体、图标、启动按钮
update_widget_settings 更新普通+客人：可见性、功能、推荐、消息传递、链接
update_widget_sorting 更新活动、任务和兑换排序偏好
update_supported_languages 添加、删除或更改默认语言

收入（8）

工具 说明
get_earning_config 阅读一般收入配置（费率、货币、到期、待定、运费/免税额）
update_earning_config 更新一般收入配置
get_earning_rules 列出默认收入规则
update_earning_rules 更新默认收入规则
create_custom_earning_rule 使用3种奖励模式之一创建自定义赚取规则
get_custom_earning_rules 列出自定义收入规则
update_custom_earning_rule 更新自定义收入规则
delete_custom_earning_rule 删除自定义收入规则

客户（7）

工具 说明
get_customers 列出具有分页和18种筛选类型的客户
get_customers_count 总客户数（总客户数、活跃客户数、非活跃客户数）
get_customer_details 按ExternalId（customerId）获取完整的客户资料
add_customer_points 将积分或货币金额添加到客户的余额中
deduct_customer_points 从客户余额中扣除积分或货币金额
assign_customer_tags 按游戏球ID为一个或多个客户分配标签
remove_customer_tags 按游戏球ID从一个或多个客户中删除标签

分析（1）

工具 说明
get_analytics_chart 从90个图表目录（8个仪表板页面，6种图表类型）中提取一个分析图表。必修的： chartName, from, to.

建筑

AI Agent (Claude, Cursor, etc.)
  +-- HTTP POST /mcp (Streamable HTTP transport)
        +-- gameball-mcp (this server)
              +-- per-request McpServer + GameballAPIClient (scoped to caller's PAT)
                    +-- HTTP (X-GB-Access-Token header)
                          +-- Gameball API (/api/v4.0/mcp/*)

根据请求，服务器实例保证用户之间没有状态泄漏。

健康

GET /healthz 回报 200 { "status": "ok" } 用于编排器探测。

发展

npm run dev    # Watch mode (recompiles on change)
npm run build  # One-time build
npm start      # Run the server

相关 MCP