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 }

配置

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

工具代码

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

看 TOKEN_MEASURENT.md 如何衡量储蓄。

可用工具集

实用工具（7）

方案2

VIP等级（2）

赎回选择权（6）

奖励活动（16）

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

小部件设置（5）

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

收入（8）

客户（7）

分析（1）

建筑

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