modern-python-guidance

Stop your AI from writing typing.List, @validator, and setup.py. 41 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.

Highlights

• Evidence status: Historical V5 content-efficacy evidence is documented with its model, prompt, sample, metric, and delivery scope; it is not a product-wide effectiveness claim (V5 benchmark details)
• 41 guides across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
• Version- and dependency-aware: filters Python-version-incompatible guidance and qualifies framework/tool guidance from project evidence
• 4 delivery methods: MCP server, CLI, Agent Skills, and Rules (auto-injects on .py file touch)
• Not Ruff: Ruff auto-fixes syntax (List → list). mpg guides design decisions that Ruff can't touch — TaskGroup over gather, Pydantic V2 migration, SQLAlchemy 2.0 style

Benchmark evidence status: historical V5 cells remain documented for audit, but no traceable numeric product claim is currently promoted. Default mpg setup end-to-end effectiveness has not yet been measured.

Note: The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and --python-version filters guides for your target environment.

Quick start

Claude Code (recommended)

pip install modern-python-guidance
mpg setup

This registers the MCP server, links Agent Skills, creates a Rules file (.claude/rules/modern-python.md), and registers a PostToolUse hook in one command. The Rules file auto-injects modern Python guidance whenever you touch Python-related files, and the hook checks each edited .py file against the guides with a detector applicable to the target project (see PostToolUse hook below). Advisory-only gaps are disclosed through CLI/MCP metadata. Start a new Claude Code session afterwards — newly registered MCP servers, skills, rules, and hooks take effect on the next launch.

CLI

pip install modern-python-guidance
mpg search "pydantic validator"
mpg retrieve pydantic-v2-validators

mpg is the short alias for modern-python-guidance. Both work.

# uv tool / pipx installs (mpg is on PATH):
claude mcp add mpg -- mpg mcp

# venv installs — Claude Code spawns MCP servers outside your venv, so register
# the interpreter's absolute path (`mpg setup` does this automatically):
claude mcp add mpg -- "$(python -c 'import sys; print(sys.executable)')" -m modern_python_guidance mcp

{
  "mcpServers": {
    "mpg": {
      "command": "mpg",
      "args": ["mcp"]
    }
  }
}

mpg setup --skills-only

mpg uninstall            # remove all
mpg uninstall --dry-run  # preview what would be removed

CLI usage

# Search guides by keyword
mpg search "pydantic validator"

# Retrieve a specific guide (full BAD/GOOD content)
mpg retrieve use-builtin-generics

# List all guides compatible with your Python version
mpg list --python-version 3.11

# Auto-detect project Python version from pyproject.toml / .python-version
mpg detect-version

# Filter by category
mpg search "timeout" --category async

# Scan a file for outdated patterns
mpg check app.py
mpg check app.py --format json | jq '.summary.guide_ids'
mpg check app.py --exit-zero  # always exit 0

# JSON output (default when piped, explicit with --format)
mpg search "typing" --format json | jq '.[0].id'

# Read dependency evidence from another project; hide proven-incompatible guides by default
mpg search "pydantic validator" --project-dir ../my-app

# Supply an exact target-environment override when files cannot prove it
mpg search "pydantic validator" --dependency-version package:pydantic=2.7.4

Guide coverage

41 guides across 3 layers:

Run mpg list to see the 41-guide catalog, or browse it on GitHub.

Version-aware filtering

Guides specify their minimum Python version. Every guidance command resolves the target Python from the nearest project context (and discloses the result as target_python: {version, source}) using this precedence:

1. --python-version flag
2. pyproject.toml requires-python
3. pyproject.toml Poetry python constraint (^3.10, ~3.11, >=3.10,<3.14)
4. .python-version file
5. Default: 3.11

The same resolver is used by CLI search/retrieve/list/check, the MCP guidance tools, and the PostToolUse hook. An explicit CLI/MCP version always wins. mpg detect-version keeps its plain output for scripts; use mpg detect-version --format json to audit the resolved version and stable source label, including when a JSON search or list result is empty.

