pypreset

A meta-tool for scaffolding Python projects with configurable YAML presets.

Supports Poetry, uv, and setuptools, generates CI workflows, testing scaffolds, type checking configs, and more.

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]

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:

# 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 # Re-tag and push an existing version pypreset version rerelease # 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 # 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 # 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:

| verify_workflow | Verify G