pypreset

io.github.KaiErikNiermann由 GitHub 帳號 KaiErikNiermann 發布v0.4.0更新於 Oct 24, 2026

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

已驗證STDIO僅桌面雲端與基礎設施開發者工具

概覽

AI 產生的概覽

依 YAML 預設範本建立與擴充 Python 專案，為 AI 助理產生 CI 工作流程、測試、Docker、文件與 PyPI 中繼資料。

可以做什麼
  • 從內建或自訂 YAML 預設建立專案，可覆寫套件管理器、目錄配置、型別檢查器等選項
  • 為既有專案加入 CI 工作流程、測試、Dockerfile、devcontainer、文件、tox 與 README
  • 驗證專案結構，並用 act 在本機驗證 GitHub Actions 工作流程
  • 列出與檢視預設，讀取或修改使用者層級預設設定
  • 設定 pyproject.toml 中的 PyPI 中繼資料並產生徽章 Markdown
適用情境
適合新建 Python 套件或命令列工具時快速取得設定完整、風格一致的骨架，也適合為既有 Python 儲存庫補上 CI、測試、Docker 或文件，而不必手寫設定檔。
執行需求
以本機 stdio 程序執行，通常透過 uvx 使用 pypreset[mcp] 套件（或本機 pip 安裝）。需要 Python 以及 uv 或 pip。工作流程驗證需要 act，完整執行需要 Docker；發佈相關指令需要已安裝並登入的 gh CLI。未宣告任何 API 金鑰或環境變數。
安裝前請注意
會寫入專案目錄中的檔案，使用強制選項時可能覆蓋既有檔案，提交前應檢查產生結果。可初始化 git 儲存庫、執行相依套件安裝，並透過 gh CLI 推送標籤或建立 GitHub 發佈。完整執行的工作流程驗證會在容器中執行工作流程，並可能將密鑰傳給 act。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 pypreset，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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

bash
pip install pypreset
# With MCP server supportpip install pypreset[mcp]

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

Commands

create -- Scaffold a new project

bash
pypreset create <name> [OPTIONS]
OptionDescription
--preset, -pPreset to use (default: empty-package)
--output, -oOutput directory (default: .)
--config, -cCustom preset YAML file
--package-managerpoetry or uv
--layoutsrc or flat
--type-checkermypy, pyright, ty, or none
--typingnone, basic, or strict
--python-versione.g., 3.12
--testing / --no-testingEnable/disable testing scaffold
--formatting / --no-formattingEnable/disable formatting config
--radon / --no-radonEnable radon complexity checking
--pre-commit / --no-pre-commitGenerate pre-commit hooks config
--bump-my-version / --no-bump-my-versionInclude bump-my-version config
--extra-package, -eAdditional packages (repeatable)
--extra-dev-package, -dAdditional dev packages (repeatable)
--docker / --no-dockerGenerate Dockerfile and .dockerignore
--devcontainer / --no-devcontainerGenerate .devcontainer/ configuration
--container-runtimedocker or podman
--coverage-toolcodecov or none
--coverage-thresholdMinimum coverage % (e.g., 80)
--docssphinx, mkdocs, or none
--docs-gh-pages / --no-docs-gh-pagesGenerate GitHub Pages deploy workflow
--tox / --no-toxGenerate tox.ini with tox-uv backend
--pyenv / --no-pyenvGenerate .python-version and use python-version-file in CI
--git / --no-gitInitialize git repository
--install / --no-installRun dependency install after creation
--dry-runPreview 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:

FlagComponentWhat it generates
--test-workflow / --no-test-workflowTest CIGitHub Actions workflow that runs pytest across a Python version matrix
--lint-workflow / --no-lint-workflowLint CIGitHub Actions workflow for ruff, type checking, and complexity analysis
--dependabot / --no-dependabotDependabot.github/dependabot.yml for automated dependency updates
--tests / --no-testsTests directorytests/ with template test files and conftest.py
--gitignore / --no-gitignoreGitignorePython-specific .gitignore
--pypi-publish / --no-pypi-publishPyPI publishGitHub Actions workflow for OIDC-based publishing to PyPI on release
--dockerfile / --no-dockerfileDockerMulti-stage Dockerfile and .dockerignore (Poetry, uv, or setuptools aware)
--devcontainer / --no-devcontainerDevcontainer.devcontainer/devcontainer.json with VS Code extensions
--codecov / --no-codecovCodecovcodecov.yml configuration
--docsDocumentationSphinx or MkDocs scaffolding (--docs sphinx or --docs mkdocs)
--tox / --no-toxtoxtox.ini with tox-uv backend for multi-environment testing
--readme / --no-readmeREADMEREADME.md generated from the shared template (badges, install, features)
--pyenv / --no-pyenvpyenv.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

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

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

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

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

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

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

ToolDescription
create_projectCreate a new project from a preset with optional overrides
augment_projectAdd CI workflows, tests, Docker, docs, and more to an existing project
validate_projectCheck structural correctness of a project directory
verify_workflowVerify GitHub Actions workflows locally using act
list_presetsList all available presets with names and descriptions
show_presetShow the full YAML configuration of a specific preset
get_user_configRead current user-level defaults
set_user_configUpdate user-level defaults
set_project_metadataSet or update PyPI metadata in pyproject.toml
generate_badgesGenerate 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

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

來源：README.md，提交 c6513eb

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.4.0最新Sep 16, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。