isco-tec

scorezilla-mcp

只需向 Claude Code 或 Cursor 提出要求，即可为你的游戏添加全球排行榜。 接入的 SDK 压缩后约为 5 KB，且没有运行时依赖。

Scorezilla 的官方模型上下文协议（MCP）服务：Scorezilla。将它连接到你的 AI 编码助手（Claude Code、Cursor、Continue.dev 等），无需离开编辑器即可发布可用的排行榜。

你可以让 AI 做什么

• “为我的游戏添加排行榜” → 自动创建游戏和排行榜，并将可直接运行的 TypeScript SDK 代码粘贴到你的项目中
• “我上次测试的分数排名是多少？” → 读取你的实时排行榜
• “列出我的游戏” / “显示 X 上的排行榜” → 查看你已有的内容

总共有 11 个工具——5 个只读工具，6 个可写工具：4 个用于创建资源（bootstrap_leaderboard、create_game、create_board、mint_key），另有 2 个用于更新配置（update_board_config——分数范围和保留策略，例如防作弊用的 maxScore；update_game_config——浏览器提交来源的允许列表）。

安装和配置

访问权限——所有 Scorezilla 账户均可使用。 在 dashboard.scorezilla.dev 免费注册，创建令牌即可开始使用。创建游戏和排行榜会计入你套餐的限额（Free：2 个游戏 × 每个游戏 3 个排行榜）；达到限额时，工具错误信息会附上直接升级链接。详见定价。

1. 获取令牌

登录 dashboard.scorezilla.dev，打开 MCP tokens，点击 Create token。复制一次 mcp_live_* 值——之后将不再显示。

2. 将服务添加到你的 AI 编码助手

Claude Code——运行一条命令（--scope user 可在每个项目中使用）：

claude mcp add scorezilla --scope user -e SCOREZILLA_TOKEN=mcp_live_… -- npx -y @scorezilla/mcp

Cursor——将以下内容添加到 ~/.cursor/mcp.json（或前往 Settings → MCP → Add new MCP server）：

{
  "mcpServers": {
    "scorezilla": {
      "command": "npx",
      "args": ["-y", "@scorezilla/mcp"],
      "env": {
        "SCOREZILLA_TOKEN": "mcp_live_…"
      }
    }
  }
}

🔒 请妥善保管 MCP 配置。 两个客户端都会以明文形式保存令牌（Claude Code 保存于 ~/.claude.json，Cursor 保存于 ~/.cursor/mcp.json）。不要将其提交到 git、同步到公开的 dotfiles 仓库，或备份到共享位置。在 macOS/Linux 上，对文件运行 chmod 600，确保只有你的用户能够读取。如果令牌泄露，请前往 dashboard.scorezilla.dev/account/tokens 撤销。

Claude Desktop——只需点击一次：从最新版本下载 scorezilla-mcp.mcpb，双击它，并在 Claude Desktop 提示时粘贴你的 mcp_live_… 令牌。令牌会保存在系统的安全凭据存储区中。

其他兼容 MCP 的客户端——将客户端指向 npx -y @scorezilla/mcp，并在环境中设置 SCOREZILLA_TOKEN。

3. 开始提问

在 Claude Code 或 Cursor 中输入：“为这个游戏添加一个 Scorezilla 排行榜。”

工具

工具	功能
list_games	列出你的游戏。请先使用此工具了解情况。
list_boards	列出某个游戏下的排行榜。
get_keys	返回公钥（可安全嵌入）和密钥前缀。完整密钥不会离开控制面板。
get_board_top_n	返回某个排行榜上的前几名条目。用于检查“我的集成是否正常工作？”
get_sdk_snippet	返回可直接粘贴的排行榜集成代码。可选的轴参数可定制：匿名/OAuth 身份、仅客户端或服务器验证的反作弊，以及服务器语言（TS/Python/Go/C#）。
bootstrap_leaderboard	一次调用即可创建新游戏和首个排行榜，然后返回小组件嵌入代码、SDK 代码片段和纯英文建议。使用相同的可选轴参数（反作弊、OAuth、服务器语言）。适用于 90 秒演示流程。
create_game	创建一个新的空游戏。适用于游戏已存在（因此 bootstrap_leaderboard 会发生冲突）或你想再创建一个游戏的情况。
create_board	在现有游戏（通过 gameId 指定）中添加排行榜，并支持完整选项（sortDir、scoreKind、retention、bounds）。
mint_key	为现有游戏生成一对新的公钥/密钥。密钥只会显示一次。
update_board_config	更改排行榜的分数范围（例如反作弊用的 maxScore）和保留策略。支持部分更新；将 null 设为清除某个范围限制。
update_game_config	设置游戏的浏览器提交来源允许列表（例如 https://yourgame.com、*.yourgame.com）。空列表表示允许所有来源。

