pypreset

設定可能な YAML プリセットを使って Python プロジェクトをひな形から作成するメタツールです。
Poetry、uv、setuptools に対応し、CI ワークフロー、テストのひな形、型チェック設定などを生成します。

mcp-name: io.github.KaiErikNiermann/pypreset

機能

• YAML 設定と単一継承に基づくプリセット方式のプロジェクト作成
• CI ワークフロー、テスト、Docker、ドキュメントなどを追加して既存プロジェクトを拡張
• 3 種類のパッケージマネージャー：Poetry、uv（PEP 621 + hatchling）、setuptools（PEP 621 + setuptools.build_meta）
• 2 種類のレイアウトスタイル：src/ レイアウトとフラットレイアウト
• 型チェック：mypy、pyright、ty、またはなし
• コード品質：ruff によるリント／フォーマット、radon による複雑度チェック、pre-commit フック
• Docker と devcontainer：マルチステージ Dockerfile、.dockerignore、VS Code devcontainer 設定（Docker または Podman）を生成
• カバレッジ連携：しきい値と除外パターンを設定できる Codecov サポート
• ドキュメントのひな形：MkDocs（Material テーマ）または Sphinx（RTD テーマ）。GitHub Pages へのデプロイは任意です
• 複数環境でのテスト：tox-uv バックエンドを使用した tox 設定
• pyenv / .python-version：pyenv と uv 用の .python-version を生成し、CI ワークフローで python-version-file を使用
• バージョン管理：bump-my-version 連携、gh CLI による GitHub リリースの自動化
• ワークフロー検証：act によるローカルでの GitHub Actions テスト（自動検出、自動インストール、ドライラン、フル実行モード）
• PyPI メタデータ管理：pyproject.toml のメタデータの読み取り、設定、公開準備状況の確認
• ユーザー既定値：~/.config/pypreset/config.yaml に永続化される設定
• MCP サーバー：Model Context Protocol を通じて、すべての機能を AI コーディングアシスタントに公開

インストール

pip install pypreset

# With MCP server support
pip install pypreset[mcp]

クイックスタート

# 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

コマンド

create -- 新しいプロジェクトのひな形を作成

pypreset create <name> [OPTIONS]

オプション	説明
--preset, -p	使用するプリセット（既定値：empty-package）
--output, -o	出力ディレクトリ（既定値：.）
--config, -c	カスタムプリセット YAML ファイル
--package-manager	poetry または uv
--layout	src または flat
--type-checker	mypy、pyright、ty、または none
--typing	none、basic、または strict
--python-version	例：3.12
--testing / --no-testing	テストのひな形を有効／無効にする
--formatting / --no-formatting	フォーマット設定を有効／無効にする
--radon / --no-radon	radon による複雑度チェックを有効にする
--pre-commit / --no-pre-commit	pre-commit フック設定を生成する
--bump-my-version / --no-bump-my-version	bump-my-version 設定を含める
--extra-package, -e	追加パッケージ（複数回指定可能）
--extra-dev-package, -d	追加の開発用パッケージ（複数回指定可能）
--docker / --no-docker	Dockerfile と .dockerignore を生成する
--devcontainer / --no-devcontainer	.devcontainer/ 設定を生成する
--container-runtime	docker または podman
--coverage-tool	codecov または none
--coverage-threshold	最小カバレッジ率（例：80）
--docs	sphinx、mkdocs、または none
--docs-gh-pages / --no-docs-gh-pages	GitHub Pages デプロイワークフローを生成する
--tox / --no-tox	tox-uv バックエンドを使用した tox.ini を生成する
--pyenv / --no-pyenv	.python-version を生成し、CI で python-version-file を使用する
--git / --no-git	git リポジトリを初期化する
--install / --no-install	作成後に依存関係をインストールする
--dry-run	何も生成せず、作成される内容をプレビューする

augment -- 既存のプロジェクトにコンポーネントを追加

pyproject.toml を分析して使用中のツールを自動検出し、選択したコンポーネントを生成します。デフォルトでは対話モードで実行され（検出できない値を入力するよう求められます）、--auto を指定すると入力を省略できます。

pypreset augment [path] [OPTIONS]

利用可能なコンポーネント：