# Only shows guides compatible with Python 3.9 (explicit override)
mpg list --python-version 3.9
# Excludes: TaskGroup (3.11+), match/case (3.10+), etc.

Dependency-aware applicability

Framework and toolchain guides declare machine-readable applies-to-packages and/or applies-to-tools metadata. Every declared requirement must be proven (AND semantics). mpg search and mpg list hide guidance that is proven incompatible by default; use --include-incompatible to inspect it. retrieve always returns an explicitly requested guide so migration work can be reviewed.

Use --project-dir PATH to read the nearest project evidence, and repeat --dependency-version KIND:NAME=VERSION for an exact target-environment override. The MCP search_guides, retrieve_guides, and list_guides tools expose the same project_dir (relative to the MCP server), dependency_versions object, and include_incompatible option where filtering applies.

Results contain additive dependency_requirements and dependency_compatibility objects. Status is deliberately conservative:

• confirmed: all requirements are proven compatible;
• incompatible: at least one requirement is proven incompatible;
• unknown: evidence is absent, ambiguous, conditional, or cannot safely prove a range.

Unknown is not confirmation. Do not infer the target environment from the interpreter running mpg, a [tool.uv]/[tool.ruff] table, optional or dependency-group entries, or an unrooted/ambiguous lockfile. The PostToolUse hook suppresses known-incompatible findings and asks for verification when status is unknown; mpg check follows the same rule and annotates remaining unknown findings in JSON/human output.

PostToolUse hook

mpg setup registers a PostToolUse hook by default (see Quick start above) — no manual .claude/settings.local.json editing needed. It checks every .py file Claude edits or writes against the detector-capable guides applicable to the target project and surfaces findings via hookSpecificOutput.additionalContext, so Claude receives them as part of its own context rather than as a raw stderr error.

mpg check and the PostToolUse hook automatically check only guides with a detector for the target Python/dependency context. The current catalog has 26 detectable guides out of 41; 15 are advisory-only and are not claimed as actively checked. Advisory-only guides: dataclass-modern, dict-merge-operator, django-check-constraints, exception-groups, fastapi-typed-state, httpx-streaming, match-case-patterns, override-decorator, pytest-parametrize, pytest-raises-match, removeprefix-removesuffix, ruff-over-flake8, sqlalchemy-async-session, template-strings, uv-over-pip. A clean automatic check does not certify advisory-only guidance. Use mpg list --format json or MCP metadata to inspect each guide's detection status.

This capability contract is distinct from #152: #181 describes which guides can produce automatic findings after activation, while #152 measures whether an organic development session reaches the catalog at all.

A few things worth knowing about how it behaves:

• It scans the whole edited file, not just your diff. An edit anywhere in a file can resurface pre-existing outdated patterns you didn't touch this time, not only the lines you just wrote.
• Findings are capped at 5 per edit, plus a +N more summary line, to bound how much context gets injected.
• Only the guide ID and line number are surfaced — never the matching source line itself. Echoing arbitrary file content back as an authoritative-looking hook message would be an indirect prompt-injection channel; guide_id + line number is enough for Claude to look up the modern form.
• The project's target Python version is auto-detected the same way as mpg detect-version (nearest pyproject.toml requires-python / Poetry python constraint, or .python-version, walking up from the edited file), so patterns that require a newer Python than your project targets are not flagged. The resolved target and source are shown in the summary ([target: py3.X; source: SOURCE]).
• Non-Python files and clean files produce no output.
• An existing project (Skills/Rules already linked from a previous mpg setup) is never silently opted in — see the --with-hook/--no-hook flags above.

Verify with /hooks in Claude Code to confirm it's active.

For manual CLI use, mpg check --quiet <file> uses the same automatic resolver. Pass --python-version X.Y when you intentionally want an explicit override; the JSON output contains the same top-level target_python object.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/python",
            "args": ["-m", "modern_python_guidance", "hook", "claude-post-tool-use"]
          }
        ]
      }
    ]
  }
}

Development

git clone https://github.com/yottayoshida/modern-python-guidance.git
cd modern-python-guidance
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for project structure and guide authoring details.

License

Apache-2.0 OR MIT — see LICENSE and LICENSE-MIT.