python-docs-mcp-server 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

mcp_server_python_docs/__main__.py

@@ -65,6 +65,8 @@ logging.basicConfig(
 logger = logging.getLogger("mcp_server_python_docs")
 
 # === Now safe to import everything else ===
+import subprocess  # noqa: E402
+
 import click  # noqa: E402
 
 from mcp_server_python_docs.ingestion.cpython_versions import (  # noqa: E402
@@ -110,6 +112,33 @@ def serve() -> None:
         pass  # Client disconnected (HYGN-03)
 
 
+def _verify_cpython_source_sha(
+    clone_dir: str,
+    *,
+    version: str,
+    tag: str,
+    expected_sha: str,
+) -> None:
+    """Abort the docs build if a CPython tag resolves to unexpected content."""
+    rev_parse = subprocess.run(
+        ["git", "-C", clone_dir, "rev-parse", "HEAD"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    actual_sha = rev_parse.stdout.strip()
+    if actual_sha != expected_sha:
+        logger.error(
+            "CPython %s source integrity check failed: tag %s "
+            "resolved to %s, expected %s. Aborting build.",
+            version,
+            tag,
+            actual_sha,
+            expected_sha,
+        )
+        raise SystemExit(1)
+
+
 @main.command("build-index")
 @click.option(
     "--versions",
@@ -124,7 +153,6 @@ def serve() -> None:
 def build_index(versions: str, skip_content: bool) -> None:
     """Build the documentation index from objects.inv and Sphinx JSON."""
     import shutil
-    import subprocess
     import tempfile
     import venv
     from pathlib import Path
@@ -224,6 +252,12 @@ def build_index(versions: str, skip_content: bool) -> None:
                         capture_output=True,
                         text=True,
                     )
+                    _verify_cpython_source_sha(
+                        clone_dir,
+                        version=version,
+                        tag=config["tag"],
+                        expected_sha=config["sha"],
+                    )
 
                     # Create dedicated Sphinx venv (INGR-C-02)
                     venv_dir = os.path.join(clone_dir, "_sphinx_venv")

mcp_server_python_docs/cache/__init__.py

@@ -0,0 +1 @@
+"""Cache support utilities."""

mcp_server_python_docs/cache/codec.py

@@ -0,0 +1,114 @@
+"""Versioned codecs for cache-at-rest payloads."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import zstandard as zstd
+
+_SUPPORTED_CODECS = ["none", "zstd", "zstd-dict-v1"]
+
+
+@dataclass(frozen=True)
+class _Codec:
+    encode: Callable[[str, object | None], bytes]
+    decode: Callable[[bytes, object | None], str]
+
+
+def list_supported() -> list[str]:
+    """Return codec ids in stable preference order."""
+
+    return list(_SUPPORTED_CODECS)
+
+
+def encode(text: str, codec: str, *, dictionary: object | None = None) -> bytes:
+    """Encode text using a supported cache codec."""
+
+    try:
+        handler = _REGISTRY[codec]
+    except KeyError as e:
+        raise ValueError(f"Unsupported cache codec: {codec}") from e
+    return handler.encode(text, dictionary)
+
+
+def decode(blob: bytes, codec: str, *, dictionary: object | None = None) -> str:
+    """Decode text using the codec stored with the cache row."""
+
+    try:
+        handler = _REGISTRY[codec]
+    except KeyError as e:
+        raise ValueError(f"Unsupported cache codec: {codec}") from e
+    return handler.decode(blob, dictionary)
+
+
+def _encode_none(text: str, dictionary: object | None) -> bytes:
+    _reject_dictionary("none", dictionary)
+    return text.encode("utf-8")
+
+
+def _decode_none(blob: bytes, dictionary: object | None) -> str:
+    _reject_dictionary("none", dictionary)
+    return blob.decode("utf-8")
+
+
+def _encode_zstd(text: str, dictionary: object | None) -> bytes:
+    _reject_dictionary("zstd", dictionary)
+    try:
+        return zstd.ZstdCompressor().compress(text.encode("utf-8"))
+    except zstd.ZstdError as e:
+        raise ValueError(f"zstd encode failed: {e}") from e
+
+
+def _decode_zstd(blob: bytes, dictionary: object | None) -> str:
+    _reject_dictionary("zstd", dictionary)
+    try:
+        return zstd.ZstdDecompressor().decompress(blob).decode("utf-8")
+    except zstd.ZstdError as e:
+        raise ValueError(f"zstd decode failed: {e}") from e
+
+
+def _encode_zstd_dict(text: str, dictionary: object | None) -> bytes:
+    try:
+        return zstd.ZstdCompressor(dict_data=_coerce_dictionary(dictionary)).compress(
+            text.encode("utf-8")
+        )
+    except zstd.ZstdError as e:
+        raise ValueError(f"zstd dictionary encode failed: {e}") from e
+
+
+def _decode_zstd_dict(blob: bytes, dictionary: object | None) -> str:
+    try:
+        return (
+            zstd.ZstdDecompressor(dict_data=_coerce_dictionary(dictionary))
+            .decompress(blob)
+            .decode("utf-8")
+        )
+    except zstd.ZstdError as e:
+        raise ValueError(f"zstd dictionary decode failed: {e}") from e
+
+
+def _reject_dictionary(codec: str, dictionary: object | None) -> None:
+    if dictionary is not None:
+        raise ValueError(f"Codec {codec!r} does not use a dictionary")
+
+
+def _coerce_dictionary(dictionary: object | None) -> zstd.ZstdCompressionDict:
+    if dictionary is None:
+        raise ValueError("Codec 'zstd-dict-v1' requires an explicit dictionary")
+    if isinstance(dictionary, zstd.ZstdCompressionDict):
+        return dictionary
+    if isinstance(dictionary, bytes):
+        return zstd.ZstdCompressionDict(dictionary)
+    if isinstance(dictionary, bytearray | memoryview):
+        return zstd.ZstdCompressionDict(bytes(dictionary))
+    raise TypeError(f"Unsupported zstd dictionary object: {type(dictionary).__name__}")
+
+
+_REGISTRY: dict[str, _Codec] = {
+    "none": _Codec(_encode_none, _decode_none),
+    "zstd": _Codec(_encode_zstd, _decode_zstd),
+    "zstd-dict-v1": _Codec(_encode_zstd_dict, _decode_zstd_dict),
+}
+
+__all__ = ["decode", "encode", "list_supported"]

mcp_server_python_docs/ingestion/cpython_versions.py

@@ -8,6 +8,7 @@ class CPythonDocsBuildConfig(TypedDict):
     """Build settings for one CPython documentation release."""
 
     tag: str
+    sha: str
     sphinx_pin: str
 
 
@@ -21,12 +22,32 @@ SUPPORTED_DOC_VERSIONS: Final[tuple[str, ...]] = (
 
 SUPPORTED_DOC_VERSIONS_CSV: Final[str] = ",".join(SUPPORTED_DOC_VERSIONS)
 
-# CPython git tags are pinned so content builds are reproducible and do not
-# drift when a maintenance branch receives new commits.
+# CPython git SHAs are authoritative for content build integrity. Tags are kept
+# for human-readable version mapping, but a moved tag must fail verification.
 CPYTHON_DOCS_BUILD_CONFIG: Final[dict[str, CPythonDocsBuildConfig]] = {
-    "3.10": {"tag": "v3.10.20", "sphinx_pin": "sphinx==3.4.3"},
-    "3.11": {"tag": "v3.11.15", "sphinx_pin": "sphinx~=7.2.0"},
-    "3.12": {"tag": "v3.12.13", "sphinx_pin": "sphinx~=8.2.0"},
-    "3.13": {"tag": "v3.13.13", "sphinx_pin": "sphinx<9.0.0"},
-    "3.14": {"tag": "v3.14.4", "sphinx_pin": "sphinx<9.0.0"},
+    "3.10": {
+        "tag": "v3.10.20",
+        "sha": "842e987df856a5d4db37933c62a3456930a19092",
+        "sphinx_pin": "sphinx==3.4.3",
+    },
+    "3.11": {
+        "tag": "v3.11.15",
+        "sha": "2340a037f7450e70fccfe411e6531afb4d57a312",
+        "sphinx_pin": "sphinx~=7.2.0",
+    },
+    "3.12": {
+        "tag": "v3.12.13",
+        "sha": "3bb231a6a5dc02b95658877318bf61501a7209e9",
+        "sphinx_pin": "sphinx~=8.2.0",
+    },
+    "3.13": {
+        "tag": "v3.13.13",
+        "sha": "01104ce1beb3135c2e0c01ec835b994c1f55a1c0",
+        "sphinx_pin": "sphinx<9.0.0",
+    },
+    "3.14": {
+        "tag": "v3.14.4",
+        "sha": "23116f998f6789d8c2fbe5ed5b8146854c8c2a4f",
+        "sphinx_pin": "sphinx<9.0.0",
+    },
 }

mcp_server_python_docs/services/persistent_cache.py

@@ -10,10 +10,13 @@ from typing import NamedTuple
 
 from pydantic import ValidationError
 
+from mcp_server_python_docs.cache.codec import decode as decode_cache_payload
+from mcp_server_python_docs.cache.codec import encode as encode_cache_payload
 from mcp_server_python_docs.models import GetDocsResult
 
 logger = logging.getLogger(__name__)
 _NO_ANCHOR_KEY = "\x00mcp-python-docs:no-anchor\x00"
+DEFAULT_RETRIEVED_DOCS_CACHE_CODEC = "zstd"
 
 
 class CacheStats(NamedTuple):
@@ -25,8 +28,15 @@ class CacheStats(NamedTuple):
 class PersistentDocsCache:
     """Persist get_docs results by index fingerprint, version, and request identity."""
 
-    def __init__(self, cache_path: Path, index_path: Path) -> None:
+    def __init__(
+        self,
+        cache_path: Path,
+        index_path: Path,
+        *,
+        default_codec: str = DEFAULT_RETRIEVED_DOCS_CACHE_CODEC,
+    ) -> None:
         self._cache_path = Path(cache_path)
+        self._default_codec = default_codec
         # Set after fingerprint stat succeeds; stays "" if init fails so the
         # cache disables cleanly without leaking partial state.
         self._fingerprint = ""
@@ -47,9 +57,11 @@ class PersistentDocsCache:
                 "CREATE TABLE IF NOT EXISTS retrieved_docs_cache ("
                 "index_fingerprint TEXT NOT NULL, version TEXT NOT NULL, slug TEXT NOT NULL, "
                 "anchor TEXT NOT NULL, max_chars INTEGER NOT NULL, start_index INTEGER NOT NULL, "
-                "result_json TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, "
+                "result_json TEXT NOT NULL, compression TEXT NOT NULL DEFAULT 'none', "
+                "created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, "
                 "PRIMARY KEY (index_fingerprint, version, slug, anchor, max_chars, start_index))"
             )
+            self._ensure_compression_column()
             self._conn.execute(
                 "DELETE FROM retrieved_docs_cache WHERE index_fingerprint != ?",
                 (self._fingerprint,),
@@ -74,6 +86,18 @@ class PersistentDocsCache:
     def _anchor_key(anchor: str | None) -> str:
         return _NO_ANCHOR_KEY if anchor is None else anchor
 
+    def _ensure_compression_column(self) -> None:
+        if self._conn is None:
+            return
+        columns = {
+            row[1] for row in self._conn.execute("PRAGMA table_info(retrieved_docs_cache)")
+        }
+        if "compression" not in columns:
+            self._conn.execute(
+                "ALTER TABLE retrieved_docs_cache "
+                "ADD COLUMN compression TEXT NOT NULL DEFAULT 'none'"
+            )
+
     def stats(self) -> CacheStats:
         return CacheStats(self._hits, self._misses, self._writes)
 
@@ -87,7 +111,8 @@ class PersistentDocsCache:
         with self._lock:
             try:
                 row = self._conn.execute(
-                    "SELECT result_json FROM retrieved_docs_cache WHERE index_fingerprint = ? "
+                    "SELECT result_json, compression FROM retrieved_docs_cache "
+                    "WHERE index_fingerprint = ? "
                     "AND version = ? AND slug = ? AND anchor = ? AND max_chars = ? "
                     "AND start_index = ?",
                     (
@@ -107,8 +132,10 @@ class PersistentDocsCache:
                 self._misses += 1
                 return None
             try:
-                result = GetDocsResult.model_validate_json(row[0])
-            except (ValidationError, ValueError) as e:
+                payload = row[0].encode("utf-8") if isinstance(row[0], str) else bytes(row[0])
+                result_json = decode_cache_payload(payload, row[1])
+                result = GetDocsResult.model_validate_json(result_json)
+            except (ValidationError, ValueError, TypeError) as e:
                 self._misses += 1
                 logger.warning("Persistent docs cache entry ignored: %s", e)
                 return None
@@ -123,7 +150,7 @@ class PersistentDocsCache:
                 self._conn.execute(
                     "INSERT OR REPLACE INTO retrieved_docs_cache "
                     "(index_fingerprint, version, slug, anchor, max_chars, start_index, "
-                    "result_json) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    "result_json, compression) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
                     (
                         self._fingerprint,
                         result.version,
@@ -131,7 +158,8 @@ class PersistentDocsCache:
                         self._anchor_key(result.anchor),
                         max_chars,
                         start_index,
-                        result.model_dump_json(),
+                        encode_cache_payload(result.model_dump_json(), self._default_codec),
+                        self._default_codec,
                     ),
                 )
                 self._conn.commit()

{python_docs_mcp_server-0.2.1.dist-info → python_docs_mcp_server-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docs-mcp-server
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -22,6 +22,7 @@ Requires-Dist: platformdirs>=4.0
 Requires-Dist: pydantic<3.0,>=2.0.0
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: sphobjinv<3.0,>=2.4
+Requires-Dist: zstandard>=0.23.0
 Provides-Extra: pysqlite3
 Requires-Dist: pysqlite3-binary>=0.5.4; extra == 'pysqlite3'
 Description-Content-Type: text/markdown
@@ -37,7 +38,7 @@ Description-Content-Type: text/markdown
 [![CodeQL](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ayhammouda/python-docs-mcp-server/badge)](https://scorecard.dev/viewer/?uri=github.com/ayhammouda/python-docs-mcp-server)
 [![python-docs-mcp-server MCP server](https://glama.ai/mcp/servers/ayhammouda/python-docs-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/ayhammouda/python-docs-mcp-server)
-[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.1.4-0f766e)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ayhammouda%2Fpython-docs-mcp-server)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-latest-0f766e)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ayhammouda%2Fpython-docs-mcp-server)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
 [![No API Keys](https://img.shields.io/badge/API%20keys-none-success)](#why-use-it)

{python_docs_mcp_server-0.2.1.dist-info → python_docs_mcp_server-0.3.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 mcp_server_python_docs/__init__.py,sha256=sUtQT81momSAPMywIkgnR7BZxJHn53rpcjSE3CTAUws,499
-mcp_server_python_docs/__main__.py,sha256=_LmCa1p3O1gSnOcOC7UXoNbqmIo2LBha3FDsfUUkJ_8,21196
+mcp_server_python_docs/__main__.py,sha256=d6ZyRgkmOW7XUUgoGjOMEzCVoHL-aHuqmFKdxxkucvk,22165
 mcp_server_python_docs/app_context.py,sha256=5kK4JcTiKgJGOV_gFE8aVktYdtCpeDbZunIrlt4SxyA,1403
 mcp_server_python_docs/detection.py,sha256=bYYSfpMymHk9wehNW66oItX6yFUoCC2JXDRZLYpM0Vw,2860
 mcp_server_python_docs/diagnostics.py,sha256=FyC6QDFLvozARpYuMnaKfJwaN6BCzVycME_SkNs2YIs,2370
@@ -7,9 +7,11 @@ mcp_server_python_docs/errors.py,sha256=XTOm1raJfxS2adaOPZdwj0SuhpMAXAdjBsF2-zTv
 mcp_server_python_docs/models.py,sha256=A9XtcJPJFDa6jn7pHa4yDS1TPlnpIc3A7WEeKu4qqOw,10247
 mcp_server_python_docs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_server_python_docs/server.py,sha256=8F27o2hTyi1rwSNoMo8lGYXCvhwEHS7cVHI7n9p5Y2M,15469
+mcp_server_python_docs/cache/__init__.py,sha256=Eba8m5Xi3LYQKz5ictK9whVi_SZJWr5vZE1AtKDb26U,31
+mcp_server_python_docs/cache/codec.py,sha256=tOEuHDqa6ziF2T05JubtDg_QnqvYRuheZijZUTX9lpE,3653
 mcp_server_python_docs/data/synonyms.yaml,sha256=LgJxamZ9QT6Pykva7M1uM8juSd9ybHuv3vUOKrUFMg4,10696
 mcp_server_python_docs/ingestion/__init__.py,sha256=Yd7Jk7hD7XG3eoBVQpYiG94EwJGfI3qXxVCpA8JszYg,66
-mcp_server_python_docs/ingestion/cpython_versions.py,sha256=mEhjuT7q8Bo1aZ-zj6PSqmbq2Bz64g4xj50ttqA4QUU,977
+mcp_server_python_docs/ingestion/cpython_versions.py,sha256=_28TX26eGEiiEV_6NthaPg8vwvwjuus2yVLn7ktvcyo,1426
 mcp_server_python_docs/ingestion/inventory.py,sha256=5gQCWOo1tBiQgv-e_A9KR9n2xfP4YAnJrSmb0pFbzwY,5672
 mcp_server_python_docs/ingestion/publish.py,sha256=gra87NgH1i4T92nSwf3sqp4AnKuuzQfrcE7ySnDgcSQ,17247
 mcp_server_python_docs/ingestion/sphinx_json.py,sha256=OXrZ8LMeLFn2har2TVnWVNwMY9b5z1VCMioQdIE5gJE,20270
@@ -23,15 +25,15 @@ mcp_server_python_docs/services/compare.py,sha256=wWsgD8w9fl3L7gr-mcdd6ntY_V1pGt
 mcp_server_python_docs/services/content.py,sha256=7O5XGbR9QWICMxYAd-cp_pPF86tNLcYAMIwyCP_i8dk,5342
 mcp_server_python_docs/services/observability.py,sha256=rwnkIDelNkclHzuwsktGUoU2fzYCuiR1niVRmOwJHJg,4839
 mcp_server_python_docs/services/package_docs.py,sha256=0Qq8PtRL_KdiTFUtllaj4KFHz6u9L903zcORVpYmR1U,5605
-mcp_server_python_docs/services/persistent_cache.py,sha256=KpjutXAVhFPXB-QhgtShxWuTTG0mZWc7j-st7LglfL8,5747
+mcp_server_python_docs/services/persistent_cache.py,sha256=p1uhTkwmXRP-v79jaIPDTEv9Z0G0iqCUnUDKmFQA6GA,6956
 mcp_server_python_docs/services/search.py,sha256=Pjt4IDfnogWTGYKFJ_4ODbq1xbUZ0ybceD6yj7Ep6lw,4545
 mcp_server_python_docs/services/version.py,sha256=nPkWhksZo7B4QIp-knlSEvVXFmKIcVUq6tWRTJAe5aA,1467
 mcp_server_python_docs/services/version_resolution.py,sha256=rULBoqq97t0ZfSWSy-ecI3wALx5t_3OWuok1hZK8w0w,2643
 mcp_server_python_docs/storage/__init__.py,sha256=YNeNr7FW9Vgvo79oXgKXE3eGP0WwWDqRgTZ7lg7MFW4,62
 mcp_server_python_docs/storage/db.py,sha256=Lys8HN3IvgmNpr_qyocUQghcZnwHf2lz9eq_BFmwi54,5634
 mcp_server_python_docs/storage/schema.sql,sha256=4cXPktPQSLfbjkSjirpf0dA2CphlO9UCIKUxnLiIm_g,5637
-python_docs_mcp_server-0.2.1.dist-info/METADATA,sha256=cRyy9YN4VFMSHudIlNbZEW2NB2D6B9F72mwDK5FCUNM,13880
-python_docs_mcp_server-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_docs_mcp_server-0.2.1.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
-python_docs_mcp_server-0.2.1.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
-python_docs_mcp_server-0.2.1.dist-info/RECORD,,
+python_docs_mcp_server-0.3.0.dist-info/METADATA,sha256=_3VIV56ywUeSNOWBiexQl2RbhI8MO49wLmFsAQDPW34,13913
+python_docs_mcp_server-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_docs_mcp_server-0.3.0.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
+python_docs_mcp_server-0.3.0.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
+python_docs_mcp_server-0.3.0.dist-info/RECORD,,