Developer Environment Setup (Linux & macOS)¶

This document describes how to set up a full development environment for adif-mcp on Linux and macOS. The project uses uv, pre-commit, and modern Python packaging. These instructions assume you are comfortable with the terminal.

1. System Requirements¶

Python: 3.11 or newer (3.13 recommended)
uv: fast Python package manager and build tool
git: version control
make: for running project tasks
pre-commit: for local checks before commit (installed via uv tools)

Linux (Debian/Ubuntu)¶

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git make

macOS¶

Install Xcode Command Line Tools (for make, git, compilers):
```
xcode-select --install
```

Install Homebrew (if not installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Ensure Python 3.11+ is installed (Homebrew or Python.org).

2. Install uv¶

The project standardizes on uv for dependency management.

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

3. Clone the Repository¶

git clone https://github.com/<your-org>/adif-mcp.git
cd adif-mcp

4. Sync Dependencies¶

Create and sync the virtual environment:

uv sync --frozen

This will: - Create .venv/ - Install runtime + dev dependencies from uv.lock

5. Install pre-commit Hooks¶

Install pre-commit globally with uv:

uv tool install pre-commit

Register the hooks in this repo:

pre-commit install

You can test them manually:

pre-commit run --all-files

6. Verify Development Setup¶

Run all quality gates:

make gate

Expected: all checks (ruff, mypy, interrogate, manifests) should pass.

Run smoke tests:

make smoke-all

Expected: probes and CLI run without errors (Clublog probe may return HTTP 403 by design).

7. Useful Commands¶

Format & lint:

uv run ruff check src --fix
uv run ruff format src

Type checking:
```
uv run mypy src test
```

Docstring coverage:

uv run interrogate -v -c pyproject.toml

Run tests:
```
uv run pytest -q
```
Validate manifests:
```
make manifest
```

8. macOS Notes¶

If using Python from python.org installer, you may need:

python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pip setuptools wheel

If keyring prompts do not appear, install keyring backend:
```
brew install keyring
```

9. Linux Notes¶

Some Linux distros require a keyring daemon for secrets. If unavailable, credentials will store non-secret refs only.

Install recommended packages:

sudo apt install gnome-keyring libsecret-1-0

10. Confirm CLI Works¶

uv run adif-mcp --help

Should display the CLI help with subcommands.