fix: harden cache constructor and tighten package-docs types

- persistent_cache: move _fingerprint_index() inside the try-except
  so a missing index.db disables the cache cleanly instead of raising
  FileNotFoundError out of the constructor and crashing server startup
  (CodeRabbit Major)

- models: tighten PackageDocsSource.kind and PackageDocsResult
  .trust_boundary to Literal types so invalid values fail validation
  at construction (CodeRabbit nitpick); add PackageKind alias and
  propagate it through package_docs._source signature, with a cast at
  the dynamic _ALLOWED-derived call site (runtime-safe — the allowlist
  enumeration matches the Literal exactly)

Tests: cache disables gracefully on missing index, PackageDocsSource
rejects unknown kind, PackageDocsResult rejects unknown trust_boundary.

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

Author: ayhammouda

src/mcp_server_python_docs/models.py

@@ -167,13 +167,31 @@ class DetectPythonVersionResult(BaseModel):
 
 # --- lookup_package_docs models ---
 
+# Bounded kind vocabulary: hardcoded values from `_source` calls plus the
+# normalized members of `_ALLOWED` (with spaces → underscores) in
+# services/package_docs.py. Keep these in sync.
+PackageKind = Literal[
+    "pypi",
+    "docs",
+    "documentation",
+    "homepage",
+    "home_page",
+    "source",
+    "source_code",
+    "repository",
+    "repo",
+]
+
 
 class PackageDocsSource(BaseModel):
     """A package-declared documentation or project source URL."""
 
     label: str = Field(description="Label from PyPI metadata or a normalized core metadata field")
     url: str = Field(description="HTTP(S) URL declared by the package on PyPI")
-    kind: str = Field(description="Source category, such as docs, homepage, source, or pypi")
+    kind: PackageKind = Field(
+        description="Source category: pypi, docs, documentation, homepage, home_page, "
+        "source, source_code, repository, or repo"
+    )
     declared_by: str = Field(description="Where this source declaration came from")
 
 
@@ -184,7 +202,7 @@ class PackageDocsResult(BaseModel):
     version: str = Field(description="Latest version reported by PyPI metadata")
     summary: str = Field(default="", description="Package summary from PyPI metadata")
     metadata_source: str = Field(description="Official PyPI JSON API URL used for lookup")
