io.github.KaiErikNiermann/pypreset

<p align="center"> <img src="https://raw.githubusercontent.com/KaiErikNiermann/pypreset/main/resources/banner.png" alt="PyPreset" height="160"> </p>

<p align="center"> A meta-tool for scaffolding Python projects with configurable YAML presets.<br> Supports Poetry, uv, and setuptools, generates CI workflows, testing scaffolds, type checking configs, and more. </p>

mcp-name: io.github.KaiErikNiermann/pypreset

Features

• Preset-based project creation from YAML configs with single inheritance
• Augment existing projects with CI workflows, tests, Docker, documentation, and more
• Three package managers: Poetry, uv (PEP 621 + hatchling), and setuptools (PEP 621 + setuptools.build_meta)
• Two layout styles: src/ layout and flat layout
• Type checking: mypy, pyright, ty, or none
• Code quality: ruff linting/formatting, radon complexity checks, pre-commit hooks
• Docker & devcontainer: generate multi-stage Dockerfiles, .dockerignore, and VS Code devcontainer configs (Docker or Podman)
• Coverage integration: Codecov support with configurable thresholds and ignore patterns
• Documentation scaffolding: MkDocs (Material theme) or Sphinx (RTD theme) with optional GitHub Pages deployment
• Multi-environment testing: tox configuration with tox-uv backend
• pyenv / .python-version: generate .python-version for pyenv and uv, with python-version-file in CI workflows
• Version management: bump-my-version integration, GitHub release automation via gh CLI
• Workflow verification: local GitHub Actions testing with act (auto-detect, auto-install, dry-run and full-run modes)
• PyPI metadata management: read, set, and check publish-readiness of pyproject.toml metadata
• User defaults: persistent config at ~/.config/pypreset/config.yaml
• MCP server: expose all functionality to AI coding assistants via the Model Context Protocol

Installation

pip install pypreset

# With MCP server support
pip install pypreset[mcp]

Quick Start

# Create a CLI tool project with Poetry
pypreset create my-cli --preset cli-tool

# Create a data science project with uv
pypreset create my-analysis --preset data-science --package-manager uv

# Create an empty package with src layout (default)
pypreset create my-package --preset empty-package

# Create a Discord bot
pypreset create my-bot --preset discord-bot

# Create a project with Docker support
pypreset create my-service --preset cli-tool --docker --devcontainer

# Create with .python-version for pyenv/uv
pypreset create my-lib --pyenv --python-version 3.13

# Create with Podman, Codecov, docs, and tox
pypreset create my-project --preset empty-package \
    --container-runtime podman --docker \
    --coverage-tool codecov --coverage-threshold 80 \
    --docs mkdocs --docs-gh-pages \
    --tox

Commands

create -- Scaffold a new project

pypreset create <name> [OPTIONS]

Option	Description
--preset, -p	Preset to use (default: empty-package)
--output, -o	Output directory (default: .)
--config, -c	Custom preset YAML file
--package-manager	poetry or uv
--layout	src or flat
--type-checker	mypy, pyright, ty, or none
--typing	none, basic, or strict
--python-version	e.g., 3.12
--testing / --no-testing	Enable/disable testing scaffold
--formatting / --no-formatting	Enable/disable formatting config
--radon / --no-radon	Enable radon complexity checking
--pre-commit / --no-pre-commit	Generate pre-commit hooks config
--bump-my-version / --no-bump-my-version	Include bump-my-version config
--extra-package, -e	Additional packages (repeatable)
--extra-dev-package, -d	Additional dev packages (repeatable)
--docker / --no-docker	Generate Dockerfile and .dockerignore
--devcontainer / --no-devcontainer	Generate .devcontainer/ configuration
--container-runtime	docker or podman
--coverage-tool	codecov or none
--coverage-threshold	Minimum coverage % (e.g., 80)
--docs	sphinx, mkdocs, or none
--docs-gh-pages / --no-docs-gh-pages	Generate GitHub Pages deploy workflow
--tox / --no-tox	Generate tox.ini with tox-uv backend
--pyenv / --no-pyenv	Generate .python-version and use python-version-file in CI
--git / --no-git	Initialize git repository
--install / --no-install	Run dependency install after creation
--dry-run	Preview what would be created without generating anything

augment -- Add components to an existing project

