Unity-Open-MCP / scripts

# Scripts rules

## Scope

Rules for `scripts/` — version sync, token-estimate codegen, and MCP test
suites. Root `AGENTS.md` also applies. Human overview:
[`scripts/README.md`](README.md).

## Generated outputs

- Never hand-edit generated targets. Run the owning script instead.
- Version strings: `node scripts/sync-version.mjs` (shared trio) or
  `--hub` for Unity Hub Pro. Canonical contract:
  [Maintainer versioning](../docs/contributing/versioning.md).
- Lockstep release (set + commit + tag + push): `node scripts/release.mjs X.Y.Z`
  (wrapper around sync-version + token estimates; does not replace those tools).
  Push trio tags and the Hub tag in separate git pushes (≤3 tags per command);
  GitHub skips tag webhook events when more than three tags are pushed at once.
- Consuming projects are the opposite direction and never a generated target
  here: `node scripts/switch-project-version.mjs <project> <X.Y.Z>` rewrites
  another project's client-config npm pins and UPM `#bridge-v` / `#verify-v`
  pins. Keep its rewrite set aligned with the pin shapes `sync-version.mjs`
  emits — a new pin surface in `docs/setup/` usually means a new one in the
  wild too.
- Token estimates: `node scripts/generate-token-estimates.mjs` writes
  `packages/bridge/Editor/UI/BridgeToolTokenEstimates.cs`. Regenerate after
  MCP tool schema, catalog, or group changes; `--check` is advisory in CI.
- Batch preflight schemas: `node scripts/generate-batch-schemas.mjs` derives
  `BridgeBatchSchemas.cs` from MCP `ALL_TOOLS`; regenerate after schema changes
  and verify with `--check`.
- Coverage matrix (`gen-mcp-coverage-matrix.mjs`) is internal/gitignored.

## MCP suite selection

| Suite | Script | Use when |
|---|---|---|
| Smoke | `mcp-smoke.mjs` | Fast live health check |
| S0 | `mcp-full-test.mjs` | Registration/reachability for every tool |
| S1 | `mcp-behavior.mjs` | Strict behavioral paths |
| S2 | `mcp-headless.mjs` | Batch/offline with Editor closed |
| S3 | `mcp-protocol.mjs` | Stdio protocol |
| S4 | `mcp-extensions.mjs` | Embedded-domain chains |
| S5 | `mcp-sandbox.mjs` | Destructive lifecycle on a disposable clone |

Shared helpers live in `mcp-test-lib.mjs` (not run directly). Catalog detail:
`docs/troubleshooting-contributors.md#mcp-test-suite-catalog`. Build
`mcp-server/` before live suites. Default project is `./demo`.

## Same-task mirrors

- Script behavior or flag changes that affect contributor workflows: update
  `scripts/README.md` and, when applicable,
  `docs/troubleshooting-contributors.md`.
- Suite ownership of a new tool: keep the coverage matrix regenerable (no
  orphan registered tools).

More agent context in AlexeyPerov/Unity-Open-MCP

26 other files this repository gives its agents.