feat: add detect_python_version tool and auto-default get_docs to user's Python

Detects the user's Python version at startup by probing .python-version,
python3 in PATH, then server runtime. When the detected version matches
an indexed doc set, get_docs defaults to it instead of the arbitrary
highest version. search_docs remains cross-version by design (CR-01).

New detect_python_version tool lets LLMs explicitly query the detection
result including source and whether it matched an indexed version.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ayhammouda

src/mcp_server_python_docs/app_context.py

@@ -25,3 +25,5 @@ class AppContext:
     content_service: ContentService
     version_service: VersionService
     synonyms: dict[str, list[str]] = field(default_factory=dict)
+    detected_python_version: str | None = None
+    detected_python_source: str | None = None

src/mcp_server_python_docs/detection.py

@@ -0,0 +1,82 @@
+"""Python version detection from the user's environment.
+
+Probes multiple sources to determine which Python version the user
+is working with, so the server can default to the right documentation.
+
+Detection order:
+1. .python-version file in cwd (pyenv, mise, rtx convention)
+2. ``python3 --version`` in PATH (user's active interpreter)
+3. ``sys.version_info`` (server's own runtime — last resort)
+"""
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_VERSION_RE = re.compile(r"(\d+\.\d+)")
+
+
+def _parse_major_minor(raw: str) -> str | None:
+    """Extract 'X.Y' from a version string like '3.13.2', 'Python 3.13.2', 'cpython-3.13'."""
+    m = _VERSION_RE.search(raw)
+    return m.group(1) if m else None
+
+
+def detect_python_version() -> tuple[str, str]:
+    """Detect the user's Python version.
+
+    Returns:
+        Tuple of (major_minor, source) where major_minor is like '3.13'
+        and source describes how it was detected.
+    """
+    # 1. .python-version file (pyenv / mise / rtx)
+    pv_file = Path.cwd() / ".python-version"
+    if pv_file.is_file():
+        try:
+            first_line = pv_file.read_text().strip().splitlines()[0].strip()
+            version = _parse_major_minor(first_line)
+            if version:
+                logger.info("Detected Python %s from .python-version", version)
+                return version, ".python-version file"
+        except Exception:
+            pass
+
+    # 2. python3 --version in PATH
+    try:
+        result = subprocess.run(
+            ["python3", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            version = _parse_major_minor(result.stdout.strip())
+            if version:
+                logger.info("Detected Python %s from python3 in PATH", version)
+                return version, "python3 in PATH"
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        pass
+
+    # 3. Server's own runtime
+    version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    logger.info("Using server runtime Python %s as fallback", version)
+    return version, "server runtime"
+
+
+def match_to_indexed(
+    detected: str, indexed_versions: list[str]
+) -> str | None:
+    """Match a detected version to the closest indexed version.
+
+    Returns the detected version if it's in the index, otherwise None.
+    We don't guess — if 3.11 is detected but only 3.12/3.13 are indexed,
+    return None and let the normal default resolution handle it.
+    """
+    if detected in indexed_versions:
+        return detected
+    return None

src/mcp_server_python_docs/models.py

@@ -136,3 +136,24 @@ class ListVersionsResult(BaseModel):
     versions: list[VersionInfo] = Field(
         description="Available documentation versions",
     )
+
+
+# --- detect_python_version models ---
+
+
+class DetectPythonVersionResult(BaseModel):
+    """Output from detect_python_version tool."""
+
+    detected_version: str = Field(
+        description="Python major.minor detected from the user's environment (e.g. '3.13')"
+    )
+    source: str = Field(
+        description="How the version was detected: '.python-version file', 'python3 in PATH', or 'server runtime'"
+    )
+    matched_index_version: str | None = Field(
+        default=None,
+        description="The detected version if it matches an indexed doc set, otherwise null",
+    )
+    is_default: bool = Field(
+        description="Whether this detected version is being used as the default for get_docs"
+    )

src/mcp_server_python_docs/server.py

@@ -22,8 +22,14 @@
 from mcp.types import ToolAnnotations
 
 from mcp_server_python_docs.app_context import AppContext
+from mcp_server_python_docs.detection import detect_python_version, match_to_indexed
 from mcp_server_python_docs.errors import DocsServerError
-from mcp_server_python_docs.models import GetDocsResult, ListVersionsResult, SearchDocsResult
+from mcp_server_python_docs.models import (
+    DetectPythonVersionResult,
+    GetDocsResult,
+    ListVersionsResult,
+    SearchDocsResult,
+)
 from mcp_server_python_docs.services.content import ContentService
 from mcp_server_python_docs.services.search import SearchService
 from mcp_server_python_docs.services.version import VersionService
@@ -83,6 +89,21 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     content_svc = ContentService(db)
     version_svc = VersionService(db)
 
+    # Detect user's Python version and match to indexed versions
+    detected_ver, detected_src = detect_python_version()
+    indexed_versions = [
+        r[0] for r in db.execute("SELECT version FROM doc_sets ORDER BY version").fetchall()
+    ]
+    matched = match_to_indexed(detected_ver, indexed_versions)
+    if matched:
+        logger.info("User Python %s matches indexed version — using as default", matched)
+    else:
+        logger.info(
+            "User Python %s not in index %s — using normal default",
+            detected_ver,
+            indexed_versions,
+        )
+
     try:
         yield AppContext(
             db=db,
@@ -91,6 +112,8 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
             search_service=search_svc,
             content_service=content_svc,
             version_service=version_svc,
+            detected_python_version=matched,
+            detected_python_source=detected_src,
         )
     except Exception:
         # HYGN-05: log lifespan errors, write last-error.log, re-raise original
@@ -155,6 +178,9 @@ def get_docs(
         """Retrieve a documentation page or specific section. Provide anchor for
         section-only retrieval (much cheaper). Pagination via start_index."""
         app_ctx: AppContext = ctx.request_context.lifespan_context
+        # Auto-default to detected Python version when no version specified
+        if version is None and app_ctx.detected_python_version:
+            version = app_ctx.detected_python_version
         try:
             return app_ctx.content_service.get_docs(
                 slug, version, anchor, max_chars, start_index
@@ -179,6 +205,29 @@ def list_versions(
             logger.exception("Unexpected error in list_versions")
             raise ToolError(f"Internal error: {type(e).__name__}")
 
+    @mcp.tool(annotations=_TOOL_ANNOTATIONS)
+    def detect_python_version(
+        ctx: Context = None,  # type: ignore[assignment]
+    ) -> DetectPythonVersionResult:
+        """Detect the Python version in the user's environment.
+        Returns the detected version, how it was found, and whether it
+        matches an indexed documentation set."""
+        app_ctx: AppContext = ctx.request_context.lifespan_context
+        detected_ver = app_ctx.detected_python_version
+        detected_src = app_ctx.detected_python_source or "unknown"
+
+        # Re-run detection to get the raw version even if it didn't match
+        from mcp_server_python_docs.detection import detect_python_version as _detect
+
+        raw_ver, raw_src = _detect()
+
+        return DetectPythonVersionResult(
+            detected_version=raw_ver,
+            source=raw_src,
+            matched_index_version=detected_ver,
+            is_default=detected_ver is not None,
+        )
+
     # SRVR-07: _meta hint for get_docs tool.
     # FastMCP 1.27 does not expose a public API for setting _meta on tool
     # definitions. Deferred until the mcp SDK adds _meta support to the

tests/test_services.py

@@ -387,12 +387,12 @@ def test_all_tools_have_annotations(self):
                 annotations.openWorldHint is False
             ), f"{name} openWorldHint should be False"
 
-    def test_three_tools_registered(self):
+    def test_four_tools_registered(self):
         from mcp_server_python_docs.server import create_server
 
         server = create_server()
         tools = server._tool_manager._tools
-        assert len(tools) == 3
+        assert len(tools) == 4
 
 
 # === validate-corpus Tests ===