python-docs-mcp-server 0.2.0__tar.gz → 0.2.1__tar.gz

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.2.1] — 2026-05-29
+
+### Fixed
+
+- **`build-index` on Python 3.14** — Sphinx's parallel JSON build (`-j auto`)
+  raised `_pickle.PicklingError` on Python 3.14, which flipped the default
+  `multiprocessing` start method on POSIX from `fork` to `forkserver`
+  (`forkserver` must pickle worker tasks, but Sphinx's `ParallelTasks` holds an
+  unpicklable local closure). The builder now falls back to a serial build
+  (`-j 1`) on 3.14+ while keeping the parallel path on `fork`-default
+  interpreters (3.13 and earlier). Server runtime behavior is unchanged.
+
 ## [0.2.0] — 2026-05-29
 
 ### Added

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docs-mcp-server
-Version: 0.2.0
+Version: 0.2.1
 Summary: The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT, token-frugal.
 Author-email: Aymen Hammouda <hammouda.aymen@gmail.com>
 License-Expression: MIT

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-docs-mcp-server"
-version = "0.2.0"
+version = "0.2.1"
 description = "The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT, token-frugal."
 readme = "README.md"
 license = "MIT"

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/ayhammouda/python-docs-mcp-server",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.2.1",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "python-docs-mcp-server",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/src/mcp_server_python_docs/ingestion/sphinx_json.py

@@ -13,6 +13,7 @@ import logging
 import os
 import re
 import sqlite3
+import sys
 from collections.abc import Mapping
 from pathlib import Path
 
@@ -166,6 +167,25 @@ def make_sphinx_json_env(
     return env
 
 
+def sphinx_parallel_jobs(
+    version_info: tuple[int, ...] = (sys.version_info.major, sys.version_info.minor),
+) -> str:
+    """Return the Sphinx ``-j`` value for the build interpreter.
+
+    The Sphinx venv is created from the current interpreter (``venv.create``),
+    so ``sys.version_info`` reflects the Python that will run ``sphinx-build``.
+
+    Python 3.14 changed the default ``multiprocessing`` start method on
+    POSIX from ``fork`` to ``forkserver``. ``forkserver`` pickles the work
+    handed to child processes, but Sphinx's parallel build passes a
+    ``ParallelTasks`` object holding a local closure
+    (``Builder._read_parallel.<locals>.merge``) that cannot be pickled, so
+    ``-j auto`` raises ``_pickle.PicklingError`` on 3.14+. Fall back to a
+    serial build there; ``fork``-default interpreters keep the parallel path.
+    """
+    return "1" if version_info >= (3, 14) else "auto"
+
+
 def build_sphinx_json_command(
     sphinx_build: Path | str,
     doc_dir: Path | str,
@@ -179,7 +199,7 @@ def build_sphinx_json_command(
         "-D",
         "html_theme=classic",
         "-j",
-        "auto",
+        sphinx_parallel_jobs(),
         str(doc_dir),
         str(json_out),
     ]

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/tests/test_ingestion.py

@@ -34,6 +34,7 @@ from mcp_server_python_docs.ingestion.sphinx_json import (
     parse_fjson,
     populate_synonyms,
     rebuild_fts_indexes,
+    sphinx_parallel_jobs,
     write_json_build_requirements,
     write_sphinx_json_sitecustomize,
 )
@@ -227,11 +228,22 @@ class TestSphinxJsonCommand:
             "-D",
             "html_theme=classic",
             "-j",
-            "auto",
+            sphinx_parallel_jobs(),
             str(doc_dir),
             str(json_out),
         ]
 
+    def test_sphinx_parallel_jobs_auto_before_314(self):
+        """Pre-3.14 interpreters keep the parallel 'auto' build (fork default)."""
+        assert sphinx_parallel_jobs((3, 10, 0)) == "auto"
+        assert sphinx_parallel_jobs((3, 13, 5)) == "auto"
+
+    def test_sphinx_parallel_jobs_serial_on_314_plus(self):
+        """3.14+ flipped multiprocessing to forkserver, which can't pickle
+        Sphinx's parallel ParallelTasks closures -> force a serial build."""
+        assert sphinx_parallel_jobs((3, 14, 0)) == "1"
+        assert sphinx_parallel_jobs((3, 15, 1)) == "1"
+
 
 # ── fjson parsing tests (INGR-C-04) ──
 

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/tests/test_mcp_get_docs_cache_smoke.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 
 import sqlite3
 import subprocess
-import sys
 from pathlib import Path
 
 from mcp_server_python_docs.services.persistent_cache import _NO_ANCHOR_KEY
@@ -14,6 +13,7 @@ from tests.test_stdio_smoke import (
     _isolated_cache_env,
     _make_notification,
     _make_request,
+    _run_server_until_responses,
 )
 
 
@@ -80,13 +80,10 @@ def _create_contentful_json_index(cache_dir: Path) -> Path:
 
 
 def _run_server(stdin_data: bytes, env: dict[str, str]) -> subprocess.CompletedProcess:
-    return subprocess.run(
-        [sys.executable, "-m", "mcp_server_python_docs", "serve"],
-        input=stdin_data,
-        capture_output=True,
-        timeout=15,
-        env=env,
-    )
+    # Use the polling runner (waits for the tools/call reply before closing
+    # stdin) instead of subprocess.run(input=...), which races the server's
+    # EOF-driven shutdown and flakes on cold CI runners.
+    return _run_server_until_responses(stdin_data, env)
 
 
 def _initialized_tool_call(name: str, arguments: dict, req_id: int = 2) -> bytes:

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/tests/test_stdio_smoke.py

@@ -184,6 +184,87 @@ def _request_ids(stdin_data: bytes) -> list[int]:
     return request_ids
 
 
+def _run_server_until_responses(
+    stdin_data: bytes, env: dict[str, str], timeout: int = 15,
+) -> subprocess.CompletedProcess:
+    """Run the MCP server, stream stdin, and wait for every expected response.
+
+    Unlike a fire-and-forget ``subprocess.run(input=...)``, this keeps stdin
+    open until each request id in ``stdin_data`` has a matching response on
+    stdout (or the timeout/exit fires). That avoids a race where the server's
+    read loop shuts down on stdin EOF before the final ``tools/call`` handler
+    flushes its reply — the source of CI flakiness on cold runners.
+    """
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "mcp_server_python_docs", "serve"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+    assert proc.stdin is not None
+    assert proc.stdout is not None
+    assert proc.stderr is not None
+
+    stdout_lines: list[bytes] = []
+    stderr_lines: list[bytes] = []
+    output_lock = threading.Lock()
+
+    def read_stream(stream, sink: list[bytes]) -> None:
+        for line in iter(stream.readline, b""):
+            with output_lock:
+                sink.append(line)
+
+    stdout_thread = threading.Thread(
+        target=read_stream,
+        args=(proc.stdout, stdout_lines),
+        daemon=True,
+    )
+    stderr_thread = threading.Thread(
+        target=read_stream,
+        args=(proc.stderr, stderr_lines),
+        daemon=True,
+    )
+    stdout_thread.start()
+    stderr_thread.start()
+
+    expected_ids = _request_ids(stdin_data)
+    deadline = time.monotonic() + timeout
+    try:
+        for line in stdin_data.splitlines(keepends=True):
+            proc.stdin.write(line)
+            proc.stdin.flush()
+
+        while time.monotonic() < deadline:
+            with output_lock:
+                responses = _read_responses(b"".join(stdout_lines))
+            if all(_find_response(responses, req_id) is not None for req_id in expected_ids):
+                break
+            if proc.poll() is not None:
+                break
+            time.sleep(0.02)
+    finally:
+        try:
+            proc.stdin.close()
+        except BrokenPipeError:
+            # The subprocess may have already closed stdin after handling the requests.
+            pass
+        proc.stdin = None
+
+    remaining = max(0.1, deadline - time.monotonic())
+    try:
+        proc.wait(timeout=remaining)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=5)
+
+    stdout_thread.join(timeout=1)
+    stderr_thread.join(timeout=1)
+    stdout = b"".join(stdout_lines)
+    stderr = b"".join(stderr_lines)
+    return subprocess.CompletedProcess(proc.args, proc.returncode, stdout, stderr)
+
+
 class TestStdioSmoke:
     """Spawn the MCP server as a subprocess and verify protocol compliance."""
 
