python-docs-mcp-server 0.1.2__tar.gz

python_docs_mcp_server-0.1.2/.cursorignore

@@ -0,0 +1 @@
+.planning/

python_docs_mcp_server-0.1.2/.github/INTEGRATION-TEST.md

@@ -0,0 +1,149 @@
+# Manual MCP QA Runbook
+
+Use this document for manual MCP validation during development and before a
+release. The goal is to verify real client behavior after the automated test
+suite passes.
+
+Release-specific sign-off still lives in [`.github/RELEASE.md`](RELEASE.md).
+
+## Prerequisites
+
+- CI or local checks are green:
+  - `uv run ruff check src/ tests/`
+  - `uv run pyright src/`
+  - `uv run pytest --tb=short -q`
+- Local index build completed:
+  - `uv run python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14`
+- Doctor passes:
+  - `uv run python-docs-mcp-server doctor`
+- Slow E2E workflow passes when preparing a release:
+  - GitHub Actions: `Slow E2E`
+  - Expected: Python 3.13 and 3.14 jobs both complete `build-index`, `doctor`,
+    and `validate-corpus` from an installed wheel
+- If `uv` is not on `PATH`, use `python -m uv ...` instead
+
+## Test 1: MCP Inspector quick loop
+
+Use Inspector for fast local iteration before checking real clients.
+
+### Start Inspector
+
+```bash
+npx @modelcontextprotocol/inspector uv --directory . run python-docs-mcp-server
+```
+
+### Verify
+
+- [ ] Connect successfully over stdio
+- [ ] Confirm the tool list includes:
+  - `search_docs`
+  - `get_docs`
+  - `list_versions`
+  - `detect_python_version`
+- [ ] Call `search_docs` with query `asyncio.TaskGroup`, `kind="symbol"`, `version="3.13"`
+  - Expected: exact symbol hit with `library/asyncio-task.html`
+- [ ] Call `get_docs` for the returned slug and anchor
+  - Expected: section-level documentation, not an unrelated page dump
+- [ ] Call `list_versions`
+  - Expected: indexed versions appear with the configured default version
+- [ ] Call `detect_python_version`
+  - Expected: returns local interpreter information without breaking the session
+- [ ] Observe no protocol corruption or unexplained disconnects in Inspector
+
+## Test 2: Claude Desktop integration
+
+### Setup
+
+1. Open Claude Desktop settings
+2. Add this server config:
+
+```json
+{
+  "mcpServers": {
+    "python-docs": {
+      "command": "uvx",
+      "args": ["python-docs-mcp-server"]
+    }
+  }
+}
+```
+
+3. Fully restart Claude Desktop
+4. Verify the MCP server appears in the chat UI
+
+### Checks
+
+- [ ] Ask: `what is asyncio.TaskGroup`
+  - Expected: response uses stdlib documentation, not only model prior knowledge
+- [ ] Ask: `how do I use pathlib.Path.glob`
+  - Expected: response cites the right docs section
+- [ ] Ask: `search for json parsing in Python`
+  - Expected: response surfaces `json` docs results
+- [ ] Check the Claude developer console
+  - Expected: no protocol errors or repeated reconnect loops
+
+## Test 3: Cursor integration
+
+### Setup
+
+1. Open Cursor MCP settings
+2. Add a server:
+   - Name: `python-docs`
+   - Command: `uvx`
+   - Args: `python-docs-mcp-server`
+3. Confirm the server shows as connected
+
+### Checks
+
+- [ ] Ask: `what is asyncio.TaskGroup`
+  - Expected: MCP tool usage is visible and the answer references the right docs
+- [ ] Ask: `show me the docs for collections.OrderedDict`
+  - Expected: response includes the relevant documentation section
+- [ ] Ask a second or third follow-up query
+  - Expected: the server stays connected across multiple calls
+
+## Test 4: Fresh install verification
+
+Use this when validating the published package or a clean local environment.
+
+On Windows, close the MCP client before rebuilding if the live index file is
+locked.
+
+### Checks
+
+- [ ] `uvx python-docs-mcp-server --version`
+  - Expected: prints the current package version
+- [ ] `uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14`
+  - Expected: index build completes successfully
+- [ ] `uvx python-docs-mcp-server doctor`
+  - Expected: all required checks pass
+- [ ] Follow the README from scratch
+  - Expected: a new user can get to a working client configuration without using `.planning/`
+
+## Test 5: Slow E2E workflow
+
+Run this before a release and after changes to ingestion, publishing, packaging,
+or supported Python versions.
+
+### Checks
+
+- [ ] Start the `Slow E2E` workflow from GitHub Actions
+  - Expected: both Python 3.13 and Python 3.14 jobs start
+- [ ] Confirm each job installs the built wheel into a clean virtual environment
+  - Expected: the command path is the installed `python-docs-mcp-server`, not editable source
+- [ ] Confirm `build-index --versions 3.10,3.11,3.12,3.13,3.14` passes
+  - Expected: all five versions produce content, not symbol-only fallback
+- [ ] Confirm `doctor` and `validate-corpus` pass
+  - Expected: corpus smoke checks include requested versions and the default version
+- [ ] Inspect uploaded logs if a job fails
+  - Expected: Sphinx/build logs are available as workflow artifacts
+
+## Evidence log
+
+| Test | Pass/Fail | Tester | Date | Notes |
+|------|-----------|--------|------|-------|
+| Inspector quick loop | | | | |
+| Claude Desktop | | | | |
+| Cursor | | | | |
+| Fresh install | | | | |
+| Slow E2E workflow | | | | |