Analyzes pyproject.toml to auto-detect your tooling, then generates the selected components. Runs in interactive mode by default (prompts for values it can't detect); use --auto to skip prompts.

pypreset augment [path] [OPTIONS]

Available components:

Flag	Component	What it generates
--test-workflow / --no-test-workflow	Test CI	GitHub Actions workflow that runs pytest across a Python version matrix
--lint-workflow / --no-lint-workflow	Lint CI	GitHub Actions workflow for ruff, type checking, and complexity analysis
--dependabot / --no-dependabot	Dependabot	.github/dependabot.yml for automated dependency updates
--tests / --no-tests	Tests directory	tests/ with template test files and conftest.py
--gitignore / --no-gitignore	Gitignore	Python-specific .gitignore
--pypi-publish / --no-pypi-publish	PyPI publish	GitHub Actions workflow for OIDC-based publishing to PyPI on release
--dockerfile / --no-dockerfile	Docker	Multi-stage Dockerfile and .dockerignore (Poetry, uv, or setuptools aware)
--devcontainer / --no-devcontainer	Devcontainer	.devcontainer/devcontainer.json with VS Code extensions
--codecov / --no-codecov	Codecov	codecov.yml configuration
--docs	Documentation	Sphinx or MkDocs scaffolding (--docs sphinx or --docs mkdocs)
--tox / --no-tox	tox	tox.ini with tox-uv backend for multi-environment testing
--readme / --no-readme	README	README.md generated from the shared template (badges, install, features)
--pyenv / --no-pyenv	pyenv	.python-version file for pyenv and uv version pinning

# Interactive mode (prompts for missing values)
pypreset augment ./my-project

# Auto-detect everything, no prompts
pypreset augment --auto

# Generate only specific components
pypreset augment --test-workflow --lint-workflow --gitignore

# Add Docker and devcontainer
pypreset augment --dockerfile --devcontainer

# Add PyPI publish workflow
pypreset augment --pypi-publish

# Add documentation scaffolding
pypreset augment --docs mkdocs

# Generate a README from your project metadata
pypreset augment --readme

# Overwrite existing files
pypreset augment --force

workflow -- Local workflow verification

Verify GitHub Actions workflows locally using act. The proxy auto-detects whether act is installed, can install it on supported systems, and surfaces all act output directly.

# Verify all workflows (dry-run, no containers)
pypreset workflow verify

# Verify a specific workflow file
pypreset workflow verify --workflow .github/workflows/ci.yaml

# Verify a specific job
pypreset workflow verify --job lint

# Full run (executes in containers, requires Docker)
pypreset workflow verify --full-run

# Auto-install act if missing
pypreset workflow verify --auto-install

# Pass extra flags to act
pypreset workflow verify --flag="--secret=GITHUB_TOKEN=xxx"

# Check if act is installed
pypreset workflow check-act

# Install act automatically
pypreset workflow install-act

Supported auto-install targets: Arch Linux (pacman), Ubuntu/Debian (apt), Fedora (dnf), macOS/Linux with Homebrew. Other systems get a link to the act installation page.

version -- Release management

pypreset version release --bump patch     # 0.1.0 -> 0.1.1
pypreset version release --bump minor     # 0.1.0 -> 0.2.0
pypreset version release --bump major     # 0.1.0 -> 1.0.0
pypreset version release-version 2.0.0    # Explicit version
pypreset version rerun <ver>              # Re-tag and push an existing version
pypreset version rerelease <ver>          # Delete and recreate a GitHub release

Requires the gh CLI to be installed and authenticated.

metadata -- PyPI metadata management

pypreset metadata show                                   # Display current metadata
pypreset metadata set --description "My cool package"    # Set description
pypreset metadata set --github-owner myuser              # Auto-generate URLs
pypreset metadata set --license MIT --keyword python     # Set license and keywords
pypreset metadata check                                  # Check publish-readiness

badges -- Generate badge markdown

Reads pyproject.toml to detect your project name, repository URL, and license, then prints badge markdown you can paste into your README.

pypreset badges                  # Badges for current directory
pypreset badges ./my-project     # Badges for a specific project

Other commands

pypreset list-presets              # List all available presets
pypreset show-preset <name>        # Show full preset details
pypreset validate [path]           # Validate project structure
pypreset analyze [path]            # Detect and display project tooling
pypreset config show               # Show current user defaults
pypreset config init               # Create default config file
pypreset config set <key> <value>  # Set a config value

Presets

Built-in presets: empty-package, cli-tool, data-science, discord-bot.

Presets are YAML files that define metadata, dependencies, directory structure, testing, formatting, and more. They support single inheritance via the base: field. Presets can override the README template by setting metadata.readme_template to a custom .j2 filename.

Custom presets

Place custom preset files in ~/.config/pypreset/presets/ or pass a file directly:

pypreset create my-project --config ./my-preset.yaml

User presets take precedence over built-in presets with the same name.

User Configuration

Persistent defaults are stored at ~/.config/pypreset/config.yaml and applied as the lowest-priority layer (presets and CLI flags override them).

pypreset config init                    # Create with defaults
pypreset config set layout flat         # Set default layout
pypreset config set type_checker ty     # Set default type checker
pypreset config show                    # View current config

MCP Server

pypreset is published to the MCP Registry as io.github.KaiErikNiermann/pypreset.

Install via the registry (recommended):

# Claude Code
claude mcp add pypreset -- uvx --from "pypreset[mcp]" pypreset-mcp

# Or add manually to ~/.claude/settings.json

{
  "mcpServers": {
    "pypreset": {
      "command": "uvx",
      "args": ["--from", "pypreset[mcp]", "pypreset-mcp"]
    }
  }
}

Or install locally:

pip install pypreset[mcp]

{
  "mcpServers": {
    "pypreset": {
      "command": "pypreset-mcp",
      "args": []
    }
  }
}

Available tools:

Tool	Description
create_project	Create a new project from a preset with optional overrides
augment_project	Add CI workflows, tests, Docker, docs, and more to an existing project
validate_project	Check structural correctness of a project directory
verify_workflow	Verify GitHub Actions workflows locally using act
list_presets	List all available presets with names and descriptions
show_preset	Show the full YAML configuration of a specific preset
get_user_config	Read current user-level defaults
set_user_config	Update user-level defaults
set_project_metadata	Set or update PyPI metadata in pyproject.toml
generate_badges	Generate badge markdown links from project metadata

Resources: preset://list, config://user, template://list

Prompts: create-project, augment-project

Development

All tasks use the Justfile:

just install     # Install dependencies
just test        # Run tests
just test-cov    # Tests with coverage
just lint        # Ruff check
just format      # Ruff format
just typecheck   # Pyright
just radon       # Cyclomatic complexity check
just check       # lint + typecheck + radon + test
just all         # format + lint-fix + typecheck + radon + test

See CONTRIBUTING.md for development setup and guidelines.

License

MIT