{
  "markdown": "# scorezilla-mcp\n\n[![npm version](https://img.shields.io/npm/v/@scorezilla/mcp.svg)](https://www.npmjs.com/package/@scorezilla/mcp)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nOfficial Model Context Protocol (MCP) server for [Scorezilla](https://scorezilla.dev) — the easiest way to add a leaderboard to your game. Connect this server to your AI coding assistant (Claude Code, Cursor, Continue.dev, …) and ship a working leaderboard without leaving your editor.\n\n## What you can ask the AI to do\n\n- \"Add a leaderboard to my game\" → it bootstraps a game + board and pastes ready-to-run TypeScript SDK code into your project\n- \"What did my last test score rank?\" → it reads your live leaderboard\n- \"List my games\" / \"show me the boards on X\" → it inspects what you already have\n\nEleven tools total — five read-only, and six that write: four that create resources (`bootstrap_leaderboard`, `create_game`, `create_board`, `mint_key`) plus two that update config (`update_board_config` — score bounds + retention, e.g. an anti-cheat `maxScore`; `update_game_config` — the browser-submit origin allowlist).\n\n## Install + configure\n\n> **Status — v0.3.0.** Published on the `@latest` dist-tag. `0.3.0` adds three create-only write tools — `create_game`, `create_board`, `mint_key` — so an agent can provision against an **existing** game (add boards, mint keys, create more games), not just bootstrap a brand-new one. `0.2.0` added the integration-axis arguments (identity strategy, OAuth provider, hosting/anti-cheat pattern, server language) to `bootstrap_leaderboard` + `get_sdk_snippet`. Destructive ops (edit/delete, key revocation) remain dashboard-only by design.\n\n### 1. Get a token\n\nSign in at [dashboard.scorezilla.dev](https://dashboard.scorezilla.dev), open **MCP tokens**, click **Create token**. Copy the `mcp_live_*` value once — it's not shown again.\n\n### 2. Add the server to your AI coding assistant\n\n**Claude Code** — edit `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"scorezilla\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@scorezilla/mcp\"],\n      \"env\": {\n        \"SCOREZILLA_TOKEN\": \"mcp_live_…\"\n      }\n    }\n  }\n}\n```\n\n> 🔒 **Keep `~/.claude/settings.json` private.** The token is stored in plaintext in that file. Make sure it's not committed to git (it's usually in your `.gitignore`), not synced to a public dotfiles repo, and not backed up to a shared location. On macOS/Linux: `chmod 600 ~/.claude/settings.json` so only your user can read it. If a token leaks, revoke it at [dashboard.scorezilla.dev/account/tokens](https://dashboard.scorezilla.dev/account/tokens).\n\n**Cursor** — open Settings → Features → MCP → Add new MCP server, then use the same `command` + `args` + `env` shape.\n\n**Anything else MCP-compatible** — point your client at `npx -y @scorezilla/mcp` with `SCOREZILLA_TOKEN` set in the environment.\n\n### 3. Ask away\n\nIn Claude Code or Cursor: _\"Add a Scorezilla leaderboard to this game.\"_\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `list_games` | Lists your games. Use this first to orient. |\n| `list_boards` | Lists leaderboards under a game. |\n| `get_keys` | Returns the public key (safe to embed) and the secret-key prefix. The full secret never leaves the dashboard. |\n| `get_board_top_n` | Returns the top entries on a board. The \"is my integration working?\" tool. |\n| `get_sdk_snippet` | Returns ready-to-paste integration code for a board. Optional axis args tailor it: anonymous/OAuth identity, client-only vs. server-validated **anti-cheat**, and the server language (TS/Python/Go/C#). |\n| `bootstrap_leaderboard` | Creates a new game + first board in one call, then returns the **widget embed** + **SDK snippet** + a plain-English recommendation. Same optional axis args (anti-cheat, OAuth, server language). The 90-second-demo path. |\n| `create_game` | Creates a new (empty) game. Use when a game already exists (so `bootstrap_leaderboard` would conflict) or you want another. |\n| `create_board` | Adds a leaderboard board to an **existing** game (by `gameId`), with full options (sortDir, scoreKind, retention, bounds). |\n| `mint_key` | Mints a fresh public/secret key pair for an existing game. The secret is shown once. |\n\n## Flags\n\n```bash\nscorezilla-mcp [--read-only] [--base-url=<url>] [--version] [--help]\n```\n\n- `--read-only` — refuse to register the write tools (`bootstrap_leaderboard`, `create_game`, `create_board`, `mint_key`, `update_board_config`, `update_game_config`). Use this on shared/CI configs to guarantee the AI can't create or change resources.\n- `--base-url=<url>` — override the API origin. Defaults to `https://api.scorezilla.dev`. Useful for self-hosted or staging environments.\n\n## Env vars\n\n- `SCOREZILLA_TOKEN` — **required**. Bearer token issued at [dashboard.scorezilla.dev/account/tokens](https://dashboard.scorezilla.dev/account/tokens).\n- `SCOREZILLA_BASE_URL` — same as `--base-url`, but via env. CLI flag wins if both are set.\n- `SCOREZILLA_BETA_TOKEN` — pre-public closed-beta only. When set, sent as the `X-MCP-Beta` header on every API call to unlock the MCP namespace before the public switch is flipped. You'll only need this if a Scorezilla team member gave you a beta token; ignore otherwise.\n\n## Tokens: how they work\n\n- Tokens are scoped to the developer who issued them and see every game associated with their account.\n- The MCP server **never** returns the secret-key plaintext for a game — for that, copy from the dashboard.\n- Revoke a token any time at [dashboard.scorezilla.dev/account/tokens](https://dashboard.scorezilla.dev/account/tokens). Revocations propagate within a few seconds.\n- Tokens are bearer credentials: anyone with the value can call the API on your behalf. Don't commit them to source; don't paste them into shared chats. Keep them in `env` blocks, password managers, or secret stores.\n\n## Runtime requirements\n\n- Node ≥ 20\n- A network path to `https://api.scorezilla.dev`\n\n## Releasing\n\nReleases are CI-driven and require an approval click in the `npm-publish` GitHub Environment. The full flow:\n\n1. **Author a changeset** locally: `pnpm changeset` — describes what changed and the bump type. Commit the file under `.changeset/`.\n2. **Merge to main.** `.github/workflows/release.yml` runs and opens a \"chore(release): version @scorezilla/mcp\" PR that bumps `package.json`, syncs `server.json` (the MCP Registry manifest) via `scripts/sync-server-json-version.mjs`, and updates `CHANGELOG.md`.\n3. **Merge the version PR.** The same workflow then publishes:\n   - npm tarball with `--provenance` (verifiable build attestation via GH OIDC + sigstore)\n   - MCP Registry record via `mcp-publisher login github-oidc` → `mcp-publisher publish`\n   - Post-publish smoke test that installs the published tarball and runs the binary\n4. **Pre-flight guards** that run before publish: typecheck, test, build, bin smoke (`node dist/index.js --version`), and `release:check` (asserts `package.json` and `server.json` versions agree).\n\nManual publishes from a developer terminal still work (`bash scripts/publish.sh`) but aren't the path CI takes — they skip provenance and approval gates. Use only for one-off recovery.\n\n## Issues / feedback\n\n[GitHub Issues](https://github.com/isco-tec/scorezilla-mcp/issues).\n\n## License\n\n[MIT](./LICENSE).\n",
  "bytes": 7312,
  "sha": "f81b8dd43eeed485638b62daf78c86c3568208fbefee1e0fa3608429df8305a9",
  "repo_slug": "isco-tec/scorezilla-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_isco_tec_mcp_beeca00e/readme"
}