mcptoon: Instructions file for Codex

AGENTS.md — rules for AI agents working on mcptoon

Any AI agent (Codex, Claude Code, Cursor, DSH, ...) writing code, docs, or cutting releases in this repo follows the rules on this page. They exist because mcptoon is now carried by external automation: numtide/llm-agents.nix packages this project and an official bot auto-bumps it on every PyPI release. A careless release breaks that channel; these rules keep it clean. Human contributors: see CONTRIBUTING.md.

Hard rules

1. Zero dependencies, always. The dependencies field in pyproject.toml stays empty. Standard library only. CI enforces this via scripts/check_zero_deps.py — treat a red zero-deps job as a broken build, not a suggestion.
2. Tests gate every change. New behavior ships with tests in tests/. Run python -m pytest tests/ and paste the real green output before claiming done.
3. Windows is a first-class target. Anything touching paths, subprocess, or npx must work on Windows; the CI matrix runs it on every PR.
4. Conventional Commits for every commit (feat:, fix:, docs:, test:, chore:).

Release discipline

A release is complete only when all five land together:

1. version bumped in pyproject.toml
2. CHANGELOG.md entry written for the new version
3. full test suite green
4. git tag vX.Y.Z pushed
5. PyPI publish green (.github/workflows/publish.yml)

The numtide bot turns PyPI releases into Nix bump PRs automatically. A version that exists on main but not on PyPI (or the reverse) leaves a broken bump in that channel. Breaking changes must land as deprecation warnings one minor version before removal.

Details that bit us during v0.7.4 (2026-09-05), so they are now part of the ritual:

• The version lives in four places. pyproject.toml, server.json (twice: top level and packages[]), and the hardcoded __version__ in src/mcptoon/__init__.py. 0.7.6 shipped with mcptoon --version printing 0.7.5 because the last one was missed — caught only by the post-release smoke test. tests/test_registry_sync.py now pins all of them together; update every one on every bump.
• The publish workflows used to race each other. publish.yml and publish-mcp.yml start on the same release event; the registry run validated the PyPI version while the wheel was still uploading and failed with 400. This happened on both 0.7.6 and 0.7.7. Root cause fixed in publish-mcp.yml: a wait step now polls PyPI's JSON API for the released version (up to 5 minutes) before pushing the registry record. If the wait step ever times out, retry with gh workflow run publish-mcp.yml -f reason=....
• Pushing a tag does not publish. publish.yml triggers on release: [published], so a GitHub Release must be created (gh release create vX.Y.Z --notes-file …).
• Verify against the real index. This machine's pip points at a mirror that lags — and its global ALL_PROXY=socks5:// breaks fresh venvs (no PySocks). Confirm a fresh release with a clean venv, proxy vars cleared: python -m venv .scratch/check && .scratch/check/Scripts/python -m pip install --no-cache-dir --index-url https://pypi.org/simple/ mcptoon, then run mcptoon --version from that venv and compare with the tag.
• Run the lint job locally (python -m ruff check src/mcptoon/ tests/, ruff 0.15.20) before pushing — unpushed commits never see CI, and one UP037 turned the release red.
• Update the Tests-<n> passed badges in README.md and README.zh-CN.md (and the matching comment in their contributor sections) to the suite total of the release.
• The MCP Registry record used to be pushed by hand. 0.7.0 and 0.7.2 were published from a laptop; 0.7.3–0.7.5 never reached it, and server.json's package version had drifted a release behind its own top-level version. publish-mcp.yml now publishes on every release, and tests/test_registry_sync.py fails CI if the versions, the mcp-name: marker in the PyPI README, or the workflow drift apart. Do not remove that marker when rewriting the README — it is invisible when rendered and load-bearing.