フラグ	コンポーネント	生成される内容
--test-workflow / --no-test-workflow	テスト CI	Python のバージョンマトリックスで pytest を実行する GitHub Actions ワークフロー
--lint-workflow / --no-lint-workflow	Lint CI	ruff、型チェック、複雑度分析用の GitHub Actions ワークフロー
--dependabot / --no-dependabot	Dependabot	依存関係を自動更新する .github/dependabot.yml
--tests / --no-tests	テストディレクトリ	テンプレートのテストファイルと conftest.py を含む tests/
--gitignore / --no-gitignore	Gitignore	Python 用の .gitignore
--pypi-publish / --no-pypi-publish	PyPI への公開	リリース時に PyPI へ OIDC ベースで公開する GitHub Actions ワークフロー
--dockerfile / --no-dockerfile	Docker	マルチステージの Dockerfile と .dockerignore（Poetry、uv、または setuptools を認識）
--devcontainer / --no-devcontainer	Devcontainer	VS Code 拡張機能を含む .devcontainer/devcontainer.json
--codecov / --no-codecov	Codecov	codecov.yml の設定
--docs	ドキュメント	Sphinx または MkDocs のひな型（--docs sphinx または --docs mkdocs）
--tox / --no-tox	tox	複数環境でのテスト用 tox-uv バックエンドを備えた tox.ini
--readme / --no-readme	README	共通テンプレートから生成される README.md（バッジ、インストール方法、機能）
--pyenv / --no-pyenv	pyenv	pyenv と uv のバージョン固定用 .python-version ファイル

# 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 -- ローカルでのワークフロー検証

act を使用して GitHub Actions ワークフローをローカルで検証します。プロキシは act がインストールされているかどうかを自動検出し、対応システムではインストールでき、act の出力をすべて直接表示します。

# 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

自動インストールに対応している環境：Arch Linux（pacman）、Ubuntu/Debian（apt）、Fedora（dnf）、Homebrew を使用する macOS/Linux。その他のシステムでは、act のインストールページへのリンクが表示されます。

version -- リリース管理

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

gh CLI のインストールと認証が必要です。

metadata -- PyPI メタデータ管理

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 -- バッジの Markdown を生成

pyproject.toml を読み取り、プロジェクト名、リポジトリ URL、ライセンスを検出して、README に貼り付けられるバッジの Markdown を出力します。

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

その他のコマンド

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

プリセット

組み込みプリセット：empty-package、cli-tool、data-science、discord-bot。

プリセットは、メタデータ、依存関係、ディレクトリ構成、テスト、フォーマットなどを定義する YAML ファイルです。base: フィールドを使用して、単一の継承に対応しています。metadata.readme_template にカスタムの .j2 ファイル名を設定すると、プリセットで README テンプレートを上書きできます。

カスタムプリセット

カスタムプリセットファイルを ~/.config/pypreset/presets/ に配置するか、ファイルを直接指定します。

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

ユーザープリセットは、同じ名前の組み込みプリセットより優先されます。

ユーザー設定

永続的なデフォルト設定は ~/.config/pypreset/config.yaml に保存され、最も優先度の低いレイヤーとして適用されます（プリセットと CLI フラグがこれらの設定を上書きします）。

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 サーバー

pypreset は io.github.KaiErikNiermann/pypreset として MCP Registry に公開されています。

レジストリ経由でインストール（推奨）：

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

またはローカルにインストール：

pip install pypreset[mcp]

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

利用可能なツール：

ツール	説明
create_project	プリセットから新しいプロジェクトを作成します。オプションで上書き設定を指定できます
augment_project	既存のプロジェクトに CI ワークフロー、テスト、Docker、ドキュメントなどを追加します
validate_project	プロジェクトディレクトリの構造が正しいか確認します
verify_workflow	act を使って GitHub Actions ワークフローをローカルで検証します
list_presets	利用可能なすべてのプリセットの名前と説明を一覧表示します
show_preset	特定のプリセットの YAML 設定全体を表示します
get_user_config	現在のユーザーレベルの既定値を読み取ります
set_user_config	ユーザーレベルの既定値を更新します
set_project_metadata	pyproject.toml の PyPI メタデータを設定または更新します
generate_badges	プロジェクトのメタデータからバッジの Markdown リンクを生成します

リソース：preset://list、config://user、template://list

プロンプト：create-project、augment-project

開発

すべてのタスクで 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

開発環境のセットアップとガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT