python-mcp-bootstrap 0.1.3__py3-none-any.whl

python_mcp_bootstrap/__init__.py

@@ -0,0 +1,58 @@
+"""Shared, stdlib-only bootstrap for Python MCP applications."""
+
+from __future__ import annotations
+
+from .core import (
+    CARD,
+    PIN,
+    PIN_FILE,
+    PYTHON_DIR,
+    REPAIR_CARD,
+    REQUIRED,
+    UV_INSTALL,
+    VENV_DIR,
+    BootstrapSpec,
+    Exec,
+    Main,
+    Probe,
+    Runner,
+    bootstrap,
+    find_uv,
+    floor_text,
+    format_version,
+    interpreter_version,
+    provision,
+    required_text,
+    run_command,
+    venv_python,
+    version_tuple,
+)
+
+__version__ = "0.1.3"
+
+__all__ = [
+    "CARD",
+    "PIN",
+    "PIN_FILE",
+    "PYTHON_DIR",
+    "REPAIR_CARD",
+    "REQUIRED",
+    "UV_INSTALL",
+    "VENV_DIR",
+    "BootstrapSpec",
+    "Exec",
+    "Main",
+    "Probe",
+    "Runner",
+    "__version__",
+    "bootstrap",
+    "find_uv",
+    "floor_text",
+    "format_version",
+    "interpreter_version",
+    "provision",
+    "required_text",
+    "run_command",
+    "venv_python",
+    "version_tuple",
+]

python_mcp_bootstrap/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m python_mcp_bootstrap``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python_mcp_bootstrap/cli.py

@@ -0,0 +1,57 @@
+"""Command-line diagnostics for the bootstrap contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .core import PIN, REQUIRED, find_uv, required_text
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python-mcp-bootstrap",
+        description="Inspect the pre-install Python bootstrap contract.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="print the bootstrap pin and current selection facts as JSON",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the diagnostic CLI.
+
+    This command is intentionally diagnostic: it never invokes uv, pip, or a
+    subprocess. Application first-run wrappers call the library API instead.
+    """
+
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if not args.check:
+        parser.print_help()
+        return 2
+
+    payload = {
+        "ok": True,
+        "version": __version__,
+        "required": f">={required_text(REQUIRED)}",
+        "pin": PIN,
+        "uv": find_uv(),
+    }
+    json.dump(payload, sys.stdout, indent=2, sort_keys=True)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python_mcp_bootstrap/core.py

