Gameball Integrations

Unified Model Context Protocol (MCP) server providing comprehensive access to Gameball's developer documentation and API integration.

Features

This server combines two subsystems and a status tool:

Documentation Tools (7 tools)

• No API keys required - Automatically fetches and indexes documentation from GitHub
• Search and browse Gameball developer docs
• Get API endpoint specifications
• Generate code examples in multiple languages (JavaScript, Python, C#, Go, PHP, Java)
• Access tutorials and guides

Integration Tools (71 tools)

• Requires API keys - Make real API calls to Gameball's services
• Customer management (create, update, query, balance, tags, notifications)
• Transaction handling (cashback, redemption, holds, refunds, OTP)
• Order tracking and queries
• Coupon validation and burning
• Batch operations
• Configuration queries
• Referral system
• Leaderboards
• Events and payments

Status Tool (1 tool)

• gameball-status - Shows server health, subsystem status, configuration, and cache info

Total: 79 tools in one server

Installation

Prerequisites

• Node.js >= 20
• Clone and build the project:

git clone <repository-url> gameball-integrations
cd gameball-integrations
npm install
npm run build

Add to Your Project (recommended)

Create a .mcp.json file at the root of your project. Claude Code automatically detects this file and loads the MCP server for that workspace.

Docs only (no API keys needed):

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

Docs + Integration (requires API keys):

{
  "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"
      }
    }
  }
}

Tip: If the MCP repo is a sibling directory, use a relative path: "args": ["../gameball-integrations/dist/index.js"]

Add Globally (all projects)

To make the tools available across all projects, add the config to ~/.claude/settings.json under the same mcpServers structure shown above.

Via Claude Code 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

Environment Variables

Variable	Required	Description	Default
GAMEBALL_API_KEY	For integration tools	Your Gameball API key	""
GAMEBALL_SECRET_KEY	For sensitive operations	Your Gameball secret key	undefined
GAMEBALL_BASE_URL	No	API base URL	https://api.gameball.co
GITHUB_TOKEN	No	GitHub token for higher rate limits	undefined

Tool Categories

Documentation Tools (docs-* prefix)

All documentation tools work without API keys:

Tool	Description
docs-lookup-topic	START HERE - Comprehensive lookup returning tutorials, docs, and API endpoints for a topic
docs-get-doc	Get full content of a specific documentation page
docs-get-api-endpoint	Get detailed API endpoint specification with parameters and schemas
docs-generate-code-example	Generate code examples in JavaScript, Python, C#, Go, PHP, or Java
docs-search-docs	Full-text search across all documentation
docs-list-sections	Browse documentation structure and available topics
docs-get-tutorial	Get step-by-step tutorial content

Integration Tools (by domain)

All integration tools require GAMEBALL_API_KEY. Tools marked with 🔒 also require GAMEBALL_SECRET_KEY.

Authentication (1 tool)

• generate-session-token - Generate JWT session token

Customers (21 tools)

• 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
• And more...

Transactions (13 tools)

• cashback-transaction, redeem-points, redeem-points-otp
• hold-points, cancel-hold, refund-transaction
• query-transactions, reverse-transaction
• And more...

Orders (4 tools)

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

Coupons (7 tools)

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

Batch Operations (9 tools)

• batch-adjust-balance, batch-send-events, batch-cashback
• batch-redeem, batch-refund, batch-hold, batch-cancel-hold
• And more...

Configuration (10 tools)

• get-action-config, get-challenge-config, get-level-config
• get-tier-config, query-tiers, query-levels
• And more...

Other Domains

• Custom (2 tools): Utilities like customer count, cart tracking
• Events (1 tool): Send customer events
• Leaderboard (1 tool): Get leaderboard rankings
• Payments (1 tool): Record payments
• Referrals (1 tool): Validate referral codes

Status Tool

Tool	Description
gameball-status	Shows subsystem health, API key configuration, cache location, and sync status

How It Works

Startup

1. Fetches the latest commit SHA from GitHub (single API call)
2. Loads both subsystems in parallel:
   • Docs subsystem: Fetches .mdx files and docs.json, builds MiniSearch index
   • Integration subsystem: Fetches openapi.json independently (gzip-cached)
3. Parses the OpenAPI spec into endpoint definitions (shared by both subsystems)
4. Registers all tools and connects via stdio

Progress is reported to stderr during loading:

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

Documentation Subsystem

• GitHub Fetching: Fetches Gameball docs from GitHub with batched requests
• Commit-SHA Cache: Validates cache with 1 API call, re-fetches only when docs change
• Full-Text Indexing: MiniSearch with fuzzy matching and heading-based chunking
• Stale-Cache Fallback: Uses cached docs if GitHub is unreachable

Integration Subsystem

• Independent OpenAPI Fetch: Fetches only openapi.json (not the full docs repo)
• Gzip Cache: Stores the OpenAPI spec compressed with atomic writes
• Auto-Generated Tools: All 71 tools generated from OpenAPI spec at startup
• Smart Adaptive Verbosity: Intelligent descriptions save 78% tokens (~7,000 tokens)
• HTTP Client: Wraps Gameball API v4.0 with automatic auth header injection

Graceful Failure

All GitHub fetches have a 10-second timeout. If GitHub is unavailable:

• With cache: Falls back to stale cached data
• Without cache (cold start): Server starts with 0 tools + status tool
• The gameball-status tool always registers and shows the error state

First run: ~2-3 seconds (fetches from GitHub) Subsequent runs: ~200-500ms (validates cache with 1 API call)

Architecture

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 Layout

~/.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

Usage Examples

Learning about 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

Making API Calls

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

Checking Server Health

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

Development

# 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

Requirements

• Node.js >= 20
• For integration tools: Valid Gameball API credentials

License

MIT

Links

• Gameball Documentation
• Gameball API Reference
• MCP Protocol

Support

For issues or questions:

• Documentation tools: Check cache at ~/.cache/gameball-integrations/
• Integration tools: Verify API credentials in environment variables
• GitHub Issues: [Report bugs or request features]