Gbx MCP Beta

游戏球集成

统一模型上下文协议（MCP）服务器提供对Gameball开发人员文档和API集成的全面访问。

特性

该服务器结合了两个子系统和一个状态工具：

文档工具（7个工具）

• 不需要API密钥 -自动从GitHub获取并索引文档
• 搜索和浏览Gameball开发者文档
• 获取API端点规范
• 生成多种语言的代码示例（JavaScript、Python、C#、Go、PHP、Java）
• 访问教程和指南

集成工具（71个工具）

• 需要API密钥 -对Gameball的服务进行真正的API调用
• 客户管理（创建、更新、查询、余额、标签、通知）
• 交易处理（现金返还、赎回、持有、退款、OTP）
• 订单跟踪和查询
• 优惠券验证和销毁
• 批量操作
• 配置查询
• 转诊制度
• 排行榜
• 活动和付款

状态工具（1个工具）

• gameball-status -显示服务器运行状况、子系统状态、配置和缓存信息

总计：一台服务器上有79个工具

安装

先决条件

• Node.js>=20
• 克隆并构建项目：

git clone  gameball-integrations
cd gameball-integrations
npm install
npm run build

添加到您的项目（推荐）

创建一个 .mcp.json 将文件放在项目的根目录下。Claude Code会自动检测此文件并加载该工作区的MCP服务器。

仅限文档 （不需要API密钥）：

{
  "mcpServers": {
    "gameball": {
      "command": "node",
      "args": ["/path/to/gameball-integrations/dist/index.js"]
    }
  }
}

文档+集成 （需要API密钥）：

