scorezilla-mcp: Instructions file for Claude Code

CLAUDE.md

Official MCP server for Scorezilla (scorezilla.dev) — a stdio CLI (npx -y @scorezilla/mcp) that lets AI coding assistants manage game leaderboards. Thin client of api.scorezilla.dev; no hosted component here. This repo is PUBLIC — never commit tokens, secrets, or private-monorepo internals.

Stack

TypeScript (ESM), Node >= 20, @modelcontextprotocol/sdk, zod v4. tsup bundles to dist/index.js (the published bin), vitest for tests, changesets for versioning.

Commands

Package manager is pnpm (v9 in CI) — never npm/yarn.

• pnpm typecheck — tsc --noEmit (also enforces compile-time contract assertions)
• pnpm test — vitest run
• pnpm build — tsup
• node dist/index.js --version — bin smoke test (run after build, CI does)
• pnpm release:check — package.json ↔ server.json version sync guard
• pnpm changeset — add a changeset (required for any user-facing change)

Deploy (npm publish)

• Publishing is CI-only via .github/workflows/release.yml — never run npm publish or bash scripts/publish.sh manually (the manual path skips provenance; it exists only as a documented disaster fallback).
• Actual flow (changesets, NOT tag-based): merge to main → Release workflow (every run pauses for manual approval via the npm-publish GitHub Environment) → changesets opens/updates a "Version Packages" PR → merging that PR publishes to npm with --provenance (+ @scorezilla/mcp@<version> git tag and GitHub release), runs a post-publish install smoke test, then publishes to the MCP Registry (mcp-publisher; waits for npm propagation and retries the Registry's "version not found").
• Never bump versions by hand — changesets only. package.json and server.json must stay in sync (scripts/sync-server-json-version.mjs; release:check guards it).
• workflow_dispatch input registry_resync: true re-publishes the current version to the MCP Registry only — recovery for "npm published, registry step failed".

Rules & gotchas

• Contract mirror: src/contract.ts is a hand-maintained MIRROR of the private monorepo's MCP wire contract. When test/contract-drift.test.ts fails after an upstream sync, update src/contract.ts to match the vendored test/contract/mcp.generated.ts — NEVER edit the vendored file, never invent fields, never "fix" the test. A red drift check after upstream changes is by design, not a bug.
• Part of the drift guard is compile-time (expectTypeOf) — it fails pnpm typecheck, not pnpm test. Run both.
• Base URL is HTTPS-only (localhost exempted); write tools send content-derived Idempotency-Key headers — preserve both behaviors when touching the HTTP layer.
• Runtime env vars (users', not CI): SCOREZILLA_TOKEN, SCOREZILLA_BASE_URL, SCOREZILLA_BETA_TOKEN. Reference names only; never write values anywhere.
• MCPB bundle for Claude Desktop: after each release, run pnpm pack:mcpb on main and attach the output to the new GitHub release under the stable name scorezilla-mcp.mcpb (gh release upload "@scorezilla/mcp@<version>" scorezilla-mcp.mcpb). The README links releases/latest/download/scorezilla-mcp.mcpb, so a release without it breaks that link. (Smithery was the other MCPB consumer; it shut down publishing on 2026-10-31 — don't target it.)
• Claude plugin (plugin/) is submitted to Anthropic's plugin directory, which tracks main. It pins the MCP server via plugin/package.json + plugin/package-lock.json (npm, not pnpm; needed for the directory's Verified badge). After each @scorezilla/mcp release: bump the pin, run npm install --package-lock-only --ignore-scripts in plugin/, bump version in plugin/.claude-plugin/plugin.json, then claude plugin validate --strict ./plugin. Before testing with claude --plugin-dir ./plugin, run npm ci --ignore-scripts in plugin/ (in-place loads skip the dependency install).
• The README has no version-specific text (the old "Status" blurb was removed in #75); the version lives in plugin/README.md, bumped with the plugin pin.
• Pre-flight before any PR: pnpm typecheck && pnpm test && pnpm build && node dist/index.js --version.