Skip to content

Development template updates

This established utility server first adopted development tooling from justpen-mcp-dev-template at d9848a0927c238fd1b11189930a292ff60efef16. Its current development baseline is v0.4.0, commit 2b9f8a3167e1910f5cc95c18a03f7aaf842db099.

Reviewed adoption and history

The v0.4.0 adoption renders a separate reference with the real project identity, then applies reviewed development changes to the existing application. The genuine Copier record comes from that reference; it does not claim that this server was originally created by Copier. No first-run bootstrap or recopy runs over the app.

Keep .copier-answers.yml committed and let Copier maintain its source, revision and answers. The recorded initial_version = 0.0.0 describes the generated comparison baseline, not the application version. Run make version to read the utility version; template updates preserve the application version.

The explicit changelog_start_rev at standalone commit 959e9578785439ba7fbb0e25e8fa8dbbc4ec43c0 stays authoritative after enrollment. Preserve the real Git history and historical tags; do not replace that boundary with the first Copier record. The template's MIT attribution is limited to infrastructure; the utility application remains proprietary.

Update on a feature branch

Begin with a clean, committed checkout. Fetch an exact upstream commit without importing template release tags into the application's tag namespace:

git switch -c chore/update-template
git fetch --no-tags https://github.com/justpenkit/justpen-mcp-dev-template.git main:refs/remotes/template/main
template_commit=$(git rev-parse refs/remotes/template/main)
uvx --from 'copier>=9.18.2,<10' copier update --vcs-ref="$template_commit" --defaults
git diff

Codex uses codex/update-template. The update uses the source URL in the genuine Copier record and the exact fetched commit. Use a full clone, fetch before each update, and never merge the template branch or copy its release tags into this application.

--defaults reuses the recorded answers. Keep the reference's initial-version answer so Copier can compare generated baselines while preserving application version changes. Omit --defaults to review answers; use --vcs-ref=:current: when changing answers without upgrading the template. Always select a revision.

Project customizations to preserve

Copier compares the old reference, new reference and application changes. Changes to the same lines can conflict. Inspect every diff and all Git conflict entries; resolve them while preserving:

  • Actual MCP code, TOTP/QR tool names, server identity, UTILITY_MCP_LOG_LEVEL and the status: "ok" response contract. Do not import template demo behavior.
  • uv run python -m justpen_utility_mcp. The package has no cli() entrypoint or py.typed marker; metadata must not claim either.
  • Pillow/zxing-cpp runtime dependencies and Hypothesis development tests. Use uv for necessary dependency resolution; never copy a generator lockfile.
  • Proprietary application terms and the template's MIT attribution in root NOTICE, which remains included in wheel/source distributions.
  • The application's version, historical tags and explicit standalone changelog boundary described in the release guide.
  • Product docs, API module directives, navigation and assets.
  • .hypothesis/ ignores, build/consumer/fixture Make targets, and committed QR fixtures. Regenerate fixtures only intentionally and review the binary diff.
  • Shared agent permissions, strict lint/type/coverage rules and the unit/integration split, including real MCP consumer coverage in CI.

Use uv for required dependency resolution, then make setup to refresh changed tooling and installed hooks. Use make test-one TEST=... for the relevant scenario while developing an integration test or its harness. Commit/push hooks provide routine unit and strict-docs gates; do not repeat a passing gate manually. CI checks the supported Python matrix, real tool/hook/release/docs integrations and the installed-wheel MCP consumer outside the checkout.

Review the final diff through a PR and use a regular merge commit. A template update does not itself bump this application's version. Do not use copier recopy as a shortcut, run bootstrap, or import generator tests and setup/cleanup machinery.

Protected metadata

Before an agent applies direct pyproject.toml or uv.lock changes through Copier, preview the same exact revision and answers in a disposable checkout. Present the concrete diff and obtain its required approval before applying it to the working project. Normal dependency resolution remains uv-managed. Do not use indirect writers to bypass the gate; follow the agent guide.

See Copier's update documentation for the merge model and recovery options.