{
  "mcpServers": {
    "gameball": {
      "command": "node",
      "args": ["/path/to/gameball-integrations/dist/index.js"],
      "env": {
        "GAMEBALL_API_KEY": "your-api-key",
        "GAMEBALL_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

提示： 如果MCP仓库是兄弟目录，请使用相对路径： "args": ["../gameball-integrations/dist/index.js"]

添加全球（所有项目）

要使这些工具在所有项目中都可用，请将配置添加到 ~/.claude/settings.json 在相同的情况下 mcpServers 如上所示的结构。

通过克劳德代码CLI

# Docs only
claude mcp add gameball node /path/to/gameball-integrations/dist/index.js

# With API keys
claude mcp add gameball node /path/to/gameball-integrations/dist/index.js \
  -e GAMEBALL_API_KEY=your-api-key \
  -e GAMEBALL_SECRET_KEY=your-secret-key

环境变量

工具类别

文档工具（docs-\*前缀）

所有文档工具都可以在没有API密钥的情况下工作：

集成工具（按域）

所有集成工具都需要 GAMEBALL_API_KEY标记有的工具🔒 还要求 GAMEBALL_SECRET_KEY.

身份验证（1个工具）

• generate-session-token -生成JWT会话令牌

客户（21工具）

• create-customer, get-customer, update-customer, delete-customer
• get-customer-balance, adjust-customer-balance 🔒
• get-customer-referrals, send-customer-notification
• get-customer-tags, add-customer-tag, remove-customer-tag
• 还有更多。..

交易（13种工具）

• cashback-transaction, redeem-points, redeem-points-otp
• hold-points, cancel-hold, refund-transaction
• query-transactions, reverse-transaction
• 还有更多。..

订单（4个工具）

• track-order, refund-order, query-orders, cancel-order

优惠券（7工具）

• validate-coupon, burn-coupon, lock-coupon, unlock-coupon
• revoke-burn-coupon, revoke-validation, list-customer-coupons

批量操作（9个工具）

• batch-adjust-balance, batch-send-events, batch-cashback
• batch-redeem, batch-refund, batch-hold, batch-cancel-hold
• 还有更多。..

配置（10个工具）

• get-action-config, get-challenge-config, get-level-config
• get-tier-config, query-tiers, query-levels
• 还有更多。..

其他域名

• 自定义 （2个工具）：客户计数、购物车跟踪等实用程序
• 事件 （1个工具）：发送客户事件
• 排行榜 （1个工具）：获取排行榜排名
• 支付 （1个工具）：记录付款
• 转介 （1个工具）：验证推荐码

状态工具

运作原理

初创公司

1. 从GitHub获取最新提交的SHA（单个API调用）
2. 加载两个子系统 并行:

- 文档子系统：胎儿 .mdx 文件和 docs.json，构建MiniSearch索引 - 集成子系统：胎儿 openapi.json 独立（gzip缓存）

1. 将OpenAPI规范解析为端点定义（由两个子系统共享）
2. 注册所有工具并通过stdio连接

加载过程中向stderr报告进度：

Checking for updates...
Loading...
Ready — 79 tools

文档子系统

• GitHub获取：使用批处理请求从GitHub获取Gameball文档
• 提交SHA缓存：使用1个API调用验证缓存，仅在文档更改时重新传递
• 全文索引：具有模糊匹配和基于标题的组块的MiniSearch
• 过期缓存回退：如果无法访问GitHub，则使用缓存文档

集成子系统

• 独立OpenAPI获取：仅限胎儿 openapi.json （不是完整的文档仓库）
• Gzip缓存：存储用原子写入压缩的OpenAPI规范
• 自动生成的工具：启动时从OpenAPI规范生成的所有71个工具
• 智能自适应冗长：智能描述可节省78%的令牌（约7000个令牌）
• HTTP客户端：使用自动身份验证标头注入包裹Gameball API v4.0

优雅故障

所有GitHub获取都有一个 10秒超时.如果GitHub不可用：

• 使用缓存：回退到过时的缓存数据
• 无缓存（冷启动）：服务器以0个工具+状态工具启动
• 这 gameball-status 工具始终记录并显示错误状态

首次运行：约2-3秒（从GitHub获取） 后续运行：约200-500ms（使用1个API调用验证缓存）

建筑

gameball-integrations/
├── src/
│   ├── index.ts              # Entry point (stdio transport)
│   ├── server.ts             # Server creation (parallel init, graceful failure)
│   ├── status-tool.ts        # gameball-status tool
│   ├── docs/                 # Documentation subsystem (7 tools)
│   │   ├── index.ts          # Init + tool registration
│   │   ├── fetcher.ts        # GitHub fetching + SHA-based cache
│   │   ├── doc-indexer.ts    # MiniSearch indexing + chunking
│   │   ├── mdx-parser.ts     # MDX → plain text
│   │   ├── codegen.ts        # Multi-language code generation
│   │   ├── types.ts          # Doc-specific types
│   │   └── tools/            # 7 documentation tools
│   ├── integration/          # API integration subsystem (71 tools)
│   │   ├── index.ts          # Client creation + tool registration
│   │   ├── openapi-fetcher.ts # Independent openapi.json fetch + gzip cache
│   │   ├── http-client.ts    # GameballClient (auth, error formatting)
│   │   └── generator.ts      # Auto-generates 71 tools from OpenAPI
│   └── shared/               # Common utilities
│       ├── github-cache.ts   # GitHub fetch, SHA check, cache dir, timeout
│       ├── types.ts          # Shared type definitions (ApiEndpoint, etc.)
│       └── openapi-parser.ts # OpenAPI JSON → ApiEndpoint map

缓存布局

~/.cache/gameball-integrations/
├── manifest.json             # Docs cache manifest (commitSha, file list)
├── [__-delimited .mdx files] # Cached documentation pages
├── openapi-manifest.json     # OpenAPI cache manifest (commitSha, timestamp)
└── openapi.json.gz           # Gzip-compressed OpenAPI spec

用法示例

学习Gameball

Use docs-lookup-topic to learn about "customer referrals"
Use docs-get-doc to read "tutorials-new/referral-setup"
Use docs-generate-code-example for JavaScript customer creation

进行API调用

Use create-customer to register a new customer
Use cashback-transaction to reward points
Use query-transactions to check transaction history

检查服务器运行状况

Use gameball-status to see subsystem status, config, and cache info

发展

# Install dependencies
npm install

# Run in development mode (with auto-reload)
npm run dev

# Build for production
npm run build

# Run built version
npm start

需求

• Node.js>=20
• 对于集成工具：有效的Gameball API凭证

许可证

麻省理工学院

链接

• Gameball文档
• 游戏球API参考
• MCP协议

支持

对于问题或疑问：

• 文档工具：检查缓存 ~/.cache/gameball-integrations/
• 集成工具：验证环境变量中的API凭据
• GitHub问题：\[报告错误或请求功能\]