python_docs_mcp_server-0.1.2/.github/RELEASE.md

@@ -0,0 +1,198 @@
+# Release Process
+
+## One-Time Setup: PyPI Trusted Publishing
+
+Before the first release, configure PyPI Trusted Publishing:
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Add a new pending publisher:
+   - **PyPI project name**: `python-docs-mcp-server`
+   - **Owner**: your GitHub username or org
+   - **Repository**: `python-docs-mcp-server`
+   - **Workflow name**: `release.yml`
+   - **Environment name**: `pypi`
+3. In the GitHub repo, go to Settings > Environments
+4. Create an environment named `pypi`
+5. (Optional) Add environment protection rules:
+   - Required reviewers (recommended for first release)
+   - Deployment branches: only `main` tags
+
+## Notes
+
+**Runtime coverage:** The release workflow builds and tests against Python 3.13 only.
+Python 3.12 is covered by the CI workflow (`ci.yml`) which runs a 2x2 matrix
+(3.12/3.13 x ubuntu/macos) on every push to `main`. Since tags are created
+from commits that have already passed CI, 3.12 compatibility is verified before
+the release workflow runs. This is an accepted trade-off to keep the release
+artifact pipeline simple (single Python version produces the wheel).
+
+**Documentation coverage:** The full docs index target is Python documentation
+versions 3.10 through 3.14.
+
+## Creating a Release
+
+1. Ensure all tests pass on main:
+   ```bash
+   uv run pytest --tb=short -q
+   uv run ruff check src/ tests/
+   uv run pyright src/
+   ```
+
+2. Verify the version in `pyproject.toml` is correct:
+   ```bash
+   grep '^version' pyproject.toml
+   # Should show: version = "0.1.2"
+   ```
+
+3. Create and push the tag:
+   ```bash
+   git tag -a v0.1.2 -m "Release v0.1.2"
+   git push origin v0.1.2
+   ```
+
+4. Monitor the release workflow at:
+   https://github.com/<owner>/python-docs-mcp-server/actions/workflows/release.yml
+
+5. Verify the package on PyPI:
+   https://pypi.org/project/python-docs-mcp-server/0.1.2/
+
+## Post-Release Verification
+
+After the package is published:
+
+```bash
+# In a fresh environment:
+uvx python-docs-mcp-server --version
+# Should print: 0.1.1
+
+# Or via pipx:
+pipx run python-docs-mcp-server --version
+# Should print: 0.1.1
+```
+
+## v0.1.1 Release Checklist
+
+Complete these steps in order. Each step has a checkbox -- do not skip ahead.
+
+### Pre-Release Verification
+
+- [ ] All CI tests green on main: check https://github.com/<owner>/python-docs-mcp-server/actions/workflows/ci.yml
+- [ ] Local test suite passes:
+  ```bash
+  uv run pytest --tb=short -q
+  ```
+- [ ] Version in `pyproject.toml` is `0.1.1`:
+  ```bash
+  grep '^version' pyproject.toml
+  ```
+- [ ] Integration tests from `.github/INTEGRATION-TEST.md` are complete and signed off
+- [ ] Doctor subcommand passes:
+  ```bash
+  uv run python-docs-mcp-server doctor
+  ```
+
+### PyPI Trusted Publishing Setup (one-time)
+
+- [ ] PyPI pending publisher configured at https://pypi.org/manage/account/publishing/:
+  - PyPI project name: `python-docs-mcp-server`
+  - Owner: `<your-github-username>`
+  - Repository: `python-docs-mcp-server`
+  - Workflow name: `release.yml`
+  - Environment name: `pypi`
+- [ ] GitHub environment `pypi` created in repo Settings > Environments
+
+### Tag and Release
+
+- [ ] Create the annotated tag:
+  ```bash
+  git tag -a v0.1.1 -m "Release v0.1.1
+
+  First public release of python-docs-mcp-server.
+
+  A read-only, version-aware MCP retrieval server over Python
+  standard library documentation (3.10 through 3.14).
+
+  Installable via: uvx python-docs-mcp-server"
+  ```
+- [ ] Push the tag to trigger the release workflow:
+  ```bash
+  git push origin v0.1.1
+  ```
+- [ ] Monitor the workflow run: https://github.com/<owner>/python-docs-mcp-server/actions/workflows/release.yml
+- [ ] Verify all three jobs pass: `build` -> `publish` -> `github-release`
+
+### Post-Release Verification (SHIP-06)
+
+- [ ] Package visible on PyPI: https://pypi.org/project/python-docs-mcp-server/0.1.2/
+- [ ] Attestation visible on PyPI package page (look for "Provenance" badge)
+- [ ] Fresh install test:
+  ```bash
+  # Clear any cached version
+  uv cache clean python-docs-mcp-server 2>/dev/null || true
+
+  # Install and verify version
+  uvx python-docs-mcp-server --version
+  # Expected output: 0.1.1
+  ```
+- [ ] Full README flow test (from a clean environment):
+  ```bash
+  # Step 1: Install
+  uvx python-docs-mcp-server --version
+  # Should print 0.1.1
+
+  # Step 2: Build index
+  uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
+  # Should complete successfully
+
+  # Step 3: Doctor check
+  uvx python-docs-mcp-server doctor
+  # All checks should PASS
+  ```
+- [ ] Slow E2E workflow passes:
+  - Run GitHub Actions workflow `Slow E2E`
+  - Confirm Python 3.13 and Python 3.14 jobs both pass
+  - Confirm each job installs the built wheel, runs
+    `build-index --versions 3.10,3.11,3.12,3.13,3.14`, `doctor`, and
+    `validate-corpus`
+
+### Post-PyPI Launch Pack Cleanup
+
+- [ ] Remove every temporary PyPI pre-release block from `README.md`:
+  - Mechanical pass: delete every region from `<!-- PRE-PYPI:` to `<!-- /PRE-PYPI -->` (inclusive). Each block now encloses its surrounding heading + lead-in sentence + code, so a single pass produces a clean README.
+  - Reference command:
+    `perl -0777 -i -pe 's/<!-- PRE-PYPI:.*?<!-- \/PRE-PYPI -->\n*//gs' README.md`
+  - Make the published package commands (`uvx python-docs-mcp-server ...`) the
+    primary install, build-index, MCP client, `doctor`, and `validate-corpus`
+    examples
+- [ ] Verify `README.md` has no temporary pre-release install artifacts:
+  ```bash
+  rg -n 'PRE[-]PYPI|Before PyPI publishing|Until the first PyPI|After PyPI publishing|git\\+https://github.com/.*/python-docs-mcp-server' README.md
+  ```
+  The command should return no output.
+- [ ] Review `docs/launch/` so no public launch copy still asks users to install
+  from GitHub source after the PyPI package is available. Intentional historical
+  pre-release drafts may remain, but they must stay clearly labeled as
+  pre-PyPI-only.
+- [ ] Submit `server.json` to https://registry.modelcontextprotocol.io/ via the
+  `mcp-publisher` CLI after the PyPI smoke test passes; verify the registry
+  listing appears and points at version 0.1.1
+- [ ] Use the post-PyPI draft in `docs/launch/show-hn.md` for the HN submission
+- [ ] Use `docs/launch/reddit-posts.md` for the r/Python and r/LocalLLaMA
+  submissions after the PyPI release smoke test passes
+- [ ] Commit and push the README cleanup before public launch posts go out
+
+- [ ] Claude Desktop test with published package:
+  Configure `mcpServers` with `uvx python-docs-mcp-server` and verify
+  "what is asyncio.TaskGroup" returns a correct hit
+
+### Release Complete
+
+- [ ] GitHub Release exists with attached artifacts
+- [ ] PyPI page shows 0.1.1 with attestation
+- [ ] README install instructions verified end-to-end
+- [ ] README no longer contains temporary pre-PyPI GitHub-source install blocks
+- [ ] Slow E2E workflow passed for the release candidate
+- [ ] Tag v0.1.1 exists in git
+
+**Release date**: _______________
+**Released by**: _______________

python_docs_mcp_server-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12", "3.13"]
+
+    runs-on: ${{ matrix.os }}
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run linter
+        run: uv run ruff check src/ tests/
+
+      - name: Run type checker
+        run: uv run pyright src/
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q
+
+      - name: Verify wheel contents
+        run: |
+          uv build
+          uv run python -c "
+          import zipfile, glob, sys
+          wheels = glob.glob('dist/*.whl')
+          if not wheels:
+              print('No wheel found')
+              sys.exit(1)
+          with zipfile.ZipFile(wheels[0]) as zf:
+              names = zf.namelist()
+              if not any('synonyms.yaml' in n for n in names):
+                  print('synonyms.yaml not found in wheel')
+                  sys.exit(1)
+              print('Wheel contents OK')
+          "

python_docs_mcp_server-0.1.2/.github/workflows/e2e.yml

@@ -0,0 +1,57 @@
+name: Slow E2E
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 4 * * 1"
+
+jobs:
+  installed-build-index:
+    name: Installed build-index (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Build package
+        run: uv build
+
+      - name: Install wheel in clean virtual environment
+        run: |
+          uv run --python ${{ matrix.python-version }} python -m venv .e2e-venv
+          .e2e-venv/bin/python -m pip install --upgrade pip
+          .e2e-venv/bin/python -m pip install dist/*.whl
+          .e2e-venv/bin/python-docs-mcp-server --version
+
+      - name: Build and validate full docs index
+        env:
+          HOME: ${{ runner.temp }}/mcp-python-docs-home
+          XDG_CACHE_HOME: ${{ runner.temp }}/mcp-python-docs-cache
+        run: |
+          set -o pipefail
+          .e2e-venv/bin/python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14 \
+            2>&1 | tee "${RUNNER_TEMP}/build-index-${{ matrix.python-version }}.log"
+          .e2e-venv/bin/python-docs-mcp-server doctor
+          .e2e-venv/bin/python-docs-mcp-server validate-corpus
+
+      - name: Upload E2E logs and cache artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-python-${{ matrix.python-version }}
+          path: |
+            ${{ runner.temp }}/build-index-${{ matrix.python-version }}.log
+            ${{ runner.temp }}/mcp-python-docs-cache
+          retention-days: 7

python_docs_mcp_server-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,119 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Build & Test
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${PKG_VERSION}"
+            exit 1
+          fi
+          echo "Version check passed: ${PKG_VERSION}"
+
+      - name: Run linter
+        run: uv run ruff check src/ tests/
+
+      - name: Run type checker
+        run: uv run pyright src/
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q
+
+      - name: Build package
+        run: uv build
+
+      - name: Verify wheel contents
+        run: |
+          uv run python -c "
+          import zipfile, glob, sys
+          wheels = glob.glob('dist/*.whl')
+          if not wheels:
+              print('No wheel found')
+              sys.exit(1)
+          with zipfile.ZipFile(wheels[0]) as zf:
+              names = zf.namelist()
+              if not any('synonyms.yaml' in n for n in names):
+                  print('synonyms.yaml not found in wheel')
+                  sys.exit(1)
+              print('Wheel contents OK')
+          "
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    name: Publish to PyPI
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+      attestations: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: 'dist/*'
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    name: Create GitHub Release
+    timeout-minutes: 10
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true