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 分

    请在仓库或注册中心条目中声明许可证。