Skip to content
BranchesTags

Latest commit

 

History

13 Commits

Folders and files

NameName
Last commit message
Last commit date
src
src
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

catze-games-infra-mcp

MCP (Model Context Protocol) server for the Catze games backend. Connects AI assistants to game metadata, users, leaderboards, and analytics — read for most resources, plus controlled write access for request and const definitions with automatic on-disk backups.

Installation

npm install
npm run build

Configuration

This server uses stdio transport. Set the following environment variables to configure server profiles:

Variable Description
CATZE_DEFAULT_PROFILE Default profile on startup (defaults to dev)
CATZE_{PROFILE}_URL Backend server URL
CATZE_{PROFILE}_GAME_ID Game UUID from backoffice
CATZE_{PROFILE}_API_KEY API key for the game
CATZE_BACKUP_DIR Override directory for automatic backups (defaults to ~/.catze-mcp/backups)

Setting CATZE_DEV_URL, CATZE_MAIN_URL, and CATZE_LOCAL_URL creates three profiles: dev, main, local. Switch at runtime with catze-switch-profile.

Claude Code 
claude mcp add catze-games-infra \
  -e CATZE_DEFAULT_PROFILE=dev \
  -e CATZE_DEV_URL=https://dev-be.games.catze.xyz \
  -e CATZE_DEV_GAME_ID=<game-id> \
  -e CATZE_DEV_API_KEY=<api-key> \
  -- node /path/to/catze-games-infra-mcp/dist/index.js
Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "catze-games-infra": {
      "command": "node",
      "args": ["/path/to/catze-games-infra-mcp/dist/index.js"],
      "env": {
        "CATZE_DEFAULT_PROFILE": "dev",
        "CATZE_DEV_URL": "https://dev-be.games.catze.xyz",
        "CATZE_DEV_GAME_ID": "<game-id>",
        "CATZE_DEV_API_KEY": "<api-key>"
      }
    }
  }
}
Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "catze-games-infra": {
      "command": "node",
      "args": ["/path/to/catze-games-infra-mcp/dist/index.js"],
      "env": {
        "CATZE_DEFAULT_PROFILE": "dev",
        "CATZE_DEV_URL": "https://dev-be.games.catze.xyz",
        "CATZE_DEV_GAME_ID": "<game-id>",
        "CATZE_DEV_API_KEY": "<api-key>"
      }
    }
  }
}

Available Tools

Profile

Tool Description
catze-current-profile Show active profile and connection info
catze-switch-profile Switch profile (dev, main, local, etc.)

Metadata

Tool Description
catze-list-tables List data tables. summary=true returns keys only
catze-get-table Get a table's schema + full row data
catze-list-requests List request definitions. summary=true returns IDs only
catze-get-request Get detailed steps for a specific request
catze-list-consts List constants. summary=true returns keys only
catze-get-const Get a specific constant's value
catze-export-requests Export all request definitions
catze-export-consts Export all constants
catze-upsert-request Create or update a request definition (write)
catze-delete-request Delete a request definition (write)
catze-import-requests Bulk import request definitions, optional purge for full rollback (write)
catze-upsert-const Create or update a const definition (write)
catze-delete-const Delete a const definition (write)
catze-import-consts Bulk import const definitions, optional purge (write)
catze-list-backups List on-disk auto-backup files for the active profile/game

Dynamic DB (read)

Tool Description
catze-db-list-tables List dynamic tables (summary). summary=true returns keys only
catze-db-get-table Get a dynamic table's schema/policy/storage
catze-db-list-rows Cursor-paged row listing with filters, sort, and ownerUserId
catze-db-dump-table Dump every row of a table to disk via cursor pagination
catze-db-changelog Read audit changelog entries for a table (or a single row)

Users

Tool Description
catze-list-users List users (supports limit, offset)
catze-get-user Get user details
catze-get-user-data Get user's game data
catze-get-user-history Get user's operation history (before/after snapshots)

Leaderboards

Tool Description
catze-list-leaderboards List leaderboards
catze-get-leaderboard Get leaderboard entries (supports limit, offset)

Analytics

Tool Description
catze-get-analytics Game analytics overview (DAU, new signups, etc.)
catze-get-retention Retention data

Notes

  • Most tools are read-only. Write access is limited to metadata requests and consts.
  • For large responses, use summary=true on list tools to fetch keys/IDs first, then query individual items.
  • Requires Node.js 18+.

Backup Policy (write operations)

Every write tool (catze-upsert-request, catze-delete-request, catze-import-requests, and the const equivalents) automatically snapshots the current state with the server's export endpoint and writes it to disk before the mutation runs. If the backup write fails, the mutation is aborted — there is no opt-out.

  • Default directory: ~/.catze-mcp/backups/{profile}/{gameId}/
  • Override with the CATZE_BACKUP_DIR env var.
  • Filename pattern: {ISO_timestamp}_{requests|consts}_{op}_{key}.json
  • Listed by catze-list-backups.
  • Recovery: pass a backup file path as backupFile to catze-import-requests / catze-import-consts.
  • purge=true on import deletes any current key not present in the backup — use only for intentional full rollback. The server has no built-in concurrency protection (no etag/version), so backups are the primary safety net.

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages