modern-python-guidance

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

• Measurable impact: AI writes modern Python 98% of the time with mpg, vs 79% without — even with vague prompts (Opus 4.8, V5 benchmark details)
• 41 guides across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
• Version-aware: auto-detects your project's Python version and filters guides accordingly
• 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

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, and creates a Rules file (.claude/rules/modern-python.md) in one command. The Rules file auto-injects modern Python guidance whenever you touch Python-related files. Start a new Claude Code session afterwards — newly registered MCP servers, skills, and rules 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.

MCP registration (Claude Code):

claude mcp add mpg -- mpg mcp

Other MCP-compatible agents (Cursor, Windsurf, etc.) — add to your MCP config:

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

Agent Skills + Rules only (Claude Code):

mpg setup --skills-only

mpg setup flags:| Flag | Purpose ||------|---------|| --mcp-only | MCP registration only || --skills-only | Project-local artifacts only (Skills + Rules) || --scope {user,local} | MCP scope (default: user) || --project-dir PATH | Target project for Skills/Rules symlinks || --dry-run | Show what would be done |

Uninstall — reverse mpg setup (deregister the MCP server and unlink Agent Skills + Rules):

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

mpg uninstall clears the MCP registration from every scope setup can write to (user and local), removes only the symlinks mpg created (never their targets or other files), and is idempotent — running it on an already-clean state is a harmless no-op.

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

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

Guide coverage

41 guides across 3 layers:

Run mpg list to see all 41 guides, or browse them on GitHub.

Version-aware filtering

Guides specify their minimum Python version. The CLI auto-detects your project's version from (in order):

1. --python-version flag
2. pyproject.toml requires-python
3. .python-version file
4. Default: 3.11

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

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.