Skip to content

Getting started

Install uv, Git and Make on macOS (Apple Silicon), Linux or WSL. uv manages Python and all project tools; no separate Node/npm or documentation installation is needed.

Clone and install

git clone https://github.com/justpenkit/justpen-utility-mcp.git
cd justpen-utility-mcp
make setup

make setup completes the initial setup:

  • make install installs the locked development and documentation dependencies into .venv/. A freshly generated project initializes its missing uv.lock through uv first.
  • On linux aarch64, where taplo publishes no wheel, make install-taplo installs the pinned upstream binary into .venv/bin after verifying its checksums.
  • Claude Code and Codex plugins the project declares are installed in project scope when those CLIs are present.
  • The project formatters normalize generated Markdown, TOML, YAML and JSON.
  • Git hooks are installed for pre-commit, pre-push and commit-msg.

The genuine Copier record comes from a reviewed, separately generated development reference. Follow the template update guide to preserve application metadata, licensing and history during updates.

Run the server

uv run python -m justpen_utility_mcp

UTILITY_MCP_LOG_LEVEL selects the log level. Application logs use stderr and MCP uses stdio. The API reference describes the two registered tools.

Automatic development gates

Git hooks run routine verification:

Stage Checks
Pre-commit Conflict/whitespace checks; lint and active-Python typing for Python changes; formatting for text changes; lock consistency for metadata changes
Commit-msg Commitizen validates the project commit-message rules
Pre-push make check and one strict make docs-build

make check covers lock consistency, all supported formatters, lint, strict typing and unit tests with 80% branch coverage. The local interpreter defaults to Python 3.13; typing and tests each use the active uv Python once. There is no additional manual gate before starting development or opening a PR. A passing pre-push hook already supplies that verification.

CI runs one check job: shared formatting, lint and the docs build once on Python 3.13, then typing and unit tests. Pull requests run typing and tests on Python 3.11, 3.12 and 3.13; the push to main after a merge re-checks 3.13 only. It rejects a missing or stale committed lock before installing dependencies. Initial project setup may create a new lockfile.

Infrastructure tests remain in generated projects. Real hook, formatter, release and documentation scenarios run through make test-integration in CI. The generator's Template CI additionally tests Copier generation and updates, including both setup routes on all three Python versions, on pull requests only. These tests are excluded from local commit/push gates.

Use make test-one TEST=tests/test_file.py::test_name for focused development. When changing an integration test or its harness, run that relevant scenario locally through the same target; the full generation matrix remains CI's job. Focused runs do not apply the suite-wide coverage threshold; pre-push does.

make build produces wheel/sdist artifacts. CI's make test-consumer verifies distribution contents, including NOTICE, installs the wheel outside the checkout and calls both tools over MCP stdio once on 3.13. This is a real integration, not a local unit-gate requirement.

make audit checks locked runtime/dev/docs dependencies. Fixture PNGs are committed; regenerate them only intentionally with make regenerate-qr-fixtures, then review the binary changes.

Editor tests

VS Code's default Run Test Task invokes make check. The Python Test Explorer's Run All Tests button runs pytest's unit suite with -m "not integration"; it does not invoke Make or run integration scenarios. Formatting on save remains enabled.

Documentation

make docs-serve starts the local MkDocs preview. make docs-build builds the site into site/ in strict mode. All pages use normal Markdown under docs/, and navigation lives in mkdocs.yml. Generated MCP projects also render their Python API reference from docstrings through mkdocstrings.

Repository setup

Keep main as the default branch and require the CI check and integration (including consumer) gates before merging when repository visibility and the GitHub plan support branch protection. Use regular merge commits. Discussions is currently disabled, so the issue chooser includes only the bug and feature forms. If Discussions is enabled later, add its contact link then. Configure automatic branch deletion if desired. These GitHub settings are separate from repository files.

Activate agent instructions and permissions before using Claude Code or Codex. See lint and typing, the PR checklist and the release process before contributing.

Use a coding agent

Claude Code and Codex share the rules in root AGENTS.md. Follow the agent setup guide to activate project permissions and the protected-files guard before development.

Make a change

  1. Open a feature branch: git switch -c type/short-description (e.g. feat/foo-bar), or codex/short-description for Codex work.
  2. Implement the change with a focused failing test, a minimal fix, and verification before committing.
  3. Walk the Pre-PR checklist before opening the PR.
  4. Use Conventional Commits for every commit subject (type(scope): subject, ≤72 chars).

For lint and type-check rules, including the suppression protocol, see Lint & typing.