Repository navigation
phase 11 — detect_python_version v2 (venv-aware) #34
Description
Activity
Vision — automated project maintainer: I am pausing this v2 spec pending a client-context check, not rejecting the version-accuracy goal.
detection.pyreads the MCP server process environment and cwd; itsVIRTUAL_ENVand.venvmay belong touvx/the client launch context rather than the user project. The current tool has no project-path input, andserver.pyalso combines a startup-cached matched version with a fresh raw detection result. Therefore DETV2-01/02 could confidently report the wrong project Python version in common MCP setups. Before implementation, reproduce cwd/env behavior in the documented Claude/Cursor/Codex integration flows, then revise acceptance criteria around an observable project context or explicitly label this as server-environment detection. Do not dispatch the current spec as agent-ready.This was generated by AI during triage.
Codex — automated triage assistant.
Agent Brief — resolve detection context before implementation
Category: enhancement
Triage state:ready-for-human(Vision supervisor routing); retainsupervisor-review.
Summary: Establish an observable and truthful Python-detection context, then revise the venv-aware acceptance criteria. The existing implementation hold remains in force.Context and redundancy check: Reviewed the full issue and Vision's 2026-10-01 hold. Searched the detector, both server call sites, application context, result model, detection/retrieval tests, README, manual integration runbook and transport ADR. At main
c97600ecc5430044e66500d04192bc61e7df71dc, detection still uses cwd.python-version, PATHpython3, then server runtime. NeitherVIRTUAL_ENVnorpyvenv.cfgis read, and the public tool has no project-path argument. The requested behavior is not already implemented. No matching prior rejection records were found in.out-of-scope/. ADR-008's subprocess/stdio model is consistent with inherited server context; it does not establish which user's project that context represents.Current behavior and fresh verification:
uv run --locked pytest tests/test_detection.py -q: 12 passed.- A controlled project fixture with
VIRTUAL_ENVand.venv/pyvenv.cfgdeclaring 3.12, with the PATH probe controlled to report 3.13, returns("3.13", "python3 in PATH"). - With separate user-project and server-launch directories requesting 3.12 and 3.13 respectively, a detector invoked from the launch directory returns
("3.13", ".python-version file"). - Calling the current registered wrapper with a startup-cached 3.12 match while fresh cwd detection reports 3.13 returns
detected_version="3.13",matched_index_version="3.12",is_default=true. The model describes the matched version as the detected version's indexed match, so this combination needs an explicit consistency/freshness decision.
These are controlled local probes of current code, not measurements from actual Claude Desktop, Cursor or Codex client sessions. No client configuration or product code was changed.
Desired behavior: The reported version, source and indexed-match/default fields have documented, consistent meanings. A server runtime or launcher venv must not be presented as the user's project interpreter without an observable relationship to that project.
Key interfaces:
detect_python_version(),match_to_indexed(), startup detection inapp_lifespan,AppContext.detected_python_version, andDetectPythonVersionResult.Acceptance criteria for Vision's decision:
- Reproduce the documented client launches and record only the relevant cwd, interpreter/PATH and venv observations; avoid credential/environment dumps.
- Record how project context is observed and bounded, or explicitly scope the feature to server-environment detection. Do not invent an API/project-path extension inside the current issue's forbidden scope.
- Define how fresh detection, cached default and indexed matching remain coherent when a version file or environment changes during a session; turn the contradictory controlled result into a deterministic acceptance case.
- Rewrite precedence and error/fallback cases for the chosen context, including unreadable/malformed venv metadata, unrelated launcher venvs, ancestor boundaries and Windows layout. Preserve existing source strings and wire shape unless Vision explicitly authorizes a compatible scope revision.
- Only after that decision, provide an agent-targetable implementation brief and pipeline preflight. Require focused detection/stdio tests and the locked canonical gate for the resulting change.
Why supervisor routing: The blocker is an unresolved product/context contract already identified by Vision, not unanswered reporter reproduction steps. Existing test success does not settle that contract. The original
VIRTUAL_ENV → .venv → ...spec is not ready for unattended implementation.Out of scope: Implementing the paused spec now, silently changing tool inputs or return shape, conda/mamba support, unrelated transport changes, a new MCP server, or claiming actual-client acceptance from these local fixtures.
Context
.planning/agent-context/detect-python-version-v2-venv-aware.mdAGENT-EXECUTION-PIPELINE.mdsrc/mcp_server_python_docs/detection.py—detect_python_version()3-step chain (.python-version→python3 --version→sys.version_info).tests/test_detection.pyalready exists (125 lines) and covers the three v1 sources. Extend it; do not recreate it.src/mcp_server_python_docs/server.py:372; result model:src/mcp_server_python_docs/models.py:147(DetectPythonVersionResult).Goal
Make
detect_python_versionreport the Python version of the active virtual environment in the user's project, while preserving the v1 fallback chain and the existing MCP wire contract verbatim.Acceptance criteria
VIRTUAL_ENVis set,detection.pyreads<VIRTUAL_ENV>/pyvenv.cfg, parses theversion = X.Y[.Z]key (falling back toversion_infoifversionis absent), and returns source"venv:VIRTUAL_ENV".VIRTUAL_ENV, a.venv/orvenv/directory found in cwd or an ancestor (bounded at filesystem/project root) is read via itspyvenv.cfgand returns source"venv:.venv".uv's andpoetry's project-root.venvare covered by the generic DETV2-02 check (no tool-specific branching).VIRTUAL_ENV → .venv/venv dir → .python-version → python3 PATH → server runtime.detect_python_version()still returns a(major_minor, source)tuple. Five distinct source strings exist: the two new"venv:VIRTUAL_ENV","venv:.venv"plus the three preserved-verbatim v1 strings".python-version file","python3 in PATH","server runtime".sourceField(description=...)inmodels.py(DetectPythonVersionResult, line ~147) is updated to enumerate all five sources, so the published tool schema does not lie. (Type staysstr; description-only edit.)tests/test_detection.pyis extended (not replaced): new tests covervenv:VIRTUAL_ENVandvenv:.venv(incl. a Windows-layoutpyvenv.cfgpath), AND the existing v1 tests are hardened withmonkeypatch.delenv("VIRTUAL_ENV", raising=False)so they stay deterministic now thatVIRTUAL_ENVis checked first. All five source strings are covered.uv run pytest tests/test_detection.py -qpasses.Success criteria (illustrative)
("3.12", "venv:VIRTUAL_ENV")..python-versionpresent →("X.Y", ".python-version file")(v1 preserved verbatim).(sys-version, "server runtime")(v1 fallback preserved verbatim).Scope boundaries
In scope: the venv-detection logic in
src/mcp_server_python_docs/detection.py, thesourcedescription string inmodels.py, and extendingtests/test_detection.py.Out of scope (stop and comment):
detect_python_versionMCP wrapper signature or the(major_minor, source)return shape.Forbidden-territory reminders (pipeline §2)
server.py:372wrapper signature and the tuple/model shape must not change. Only the set of possiblesourcevalues grows, plus its description text.delenvto keep a test deterministic is hardening, and is required here.)pyproject.tomledits.Validation commands (pipeline §5)
uv run ruff check src/ tests/ uv run pyright src/ uv run pytest --tb=short -q uv run python-docs-mcp-server doctor # detect_python_version backs an MCP tool — also run the wire smoke: uv run pytest tests/test_stdio_smoke.py -qPR template & recovery (pipeline §6, §8)
.github/PULL_REQUEST_TEMPLATE/agent.md; PR title matches this issue verbatim.pyvenv.cfgvariants? Stop, writeWORKING-NOTES.md, comment per §8 — do not invent.Effort estimate
~2–3 hours.