pypreset

Official

by KaiErikNiermann · Python

Scaffold Python projects from YAML presets, augment existing projects with CI/tests.

io.github.KaiErikNiermann/pypreset MCP Server

This MCP server provides project scaffolding from YAML presets. It generates and augments Python projects by applying configurable templates, and it can include setup for dependency managers (Poetry, uv, and setuptools), CI workflows, testing scaffolds, type checking configuration, and additional project files.

🛠️ Key Features

Preset-based project creation from YAML configs with single inheritance
Augment existing projects with CI workflows, tests, Docker, documentation, and more
Generates CI workflows, testing scaffolds, and type checking configs

🚀 Use Cases

Create new Python project structures from reusable YAML presets
Retrofit an existing repository with CI, tests, container, and documentation scaffolding
Standardize configuration across projects using templates

⚡ Developer Benefits

Supports multiple Python packaging/tooling options (Poetry, uv, setuptools)
Centralizes project configuration via YAML presets
Produces consistent CI and testing scaffolds

Topics

project-setuppython314scaffoldtemplatespython-scaffold

README.md13 KBView on GitHub

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

bash

pip install pypreset

# With MCP server support
pip install pypreset[mcp]

Quick Start

bash

# 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

bash

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.

bash

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

bash

# 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.

bash

# 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

bash

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

bash

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.

bash

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

Other commands

bash

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:

bash

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).

bash

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):

bash

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

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

json

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

Or install locally:

bash

pip install pypreset[mcp]

json

{
  "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:

bash

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

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

io.github.KaiErikNiermann/pypreset MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

Topics

Features

Installation

Quick Start

Commands

create -- Scaffold a new project

augment -- Add components to an existing project

workflow -- Local workflow verification

version -- Release management

metadata -- PyPI metadata management

badges -- Generate badge markdown

Other commands

Presets

Custom presets

User Configuration

MCP Server

Development

License

Install

Related servers

`create` -- Scaffold a new project

`augment` -- Add components to an existing project

`workflow` -- Local workflow verification

`version` -- Release management

`metadata` -- PyPI metadata management

`badges` -- Generate badge markdown