modern-python-guidance 0.1.0__tar.gz → 0.1.2__tar.gz

modern_python_guidance-0.1.2/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.2] — 2026-05-26
+
+### Changed
+
+- SKILL.md: replace inventory tables with 9 embedded BAD→GOOD arrow-list patterns (high-frequency × Ruff-uncovered) for pre-generation injection without MCP tool calls
+- README: Quick start example changed from `use-builtin-generics` to `pydantic-v2-validators` (Layer 2 differentiation)
+
+### Added
+
+- MIT license (dual-licensed under Apache-2.0 OR MIT)
+- `test_skill_sync.py`: 8 sync tests for SKILL.md ↔ guide file consistency (V-001/V-002/V-009/V-010)
+
+## [0.1.1] — 2026-05-25
+
+### Added
+
+- Built-in MCP server (`mpg mcp`) exposing all 4 commands as tools over JSON-RPC 2.0 stdio transport — zero additional dependencies
+- Setup: `claude mcp add mpg -- mpg mcp` for Claude Code, or add to `.mcp.json` manually
+- 4 MCP tools: `search_guides`, `retrieve_guides`, `list_guides`, `detect_python_version`
+- CWD confinement for `detect_python_version` (rejects absolute paths, traversal, symlink escape)
+- Resilient message parsing: malformed messages are skipped instead of crashing the server
+- JSON-RPC 2.0 notification compliance (no response for messages without `id`)
+- 19 subprocess-based integration tests for MCP server
+
+## [0.1.0] — 2026-05-24
+
+Initial release.
+
+### Added
+
+- CLI tool with `search`, `retrieve`, `list`, and `detect-version` commands
+- `mpg` short alias (both `mpg` and `modern-python-guidance` work)
+- 30 version-aware BAD/GOOD pattern guides across 3 layers: stdlib (16), frameworks (9), toolchain (5)
+- Weighted keyword search with fuzzy fallback via `difflib.SequenceMatcher`
+- Python version auto-detection from `pyproject.toml`, `.python-version`, or `--python-version` flag
+- JSON output (default when piped) and human-readable output (default for TTY)
+- Agent Skills plugin (`SKILL.md`) for Claude Code integration
+- Strict YAML-subset frontmatter parser (no PyYAML dependency)
+- GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
+
+[0.1.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.2
+[0.1.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.1
+[0.1.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.0

modern_python_guidance-0.1.2/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iori Yoshida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.2}/PKG-INFO

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.1.0
+Version: 0.1.2
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Issues, https://github.com/yottayoshida/modern-python-guidance/issues
 Author-email: Iori Yoshida <i.yoshida@raksul.com>
-License-Expression: Apache-2.0
+License-Expression: Apache-2.0 OR MIT
 License-File: LICENSE
+License-File: LICENSE-MIT
 Keywords: ai,coding-agent,guidance,linter,modernization,python
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -45,17 +47,17 @@ LLMs often produce outdated Python — `typing.List` instead of `list`, `@valida
 pip install modern-python-guidance
 
 # Search for a pattern
-mpg search "typing list"
-#   use-builtin-generics                     score=18.0  [typing]
+mpg search "pydantic validator"
+#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
-mpg retrieve use-builtin-generics
-# --- use-builtin-generics (version match: YES) ---
+mpg retrieve pydantic-v2-validators
+# --- pydantic-v2-validators (version match: YES) ---
 # ## BAD
-# from typing import List, Dict, Optional
+# @validator("name")
 # ...
 # ## GOOD
-# names: list[str] = []
+# @field_validator("name")
 # ...
 ```
 
@@ -110,6 +112,40 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
+## MCP server
+
+mpg includes a built-in [MCP](https://modelcontextprotocol.io) server that exposes all 4 commands as tools. AI agents (Claude Code, Cursor, Gemini CLI, etc.) can discover and call them directly.
+
+### Setup with Claude Code
+
+```bash
+claude mcp add mpg -- mpg mcp
+```
+
+Or add to `.mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "mpg": {
+      "command": "mpg",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `search_guides` | Search guides by keyword with fuzzy matching |
+| `retrieve_guides` | Get full BAD/GOOD content by guide ID |
+| `list_guides` | Browse all guides, filter by category/version |
+| `detect_python_version` | Auto-detect project Python version |
+
+The MCP server uses stdio transport (JSON-RPC 2.0) and adds zero additional dependencies.
+
 ## Agent Skills integration
 
 This project doubles as a [Claude Code Agent Skills](https://docs.anthropic.com/en/docs/claude-code) plugin. Install it into your project's `.claude/skills/` to give Claude automatic access to modern Python patterns when writing or reviewing code.
@@ -139,7 +175,8 @@ ruff check src/ tests/
 
 ```
 src/modern_python_guidance/
-├── cli.py              # Entry point (search, retrieve, list, detect-version)
+├── cli.py              # Entry point (search, retrieve, list, detect-version, mcp)
+├── mcp_server.py       # MCP server (JSON-RPC 2.0 over stdio)
 ├── frontmatter.py      # YAML-subset parser (no PyYAML dependency)
 ├── guide_index.py      # Guide discovery and indexing
 ├── search.py           # Weighted keyword search + fuzzy fallback
@@ -177,4 +214,4 @@ Contributions welcome! To add a new guide:
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.2}/README.md

@@ -16,17 +16,17 @@ LLMs often produce outdated Python — `typing.List` instead of `list`, `@valida
 pip install modern-python-guidance
 
 # Search for a pattern
-mpg search "typing list"
-#   use-builtin-generics                     score=18.0  [typing]
+mpg search "pydantic validator"
+#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
-mpg retrieve use-builtin-generics
-# --- use-builtin-generics (version match: YES) ---
+mpg retrieve pydantic-v2-validators
+# --- pydantic-v2-validators (version match: YES) ---
 # ## BAD
-# from typing import List, Dict, Optional
+# @validator("name")
 # ...
 # ## GOOD
-# names: list[str] = []
+# @field_validator("name")
 # ...
 ```
 
@@ -81,6 +81,40 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
+## MCP server
+
+mpg includes a built-in [MCP](https://modelcontextprotocol.io) server that exposes all 4 commands as tools. AI agents (Claude Code, Cursor, Gemini CLI, etc.) can discover and call them directly.
+
+### Setup with Claude Code
+
+```bash
+claude mcp add mpg -- mpg mcp
+```
+
+Or add to `.mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "mpg": {
+      "command": "mpg",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `search_guides` | Search guides by keyword with fuzzy matching |
+| `retrieve_guides` | Get full BAD/GOOD content by guide ID |
+| `list_guides` | Browse all guides, filter by category/version |
+| `detect_python_version` | Auto-detect project Python version |
+
+The MCP server uses stdio transport (JSON-RPC 2.0) and adds zero additional dependencies.
+
 ## Agent Skills integration
 
 This project doubles as a [Claude Code Agent Skills](https://docs.anthropic.com/en/docs/claude-code) plugin. Install it into your project's `.claude/skills/` to give Claude automatic access to modern Python patterns when writing or reviewing code.
@@ -110,7 +144,8 @@ ruff check src/ tests/
 
 ```
 src/modern_python_guidance/
-├── cli.py              # Entry point (search, retrieve, list, detect-version)
+├── cli.py              # Entry point (search, retrieve, list, detect-version, mcp)
+├── mcp_server.py       # MCP server (JSON-RPC 2.0 over stdio)
 ├── frontmatter.py      # YAML-subset parser (no PyYAML dependency)
 ├── guide_index.py      # Guide discovery and indexing
 ├── search.py           # Weighted keyword search + fuzzy fallback
@@ -148,4 +183,4 @@ Contributions welcome! To add a new guide:
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.2}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.1.0"
+version = "0.1.2"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
-license = "Apache-2.0"
+license = "Apache-2.0 OR MIT"
 requires-python = ">=3.11"
 authors = [
     { name = "Iori Yoshida", email = "i.yoshida@raksul.com" },
@@ -18,6 +18,7 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
+    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",

modern_python_guidance-0.1.2/skills/modern-python-guidance/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: modern-python-guidance
+description: Version-aware BAD/GOOD pattern guides for modern Python. Use when writing, reviewing, or refactoring Python code to avoid outdated patterns (e.g. typing.List → list, @validator → @field_validator, setup.py → pyproject.toml). Triggers on "Python", "modernize", "upgrade", "deprecated", "pydantic", "fastapi", "httpx", "typing", "dataclass", "asyncio".
+---
+
+# Modern Python Guidance
+
+Pre-generation design patterns that Ruff cannot auto-fix. Apply these transformations when writing or reviewing Python code.
+
+## When to use
+
+- Writing new Python code (use modern patterns from the start)
+- Reviewing Python code (flag outdated patterns)
+- Migrating from Pydantic V1 to V2
+- Upgrading Python version (check which new features are available)
+- Replacing legacy tooling (setup.py, flake8, pip)
+
+## Embedded patterns (high-frequency, Ruff-uncovered)
+
+### Pydantic V2 (>=3.9)
+
+- `@validator("f")` → `@field_validator("f")`
+- `@root_validator` → `@model_validator(mode="after")`
+- `class Config:` → `model_config = ConfigDict(...)`
+- `orm_mode` → `from_attributes`, `allow_population_by_field_name` → `populate_by_name`
+- `.parse_obj(d)` → `.model_validate(d)`, `.parse_raw(j)` → `.model_validate_json(j)`
+- `.dict()` → `.model_dump()`, `.json()` → `.model_dump_json()`
+- `.schema()` → `.model_json_schema()`, `.copy()` → `.model_copy()`
+
+### FastAPI (>=3.9)
+
+- `@app.on_event("startup")`/`"shutdown"` → `@asynccontextmanager` lifespan + `FastAPI(lifespan=lifespan)`; yield dict becomes `request.state`
+- `db: Session = Depends(get_db)` → `DbDep = Annotated[Session, Depends(get_db)]`; reusable type alias per PEP 593
+
+### httpx
+
+- Per-request `async with httpx.AsyncClient()` → shared `AsyncClient` with `base_url`
+  - Caveat: shared client must be closed via `async with` or lifespan management
+
+### asyncio (>=3.11)
+
+- `await asyncio.gather(a(), b())` → `async with asyncio.TaskGroup() as tg:` + `tg.create_task()`; access results via `task.result()`
+  - Caveat: 3.11+ only. `TaskGroup` cancels siblings on error and raises `ExceptionGroup`; `gather` preserves return order and supports `return_exceptions=True`
+
+### Toolchain
+
+- `setup.py` / `setup.cfg` → `pyproject.toml` with `[build-system]` + `[project]` (PEP 621)
+- `subprocess.run(f"cmd {arg}", shell=True)` → `subprocess.run(["cmd", arg], check=True)`
+  - Caveat: `shell=True` is valid when pipes/globs are needed; use `shlex.quote()` for user input
+
+## All 30 guides by category
+
+- **typing** (6): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`
+- **async** (3): `taskgroup-over-gather`, `exception-groups`, `async-timeout-context`
+- **stdlib** (4): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`
+- **data-structures** (3): `dict-merge-operator`, `match-case-patterns`, `dataclass-modern`
+- **pydantic** (4): `pydantic-v2-validators`, `pydantic-v2-config`, `pydantic-v2-model-api`, `pydantic-v2-serialization`
+- **fastapi** (3): `fastapi-lifespan`, `fastapi-annotated-depends`, `fastapi-typed-state`
+- **httpx** (2): `httpx-async-client-reuse`, `httpx-streaming`
+- **toolchain** (5): `pyproject-toml-over-setup`, `uv-over-pip`, `ruff-over-flake8`, `no-pickle`, `safe-subprocess`
+
+For full code examples, use `mpg retrieve <guide-id>` or MCP tool `retrieve_guides`.

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.2}/src/modern_python_guidance/__init__.py

@@ -1,3 +1,3 @@
 """Modern Python Guidance — version-aware BAD/GOOD pattern guides for AI coding agents."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.2}/src/modern_python_guidance/cli.py

@@ -62,6 +62,9 @@ def main(argv: list[str] | None = None) -> None:
     p_detect = subparsers.add_parser("detect-version", help="Detect project Python version")
     p_detect.add_argument("--project-dir", type=Path, help="Project directory (default: cwd)")
 
+    # mcp
+    subparsers.add_parser("mcp", help="Start MCP server (JSON-RPC over stdio)")
+
     args = parser.parse_args(argv)
 
     if args.command is None:
@@ -81,6 +84,8 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_list(args)
         elif args.command == "detect-version":
             _cmd_detect_version(args)
+        elif args.command == "mcp":
+            _cmd_mcp()
     except BrokenPipeError:
         sys.exit(0)
 
@@ -200,3 +205,9 @@ def _cmd_list(args: argparse.Namespace) -> None:
 def _cmd_detect_version(args: argparse.Namespace) -> None:
     version = detect_version(project_dir=args.project_dir)
     print(version)
+
+
+def _cmd_mcp() -> None:
+    from modern_python_guidance.mcp_server import serve
+
+    serve()