pypreset

mcp-name: io.github.KaiErikNiermann/pypreset

A meta-tool for scaffolding Python projects with configurable YAML presets. Supports Poetry and uv, generates CI workflows, testing scaffolds, type checking configs, and more.

Features

• Preset-based project creation from YAML configs with single inheritance
• Augment existing projects with GitHub Actions workflows, tests, dependabot, .gitignore
• Two package managers: Poetry and uv (PEP 621 + hatchling)
• 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
• Version management: bump-my-version integration, GitHub release automation via gh CLI
• User defaults: persistent config at ~/.config/pypreset/config.yaml
• MCP server: expose all functionality to AI coding assistants via 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 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.

# 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 Dockerfile and devcontainer config
pypreset augment --dockerfile --devcontainer

# Add Codecov, documentation, or tox
pypreset augment --codecov
pypreset augment --docs mkdocs
pypreset augment --tox

# Overwrite existing files
pypreset augment --force

version — Release management

pypreset version release <bump>         # Bump, commit, tag, push, release
pypreset version release-version <ver>  # Explicit version, then release
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.

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.

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: create_project, augment_project, validate_project, list_presets, show_preset, get_user_config, set_user_config

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