pypreset

io.github.KaiErikNiermannPublished by GitHub account KaiErikNiermannv0.4.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyCloud & Infrastructure Developer Tools

Server details

Identifier: io.github.KaiErikNiermann/pypreset
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account KaiErikNiermann for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.KaiErikNiermann%2Fpypreset.svg)](https://sourceweft.com/mcp/io.github.KaiErikNiermann%2Fpypreset?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Scaffolds and augments Python projects from YAML presets, generating CI workflows, tests, Docker, docs and PyPI metadata for an AI assistant.

What you can do: Create projects from built-in or custom YAML presets with overrides for package manager, layout, type checker and tooling
Add CI workflows, tests, Dockerfiles, devcontainers, docs, tox and README files to an existing project
Validate project structure and verify GitHub Actions workflows locally with act
List and show presets, and read or update user-level defaults
Set PyPI metadata in pyproject.toml and generate badge markdown
When to use it: Useful when starting a new Python package or CLI tool and wanting a consistent, tooled-up skeleton, or when retrofitting CI, tests, Docker or documentation onto an existing Python repository without hand-writing config files.
Requirements: Runs as a local stdio process, typically via uvx with the pypreset[mcp] package (or a local pip install). Needs Python and uv or pip. Workflow verification needs act, and full runs need Docker; release commands need the gh CLI installed and authenticated. No API keys or environment variables are declared.

Before you install

It writes files into project directories and can overwrite existing files when forced, so review generated output before committing. It can initialize git repositories, run dependency installs, and push tags or create GitHub releases through the gh CLI. Workflow verification with full runs executes workflows in containers and may pass secrets to act.

Installation

In SourceWeft

Open pypreset in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[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

Quick Start

bash

# Create a CLI tool project with Poetrypypreset create my-cli --preset cli-tool
# Create a data science project with uvpypreset 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 botpypreset create my-bot --preset discord-bot
# Create a project with Docker supportpypreset create my-service --preset cli-tool --docker --devcontainer
# Create with .python-version for pyenv/uvpypreset create my-lib --pyenv --python-version 3.13
# Create with Podman, Codecov, docs, and toxpypreset create my-project --preset empty-package \    --container-runtime podman --docker \    --coverage-tool codecov --coverage-threshold 80 \    --docs mkdocs --docs-gh-pages \    --tox

# Create a CLI tool project with Poetrypypreset create my-cli --preset cli-tool
# Create a data science project with uvpypreset 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 botpypreset create my-bot --preset discord-bot
# Create a project with Docker supportpypreset create my-service --preset cli-tool --docker --devcontainer
# Create with .python-version for pyenv/uvpypreset create my-lib --pyenv --python-version 3.13
# Create with Podman, Codecov, docs, and toxpypreset 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

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.

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 promptspypreset augment --auto
# Generate only specific componentspypreset augment --test-workflow --lint-workflow --gitignore
# Add Docker and devcontainerpypreset augment --dockerfile --devcontainer
# Add PyPI publish workflowpypreset augment --pypi-publish
# Add documentation scaffoldingpypreset augment --docs mkdocs
# Generate a README from your project metadatapypreset augment --readme
# Overwrite existing filespypreset augment --force

# Interactive mode (prompts for missing values)pypreset augment ./my-project
# Auto-detect everything, no promptspypreset augment --auto
# Generate only specific componentspypreset augment --test-workflow --lint-workflow --gitignore
# Add Docker and devcontainerpypreset augment --dockerfile --devcontainer
# Add PyPI publish workflowpypreset augment --pypi-publish
# Add documentation scaffoldingpypreset augment --docs mkdocs
# Generate a README from your project metadatapypreset augment --readme
# Overwrite existing filespypreset 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 filepypreset workflow verify --workflow .github/workflows/ci.yaml
# Verify a specific jobpypreset workflow verify --job lint
# Full run (executes in containers, requires Docker)pypreset workflow verify --full-run
# Auto-install act if missingpypreset workflow verify --auto-install
# Pass extra flags to actpypreset workflow verify --flag="--secret=GITHUB_TOKEN=xxx"
# Check if act is installedpypreset workflow check-act
# Install act automaticallypypreset workflow install-act

# Verify all workflows (dry-run, no containers)pypreset workflow verify
# Verify a specific workflow filepypreset workflow verify --workflow .github/workflows/ci.yaml
# Verify a specific jobpypreset workflow verify --job lint
# Full run (executes in containers, requires Docker)pypreset workflow verify --full-run
# Auto-install act if missingpypreset workflow verify --auto-install
# Pass extra flags to actpypreset workflow verify --flag="--secret=GITHUB_TOKEN=xxx"
# Check if act is installedpypreset workflow check-act
# Install act automaticallypypreset 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.1pypreset version release --bump minor     # 0.1.0 -> 0.2.0pypreset version release --bump major     # 0.1.0 -> 1.0.0pypreset version release-version 2.0.0    # Explicit versionpypreset version rerun <ver>              # Re-tag and push an existing versionpypreset version rerelease <ver>          # Delete and recreate a GitHub release

pypreset version release --bump patch     # 0.1.0 -> 0.1.1pypreset version release --bump minor     # 0.1.0 -> 0.2.0pypreset version release --bump major     # 0.1.0 -> 1.0.0pypreset version release-version 2.0.0    # Explicit versionpypreset version rerun <ver>              # Re-tag and push an existing versionpypreset 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 metadatapypreset metadata set --description "My cool package"    # Set descriptionpypreset metadata set --github-owner myuser              # Auto-generate URLspypreset metadata set --license MIT --keyword python     # Set license and keywordspypreset metadata check                                  # Check publish-readiness

pypreset metadata show                                   # Display current metadatapypreset metadata set --description "My cool package"    # Set descriptionpypreset metadata set --github-owner myuser              # Auto-generate URLspypreset metadata set --license MIT --keyword python     # Set license and keywordspypreset 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 directorypypreset badges ./my-project     # Badges for a specific project

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

Other commands

bash

pypreset list-presets              # List all available presetspypreset show-preset <name>        # Show full preset detailspypreset validate [path]           # Validate project structurepypreset analyze [path]            # Detect and display project toolingpypreset config show               # Show current user defaultspypreset config init               # Create default config filepypreset config set <key> <value>  # Set a config value

pypreset list-presets              # List all available presetspypreset show-preset <name>        # Show full preset detailspypreset validate [path]           # Validate project structurepypreset analyze [path]            # Detect and display project toolingpypreset config show               # Show current user defaultspypreset config init               # Create default config filepypreset 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:

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 defaultspypreset config set layout flat         # Set default layoutpypreset config set type_checker ty     # Set default type checkerpypreset config show                    # View current config

pypreset config init                    # Create with defaultspypreset config set layout flat         # Set default layoutpypreset config set type_checker ty     # Set default type checkerpypreset 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 Codeclaude mcp add pypreset -- uvx --from "pypreset[mcp]" pypreset-mcp
# Or add manually to ~/.claude/settings.json

# Claude Codeclaude 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"]    }  }}

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

Or install locally:

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 dependenciesjust test        # Run testsjust test-cov    # Tests with coveragejust lint        # Ruff checkjust format      # Ruff formatjust typecheck   # Pyrightjust radon       # Cyclomatic complexity checkjust check       # lint + typecheck + radon + testjust all         # format + lint-fix + typecheck + radon + test

just install     # Install dependenciesjust test        # Run testsjust test-cov    # Tests with coveragejust lint        # Ruff checkjust format      # Ruff formatjust typecheck   # Pyrightjust radon       # Cyclomatic complexity checkjust check       # lint + typecheck + radon + testjust all         # format + lint-fix + typecheck + radon + test

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Source: README.md at commit c6513eb

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.4.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts
Declare a license in the repository or the registry entry.

pypreset

Overview

Installation

In SourceWeft

Other MCP clients

README

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

Tools

Version history

Score

`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