Getting started

This guide sets up development for the existing integration server. Its module entrypoint and Gmail tool behavior are independent of the development tooling.

Prerequisites

Install uv, Git and Make on macOS, Linux or WSL. uv installs the selected Python interpreter and project tools; no separate Node.js, npm or documentation toolchain is required. Pyright's Python package manages its own runtime.

Clone and set up

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

make setup installs locked development and documentation dependencies into .venv/, runs the project formatters, and installs pre-commit, pre-push and commit-msg hooks. Use make install to refresh dependencies without installing hooks, as CI does. Keep the uv-managed lockfile committed.

To run the server from this environment:

uv run python -m justpen_integration_mcp

See configuration before making a Gmail request. The existing email tests mock Gmail calls and use temporary configuration files; they do not require service-account credentials or access a real mailbox.

The development gate

Git hooks run routine verification automatically:

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, supported formatters, lint, strict typing and unit tests with 80% branch coverage. Typing and tests each use the active uv Python once, defaulting to 3.13. A passing pre-push already supplies these gates; there is no additional manual run before a PR.

CI runs shared formatting, lint and docs once on Python 3.13. Its matrix checks strict typing and 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, tool, formatter, release and docs integrations run separately on 3.13. Google API calls remain mocked; CI does not require service-account credentials or a real mailbox.

Use make lint-fix, make format and make typecheck for focused feedback when useful. make test-one TEST=tests/test_email.py::TestReadEmails::test_count_mode selects a relevant integration scenario while developing that test or its harness. Focused runs do not apply the suite-wide coverage threshold; pre-push does.

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.

Run make build when packaging or dependency metadata changes. It builds the application wheel and source distribution into dist/.

Documentation

make docs-serve starts the local MkDocs preview. make docs-build builds the static site into the gitignored site/ directory. Pages use Markdown under docs/; navigation lives in mkdocs.yml. The Python API reference uses mkdocstrings against the existing store, responses and email modules.

Documentation is maintained in this repository and previewed locally. This development setup does not configure website publication.

Use a coding agent

Claude Code and Codex share root AGENTS.md. Follow the agent setup guide to activate project permissions and the protected metadata gate. Project trust and hooks must be reviewed in a fresh host session; adding configuration files does not change the permissions of an already-running session.

Make a change

1. Create a feature branch: codex/short-description for Codex work, or type/short-description for other contributors.
2. Cover behavior changes with a focused regression, implement the change, and use focused Make checks for feedback.
3. Follow the PR checklist before opening the PR.
4. Use Conventional Commits (type(scope): subject, at most 72 characters).
5. Merge with a regular merge commit after review and green CI.

Repository maintainers should keep main as the default branch, enable Actions, and configure branch protection for all required CI gates when repository visibility and the GitHub plan support it; it is not a prerequisite for local development. For tooling updates, follow the template update guide.