@@ -198,74 +279,7 @@ class TestStdioSmoke:
         self, stdin_data: bytes, timeout: int = 15,
     ) -> subprocess.CompletedProcess:
         """Run the server subprocess with line-paced stdin and return the result."""
-        proc = subprocess.Popen(
-            [sys.executable, "-m", "mcp_server_python_docs", "serve"],
-            stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            env=self.env,
-        )
-        assert proc.stdin is not None
-        assert proc.stdout is not None
-        assert proc.stderr is not None
-
-        stdout_lines: list[bytes] = []
-        stderr_lines: list[bytes] = []
-        output_lock = threading.Lock()
-
-        def read_stream(stream, sink: list[bytes]) -> None:
-            for line in iter(stream.readline, b""):
-                with output_lock:
-                    sink.append(line)
-
-        stdout_thread = threading.Thread(
-            target=read_stream,
-            args=(proc.stdout, stdout_lines),
-            daemon=True,
-        )
-        stderr_thread = threading.Thread(
-            target=read_stream,
-            args=(proc.stderr, stderr_lines),
-            daemon=True,
-        )
-        stdout_thread.start()
-        stderr_thread.start()
-
-        expected_ids = _request_ids(stdin_data)
-        deadline = time.monotonic() + timeout
-        try:
-            for line in stdin_data.splitlines(keepends=True):
-                proc.stdin.write(line)
-                proc.stdin.flush()
-
-            while time.monotonic() < deadline:
-                with output_lock:
-                    responses = _read_responses(b"".join(stdout_lines))
-                if all(_find_response(responses, req_id) is not None for req_id in expected_ids):
-                    break
-                if proc.poll() is not None:
-                    break
-                time.sleep(0.02)
-        finally:
-            try:
-                proc.stdin.close()
-            except BrokenPipeError:
-                # The subprocess may have already closed stdin after handling the requests.
-                pass
-            proc.stdin = None
-
-        remaining = max(0.1, deadline - time.monotonic())
-        try:
-            proc.wait(timeout=remaining)
-        except subprocess.TimeoutExpired:
-            proc.kill()
-            proc.wait(timeout=5)
-
-        stdout_thread.join(timeout=1)
-        stderr_thread.join(timeout=1)
-        stdout = b"".join(stdout_lines)
-        stderr = b"".join(stderr_lines)
-        return subprocess.CompletedProcess(proc.args, proc.returncode, stdout, stderr)
+        return _run_server_until_responses(stdin_data, self.env, timeout)
 
     def test_server_lists_tools_no_stdout_pollution(self):
         """Server returns tool list and stdout has no non-JSON-RPC bytes."""

{python_docs_mcp_server-0.2.0 → python_docs_mcp_server-0.2.1}/uv.lock

@@ -541,7 +541,7 @@ wheels = [
 
 [[package]]
 name = "python-docs-mcp-server"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },