convez.ai
MCP ServerProdutividadeIntermediário
yottayoshida

Modern Python Guidance

yottayoshida/modern-python-guidance

Guias de padrões Python modernos para geração de código com IA

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que ensina agentes de IA a escrever Python moderno (2026) corrigindo padrões desatualizados. Fornece 41 guias versionados sobre stdlib, Pydantic, FastAPI, Django e outras bibliotecas, com impacto mensurável: 98% de código moderno vs 79% sem a ferramenta.

Instalação

$npx convez-ai yottayoshida/modern-python-guidance

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
2
Acompanhando
0
Saúde
71%
Último commit
há 1 mês
Versão
v1.3.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Melhorar qualidade de código gerado por agentes IA (Claude, Cursor, Windsurf)
  • Migrar codebase para práticas modernas (Pydantic V2, SQLAlchemy 2.0, TaskGroup)
  • Reforçar padrões de projeto em equipes através de Rules file automático

Veredito

Ferramenta prática e bem-medida para quem usa IA na geração de código Python. Oferece 4 métodos de integração (MCP, CLI, Skills, Rules) e cobertura real de anti-padrões que linters não conseguem detectar. Impacto comprovado em benchmarks.

README

A tradução para o português deste README ainda está na fila.

modern-python-guidance

CI PyPI version Python License

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

# 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

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

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

For venv installs, set "command" to your interpreter's absolute path and "args" to ["-m", "modern_python_guidance", "mcp"] for the same reason as above.

Agent Skills + Rules only (Claude Code):

mpg setup --skills-only

mpg setup flags:

FlagPurpose
--mcp-onlyMCP registration only
--skills-onlyProject-local artifacts only (Skills + Rules)
--scope {user,local}MCP scope (default: user)
--project-dir PATHTarget project for Skills/Rules symlinks
--dry-runShow what would be done

After registering, mpg setup checks whether a same-name registration in a higher-precedence scope (local > project > user) would shadow the one it just wrote, and prints a warning with the exact claude mcp remove command if so.

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
FlagPurpose
--mcp-onlyMCP deregistration only
--skills-onlyProject-local artifacts only (Skills + Rules)
--project-dir PATHTarget project for Skills/Rules symlinks
--dry-runShow what would be done

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

# 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'

Guide coverage

41 guides across 3 layers:

LayerCategoriesCountExamples
1 — stdlibtyping, async, stdlib, data-structures18list over List, match/case, TaskGroup, deferred annotations, t-strings
2 — frameworkspydantic, fastapi, httpx, django, sqlalchemy, pytest18Pydantic V2 migration, SQLAlchemy 2.0 style, Annotated[Depends]
3 — toolchaintoolchain5uv over pip, ruff over flake8, pickle avoidance

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. pyproject.toml Poetry python constraint (^3.10, ~3.11, >=3.10,<3.14)
  4. .python-version file
  5. 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.

Recommended hooks

Add a PostToolUse hook to auto-check Python files whenever Claude edits them. Create or update .claude/settings.json in your project:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"MultiEdit\"",
        "hooks": [
          {
            "type": "command",
            "command": "mpg hook claude-post-tool-use"
          }
        ]
      }
    ]
  }
}

The hook reads stdin from Claude Code, checks any .py file for outdated patterns, and surfaces findings as inline feedback. The project's target Python version is auto-detected from the nearest pyproject.toml (requires-python or Poetry's python constraint) or .python-version, walking up from the edited file — the same sources as mpg detect-version — so patterns that require a newer Python than your project targets are not flagged. The resolved target is shown in the summary line ([target: py3.X]). Non-Python files and clean files produce no output.

If mpg is installed in a venv (not uv tool/pipx), use the interpreter's absolute path in command: /path/to/venv/bin/python -m modern_python_guidance hook claude-post-tool-use.

Verify with /hooks in Claude Code to confirm the hook is active.

For manual CLI use, mpg check --quiet <file> --python-version X.Y runs the same check — pass your project's floor explicitly, since unlike the hook, mpg check does not auto-detect it.

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.

Ver o original no GitHub

Bom para

Relacionados