fix(ingestion): serial Sphinx build on Python 3.14+ (forkserver pickling)

Python 3.14 changed the default multiprocessing start method on POSIX from
fork to forkserver. forkserver pickles the work sent to child processes, but
Sphinx's parallel build (-j auto) passes a ParallelTasks object containing an
unpicklable local closure (Builder._read_parallel.<locals>.merge), so
build-index failed on 3.14 with _pickle.PicklingError. Caught by the Slow E2E
3.14 job; 3.13 (still fork) was unaffected.

Add sphinx_parallel_jobs(version_info) -> '1' on >=3.14 else 'auto', and use
it in build_sphinx_json_command. The Sphinx venv is created from the current
interpreter, so sys.version_info is the correct signal. Server runtime is
unaffected; only the offline index build changes.

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

Author: ayhammouda

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).
 
+## [Unreleased]
+
+### 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

src/mcp_server_python_docs/ingestion/sphinx_json.py

@@ -13,6 +13,7 @@
 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),
     ]

tests/test_ingestion.py

@@ -34,6 +34,7 @@
     parse_fjson,
     populate_synonyms,
     rebuild_fts_indexes,
+    sphinx_parallel_jobs,
     write_json_build_requirements,
     write_sphinx_json_sitecustomize,
 )
@@ -227,11 +228,22 @@ def test_build_command_uses_json_builder_and_classic_theme(self, tmp_path):
             "-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) ──