minecraft-modding-mcp AGENTS.md

AGENTS.md

Purpose and Scope

• This file defines mandatory operating rules for agents working in this repository.
• When tradeoffs conflict, prioritize public API compatibility, verification evidence, and release safety.

Core Release Policy

• From version 1.0.0 onward, the public MCP tool surface follows semantic versioning. Breaking changes require a major version bump.
• Do not bump any version unless explicitly instructed by the user. Version bump timing is decided by the user.

Public MCP Contract (MUST)

• Treat the public contract as compatibility-bound: tool names, input parameter names/types/requiredness, and response envelope shape.
• Public MCP tool responses MUST use the standard envelope: { result?, error?, meta }.
• Input validation failures MUST map to ERR_INVALID_INPUT and MUST NOT be reported as ERR_INTERNAL.
• Do not add compatibility aliases for renamed public tools or parameters unless explicitly requested by the user and documented with a removal plan.

Change Coupling Rules (MUST)

• Any user-visible or public API change MUST update CHANGELOG.md and the relevant tests in the same change set.
• README.md and docs/tool-reference.md MUST be updated in the same change set when the change touches something they already document — a tool, parameter, response field, error code, environment variable, or setup step. Both are shipped in the package, so a stale statement there reaches users. A change with no counterpart in either file does not need an edit to it.
• Do not defer documentation or test updates to follow-up commits.

Verification Gate (MUST)

• Before claiming completion for production changes, run the verification appropriate to what actually changed — not reflexively the full matrix below, and never less than what the change touches.
• When src/** or tests/** changed, run:
  • pnpm check
  • pnpm test
• When MCP transport/tool registration or manual workflows change, also run pnpm test:manual:stdio-smoke when environment permits.
• For search, index, or performance-sensitive changes, also run pnpm test:perf.
• When a change is confined to CHANGELOG.md content and/or the version field in package.json, with no other src/** or tests/** edits, pnpm check/pnpm test are not required; run pnpm check:changelog and any test that asserts against the changed value directly (for example, a test comparing the server version or the changelog-to-package-version header). Any accompanying src/** or tests/** edit brings the change back under the full gate above.
• Do not re-run a verification command solely to re-confirm a result already produced for the current, unchanged tree. If a later run — your own or a delegated worker's — reports an outcome that contradicts a fresh prior run with no tree change in between, diagnose the discrepancy before re-running the full suite again; a concurrent invocation sharing the same working tree is a common non-code cause.
• Do not claim "done", "fixed", or "passing" without fresh command output evidence.