vrchat-mcp: Instructions file for Codex

AGENTS

This repo uses linting, typechecking, and tests to validate changes.

Guidance for coding agents:

• After significant code changes (or at the end of a work loop), run npm run check.
• If you need just one step, use npm run lint, npm run typecheck, or npm test.
• After making a change, run at least one relevant targeted test (or add/edit one) and confirm it passes before reporting back.
• For PR review workflow: before pushing any new commits, respond to each open review comment (reply or reaction) and resolve the thread.
• Claude reviews non-draft, same-repository (non-fork) PRs targeting main automatically and rewrites one sticky comment per PR. It runs on pull_request_target, so the reviewer is always main's copy of .github/workflows/claude-review.yml: edits to it take effect only after merge, and a PR that changes it is reviewed by main's current copy, not by its own edits. The review job uses GitHub OIDC to retrieve BASIC's canonical Claude OAuth token from AWS Secrets Manager; there is no repository copy to rotate. Calibration lives in REVIEW.md; add the skip-claude-review label to opt a PR out.
• Keep stdout reserved for MCP protocol; log to stderr only.
• Config defaults live in src/config/defaults.json; override via VRCHAT_MCP_CONFIG_FILE (env overrides still supported).
• Prefer the local harness over Codex MCP hosting for dev iteration:
  • npm run mcp:login to authenticate (keeps the server alive while you log in).
  • npm run mcp:status, npm run mcp:logout, npm run mcp:list-tools, npm run mcp:call.
  • The harness defaults cookie storage to file. Override via config JSON or env vars if needed.
  • Use VRCHAT_MCP_SERVER_COMMAND / VRCHAT_MCP_SERVER_ARGS to switch between tsx src/index.ts and built dist/bin/cli.js.
• Write tools are enabled by default. Use writes.allow=false in config, or VRCHAT_MCP_ALLOW_WRITES=false, when a test or run must be read-only.
• Regenerate tool catalog docs after spec updates: npm run generate:tools-docs.
• Regenerate VRChat OpenAPI schemas after spec updates: npm run generate:schemas (updates src/generated/vrchat-schemas.ts; do not edit manually).
• Regenerate mock test schemas after spec tweaks: npm run generate:test-schemas (updates test/generated/mock-schemas.ts; do not edit manually).
• specs/vrchat-openapi.yaml is the community spec, not VRChat's, and drifts from the live API continuously. docs/spec-drift.md logs divergences we have observed so nobody re-investigates them — it is a record, not an authority; the live API is the source of truth. Read it before trusting a spec constraint, re-verify any entry you are about to depend on for a substantive change, and add an entry whenever you find a new divergence. Fix drift in scripts/postprocess-schemas.ts, not in the spec: the spec file is gitignored, so edits there are local-only and vanish on a fresh clone.