Skip to content

Contributing

Contributions are welcome — from Python folks who've never seen a title block and from estimators and contractors who touch plans for a living. The full guide (branch naming, commit format, PR expectations, how to add a new MCP tool) lives in CONTRIBUTING.md in the repo; this page is just the dev loop.

Dev loop

You'll need Python 3.11+ and uv:

git clone https://github.com/ContractorKeith/conmcp.git
cd conmcp
uv sync --all-extras

Then the everyday commands:

# run the tests (in-memory FastMCP client — no server process needed)
uv run pytest

# lint + formatting check (what CI runs)
uv run ruff check . && uv run ruff format --check .

# auto-fix what can be fixed
uv run ruff check --fix . && uv run ruff format .

# run the MCP server / CLI against the sample plan
uv run conmcp sample
uv run conmcp overview sample_plan.pdf

# preview this docs site locally
uv run mkdocs serve

The three rules that matter most

  1. server.py stays thin. Logic goes in pdf/ or domain/; the MCP wrapper just validates, calls, and returns. See Architecture.
  2. All file access goes through config.resolve_path() — sandbox plus audit log. Never open a user-supplied path directly.
  3. Never commit a real plan PDF. Not in tests, not in examples, not temporarily. Extend the sample plan generator instead.

Where to start