@@ -0,0 +1,729 @@
+"""Core contract for the pre-install Python bootstrap.
+
+This module is deliberately stdlib-only and importable on Python 3.12.  The
+package metadata requires 3.14, but consumers copy this file into a first-run
+entry point that may execute before the application's dependencies exist.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path, PureWindowsPath
+from typing import Any
+
+Version = tuple[int, int, int]
+Main = Callable[[list[str]], int]
+Runner = Callable[[list[str], Path, dict[str, str], int], dict[str, Any]]
+Probe = Callable[[str], Version | None]
+Exec = Callable[[str, list[str], dict[str, str]], int | None]
+
+REQUIRED: Version = (3, 14, 0)
+PIN = "3.15.2"
+VENV_DIR = ".venv"
+PYTHON_DIR = ".uv-python"
+PIN_FILE = ".python-version"
+UV_INSTALL = (
+    "uv is not installed. Install it from the official instructions, then "
+    "re-run with --install-python: "
+    "https://docs.astral.sh/uv/getting-started/installation/"
+)
+CARD_TEMPLATE = (
+    "Set up needs a project-local Python {pin} on this computer (one-time "
+    "download). Your system Python is not changed; a mismatched .venv is "
+    "moved aside. Continue?"
+)
+CARD = CARD_TEMPLATE.format(pin=PIN)
+REPAIR_CARD = (
+    "The project environment is missing the app or MCP. Re-run with "
+    "--install-python to repair it. Nothing has been downloaded. Continue?"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class BootstrapSpec:
+    """Application-specific settings for one bootstrap entry point."""
+
+    app: str
+    entrypoint: str = "first_run.py"
+    env_var: str = "MCP_BOOTSTRAP_INTERPRETER"
+    package_main: Main | None = None
+    required: Version = REQUIRED
+    pin: str = PIN
+    install_args: tuple[str, ...] = ("-e", ".")
+    verify_import: str | None = None
+    card: str = CARD
+    venv_dir: str = VENV_DIR
+    python_dir: str = PYTHON_DIR
+    pin_file: str = PIN_FILE
+    uv_install: str = UV_INSTALL
+    repair_card: str = REPAIR_CARD
+
+    def __post_init__(self) -> None:
+        if not self.app.strip():
+            raise ValueError("app must not be empty")
+        if not self.entrypoint.strip():
+            raise ValueError("entrypoint must not be empty")
+        if not self.env_var.strip():
+            raise ValueError("env_var must not be empty")
+        if not self.venv_dir.strip() or not self.python_dir.strip() or not self.pin_file.strip():
+            raise ValueError("venv_dir, python_dir, and pin_file must not be empty")
+        for field, value in (
+            ("entrypoint", self.entrypoint),
+            ("venv_dir", self.venv_dir),
+            ("python_dir", self.python_dir),
+            ("pin_file", self.pin_file),
+        ):
+            _require_project_path(field, value)
+        if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", self.env_var) is None:
+            raise ValueError(f"env_var is not a valid environment name: {self.env_var!r}")
+        if len(self.required) != 3 or any(not isinstance(part, int) for part in self.required):
+            raise ValueError(f"required is not a version: {self.required!r}")
+        if re.fullmatch(r"\d+(?:\.\d+){0,2}", self.pin) is None:
+            raise ValueError(f"pin must be a plain version: {self.pin!r}")
+        pin_version = version_tuple(self.pin)
+        if pin_version is None:
+            raise ValueError(f"pin is not a version: {self.pin!r}")
+        if pin_version < self.required:
+            raise ValueError(f"pin {self.pin!r} is older than required {self.required!r}")
+        if self.verify_import is not None and not _valid_module(self.verify_import):
+            raise ValueError(f"verify_import is not a module: {self.verify_import!r}")
+        _require_project_install_args(self.install_args)
+        if not self.repair_card.strip():
+            raise ValueError("repair_card must not be empty")
+        if self.card == CARD and self.pin != PIN:
+            object.__setattr__(self, "card", CARD_TEMPLATE.format(pin=self.pin))
+
+
+def _valid_module(value: str) -> bool:
+    parts = value.split(".")
+    return bool(parts) and all(part.isidentifier() for part in parts)
+
+
+def _escapes_project(value: str) -> bool:
+    """True when ``value`` names a path outside the project root.
+
+    ``PureWindowsPath`` is checked on every platform: a Unix-style rooted
+    path such as ``/etc/passwd`` is not absolute on Windows and would
+    otherwise pass ``Path.is_absolute()``.
+    """
+
+    posix = Path(value)
+    windows = PureWindowsPath(value)
+    return (
+        posix.is_absolute()
+        or windows.is_absolute()
+        or bool(windows.root)
+        or ".." in posix.parts
+        or ".." in windows.parts
+    )
+
+
+def _require_project_path(field: str, value: str) -> None:
+    if _escapes_project(value):
+        raise ValueError(f"{field} must stay inside the project: {value!r}")
+
+
+_RESERVED_LONG_FLAGS = frozenset({"--target", "--prefix", "--root", "--python"})
+_RESERVED_SHORT_FLAGS = frozenset({"t", "p"})
+_VALUE_SHORT_FLAGS = frozenset({"e", "r", "c", "f", "i", "C"})
+
+
+def _short_flag_problem(value: str) -> bool:
+    """True when a short token redirects the install or embeds a path.
+
+    A cluster such as ``-vt/tmp`` means ``-v -t /tmp``, so checking only the
+    first letter is not enough.  Walk the cluster until a value-taking option.
+    """
+
+    cluster = value[1:]
+    if "://" not in value and ("/" in cluster or "\\" in cluster or ".." in cluster):
+        return True
+    for char in cluster:
+        if char in _RESERVED_SHORT_FLAGS:
+            return True
+        if char in _VALUE_SHORT_FLAGS:
+            return False
+    return False
+
+
+def _require_project_install_args(values: object) -> None:
+    """Keep consumer-supplied install arguments inside the project.
+
+    A bare flag is passed through, but a path-like value is rejected whether
+    it is a separate entry (``-e ../app``), embedded in a long flag
+    (``--find-links=/tmp/wheels``), or attached to a short flag (``-t/tmp``).
+    Flags that redirect the install away from the project venv
+    (``--target``, ``--prefix``, ``--root``, ``--python`` and their short
+    forms) are rejected.  Non-path flags such as ``--index-url=...`` are left
+    alone; credentials in them are redacted before reporting.
+    """
+
+    if isinstance(values, str) or not isinstance(values, (tuple, list)):
+        raise ValueError(f"install_args must be a sequence of strings: {values!r}")
+    for value in values:
+        if not isinstance(value, str):
+            raise ValueError(f"install_args must be strings: {value!r}")
+        if value.startswith("-"):
+            if value.startswith("--"):
+                name = value.split("=", 1)[0]
+                if name in _RESERVED_LONG_FLAGS:
+                    raise ValueError(f"install_args must not redirect the install: {value!r}")
+                embedded = value.split("=")[1:]
+            else:
+                if _short_flag_problem(value):
+                    raise ValueError(
+                        f"install_args must not redirect or escape the project: {value!r}"
+                    )
+                embedded = []
+            if any(_escapes_project(part) for part in embedded):
+                raise ValueError(f"install_args must stay inside the project: {value!r}")
+            continue
+        if _escapes_project(value):
+            raise ValueError(f"install_args must stay inside the project: {value!r}")
+
+
+def version_tuple(text: object) -> Version | None:
+    """Parse ``3.15.2`` or ``Python 3.15.2`` into a three-part version.
+
+    Pre-release suffixes (``rc``, ``a``, ``b``, ``dev``) return ``None`` so a
+    release candidate never satisfies the final-release floor.  A ``.post``
+    or ``+local`` suffix is accepted as the same final version.
+    """
+
+    raw = str(text).strip()
+    if raw.casefold().startswith("python"):
+        raw = raw[6:].strip()
+    if not raw:
+        return None
+    match = re.fullmatch(r"(\d+)(?:\.(\d+))?(?:\.(\d+))?(.*)", raw)
+    if match is None:
+        return None
+    major, minor, patch, suffix = match.groups()
+    if suffix and not (suffix.startswith("+") or suffix.startswith(".post")):
+        return None
+    return (int(major), int(minor or 0), int(patch or 0))
+
+
+def format_version(found: Version) -> str:
+    """Render a parsed version as ``major.minor.patch``."""
+
+    return ".".join(str(part) for part in found)
+
+
+def required_text(required: Version = REQUIRED) -> str:
+    """Render the full floor version, including the patch component."""
+
+    return format_version(required)
+
+
+def floor_text(required: Version = REQUIRED) -> str:
+    """Render the human-facing floor, dropping a zero patch component."""
+
+    major, minor, patch = required
+    return f"{major}.{minor}" if patch == 0 else format_version(required)
+
+
+def venv_python(root: Path, venv_dir: str = VENV_DIR) -> Path:
+    """The interpreter a project-local venv writes on this platform."""
+
+    if os.name == "nt":
+        return Path(root) / venv_dir / "Scripts" / "python.exe"
+    return Path(root) / venv_dir / "bin" / "python"
+
+
+def find_uv() -> str | None:
+    """Find uv without installing or downloading anything."""
+
+    found = shutil.which("uv")
+    if found:
+        return found
+
+    home = Path.home()
+    if os.name == "nt":
+        candidates = [
+            home / ".local" / "bin" / "uv.exe",
+            home / ".cargo" / "bin" / "uv.exe",
+        ]
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            candidates.extend(
+                [
+                    Path(local) / "uv" / "uv.exe",
+                    Path(local) / "Microsoft" / "WinGet" / "Links" / "uv.exe",
+                ]
+            )
+    else:
+        candidates = [
+            home / ".local" / "bin" / "uv",
+            home / ".cargo" / "bin" / "uv",
+        ]
+
+    for candidate in candidates:
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return None
+
+
+_CREDENTIAL_URL = re.compile(r"([A-Za-z][A-Za-z0-9+.-]*://)[^/\s:@]+(?::[^/\s@]*)?@", re.IGNORECASE)
+_SECRET_FIELD = re.compile(
+    r"(?i)([\"']?\b(?:[A-Za-z0-9]+[_-])?"
+    r"(?:token|api[_-]?key|password|passwd|secret|private[_-]?key)\b[\"']?)"
+    r"(\s*[=:]\s*)"
+    r"(\"[^\"]*\"|'[^']*'|\S+)"
+)
+_BEARER_TOKEN = re.compile(r"(?i)\b(bearer\s+)[A-Za-z0-9._~+/=-]{8,}")
+
+
+def _redact(text: str) -> str:
+    """Mask credentials that a tool may echo into diagnostics.
+
+    Covers URL userinfo, ``key=value`` / ``"key": "value"`` pairs, and
+    ``Authorization: Bearer`` headers.  Over-redacting is preferred to leaking.
+    """
+
+    text = _CREDENTIAL_URL.sub(r"\1***:***@", text)
+    text = _BEARER_TOKEN.sub(r"\1***", text)
+    return _SECRET_FIELD.sub(r"\1\2***", text)
+
+
+def run_command(command: list[str], cwd: Path, env: dict[str, str], timeout: int) -> dict[str, Any]:
+    """Run one provisioning step. Never raises for a missing or slow tool."""
+
+    if not command:
+        return {"returncode": 2, "stdout": "", "stderr": "empty command"}
+
+    try:
+        done = subprocess.run(
+            command,
+            cwd=str(cwd),
+            env=env,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return {"returncode": 1, "stdout": "", "stderr": _redact(str(exc))[-2000:]}
+    return {
+        "returncode": done.returncode,
+        "stdout": _redact(done.stdout or "")[-2000:],
+        "stderr": _redact(done.stderr or "")[-2000:],
+    }
+
+
+def interpreter_version(exe: str | Path) -> Version | None:
+    """Version of another interpreter, without importing the application."""
+
+    path = Path(exe)
+    if not path.is_file():
+        return None
+    result = run_command(
+        [str(path), "-c", "import sys; print(sys.version.split()[0])"],
+        path.parent,
+        dict(os.environ),
+        30,
+    )
+    if result.get("returncode") != 0:
+        return None
+    return version_tuple(result.get("stdout", ""))
+
+
+def _move_aside(path: Path) -> Path:
+    """Keep a venv from another version or a broken run instead of deleting it."""
+
+    backup = path.with_name(path.name + ".previous")
+    index = 1
+    while backup.exists():
+        backup = path.with_name(path.name + f".previous-{index}")
+        index += 1
+    path.rename(backup)
+    return backup
+
+
+def _verify_command(python: Path, spec: BootstrapSpec) -> list[str] | None:
+    module = spec.verify_import
+    if module is None:
+        return None
+    code = f"import importlib; importlib.import_module({module!r})"
+    # ``-I`` implies ``-P`` and also drops PYTHONPATH/user site: only the target
+    # interpreter's own site-packages may satisfy the import.  Without this, a
+    # flat package at the project root imports through the cwd on sys.path, the
+    # check passes, and the repair install never runs.
+    return [str(python), "-I", "-P", "-c", code]
+
+
+def _installed(
+    python: Path,
+    spec: BootstrapSpec,
+    root: Path,
+    env: dict[str, str],
+    run: Runner,
+) -> bool:
+    command = _verify_command(python, spec)
+    if command is None:
+        return True
+    result = run(command, root, env, 60)
+    return result.get("returncode") == 0
+
+
+def _step(command: list[str], result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "command": [_redact(part) for part in command],
+        "returncode": result.get("returncode"),
+        "stderr": _redact(str(result.get("stderr", "")))[-2000:],
+    }
+
+
+def _failed(reason: str, spec: BootstrapSpec, **extra: object) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "app": spec.app,
+        "reason": reason,
+        "card": spec.card,
+    }
+    payload.update(extra)
+    return payload
+
+
+def _needs_install(python: Path, spec: BootstrapSpec, found: Version) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "installed": False,
+        "app": spec.app,
+        "reason": "needs_install",
+        "interpreter": str(python),
+        "python_version": format_version(found),
+        "required": f">={floor_text(spec.required)}",
+        "pin": spec.pin,
+        "needs_consent": True,
+        "card": spec.repair_card,
+        "next": f"python {spec.entrypoint} --install-python",
+    }
+
+
+def provision(
+    root: Path,
+    spec: BootstrapSpec,
+    *,
+    uv: str | None = None,
+    run: Runner = run_command,
+    probe: Probe = interpreter_version,
+) -> dict[str, Any]:
+    """Provision the pinned interpreter, venv, and application install.
+
+    The caller is responsible for obtaining consent first.  This function never
+    prompts and never installs uv; a missing uv is returned as ``needs_uv``.
+    """
+
+    root = Path(root)
+    uv = uv or find_uv()
+    if not uv:
+        return _failed("needs_uv", spec, tip=spec.uv_install)
+
+    python = venv_python(root, spec.venv_dir)
+    venv_path = root / spec.venv_dir
+    env = dict(os.environ)
+    env["UV_PYTHON_INSTALL_DIR"] = str(root / spec.python_dir)
+    env["UV_PYTHON_DOWNLOADS"] = "automatic"
+    env["UV_PYTHON_PREFERENCE"] = "only-managed"
+    env["UV_NO_PROGRESS"] = "1"
+    steps: list[dict[str, Any]] = []
+
+    need_venv = True
+    if python.is_file():
+        found = probe(str(python))
+        if found and found >= spec.required:
+            need_venv = False
+            if _installed(python, spec, root, env, run):
+                return {
+                    "ok": True,
+                    "app": spec.app,
+                    "reason": None,
+                    "interpreter": str(python),
+                    "python_version": format_version(found),
+                    "ran_install": False,
+                    "installed": True,
+                    "steps": steps,
+                }
+        else:
+            try:
+                _move_aside(venv_path)
+            except OSError as exc:
+                return _failed("venv_locked", spec, detail=str(exc), steps=steps)
+    elif venv_path.exists():
+        try:
+            _move_aside(venv_path)
+        except OSError as exc:
+            return _failed("venv_locked", spec, detail=str(exc), steps=steps)
+
+    if need_venv:
+        for command, timeout in (
+            ([uv, "python", "install", spec.pin], 600),
+            ([uv, "venv", spec.venv_dir, "--python", spec.pin, "--seed"], 300),
+        ):
+            result = run(command, root, env, timeout)
+            steps.append(_step(command, result))
+            if result.get("returncode") != 0:
+                return _failed("provision_failed", spec, steps=steps)
+
+    install_command = [
+        uv,
+        "pip",
+        "install",
+        *spec.install_args,
+        "--python",
+        str(python),
+    ]
+    result = run(install_command, root, env, 600)
+    steps.append(_step(install_command, result))
+    if result.get("returncode") != 0:
+        return _failed("provision_failed", spec, steps=steps)
+
+    verify_command = _verify_command(python, spec)
+    if verify_command is not None:
+        result = run(verify_command, root, env, 60)
+        steps.append(_step(verify_command, result))
+        if result.get("returncode") != 0:
+            return _failed("provision_failed", spec, steps=steps)
+
+    found = probe(str(python))
+    if not found or found < spec.required:
+        return _failed("provision_failed", spec, steps=steps, python_version=None)
+
+    # Only a run that installed the pin may advance ``.python-version``.  On a
+    # reuse/repair path the existing interpreter is already good, so writing
+    # ``spec.pin`` would point a future offline run at an interpreter that was
+    # never downloaded.
+    if need_venv:
+        pin_path = root / spec.pin_file
+        wanted = spec.pin + "\n"
+        try:
+            if not pin_path.is_file() or pin_path.read_text(encoding="utf-8") != wanted:
+                temporary = pin_path.with_name(pin_path.name + ".tmp")
+                temporary.write_text(wanted, encoding="utf-8")
+                os.replace(temporary, pin_path)
+        except (OSError, UnicodeError) as exc:
+            return _failed("pin_write_failed", spec, detail=str(exc), steps=steps)
+
+    return {
+        "ok": True,
+        "app": spec.app,
+        "reason": None,
+        "interpreter": str(python),
+        "python_version": format_version(found),
+        "ran_install": True,
+        "installed": True,
+        "steps": steps,
+    }
+
+
+def _report(payload: dict[str, Any], code: int) -> int:
+    sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+    return code
+
+
+def _default_exec(path: str, argv: list[str], env: dict[str, str]) -> int | None:
+    """Replace the process on POSIX; wait for the child on Windows."""
+
+    if os.name == "nt":
+        return int(subprocess.call(argv, env=env))
+    os.execve(path, argv, env)
+
+
+def _exec(
+    exec_fn: Exec,
+    python: Path,
+    root: Path,
+    spec: BootstrapSpec,
+    args: list[str],
+) -> int:
+    """Replace this process with the chosen interpreter, same script and args."""
+
+    env = dict(os.environ)
+    env[spec.env_var] = str(python)
+    argv = [str(python), str(Path(root) / spec.entrypoint), *args]
+    result = exec_fn(str(python), argv, env)
+    return int(result or 0)
+
+
+def _too_old(found: str | None, spec: BootstrapSpec, **extra: object) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "installed": False,
+        "app": spec.app,
+        "reason": "python_too_old",
+        "found": found,
+        "required": f">={floor_text(spec.required)}",
+        "pin": spec.pin,
+    }
+    payload.update(extra)
+    return payload
+
+
+def _handed_off(spec: BootstrapSpec) -> bool:
+    """True when a previous handoff recorded a usable interpreter.
+
+    ``spec.env_var`` is the handoff signal.  A consumer may branch on it and
+    continue without calling ``bootstrap()`` again, so the first pass is
+    allowed to exec once to set it.  Every later pass sees it set, which is
+    what keeps a consumer that does not branch from looping.
+    """
+
+    recorded = os.environ.get(spec.env_var, "").strip()
+    return bool(recorded) and os.path.isfile(recorded)
+
+
+def _missing_continuation(spec: BootstrapSpec) -> dict[str, Any]:
+    """Report a handoff that has nowhere to continue.
+
+    Reached only after ``spec.env_var`` is already set: the interpreter has
+    been chosen, the entry point has been relaunched, and no continuation is
+    configured to take over.  Exec'ing again would be the same process with the
+    same arguments, so this is an error, not a handoff.
+    """
+
+    return {
+        "ok": False,
+        "installed": False,
+        "app": spec.app,
+        "reason": "missing_continuation",
+        "interpreter": sys.executable,
+        "required": f">={floor_text(spec.required)}",
+        "pin": spec.pin,
+        "env_var": spec.env_var,
+        "handed_off": _handed_off(spec),
+        "detail": (
+            "the running interpreter already meets the floor and no continuation "
+            "is configured; pass BootstrapSpec.package_main (or main_fn) so setup "
+            "can continue in-process instead of re-executing this entry point"
+        ),
+    }
+
+
+def bootstrap(
+    args: list[str],
+    root: Path,
+    spec: BootstrapSpec,
+    *,
+    exec_fn: Exec | None = None,
+    run: Runner = run_command,
+    uv: str | None = None,
+    probe: Probe = interpreter_version,
+    current: Version | None = None,
+    main_fn: Main | None = None,
+) -> int:
+    """Decide which interpreter runs the install, then hand over to it.
+
+    Order: explicit ``--python``, the running interpreter, an existing good
+    ``.venv``, then the consent card.  Only a real download needs consent.
+    """
+
+    exec_fn = exec_fn or _default_exec
+    root = Path(root)
+    cleaned: list[str] = []
+    override: str | None = None
+    consent = False
+    index = 0
+    while index < len(args):
+        token = args[index]
+        if token == "--":
+            cleaned.extend(args[index + 1 :])
+            break
+        if token == "--python":
+            if index + 1 >= len(args) or args[index + 1].startswith("--"):
+                return _report(
+                    {
+                        "ok": False,
+                        "installed": False,
+                        "app": spec.app,
+                        "reason": "python_flag_missing",
+                    },
+                    2,
+                )
+            override = args[index + 1]
+            index += 2
+            continue
+        if token.startswith("--python="):
+            value = token.split("=", 1)[1]
+            if not value:
+                return _report(
+                    {
+                        "ok": False,
+                        "installed": False,
+                        "app": spec.app,
+                        "reason": "python_flag_missing",
+                    },
+                    2,
+                )
+            override = value
+            index += 1
+            continue
+        if token == "--install-python":
+            consent = True
+            index += 1
+            continue
+        cleaned.append(token)
+        index += 1
+
+    running = (
+        current if current is not None else (version_tuple(sys.version.split()[0]) or (0, 0, 0))
+    )
+    continuation = main_fn or spec.package_main
+
+    if override is not None:
+        found = probe(override)
+        if not found or found < spec.required:
+            return _report(
+                _too_old(format_version(found) if found else None, spec, override=True), 3
+            )
+        return _exec(exec_fn, Path(override), root, spec, cleaned)
+
+    if running >= spec.required:
+        if continuation is not None:
+            os.environ[spec.env_var] = sys.executable
+            return continuation(cleaned)
+        if _handed_off(spec):
+            return _report(_missing_continuation(spec), 7)
+        return _exec(exec_fn, Path(sys.executable), root, spec, cleaned)
+
+    python = venv_python(root, spec.venv_dir)
+    broken_venv: tuple[Path, Version] | None = None
+    if python.is_file():
+        found = probe(str(python))
+        if found and found >= spec.required:
+            if spec.verify_import is None:
+                return _exec(exec_fn, python, root, spec, cleaned)
+            if _installed(python, spec, root, dict(os.environ), run):
+                return _exec(exec_fn, python, root, spec, cleaned)
+            broken_venv = (python, found)
+
+    if not consent:
+        if broken_venv is not None:
+            return _report(_needs_install(broken_venv[0], spec, broken_venv[1]), 6)
+        return _report(
+            _too_old(
+                format_version(running),
+                spec,
+                needs_consent=True,
+                card=spec.card,
+                next=f"python {spec.entrypoint} --install-python",
+            ),
+            3,
+        )
+
+    provisioned = provision(root, spec, uv=uv, run=run, probe=probe)
+    if not provisioned.get("ok"):
+        payload = dict(provisioned)
+        payload["installed"] = False
+        code = 4 if provisioned.get("reason") == "needs_uv" else 5
+        return _report(payload, code)
+    return _exec(exec_fn, Path(str(provisioned["interpreter"])), root, spec, cleaned)

python_mcp_bootstrap-0.1.3.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: python-mcp-bootstrap
+Version: 0.1.3
+Summary: Pre-install Python runtime bootstrap for MCP applications.
+Project-URL: Repository, https://github.com/4zhmv6zvj2-afk/python-mcp-bootstrap
+Author-email: Ron <4zhmv6zvj2-afk@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bootstrap,mcp,python,runtime,uv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-mcp-bootstrap
+
+A small setup helper for Python apps that use MCP.
+
+MCP (Model Context Protocol) is a way for AI assistants to use tools and data.
+Before one of those apps starts, this helper makes sure it runs on a supported
+version of Python. If your computer does not have one, it explains what is
+missing and asks before downloading anything. It never changes the Python that
+is already installed.
+
+This is a bootstrap *for* MCP applications, not an MCP implementation. It has
+no runtime dependency on the MCP SDK and never imports one.
+
+**Most people do not need to run this directly.** The app's setup script uses
+it. If you are a developer adding it to an app, jump to
+[For developers](#for-developers).
+
+
+## Do I need this?
+
+- If an app's setup tells you to run `python first_run.py`, that script uses
+  this helper. Follow the app's instructions.
+- If you are building or packaging an MCP app and need a first-run Python
+  check, use this library.
+- If you just want to run an app that is already set up, no.
+
+## What it does
+
+1. Looks for Python 3.14 or newer.
+2. Looks for a working `.venv` in the project.
+3. If the Python or the app environment is missing or incomplete, prints a
+   JSON report with a `card` and a `next` command. Nothing is downloaded.
+4. If you agree, the wrapper re-runs with `--install-python`, which installs
+   what is missing inside the project.
+5. Continues setup with that Python.
+
+It can also check a Python you name:
+
+```bash
+python first_run.py --python /path/to/python
+```
+
+## What it will not do
+
+- It will not download Python without `--install-python`.
+- It will not change your system Python or system packages.
+- It will not delete an existing `.venv`; a wrong one is moved aside.
+- It will not run `curl | sh`. If `uv` is missing, it prints a tip with the
+  official uv installation page and stops. It never runs that tip.
+- It will not run commands through a shell.
+- It masks credential-shaped values in its reports and captured output.
+
+## For developers
+
+This repository is a library, not the app. The command-line tool is a
+diagnostic:
+
+```bash
+python -m python_mcp_bootstrap --check
+python -m python_mcp_bootstrap --version
+```
+
+Distribution is GitHub Releases only: install the wheel or sdist from the
+[releases page](https://github.com/4zhmv6zvj2-afk/python-mcp-bootstrap/releases).
+This project is **not published on PyPI**, so `pip install python-mcp-bootstrap`
+does not resolve.
+
+Use `BootstrapSpec` and `bootstrap()` from an app's first-run wrapper:
+
+```python
+import sys
+from pathlib import Path
+
+from python_mcp_bootstrap import BootstrapSpec, bootstrap
+
+
+def continue_setup(args: list[str]) -> int:
+    # The rest of setup goes here.
+    del args
+    return 0
+
+
+root = Path(__file__).resolve().parent
+spec = BootstrapSpec(
+    app="example-mcp",
+    entrypoint="first_run.py",
+    env_var="EXAMPLE_MCP_INTERPRETER",
+    install_args=("-e", "."),
+    verify_import="example_mcp",
+    package_main=continue_setup,
+)
+raise SystemExit(bootstrap(sys.argv[1:], root, spec))
+```
+
+`package_main` is the function `bootstrap()` calls when the current Python is
+already suitable. Pass it: an entry point that calls `bootstrap()`
+unconditionally needs somewhere to continue.
+
+The first pass may hand off once, and it records the chosen interpreter in
+`spec.env_var`. A later pass that reaches `bootstrap()` with that variable
+already set and no continuation gets a `missing_continuation` report (exit
+`7`) instead of another exec, so the re-exec loop is gone. A wrapper that
+branches on `spec.env_var` and skips `bootstrap()` after the handoff keeps
+working, which is what the variable is for.
+
+`bootstrap()` checks `--python`, the current interpreter, and an existing
+`.venv`, in that order. It only offers to install the pinned Python after
+`--install-python`. An existing `.venv` is also checked with `verify_import`;
+the check runs isolated (`-I -P`), so only that venv's installed packages
+count. If the app or MCP module is missing, the repair card asks for
+`--install-python` before running the installer.
+
+`install_args` are consumer-controlled. Path-like entries are rejected when
+the spec is built if they are absolute, Windows-rooted, or contain `..`,
+including attached short-option values (`-t/tmp/x`). Venv-redirecting flags
+(`--target`, `--prefix`, `--root`, `--python` and their short forms) are
+rejected. Non-path flags such as `--index-url` pass through; credentials in
+reports are masked.
+
+The core is one stdlib-only file, `core.py`. It must stay importable on Python
+3.12 because it runs before the app's dependencies are installed; CI runs the
+suite on 3.12 as well as on the supported 3.14 and 3.15 interpreters.
+
+### Vendoring
+
+Consumers copy `core.py` and a `VENDOR.json` manifest instead of taking a
+runtime dependency:
+
+```bash
+python scripts/vendor.py \
+  --target /path/to/consumer \
+  --dest src/example/_vendor/python_mcp_bootstrap.py
+```
+
+Use `--check` to verify a pinned copy. The example app vendors `core.py` into
+`examples/_vendor/` and CI runs the same `vendor.py --check` sequence.
+
+- Contract: [docs/contract.md](docs/contract.md)
+- Integration details: [docs/integration.md](docs/integration.md)
+- Example first run: [examples/first_run.py](examples/first_run.py)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Contributing and release checks: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Development
+
+Requires Python 3.14+. The development pin is 3.15.2.
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest --cov=python_mcp_bootstrap --cov-fail-under=90
+python -m ruff format --check
+python -m ruff check
+python -m mypy
+python -m build
+```
+
+CI targets Python 3.14.10 and 3.15.2 on Ubuntu, macOS, and Windows, plus a 3.12
+compatibility job, a wheel/release gate, and the vendored example first run.
+CI is advisory for now (no required status checks); check the current matrix
+before merging, and treat a pending cell as not green.
+
+## Who maintains this
+
+Maintained by Ron as a small single-maintainer project. It exists because
+first-run setup for MCP apps kept re-solving the same problem: make sure a
+supported interpreter is present before the app's dependencies are, without
+touching the system Python.
+
+Issues and pull requests are welcome. There is no support SLA. `SECURITY.md`
+lists what the bootstrap does and does not guarantee.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

python_mcp_bootstrap-0.1.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+python_mcp_bootstrap/__init__.py,sha256=IS3hCfRI150bXc3zj5TwhGRiKkoLiybM6kdz6SExNhE,923
+python_mcp_bootstrap/__main__.py,sha256=S-r7PMFWeNsD5VqQP6zt-C2BjLgs7iPjpNf3iJ3qRQw,164
+python_mcp_bootstrap/cli.py,sha256=oiwp4bwA8xWy0e5dhyjNQJtJrdHvqoRUb9OFKKF_Yn8,1413
+python_mcp_bootstrap/core.py,sha256=2HLJFazzbnWXY62C3-JCga_2fFFqBiyqcZPXHE4-qUQ,25265
+python_mcp_bootstrap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_mcp_bootstrap-0.1.3.dist-info/METADATA,sha256=gEYKUZwUCUTS9Rxaa5rsvjsjd0Nt4y1b4rTLMFZDUs4,7399
+python_mcp_bootstrap-0.1.3.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+python_mcp_bootstrap-0.1.3.dist-info/entry_points.txt,sha256=YUL-12FHuCP29sNLNxkUFayI6-WytswCrpMbJBuvrYw,71
+python_mcp_bootstrap-0.1.3.dist-info/licenses/LICENSE,sha256=r4oNhys29PlJU-UAqHfmy9abFKKc0e5S17yGK0cdik0,1090
+python_mcp_bootstrap-0.1.3.dist-info/RECORD,,

python_mcp_bootstrap-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_mcp_bootstrap-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+python-mcp-bootstrap = python_mcp_bootstrap.cli:main

python_mcp_bootstrap-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 python-mcp-bootstrap contributors
+
+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.