重试

创建类工具（bootstrap_leaderboard、create_game、create_board、mint_key）会根据参数生成 Idempotency-Key。如果调用超时，且你的助手在 5 分钟内使用相同参数重试，API 会返回原始结果，而不会创建重复对象：bootstrap_leaderboard 会返回相同的游戏和排行榜，mint_key 会返回相同的密钥对。

超过该时限后，或者如果 bootstrap_leaderboard 返回 partial_failure 或 slug_taken_active，请勿再次执行初始化。调用 list_games（和 list_boards）查看现有内容，然后通过 create_board 或 mint_key 完成操作。

计划限制

创建游戏和排行榜会计入你的 Scorezilla 计划限额（Free：2 个游戏，每个游戏 3 个排行榜；详见定价）。如果写入操作会超出限额，工具会返回 plan_limit 错误，其中包含限额和直接升级链接，助手可以转发该链接。系统绝不会自动扣费。请求也会按令牌和账户进行速率限制；rate_limited 错误会说明何时可以重试。

标志

scorezilla-mcp [--read-only] [--base-url=<url>] [--version] [--help]

• --read-only — 拒绝注册写入类工具（bootstrap_leaderboard、create_game、create_board、mint_key、update_board_config、update_game_config）。在共享配置或 CI 配置中使用此选项，可确保 AI 无法创建或更改资源。
• --base-url=<url> — 覆盖 API 来源。默认值为 https://api.scorezilla.dev。适用于可自托管或暂存环境。

环境变量

• SCOREZILLA_TOKEN — 必需。在 dashboard.scorezilla.dev/account/tokens 签发的 Bearer 令牌。
• SCOREZILLA_BASE_URL — 与 --base-url 相同，但通过环境变量设置。如果两者都设置，则以 CLI 标志为准。
• SCOREZILLA_BETA_TOKEN — 不再需要；此 MCP 已向所有账户开放。为兼容性保留（设置后会作为 X-MCP-Beta 发送）。

令牌：工作原理

• 令牌的作用范围限于签发它的开发者，并可访问与其账户关联的所有游戏。
• MCP 服务绝不会返回游戏的密钥明文；如需查看，请从控制面板复制。
• 可随时在 dashboard.scorezilla.dev/account/tokens 撤销令牌。撤销会在几秒内生效。
• 令牌是持有者凭证：任何拥有该令牌值的人都能代表你调用 API。不要将其提交到源代码中，也不要粘贴到共享聊天中。请将其保存在 env 配置块、密码管理器或密钥存储中。

运行时要求

• Node ≥ 20
• 能够连接到 https://api.scorezilla.dev

发布

发布由 CI 驱动，并需要在 npm-publish GitHub Environment 中点击批准。完整流程如下：

1. 在本地编写变更集：运行 pnpm changeset，描述变更内容和版本升级类型。将文件提交到 .changeset/ 下。
2. 合并到 main。 .github/workflows/release.yml 会运行，并创建一个“chore(release): version @scorezilla/mcp” PR，该 PR 会升级 package.json 中的版本，通过 scripts/sync-server-json-version.mjs 同步 server.json（MCP Registry 清单），并更新 CHANGELOG.md。
3. 合并版本 PR。 随后，同一工作流会发布：
   • npm 压缩包，并附带 --provenance（通过 GH OIDC + sigstore 实现可验证的构建证明），以及 @scorezilla/mcp@<version> git 标签和 GitHub 发布（说明来自 CHANGELOG.md）
   • 发布后的冒烟测试：安装已发布的压缩包并运行二进制文件
   • 仅在冒烟测试通过后，通过 mcp-publisher login github-oidc → mcp-publisher publish 发布 MCP Registry 记录；此流程会等待 npm 提供该版本，并在 Registry 尚不可见时重试
4. 发布前检查会在发布前运行：类型检查、测试、构建、二进制文件冒烟测试（node dist/index.js --version）以及 release:check（确保 package.json 和 server.json 中的版本一致）。

开发者仍可在终端手动发布（bash scripts/publish.sh），但这不是 CI 采用的流程——手动发布会跳过 provenance 和审批环节。仅用于一次性故障恢复。

问题 / 反馈

GitHub Issues。

许可证

MIT。