Gameball MCP Server

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): ``json { "mcpServers": { "gameball": { "command": "node", "args": ["/path/to/gameball-integrations/dist/index.js"] } } } ``

Docs + Integration (requires API keys): ``json { "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)

1. Parses the OpenAPI spec into endpoint definitions (shared by both subsystems)
2. 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]