Getting started¶
Install uv, Git and Make on macOS, 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 install installs locked dev/docs dependencies. make setup also installs
pre-commit, pre-push and commit-msg hooks and runs the formatters. Commit changes
through a feature branch using Conventional Commits.
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 the lock, supported formatters, Ruff, strict typing and unit
tests with 80% branch coverage. Typing and tests each use the active uv Python
once, with 3.13 as the local default. A passing pre-push already supplies these
gates; do not repeat them manually before a PR.
CI runs shared formatting, lint and docs once on Python 3.13, and typing/unit coverage once per Python 3.11, 3.12 and 3.13. It rejects a missing or stale committed lock before installing dependencies. Real hook, formatter, tool, release and docs integrations run separately on 3.13.
make test-one TEST=tests/test_qr.py provides focused feedback while developing
that test or its harness; choose a specific node when appropriate. Focused runs do
not apply the suite-wide coverage threshold. 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.
VS Code's default Run Test Task invokes make check; the Python Test Explorer
selects unit tests with -m "not integration" and does not invoke Make.
make audit checks locked runtime/dev/docs dependencies. make docs-serve
previews the documentation. Fixture PNGs are committed; regenerate them only
intentionally with make regenerate-qr-fixtures, then review the binary changes.
Repository setup¶
Keep main as the default branch and require all CI quality, Python-matrix and
integration/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.