\n A meta-tool for scaffolding Python projects with configurable YAML presets. \n Supports Poetry, uv, and setuptools, generates CI workflows, testing scaffolds, type checking configs, and more.\n
\n\nmcp-name: io.github.KaiErikNiermann/pypreset\n\n## Features\n\n- **Preset-based project creation** from YAML configs with single inheritance\n- **Augment existing projects** with CI workflows, tests, Docker, documentation, and more\n- **Three package managers**: Poetry, uv (PEP 621 + hatchling), and setuptools (PEP 621 + setuptools.build_meta)\n- **Two layout styles**: `src/` layout and flat layout\n- **Type checking**: mypy, pyright, ty, or none\n- **Code quality**: ruff linting/formatting, radon complexity checks, pre-commit hooks\n- **Docker & devcontainer**: generate multi-stage Dockerfiles, `.dockerignore`, and VS Code devcontainer configs (Docker or Podman)\n- **Coverage integration**: Codecov support with configurable thresholds and ignore patterns\n- **Documentation scaffolding**: MkDocs (Material theme) or Sphinx (RTD theme) with optional GitHub Pages deployment\n- **Multi-environment testing**: tox configuration with tox-uv backend\n- **pyenv / .python-version**: generate `.python-version` for pyenv and uv, with `python-version-file` in CI workflows\n- **Version management**: bump-my-version integration, GitHub release automation via `gh` CLI\n- **Workflow verification**: local GitHub Actions testing with `act` (auto-detect, auto-install, dry-run and full-run modes)\n- **PyPI metadata management**: read, set, and check publish-readiness of `pyproject.toml` metadata\n- **User defaults**: persistent config at `~/.config/pypreset/config.yaml`\n- **MCP server**: expose all functionality to AI coding assistants via the Model Context Protocol\n\n## Installation\n\n```bash\npip install pypreset\n\n# With MCP server support\npip install pypreset[mcp]\n```\n\n## Quick Start\n\n```bash\n# Create a CLI tool project with Poetry\npypreset create my-cli --preset cli-tool\n\n# Create a data science project with uv\npypreset create my-analysis --preset data-science --package-manager uv\n\n# Create an empty package with src layout (default)\npypreset create my-package --preset empty-package\n\n# Create a Discord bot\npypreset create my-bot --preset discord-bot\n\n# Create a project with Docker support\npypreset create my-service --preset cli-tool --docker --devcontainer\n\n# Create with .python-version for pyenv/uv\npypreset create my-lib --pyenv --python-version 3.13\n\n# Create with Podman, Codecov, docs, and tox\npypreset create my-project --preset empty-package \\\n --container-runtime podman --docker \\\n --coverage-tool codecov --coverage-threshold 80 \\\n --docs mkdocs --docs-gh-pages \\\n --tox\n```\n\n## Commands\n\n### `create` -- Scaffold a new project\n\n```bash\npypreset create [OPTIONS]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--preset`, `-p` | Preset to use (default: `empty-package`) |\n| `--output`, `-o` | Output directory (default: `.`) |\n| `--config`, `-c` | Custom preset YAML file |\n| `--package-manager` | `poetry` or `uv` |\n| `--layout` | `src` or `flat` |\n| `--type-checker` | `mypy`, `pyright`, `ty`, or `none` |\n| `--typing` | `none`, `basic`, or `strict` |\n| `--python-version` | e.g., `3.12` |\n| `--testing` / `--no-testing` | Enable/disable testing scaffold |\n| `--formatting` / `--no-formatting` | Enable/disable formatting config |\n| `--radon` / `--no-radon` | Enable radon complexity checking |\n| `--pre-commit` / `--no-pre-commit` | Generate pre-commit hooks config |\n| `--bump-my-version` / `--no-bump-my-version` | Include bump-my-version config |\n| `--extra-package`, `-e` | Additional packages (repeatable) |\n| `--extra-dev-package`, `-d` | Additional dev packages (repeatable) |\n| `--docker` / `--no-docker` | Generate Dockerfile and `.dockerignore` |\n| `--devcontainer` / `--no-devcontainer` | Generate `.devcontainer/` configuration |\n| `--container-runtime` | `docker` or `podman` |\n| `--coverage-tool` | `codecov` or `none` |\n| `--coverage-threshold` | Minimum coverage % (e.g., `80`) |\n| `--docs` | `sphinx`, `mkdocs`, or `none` |\n| `--docs-gh-pages` / `--no-docs-gh-pages` | Generate GitHub Pages deploy workflow |\n| `--tox` / `--no-tox` | Generate `tox.ini` with tox-uv backend |\n| `--pyenv` / `--no-pyenv` | Generate `.python-version` and use `python-version-file` in CI |\n| `--git` / `--no-git` | Initialize git repository |\n| `--install` / `--no-install` | Run dependency install after creation |\n| `--dry-run` | Preview what would be created without generating anything |\n\n### `augment` -- Add components to an existing project\n\nAnalyzes `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.\n\n```bash\npypreset augment [path] [OPTIONS]\n```\n\n**Available components:**\n\n| Flag | Component | What it generates |\n|------|-----------|-------------------|\n| `--test-workflow` / `--no-test-workflow` | Test CI | GitHub Actions workflow that runs pytest across a Python version matrix |\n| `--lint-workflow` / `--no-lint-workflow` | Lint CI | GitHub Actions workflow for ruff, type checking, and complexity analysis |\n| `--dependabot` / `--no-dependabot` | Dependabot | `.github/dependabot.yml` for automated dependency updates |\n| `--tests` / `--no-tests` | Tests directory | `tests/` with template test files and `conftest.py` |\n| `--gitignore` / `--no-gitignore` | Gitignore | Python-specific `.gitignore` |\n| `--pypi-publish` / `--no-pypi-publish` | PyPI publish | GitHub Actions workflow for OIDC-based publishing to PyPI on release |\n| `--dockerfile` / `--no-dockerfile` | Docker | Multi-stage `Dockerfile` and `.dockerignore` (Poetry, uv, or setuptools aware) |\n| `--devcontainer` / `--no-devcontainer` | Devcontainer | `.devcontainer/devcontainer.json` with VS Code extensions |\n| `--codecov` / `--no-codecov` | Codecov | `codecov.yml` configuration |\n| `--docs` | Documentation | Sphinx or MkDocs scaffolding (`--docs sphinx` or `--docs mkdocs`) |\n| `--tox` / `--no-tox` | tox | `tox.ini` with tox-uv backend for multi-environment testing |\n| `--readme` / `--no-readme` | README | `README.md` generated from the shared template (badges, install, features) |\n| `--pyenv` / `--no-pyenv` | pyenv | `.python-version` file for pyenv and uv version pinning |\n\n```bash\n# Interactive mode (prompts for missing values)\npypreset augment ./my-project\n\n# Auto-detect everything, no prompts\npypreset augment --auto\n\n# Generate only specific components\npypreset augment --test-workflow --lint-workflow --gitignore\n\n# Add Docker and devcontainer\npypreset augment --dockerfile --devcontainer\n\n# Add PyPI publish workflow\npypreset augment --pypi-publish\n\n# Add documentation scaffolding\npypreset augment --docs mkdocs\n\n# Generate a README from your project metadata\npypreset augment --readme\n\n# Overwrite existing files\npypreset augment --force\n```\n\n### `workflow` -- Local workflow verification\n\nVerify GitHub Actions workflows locally using [act](https://nektosact.com/). The proxy auto-detects whether `act` is installed, can install it on supported systems, and surfaces all `act` output directly.\n\n```bash\n# Verify all workflows (dry-run, no containers)\npypreset workflow verify\n\n# Verify a specific workflow file\npypreset workflow verify --workflow .github/workflows/ci.yaml\n\n# Verify a specific job\npypreset workflow verify --job lint\n\n# Full run (executes in containers, requires Docker)\npypreset workflow verify --full-run\n\n# Auto-install act if missing\npypreset workflow verify --auto-install\n\n# Pass extra flags to act\npypreset workflow verify --flag=\"--secret=GITHUB_TOKEN=xxx\"\n\n# Check if act is installed\npypreset workflow check-act\n\n# Install act automatically\npypreset workflow install-act\n```\n\nSupported 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](https://nektosact.com/installation/index.html).\n\n### `version` -- Release management\n\n```bash\npypreset version release --bump patch # 0.1.0 -> 0.1.1\npypreset version release --bump minor # 0.1.0 -> 0.2.0\npypreset version release --bump major # 0.1.0 -> 1.0.0\npypreset version release-version 2.0.0 # Explicit version\npypreset version rerun # Re-tag and push an existing version\npypreset version rerelease # Delete and recreate a GitHub release\n```\n\nRequires the `gh` CLI to be installed and authenticated.\n\n### `metadata` -- PyPI metadata management\n\n```bash\npypreset metadata show # Display current metadata\npypreset metadata set --description \"My cool package\" # Set description\npypreset metadata set --github-owner myuser # Auto-generate URLs\npypreset metadata set --license MIT --keyword python # Set license and keywords\npypreset metadata check # Check publish-readiness\n```\n\n### `badges` -- Generate badge markdown\n\nReads `pyproject.toml` to detect your project name, repository URL, and license, then prints badge markdown you can paste into your README.\n\n```bash\npypreset badges # Badges for current directory\npypreset badges ./my-project # Badges for a specific project\n```\n\n### Other commands\n\n```bash\npypreset list-presets # List all available presets\npypreset show-preset # Show full preset details\npypreset validate [path] # Validate project structure\npypreset analyze [path] # Detect and display project tooling\npypreset config show # Show current user defaults\npypreset config init # Create default config file\npypreset config set # Set a config value\n```\n\n## Presets\n\nBuilt-in presets: `empty-package`, `cli-tool`, `data-science`, `discord-bot`.\n\nPresets 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.\n\n### Custom presets\n\nPlace custom preset files in `~/.config/pypreset/presets/` or pass a file directly:\n\n```bash\npypreset create my-project --config ./my-preset.yaml\n```\n\nUser presets take precedence over built-in presets with the same name.\n\n## User Configuration\n\nPersistent defaults are stored at `~/.config/pypreset/config.yaml` and applied as the lowest-priority layer (presets and CLI flags override them).\n\n```bash\npypreset config init # Create with defaults\npypreset config set layout flat # Set default layout\npypreset config set type_checker ty # Set default type checker\npypreset config show # View current config\n```\n\n## MCP Server\n\npypreset is published to the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.KaiErikNiermann/pypreset`.\n\n**Install via the registry (recommended):**\n\n```bash\n# Claude Code\nclaude mcp add pypreset -- uvx --from \"pypreset[mcp]\" pypreset-mcp\n\n# Or add manually to ~/.claude/settings.json\n```\n\n```json\n{\n \"mcpServers\": {\n \"pypreset\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"pypreset[mcp]\", \"pypreset-mcp\"]\n }\n }\n}\n```\n\n**Or install locally:**\n\n```bash\npip install pypreset[mcp]\n```\n\n```json\n{\n \"mcpServers\": {\n \"pypreset\": {\n \"command\": \"pypreset-mcp\",\n \"args\": []\n }\n }\n}\n```\n\n**Available tools:**\n\n| Tool | Description |\n|------|-------------|\n| `create_project` | Create a new project from a preset with optional overrides |\n| `augment_project` | Add CI workflows, tests, Docker, docs, and more to an existing project |\n| `validate_project` | Check structural correctness of a project directory |\n| `verify_workflow` | Verify GitHub Actions workflows locally using act |\n| `list_presets` | List all available presets with names and descriptions |\n| `show_preset` | Show the full YAML configuration of a specific preset |\n| `get_user_config` | Read current user-level defaults |\n| `set_user_config` | Update user-level defaults |\n| `set_project_metadata` | Set or update PyPI metadata in `pyproject.toml` |\n| `generate_badges` | Generate badge markdown links from project metadata |\n\n**Resources**: `preset://list`, `config://user`, `template://list`\n\n**Prompts**: `create-project`, `augment-project`\n\n## Development\n\nAll tasks use the `Justfile`:\n\n```bash\njust install # Install dependencies\njust test # Run tests\njust test-cov # Tests with coverage\njust lint # Ruff check\njust format # Ruff format\njust typecheck # Pyright\njust radon # Cyclomatic complexity check\njust check # lint + typecheck + radon + test\njust all # format + lint-fix + typecheck + radon + test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n \nMIT\n",
"bytes": 13087,
"sha": "bd589d133da35bb89e0d464f241b751aad0c498c4d5b5d13c70dc76d43b31201",
"repo_slug": "kaierikniermann/pypreset",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_kaierikniermann_pypreset_3a44655f/readme"
}
![\"PyPreset\"](\"https://raw.githubusercontent.com/KaiErikNiermann/pypreset/main/resources/banner.png\")
\n