-    trust_boundary: str = Field(
+    trust_boundary: Literal["pypi-declared-metadata"] = Field(
         default="pypi-declared-metadata",
         description="Indicates results are limited to PyPI/project-declared metadata",
     )

src/mcp_server_python_docs/services/package_docs.py

@@ -8,12 +8,16 @@
 import json
 import re
 from collections.abc import Callable
-from typing import Protocol
+from typing import Protocol, cast
 from urllib.error import HTTPError, URLError
 from urllib.parse import quote, urlparse
 from urllib.request import Request, urlopen
 
-from mcp_server_python_docs.models import PackageDocsResult, PackageDocsSource
+from mcp_server_python_docs.models import (
+    PackageDocsResult,
+    PackageDocsSource,
+    PackageKind,
+)
 from mcp_server_python_docs.services.observability import log_tool_call
 
 _ALLOWED = {
@@ -57,7 +61,7 @@ def _http_url(url: object) -> str | None:
     return url.strip() if parsed.scheme in {"http", "https"} and parsed.netloc else None
 
 
-def _source(label: str, url: object, kind: str) -> PackageDocsSource | None:
+def _source(label: str, url: object, kind: PackageKind) -> PackageDocsSource | None:
     valid = _http_url(url)
     if valid is None:
         return None
@@ -133,7 +137,10 @@ def lookup(self, package: str) -> PackageDocsResult:
             for label, url in project_urls.items():
                 lowered = str(label).strip().lower()
                 if lowered in _ALLOWED:
-                    found = _source(str(label), url, lowered.replace(" ", "_"))
+                    # Runtime-safe: members of `_ALLOWED` (with spaces → underscores)
+                    # are exactly the non-pypi entries in the PackageKind Literal.
+                    derived_kind = cast(PackageKind, lowered.replace(" ", "_"))
+                    found = _source(str(label), url, derived_kind)
                     if found is not None and found not in sources:
                         sources.append(found)
                 else:

src/mcp_server_python_docs/services/persistent_cache.py

@@ -27,7 +27,9 @@ class PersistentDocsCache:
 
     def __init__(self, cache_path: Path, index_path: Path) -> None:
         self._cache_path = Path(cache_path)
-        self._fingerprint = self._fingerprint_index(Path(index_path))
+        # Set after fingerprint stat succeeds; stays "" if init fails so the
+        # cache disables cleanly without leaking partial state.
+        self._fingerprint = ""
         self._hits = self._misses = self._writes = 0
         # ``check_same_thread=False`` lets multiple threads share the connection,
         # but per the Python sqlite3 docs writes must still be serialized by the
@@ -36,6 +38,7 @@ def __init__(self, cache_path: Path, index_path: Path) -> None:
         self._lock = threading.Lock()
         self._conn: sqlite3.Connection | None = None
         try:
+            self._fingerprint = self._fingerprint_index(Path(index_path))
             self._cache_path.parent.mkdir(parents=True, exist_ok=True)
             self._conn = sqlite3.connect(str(self._cache_path), check_same_thread=False)
             self._conn.execute("PRAGMA journal_mode = WAL")

tests/test_package_docs.py

@@ -4,6 +4,10 @@
 import json
 from urllib.error import HTTPError, URLError
 
+import pytest
+from pydantic import ValidationError
+
+from mcp_server_python_docs.models import PackageDocsResult, PackageDocsSource
 from mcp_server_python_docs.services.package_docs import (
     _PYPI_METADATA_MAX_BYTES,
     PackageDocsService,
@@ -135,3 +139,27 @@ def invalid_utf8(url: str, timeout: float):
     utf8_result = PackageDocsService(fetcher=invalid_utf8).lookup("demo")
     assert utf8_result.sources == []
     assert utf8_result.note == "Unable to retrieve PyPI metadata: UnicodeDecodeError."
+
+
+def test_package_docs_source_rejects_unknown_kind():
+    """``kind`` is a controlled vocabulary — unknown values must fail validation.
+
+    Regression for CodeRabbit nitpick: tightening ``kind`` from ``str`` to a
+    ``Literal`` formalizes the implicit contract enforced by the ``_ALLOWED``
+    set in package_docs.py and the hardcoded values used by ``_source``.
+    """
+    with pytest.raises(ValidationError):
+        PackageDocsSource(
+            label="bogus", url="https://x/", kind="bogus_kind", declared_by="x"
+        )
+
+
+def test_package_docs_result_rejects_unknown_trust_boundary():
+    """``trust_boundary`` is fixed at construction — divergence must fail."""
+    with pytest.raises(ValidationError):
+        PackageDocsResult(
+            package="x",
+            version="1",
+            metadata_source="https://pypi.org/pypi/x/json",
+            trust_boundary="something-else",
+        )

tests/test_persistent_docs_cache.py

@@ -184,6 +184,27 @@ def test_invalid_cached_json_is_best_effort_miss(tmp_path: Path, caplog):
     assert cache.stats().misses == 1
 
 
+def test_cache_disables_gracefully_when_index_missing(tmp_path: Path, caplog):
+    """Constructor must not raise when index.db is missing.
+
+    Regression for CodeRabbit Major: ``_fingerprint_index()`` calls
+    ``Path.stat()`` which raises ``FileNotFoundError``; without guarding,
+    this turns an optional cache into a startup failure for the whole server.
+    """
+    cache_path = tmp_path / "cache.sqlite3"
+    missing_index = tmp_path / "does-not-exist.db"
+    assert not missing_index.exists()
+
+    with caplog.at_level(logging.WARNING):
+        cache = PersistentDocsCache(cache_path, missing_index)
+
+    assert "Persistent docs cache disabled" in caplog.text
+    # Cache should be disabled — get returns None, put is a no-op
+    assert cache.get(
+        version="3.13", slug="x", anchor=None, max_chars=100, start_index=0
+    ) is None
+
+
 def test_concurrent_puts_serialize_safely_without_lost_writes(tmp_path: Path):
     """Concurrent put() must not race on the shared connection or stats counter.