modern-python-guidance 0.3.0__tar.gz → 0.3.1__tar.gz

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/CHANGELOG.md

@@ -2,8 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1] — 2026-05-29
+
+### Added
+
+- `mpg uninstall` command: reverses `mpg setup` by deregistering the MCP server and removing the Agent Skills symlink in one command (closes #63)
+- CLI flags: `--mcp-only`, `--skills-only`, `--project-dir`, `--dry-run` (no `--scope`; uninstall clears every scope `setup` can write to)
+- Per-scope MCP deregistration (`claude mcp remove -s local` and `-s user`): a live probe showed `claude mcp remove` without a scope removes nothing when the server is registered in multiple scopes, so uninstall enumerates scopes explicitly to avoid leaving residue
+- Symlink-only removal safety: only the symlink mpg created is removed (never its target), a non-symlink entity at the link path is refused, dangling symlinks are removed, and the parent `.claude/skills/` directory is preserved
+- 26 new tests (V-015 through V-031)
+
+### Changed
+
+- Extracted shared `_skills_link_path` helper in `setup_cmd` so `setup` and `uninstall` resolve the Skills symlink location identically (no drift)
+
 ## [0.3.0] — 2026-05-28
 
+### Added
+
+- `mpg setup` command: one-command MCP server registration + Agent Skills symlink creation. Replaces 3-4 manual steps with `pip install modern-python-guidance && mpg setup` (closes #60)
+- CLI flags: `--mcp-only`, `--skills-only`, `--scope {user,local}`, `--project-dir`, `--dry-run`
+- Project root auto-detection (`.claude/` → `.git/` → `pyproject.toml` upward search) for correct Skills symlink placement from subdirectories
+- Idempotent operation: re-running `mpg setup` skips already-correct state, replaces stale/broken symlinks, errors on non-symlink blockers
+- Partial success handling: MCP and Skills run independently; one failure does not block the other
+- 33 new tests for setup command (V-001 through V-014 verification points)
+
+### Changed
+
+- README Quick Start: reduced from 3 code blocks to 2 lines (`pip install` + `mpg setup`). Manual setup moved to collapsible `<details>` section
+
+## [0.2.3] — 2026-05-28
+
+### Fixed
+
+- `fastapi-typed-state` guide: added missing Version Notes section (closes #13)
+- `fastapi-typed-state` and `fastapi-lifespan` guides: corrected minimum version from FastAPI >= 0.93.0 to >= 0.94.0 (lifespan state dict requires Starlette >= 0.26.0, which FastAPI 0.93.0 excludes)
+
+## [0.2.2] — 2026-05-28
+
 ### Changed
 
 - Search response (MCP + CLI) now includes `tags`, `python`, `frequency`, and `snippet` fields for richer agent decision-making without requiring a follow-up retrieve call
@@ -82,6 +118,8 @@ Initial release.
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
 [0.3.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.0
+[0.2.3]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.3
+[0.2.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.2
 [0.2.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.1
 [0.2.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.0
 [0.1.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.2

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -50,15 +50,29 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 versio
 
 ## Quick start
 
-### MCP (for AI coding agents)
+### Claude Code (recommended)
 
-Install, then register the MCP server with your agent:
+```bash
+pip install modern-python-guidance
+mpg setup
+```
+
+This registers the MCP server and links Agent Skills in one command. Start a new Claude Code session afterwards — newly registered MCP servers and skills take effect on the next launch.
+
+### CLI
 
 ```bash
 pip install modern-python-guidance
+mpg search "pydantic validator"
+mpg retrieve pydantic-v2-validators
 ```
 
-**Claude Code:**
+`mpg` is the short alias for `modern-python-guidance`. Both work.
+
+<details>
+<summary>Manual setup / other agents</summary>
+
+**MCP registration (Claude Code):**
 ```bash
 claude mcp add mpg -- mpg mcp
 ```
@@ -75,29 +89,36 @@ claude mcp add mpg -- mpg mcp
 }
 ```
 
-Your agent gets access to `search_guides`, `retrieve_guides`, `list_guides`, and `detect_python_version`.
-
-### CLI
-
+**Agent Skills symlink (Claude Code):**
 ```bash
-pip install modern-python-guidance
-
-# Search for a pattern
-mpg search "pydantic validator"
-
-# Get the full guide
-mpg retrieve pydantic-v2-validators
+mpg setup --skills-only
 ```
 
-### Agent Skills (Claude Code plugin)
+**`mpg setup` flags:**
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP registration only |
+| `--skills-only` | Agent Skills symlink only |
+| `--scope {user,local}` | MCP scope (default: user) |
+| `--project-dir PATH` | Target project for Skills symlink |
+| `--dry-run` | Show what would be done |
 
+**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills):
 ```bash
-# Symlink into your project
-SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
-ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
+mpg uninstall            # remove both
+mpg uninstall --dry-run  # preview what would be removed
 ```
 
-`mpg` is the short alias for `modern-python-guidance`. Both work.
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP deregistration only |
+| `--skills-only` | Agent Skills unlink only |
+| `--project-dir PATH` | Target project for the Skills symlink |
+| `--dry-run` | Show what would be done |
+
+`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlink mpg created (never its target or other skills), and is idempotent — running it on an already-clean state is a harmless no-op.
+
+</details>
 
 ## CLI usage
 

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/README.md

@@ -19,15 +19,29 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 versio
 
 ## Quick start
 
-### MCP (for AI coding agents)
+### Claude Code (recommended)
 
-Install, then register the MCP server with your agent:
+```bash
+pip install modern-python-guidance
+mpg setup
+```
+
+This registers the MCP server and links Agent Skills in one command. Start a new Claude Code session afterwards — newly registered MCP servers and skills take effect on the next launch.
+
+### CLI
 
 ```bash
 pip install modern-python-guidance
+mpg search "pydantic validator"
+mpg retrieve pydantic-v2-validators
 ```
 
-**Claude Code:**
+`mpg` is the short alias for `modern-python-guidance`. Both work.
+
+<details>
+<summary>Manual setup / other agents</summary>
+
+**MCP registration (Claude Code):**
 ```bash
 claude mcp add mpg -- mpg mcp
 ```
@@ -44,29 +58,36 @@ claude mcp add mpg -- mpg mcp
 }
 ```
 
-Your agent gets access to `search_guides`, `retrieve_guides`, `list_guides`, and `detect_python_version`.
-
-### CLI
-
+**Agent Skills symlink (Claude Code):**
 ```bash
-pip install modern-python-guidance
-
-# Search for a pattern
-mpg search "pydantic validator"
-
-# Get the full guide
-mpg retrieve pydantic-v2-validators
+mpg setup --skills-only
 ```
 
-### Agent Skills (Claude Code plugin)
+**`mpg setup` flags:**
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP registration only |
+| `--skills-only` | Agent Skills symlink only |
+| `--scope {user,local}` | MCP scope (default: user) |
+| `--project-dir PATH` | Target project for Skills symlink |
+| `--dry-run` | Show what would be done |
 
+**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills):
 ```bash
-# Symlink into your project
-SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
-ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
+mpg uninstall            # remove both
+mpg uninstall --dry-run  # preview what would be removed
 ```
 
-`mpg` is the short alias for `modern-python-guidance`. Both work.
+| Flag | Purpose |
+|------|---------|
+| `--mcp-only` | MCP deregistration only |
+| `--skills-only` | Agent Skills unlink only |
+| `--project-dir PATH` | Target project for the Skills symlink |
+| `--dry-run` | Show what would be done |
+
+`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlink mpg created (never its target or other skills), and is idempotent — running it on an already-clean state is a harmless no-op.
+
+</details>
 
 ## CLI usage
 

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.0"
+version = "0.3.1"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/skills/modern-python-guidance/guides/fastapi/fastapi-lifespan.md

@@ -68,7 +68,7 @@ async def root(request: Request):
 
 ## Version Notes
 
-- Works on Python 3.9+ with FastAPI >= 0.93.0
+- Works on Python 3.9+ with FastAPI >= 0.94.0 (lifespan state dict requires Starlette >= 0.26.0)
 - `AsyncIterator` moved from `typing` to `collections.abc` in 3.9
 
 ## References

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/skills/modern-python-guidance/guides/fastapi/fastapi-typed-state.md

@@ -70,6 +70,11 @@ async def root(request: Request):
 - `dataclass` or `TypedDict` documents the expected shape
 - Resource cleanup is guaranteed by the context manager
 
+## Version Notes
+
+- Lifespan state dict requires FastAPI >= 0.94.0 (Starlette >= 0.26.0)
+- `@dataclass(slots=True)` requires Python 3.10+; use plain `@dataclass` on 3.9
+
 ## References
 
 - [FastAPI Lifespan State](https://fastapi.tiangolo.com/advanced/events/#lifespan-state)

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/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.2.0"
+__version__ = "0.3.1"

{modern_python_guidance-0.3.0 → modern_python_guidance-0.3.1}/src/modern_python_guidance/cli.py

@@ -65,6 +65,32 @@ def main(argv: list[str] | None = None) -> None:
     # mcp
     subparsers.add_parser("mcp", help="Start MCP server (JSON-RPC over stdio)")
 
+    # setup
+    p_setup = subparsers.add_parser(
+        "setup", help="Register MCP server and link Agent Skills",
+    )
+    p_setup.add_argument("--mcp-only", action="store_true", help="MCP registration only")
+    p_setup.add_argument("--skills-only", action="store_true", help="Skills symlink only")
+    p_setup.add_argument(
+        "--scope", choices=["user", "local"], default="user",
+        help="MCP scope (default: user)",
+    )
+    p_setup.add_argument(
+        "--project-dir", type=Path, help="Project directory for Skills symlink",
+    )
+    p_setup.add_argument("--dry-run", action="store_true", help="Show what would be done")
+
+    # uninstall
+    p_uninstall = subparsers.add_parser(
+        "uninstall", help="Reverse 'setup': deregister MCP server and unlink Agent Skills",
+    )
+    p_uninstall.add_argument("--mcp-only", action="store_true", help="MCP deregistration only")
+    p_uninstall.add_argument("--skills-only", action="store_true", help="Skills unlink only")
+    p_uninstall.add_argument(
+        "--project-dir", type=Path, help="Project directory for Skills symlink",
+    )
+    p_uninstall.add_argument("--dry-run", action="store_true", help="Show what would be done")
+
     args = parser.parse_args(argv)
 
     if args.command is None:
@@ -86,6 +112,10 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_detect_version(args)
         elif args.command == "mcp":
             _cmd_mcp()
+        elif args.command == "setup":
+            _cmd_setup(args)
+        elif args.command == "uninstall":
+            _cmd_uninstall(args)
     except BrokenPipeError:
         sys.exit(0)
 
@@ -215,3 +245,28 @@ def _cmd_mcp() -> None:
     from modern_python_guidance.mcp_server import serve
 
     serve()
+
+
+def _cmd_setup(args: argparse.Namespace) -> None:
+    from modern_python_guidance.setup_cmd import run_setup
+
+    code = run_setup(
+        scope=args.scope,
+        mcp_only=args.mcp_only,
+        skills_only=args.skills_only,
+        project_dir=args.project_dir,
+        dry_run=args.dry_run,
+    )
+    sys.exit(code)
+
+
+def _cmd_uninstall(args: argparse.Namespace) -> None:
+    from modern_python_guidance.uninstall_cmd import run_uninstall
+
+    code = run_uninstall(
+        mcp_only=args.mcp_only,
+        skills_only=args.skills_only,
+        project_dir=args.project_dir,
+        dry_run=args.dry_run,
+    )
+    sys.exit(code)

modern_python_guidance-0.3.1/src/modern_python_guidance/setup_cmd.py

@@ -0,0 +1,186 @@
+"""Automate MCP server registration and Agent Skills symlink creation."""
+
+from __future__ import annotations
+
+import importlib.resources
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SKILLS_LINK_NAME = "modern-python-guidance"
+MCP_SERVER_NAME = "mpg"
+
+
+def _find_skills_dir() -> Path:
+    """Resolve the bundled skills directory (package install or editable)."""
+    try:
+        pkg = importlib.resources.files("modern_python_guidance") / "skills"
+        skills_path = Path(str(pkg)) / SKILLS_LINK_NAME
+        if skills_path.is_dir():
+            return skills_path
+    except (TypeError, FileNotFoundError):
+        pass
+
+    src_root = Path(__file__).resolve().parent.parent.parent
+    dev_path = src_root / "skills" / SKILLS_LINK_NAME
+    if dev_path.is_dir():
+        return dev_path
+
+    msg = "Cannot locate bundled skills directory"
+    raise FileNotFoundError(msg)
+
+
+def _find_project_root(start: Path | None = None) -> Path:
+    """Walk upward from *start* to find the project root."""
+    current = (start or Path.cwd()).resolve()
+    markers = [".claude", ".git", "pyproject.toml"]
+
+    for marker in markers:
+        d = current
+        while True:
+            candidate = d / marker
+            if candidate.exists():
+                return d
+            parent = d.parent
+            if parent == d:
+                break
+            d = parent
+
+    return current
+
+
+def _skills_link_path(project_dir: Path | None = None) -> Path:
+    """Resolve the Agent Skills symlink path: ``<root>/.claude/skills/<name>``.
+
+    Single source of truth for where the skills symlink lives, shared by
+    ``setup_skills`` (creation) and ``uninstall_skills`` (removal) so the two
+    operations cannot drift in how they locate the link.
+    """
+    root = project_dir or _find_project_root()
+    return root / ".claude" / "skills" / SKILLS_LINK_NAME
+
+
+def setup_mcp(
+    *,
+    scope: str = "user",
+    dry_run: bool = False,
+) -> bool:
+    """Register the MCP server with Claude Code. Returns True on success."""
+    args = ["mcp", "add", "--scope", scope, MCP_SERVER_NAME, "--", "mpg", "mcp"]
+
+    if dry_run:
+        print(f"Would run: claude {' '.join(args)}")
+        return True
+
+    claude = shutil.which("claude")
+    if claude is None:
+        print("Error: 'claude' command not found.", file=sys.stderr)
+        print("Install Claude Code: https://claude.ai/download", file=sys.stderr)
+        print(
+            "Run 'mpg setup --skills-only' to set up Agent Skills without MCP.",
+            file=sys.stderr,
+        )
+        return False
+
+    cmd = [claude, *args]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, timeout=30)
+    except subprocess.TimeoutExpired:
+        print("Error: 'claude mcp add' timed out after 30 seconds.", file=sys.stderr)
+        return False
+
+    if result.returncode != 0:
+        stderr_text = result.stderr.decode(errors="replace").strip()
+        print(f"Error: 'claude mcp add' failed (exit {result.returncode}).", file=sys.stderr)
+        if stderr_text:
+            print(stderr_text, file=sys.stderr)
+        return False
+
+    print(f"MCP server registered with Claude Code ({scope} scope).")
+    return True
+
+
+def setup_skills(
+    *,
+    project_dir: Path | None = None,
+    dry_run: bool = False,
+) -> bool:
+    """Create Agent Skills symlink. Returns True on success."""
+    try:
+        source = _find_skills_dir()
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return False
+
+    root = project_dir or _find_project_root()
+    link_path = _skills_link_path(project_dir)
+    skills_parent = link_path.parent
+
+    if dry_run:
+        print(f"Would link: {link_path} -> {source}")
+        return True
+
+    if link_path.is_symlink():
+        current_target = Path(os.readlink(link_path))
+        if current_target == source or link_path.resolve() == source.resolve():
+            print(f"Agent Skills already linked at {link_path.relative_to(root)}")
+            return True
+        # Stale or broken symlink — replace
+        link_path.unlink()
+    elif link_path.exists():
+        print(
+            f"Error: {link_path.relative_to(root)} exists and is not a symlink.",
+            file=sys.stderr,
+        )
+        print(
+            f"Remove it manually: rm -rf {shlex.quote(str(link_path))}",
+            file=sys.stderr,
+        )
+        return False
+
+    try:
+        skills_parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(source, link_path)
+    except OSError as e:
+        print(f"Error creating symlink: {e}", file=sys.stderr)
+        return False
+
+    print(f"Agent Skills linked to {link_path.relative_to(root)}")
+    return True
+
+
+def run_setup(
+    *,
+    scope: str = "user",
+    mcp_only: bool = False,
+    skills_only: bool = False,
+    project_dir: Path | None = None,
+    dry_run: bool = False,
+) -> int:
+    """Run the full setup sequence. Returns exit code (0=success, 1=failure)."""
+    if mcp_only and skills_only:
+        print("Error: --mcp-only and --skills-only are mutually exclusive.", file=sys.stderr)
+        return 1
+
+    do_mcp = not skills_only
+    do_skills = not mcp_only
+
+    mcp_ok = True
+    skills_ok = True
+
+    if do_mcp:
+        mcp_ok = setup_mcp(scope=scope, dry_run=dry_run)
+
+    if do_skills:
+        skills_ok = setup_skills(project_dir=project_dir, dry_run=dry_run)
+
+    if mcp_ok and skills_ok:
+        if not dry_run and do_mcp and do_skills:
+            print("Ready. Start Claude Code to use mpg guides.")
+        return 0
+
+    return 1