python-docs-mcp-server 0.1.3__tar.gz → 0.1.5__tar.gz

python_docs_mcp_server-0.1.5/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Etc/UTC"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:30"
+      timezone: "Etc/UTC"
+    open-pull-requests-limit: 5

python_docs_mcp_server-0.1.5/.github/workflows/codeql.yml

@@ -0,0 +1,34 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "20 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-extended,security-and-quality
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4

{python_docs_mcp_server-0.1.3 → python_docs_mcp_server-0.1.5}/.github/workflows/release.yml

@@ -35,6 +35,16 @@ jobs:
             echo "::error::Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${PKG_VERSION}"
             exit 1
           fi
+          SERVER_VERSION=$(uv run python -c "import json; print(json.load(open('server.json'))['version'])")
+          PACKAGE_VERSION=$(uv run python -c "import json; print(json.load(open('server.json'))['packages'][0]['version'])")
+          if [ "$TAG_VERSION" != "$SERVER_VERSION" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match server.json version ${SERVER_VERSION}"
+            exit 1
+          fi
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match server.json package version ${PACKAGE_VERSION}"
+            exit 1
+          fi
           echo "Version check passed: ${PKG_VERSION}"
 
       - name: Run linter
@@ -97,9 +107,37 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
-  github-release:
+  publish-mcp-registry:
     needs: publish
     runs-on: ubuntu-latest
+    name: Publish to MCP Registry
+    timeout-minutes: 10
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
+            | tar xz mcp-publisher
+
+      - name: Validate server.json
+        run: ./mcp-publisher validate server.json
+
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish
+
+  github-release:
+    needs:
+      - publish
+      - publish-mcp-registry
+    runs-on: ubuntu-latest
     name: Create GitHub Release
     timeout-minutes: 10
     permissions:

python_docs_mcp_server-0.1.5/.github/workflows/scorecard.yml

@@ -0,0 +1,38 @@
+name: OpenSSF Scorecard
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "40 6 * * 1"
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      security-events: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Run OpenSSF Scorecard
+        uses: ossf/scorecard-action@v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload SARIF results
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif

python_docs_mcp_server-0.1.5/.github/workflows/security.yml

@@ -0,0 +1,46 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Export locked dependencies
+        run: |
+          uv export \
+            --locked \
+            --format requirements-txt \
+            --all-groups \
+            --all-extras \
+            --no-emit-project \
+            --no-hashes \
+            --output-file requirements-audit.txt \
+            >/dev/null
+
+      - name: Audit dependencies
+        run: |
+          uvx pip-audit \
+            --requirement requirements-audit.txt \
+            --no-deps \
+            --disable-pip \
+            --progress-spinner off

python_docs_mcp_server-0.1.5/.planning/POSITIONING.md

@@ -0,0 +1,20 @@
+# Locked positioning (decision 9.1, locked 2026-05-14)
+
+**Sentence (verbatim):**
+
+> For AI coding agents writing Python, python-docs-mcp-server is the canonical Python stdlib oracle: exact symbols, exact sections, exact versions — offline, **always free, always MIT**, token-frugal.
+
+**Use verbatim (no rewording) in:**
+
+- `README.md` hero
+- GitHub repo `About` text
+- `LAUNCH-POST.md` lede
+- Talk bio
+
+**Adapt for length and grammar in (preserve key phrases: `canonical Python stdlib oracle`, `always free, always MIT`, `token-frugal`):**
+
+- `glama.json` `description` — long marketing form (Glama directory display)
+- `server.json` `description` — medium form (MCP Registry display)
+- `pyproject.toml` `description` — short form (PyPI summary, ≤512 chars)
+
+The locked sentence is the anchor; adapted forms must keep the three key phrases and the wedge claim (canonical / version-aware / offline). They may drop "exact symbols, exact sections, exact versions" for brevity if needed, but never the three anchors above.

python_docs_mcp_server-0.1.5/.planning/ROADMAP.md

@@ -0,0 +1,20 @@
+# Roadmap
+
+## Current
+
+- **v0.1.4** — shipped (pre-PyPI; installed via `uvx --from git+…`)
+- **v0.1.5** — in progress. Four coordinated workstreams: positioning lockdown ("canonical Python stdlib oracle for AI coding agents — always free, always MIT, token-frugal"); first PyPI publish via Trusted Publishing; benchmark harness against competing docs MCPs; coordinated launch post on a personal blog, dev.to, and Show HN. (Note: the GitHub repo rename to `python-stdlib-mcp` originally planned for v0.1.5 was dropped on 2026-05-14 — the repo and PyPI package keep the `python-docs-mcp-server` name.)
+
+## Backlog (post-v0.1.5)
+
+| Phase | Title | Tool surface | Issue |
+|-------|-------|--------------|-------|
+| 09 | `compare_versions(symbol, v1, v2)` | New MCP tool | #TBD-link-after-PR-merges |
+| 10 | `whatsnew_for_version(version)` | New MCP tool | #TBD-link-after-PR-merges |
+| 11 | `detect_python_version` v2 (venv-aware) | Existing tool enhancement | #TBD-link-after-PR-merges |
+
+These are planned, not committed. Phase CONTEXTs at [`phases/09-compare-versions/`](phases/09-compare-versions/09-CONTEXT.md), [`phases/10-whatsnew/`](phases/10-whatsnew/10-CONTEXT.md), [`phases/11-detect-venv/`](phases/11-detect-venv/11-CONTEXT.md). Implementation kickoff requires `/gsd-plan-phase 0X`.
+
+## Historical
+
+Pre-2026-05-14 GSD workflow artifacts (phases 1–8 for v0.1.0) live in maintainers' local worktrees and are intentionally not tracked in this repo — they remain accessible to those who ran the original GSD workflow locally but are not load-bearing for current implementation work. With v0.1.5 the `.planning/` directory becomes a tracked, forward-facing surface for new phase CONTEXTs and roadmap entries.

python_docs_mcp_server-0.1.5/.planning/phases/09-compare-versions/09-CONTEXT.md

@@ -0,0 +1,40 @@
+# Phase 09 — compare_versions(symbol, v1, v2)
+
+**Status:** Backlog (post-v0.1.5)
+**Type:** New MCP tool
+
+## Goal
+
+Add an MCP tool `compare_versions(symbol, v1, v2)` that returns a structured diff of a stdlib symbol's signature, behavior, and docstring between two Python versions.
+
+## Depends on
+
+- v0.1.5 ships (PyPI debut + repo rename complete).
+- Index supports the two versions being compared (handled by `build-index`).
+
+## Requirements
+
+- CMPR-01: Tool accepts `(symbol: str, v1: str, v2: str)`. Returns a structured diff: signature change, docstring delta, deprecation flag, see-also additions/removals.
+- CMPR-02: Both versions must already be indexed; if not, tool returns an actionable error pointing at `build-index`.
+- CMPR-03: Diff format is JSON-serializable and token-frugal — no full re-printing of unchanged paragraphs.
+
+## Success criteria
+
+1. `compare_versions("asyncio.TaskGroup", "3.10", "3.11")` returns a clear, machine-readable diff showing the symbol was newly introduced in 3.11 (e.g. an `added` or `new_in` marker, not just a delta of existing fields).
+2. Comparing identical versions returns an empty diff with an explicit "no change" marker.
+3. Missing-version cases return an actionable error with the indexed-version list.
+4. Token cost of a typical diff is under 300 tokens (vs ~1500 for fetching both full doc pages).
+5. Integration test in `tests/test_compare_versions.py` exercises 3 representative symbols (one changed, one unchanged, one missing).
+
+## Plans
+
+TBD — run `/gsd-plan-phase 09` after this issue is prioritized.
+
+## UI hint
+
+No UI surface; pure MCP tool.
+
+## Out of scope
+
+- Cross-language diffs (Python stdlib only).
+- Non-symbol diffs (module-level changes belong in phase 10).

python_docs_mcp_server-0.1.5/.planning/phases/10-whatsnew/10-CONTEXT.md

@@ -0,0 +1,40 @@
+# Phase 10 — whatsnew_for_version(version)
+
+**Status:** Backlog (post-v0.1.5)
+**Type:** New MCP tool
+
+## Goal
+
+Return the official "What's New in Python `<version>`" content as structured sections, scoped by topic — new modules, deprecations, removals, performance, syntax. The current alternative is for the agent to fetch a full HTML page; this tool returns just the requested sections.
+
+## Depends on
+
+- v0.1.5 ships.
+- Ingestion already covers `whatsnew/<version>.html` (verify during phase planning).
+
+## Requirements
+
+- WNEW-01: Tool signature: `whatsnew_for_version(version: str, kind: str | None = None, start_index: int = 0, max_sections: int = 20)`. `kind` filters to a single `kind` value (see WNEW-02); `start_index` + `max_sections` paginate the response. Returns `{ "sections": [{title, anchor, body, kind}], "next_start_index": int | None }`.
+- WNEW-02: `kind` enum: `new_module | new_feature | deprecation | removal | performance | syntax | other`.
+- WNEW-03: Each section's `body` is capped at ~2k tokens. If a single section exceeds the cap, truncate with a clear marker and a `get_docs` hint. Pagination via `start_index` / `next_start_index` round-trips.
+
+## Success criteria
+
+1. `whatsnew_for_version("3.12")` returns ≥10 sections, each with a non-empty body.
+2. Each section has a stable anchor matching docs.python.org.
+3. Filtering by `kind` is supported (`whatsnew_for_version("3.12", kind="deprecation")`).
+4. Missing version returns the same actionable error pattern as `compare_versions`.
+5. Integration test in `tests/test_whatsnew.py` covers two representative versions.
+
+## Plans
+
+TBD.
+
+## UI hint
+
+No UI surface; pure MCP tool.
+
+## Out of scope
+
+- Third-party "what's new" guides.
+- Cross-version aggregation (use `compare_versions` instead).

python_docs_mcp_server-0.1.5/.planning/phases/11-detect-venv/11-CONTEXT.md

@@ -0,0 +1,43 @@
+# Phase 11 — detect_python_version v2 (venv-aware)
+
+**Status:** Backlog (post-v0.1.5)
+**Type:** Enhancement of existing MCP tool
+
+## Goal
+
+Make `detect_python_version` venv-aware: report the Python version of the *active virtual environment* in the user's project, not just the value from `.python-version` or `python3 --version` on PATH.
+
+## Depends on
+
+- v0.1.5 ships.
+- v1 implementation at `src/mcp_server_python_docs/detection.py` (current 3-step detection order: `.python-version` → `python3 --version` → `sys.version_info`).
+- v1 has NO dedicated unit test file — backfill `tests/test_detection.py` as part of this phase.
+
+## Requirements
+
+- DETV2-01: Detect active venv via the `VIRTUAL_ENV` env var; if present, read `$VIRTUAL_ENV/pyvenv.cfg` and parse the `version = X.Y[.Z]` key (the standard key written by `python -m venv`). Fall back to `version_info` only if `version` is absent — some tools write that variant.
+- DETV2-02: Detect `.venv/` or `venv/` directories in cwd or its ancestors (up to project root).
+- DETV2-03: Detect `uv`'s `.venv` and `poetry`'s `.venv` patterns.
+- DETV2-04: Preserve v1 fallback chain unchanged below the new venv checks.
+- DETV2-05: Return `(major_minor, source)` tuple. **New v2 sources:** `"venv:VIRTUAL_ENV"`, `"venv:.venv"`. **Existing v1 sources (preserved unchanged, see `src/mcp_server_python_docs/detection.py`):** `".python-version file"`, `"python3 in PATH"`, `"server runtime"`. Total: 5 distinct source strings.
+
+## Success criteria
+
+1. Inside an activated venv (3.12) on a 3.13 host: returns `("3.12", "venv:VIRTUAL_ENV")`.
+2. With no venv but `.python-version` present: returns `("X.Y", ".python-version file")` — v1 behavior preserved verbatim.
+3. With nothing else available: returns `(sys-version, "server runtime")` — v1 fallback preserved verbatim.
+4. Backfill: `tests/test_detection.py` covers all five `source` cases (2 new + 3 preserved).
+5. No regression in v1 callers (`server.py` MCP tool wrapper signature unchanged; existing source strings unchanged).
+
+## Plans
+
+TBD.
+
+## UI hint
+
+No UI surface; pure MCP tool.
+
+## Out of scope
+
+- conda / mamba environments (separate phase if demand surfaces).
+- Cross-platform venv path quirks beyond Unix + Windows (both must be tested).

{python_docs_mcp_server-0.1.3 → python_docs_mcp_server-0.1.5}/AGENTS.md

@@ -83,15 +83,15 @@ Before calling work complete:
 
 ## Context Hygiene
 
-Treat `.planning/` as archival project history, not live repo truth.
-
-Start with these files instead:
-
-- `README.md`
-- `CONTRIBUTING.md`
-- `.github/INTEGRATION-TEST.md`
-- `tests/`
-
-The generated planning files may still be useful for maintainers who want the
-old GSD workflow context, but they should not drive routine implementation
-decisions.
+`.planning/` mixes archival history with forward-facing phase CONTEXTs.
+
+- `.planning/ROADMAP.md` and `.planning/phases/0X-…/0X-CONTEXT.md` are live,
+  forward-looking specs — read these first when starting a new phase.
+- Anything else in `.planning/` (especially content dated 2026-04 or earlier)
+  is archival history. It may help maintainers reconstruct prior context but
+  should not drive routine implementation decisions.
+- For the source of truth about *what the code does today*, start with:
+  - `README.md`
+  - `CONTRIBUTING.md`
+  - `.github/INTEGRATION-TEST.md`
+  - `tests/`

python_docs_mcp_server-0.1.5/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `python-docs-mcp-server` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.5] — 2026-05-14
+
+### Added
+
+- **PyPI debut.** Install via `uvx python-docs-mcp-server` (no `--from` flag needed). The previous `uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git` path keeps working via the existing GitHub source, but the published wheel is now the canonical install route.
+- `CHANGELOG.md` (this file).
+- Locked positioning anchor: *"For AI coding agents writing Python, `python-docs-mcp-server` is the canonical Python stdlib oracle: exact symbols, exact sections, exact versions — offline, **always free, always MIT**, token-frugal."* See `.planning/POSITIONING.md` for the verbatim copy and per-surface adaptation rules.
+- Forward-facing `.planning/phases/` directory. Three post-v0.1.5 backlog items have on-disk specs:
+  - `09-compare-versions` — new MCP tool: `compare_versions(symbol, v1, v2)` structured diff.
+  - `10-whatsnew` — new MCP tool: `whatsnew_for_version(version)` section-sliced "What's New" page.
+  - `11-detect-venv` — venv-aware `detect_python_version` v2 (reads `VIRTUAL_ENV`, `.venv/`, `pyvenv.cfg`).
+
+### Changed
+
+- README hero rewritten around the canonical-source positioning. The positioning sentence now sits between the package title and the badge row, with a wedge-forward "Built for the moment your agent needs…" descriptive paragraph below the badges.
+- `glama.json` `description`, `server.json` `description`, and `pyproject.toml` `description` aligned with the locked positioning. Each surface keeps the three required anchor phrases (canonical Python stdlib oracle / always free, always MIT / token-frugal) while adapting the wording for its display length.
+- `AGENTS.md` "Context Hygiene" section now distinguishes `.planning/ROADMAP.md` and `.planning/phases/0X-…/0X-CONTEXT.md` (live, forward-looking specs) from older `.planning/` content (archival history).
+- README install instructions, MCP-client config snippets, and validation commands now lead with the PyPI install (`uvx python-docs-mcp-server`). The pre-PyPI `--from git+…` blocks have been removed.
+
+### Removed
+
+- All `<!-- PRE-PYPI -->` fenced regions from `README.md` (11 blocks, 18 GitHub-source install URLs). They were scaffolding for the pre-v0.1.5 window where the only install path was a GitHub source URL.
+
+### Notes
+
+- The PyPI package name and the GitHub repository name both remain `python-docs-mcp-server`. A rename to `python-stdlib-mcp` was planned in the v0.1.5 scope (CR §9.2) but was dropped on 2026-05-14; the historical note is preserved in `.planning/ROADMAP.md`.
+- Trusted Publishing on PyPI is wired with Sigstore attestations on every release artifact. The release workflow lives at `.github/workflows/release.yml` and runs on annotated tags matching `v*`.
+
+## [0.1.4] — 2026-05-13
+
+Pre-PyPI release. Installable only via `uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git`. Last release before the PyPI publish.