python-docs-mcp-server 0.1.2__py3-none-any.whl

mcp_server_python_docs/services/cache.py

@@ -0,0 +1,111 @@
+"""LRU cache wrappers for hot read paths (OPS-04, OPS-05).
+
+Process-lifetime-scoped caches with no TTL and no invalidation.
+Users restart the server on rebuild (documented in PUBL-05).
+
+The cached functions are created as closures that capture the
+sqlite3.Connection at construction time. This is necessary because
+lru_cache requires hashable arguments, and sqlite3.Connection is
+not hashable.
+"""
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Callable
+from functools import lru_cache
+from typing import NamedTuple
+
+
+class CachedSection(NamedTuple):
+    """Cached section data -- lightweight container for LRU cache."""
+
+    heading: str
+    content_text: str
+    anchor: str
+    uri: str
+    document_id: int
+
+
+class CachedSymbol(NamedTuple):
+    """Cached symbol resolution result."""
+
+    qualified_name: str
+    symbol_type: str
+    uri: str
+    anchor: str
+    module: str
+    version: str
+
+
+def create_section_cache(db: sqlite3.Connection) -> Callable[[int], CachedSection | None]:
+    """Create an LRU-cached section lookup function (OPS-04).
+
+    Args:
+        db: Read-only SQLite connection (captured by closure).
+
+    Returns:
+        A function ``get_section(section_id: int) -> CachedSection | None``
+        with maxsize=512.
+    """
+
+    @lru_cache(maxsize=512)
+    def get_section_cached(section_id: int) -> CachedSection | None:
+        row = db.execute(
+            """
+            SELECT heading, content_text, anchor, uri, document_id
+            FROM sections
+            WHERE id = ?
+            """,
+            (section_id,),
+        ).fetchone()
+        if row is None:
+            return None
+        return CachedSection(
+            heading=row["heading"] or "",
+            content_text=row["content_text"] or "",
+            anchor=row["anchor"] or "",
+            uri=row["uri"] or "",
+            document_id=row["document_id"],
+        )
+
+    return get_section_cached
+
+
+def create_symbol_cache(db: sqlite3.Connection) -> Callable[[str, str], CachedSymbol | None]:
+    """Create an LRU-cached symbol resolution function (OPS-04).
+
+    Args:
+        db: Read-only SQLite connection (captured by closure).
+
+    Returns:
+        A function ``resolve_symbol(qualified_name: str, version: str) -> CachedSymbol | None``
+        with maxsize=128.
+    """
+
+    @lru_cache(maxsize=128)
+    def resolve_symbol_cached(
+        qualified_name: str, version: str
+    ) -> CachedSymbol | None:
+        row = db.execute(
+            """
+            SELECT s.qualified_name, s.symbol_type, s.uri, s.anchor,
+                   s.module, d.version
+            FROM symbols s
+            JOIN doc_sets d ON s.doc_set_id = d.id
+            WHERE s.qualified_name = ? AND d.version = ?
+            LIMIT 1
+            """,
+            (qualified_name, version),
+        ).fetchone()
+        if row is None:
+            return None
+        return CachedSymbol(
+            qualified_name=row["qualified_name"],
+            symbol_type=row["symbol_type"] or "symbol",
+            uri=row["uri"],
+            anchor=row["anchor"] or "",
+            module=row["module"] or "",
+            version=row["version"],
+        )
+
+    return resolve_symbol_cached

mcp_server_python_docs/services/content.py

@@ -0,0 +1,155 @@
+"""Content service — handles get_docs for page and section retrieval.
+
+When anchor is provided, returns just that section.
+When omitted, returns the full page with truncation/pagination.
+No MCP types imported — dependency rule enforced.
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from mcp_server_python_docs.errors import PageNotFoundError
+from mcp_server_python_docs.models import GetDocsResult
+from mcp_server_python_docs.retrieval.budget import apply_budget
+from mcp_server_python_docs.services.cache import create_section_cache
+from mcp_server_python_docs.services.observability import log_tool_call
+from mcp_server_python_docs.services.persistent_cache import PersistentDocsCache
+from mcp_server_python_docs.services.version_resolution import resolve_version_strict
+
+
+class ContentService:
+    """Content retrieval service for get_docs tool.
+
+    When anchor is provided, returns just that section.
+    When omitted, returns the full page with truncation/pagination.
+    """
+
+    def __init__(
+        self,
+        db: sqlite3.Connection,
+        persistent_cache: PersistentDocsCache | None = None,
+    ) -> None:
+        self._db = db
+        self._get_section = create_section_cache(db)
+        self._persistent_cache = persistent_cache
+
+    def _resolve_version(self, version: str | None) -> str:
+        """Resolve version to a concrete version string using shared resolution logic.
+
+        Defaults to the is_default=1 version when None is passed.
+        Raises VersionNotFoundError for unknown versions (MVER-03).
+        """
+        return resolve_version_strict(self._db, version)
+
+    @log_tool_call("get_docs")
+    def get_docs(
+        self,
+        slug: str,
+        version: str | None = None,
+        anchor: str | None = None,
+        max_chars: int = 8000,
+        start_index: int = 0,
+    ) -> GetDocsResult:
+        """Retrieve documentation content by slug, optionally narrowed to a section by anchor."""
+        resolved_version = self._resolve_version(version)
+
+        if self._persistent_cache is not None:
+            cached = self._persistent_cache.get(
+                version=resolved_version,
+                slug=slug,
+                anchor=anchor,
+                max_chars=max_chars,
+                start_index=start_index,
+            )
+            if cached is not None:
+                return cached
+
+        # Find the document
+        doc_row = self._db.execute(
+            """
+            SELECT d.id, d.title, d.slug
+            FROM documents d
+            JOIN doc_sets ds ON d.doc_set_id = ds.id
+            WHERE d.slug = ? AND ds.version = ?
+            LIMIT 1
+            """,
+            (slug, resolved_version),
+        ).fetchone()
+
+        if doc_row is None:
+            raise PageNotFoundError(
+                f"Page {slug!r} not found for version {resolved_version}"
+            )
+
+        doc_id = doc_row["id"]
+        doc_title = doc_row["title"]
+
+        if anchor is not None:
+            # Section-level retrieval — use cache for repeat reads (OPS-04)
+            id_row = self._db.execute(
+                "SELECT id FROM sections WHERE document_id = ? AND anchor = ? LIMIT 1",
+                (doc_id, anchor),
+            ).fetchone()
+
+            if id_row is None:
+                raise PageNotFoundError(
+                    f"Section {anchor!r} not found in {slug!r} v{resolved_version}"
+                )
+
+            cached = self._get_section(id_row["id"])
+            if cached is not None:
+                full_text = cached.content_text
+                title = cached.heading or doc_title
+            else:
+                raise PageNotFoundError(
+                    f"Section {anchor!r} not found in {slug!r} v{resolved_version}"
+                )
+        else:
+            # Page-level retrieval: concatenate all sections in ordinal order
+            section_rows = self._db.execute(
+                """
+                SELECT heading, content_text
+                FROM sections
+                WHERE document_id = ?
+                ORDER BY ordinal
+                """,
+                (doc_id,),
+            ).fetchall()
+
+            if not section_rows:
+                full_text = ""
+            else:
+                parts = []
+                for row in section_rows:
+                    heading = row["heading"] or ""
+                    content = row["content_text"] or ""
+                    if heading:
+                        parts.append(f"## {heading}\n\n{content}")
+                    else:
+                        parts.append(content)
+                full_text = "\n\n".join(parts)
+
+            title = doc_title
+
+        # Apply budget enforcement (RETR-08)
+        truncated_text, is_truncated, next_idx = apply_budget(
+            full_text, max_chars, start_index
+        )
+
+        result = GetDocsResult(
+            content=truncated_text,
+            slug=slug,
+            title=title,
+            version=resolved_version,
+            anchor=anchor,
+            char_count=len(full_text),
+            truncated=is_truncated,
+            next_start_index=next_idx,
+        )
+        if self._persistent_cache is not None:
+            self._persistent_cache.put(
+                result=result,
+                max_chars=max_chars,
+                start_index=start_index,
+            )
+        return result

mcp_server_python_docs/services/observability.py

@@ -0,0 +1,130 @@
+"""Structured logging for service method calls (OPS-01, OPS-02, OPS-03).
+
+Implements per-service-method decorators that log structured key=value (logfmt)
+lines to stderr. NOT FastMCP middleware — the MCP SDK middleware surface is
+unstable, so we instrument at the service layer.
+
+Log format (logfmt — D-10 from Phase 1):
+  tool=search_docs version=3.13 latency_ms=12 result_count=5
+  truncated=false resolution=fts synonym_expansion=yes
+"""
+from __future__ import annotations
+
+import functools
+import inspect
+import sys
+import time
+from collections.abc import Callable
+from types import TracebackType
+from typing import Any
+
+
+def _format_logfmt(**fields: Any) -> str:
+    """Format fields as logfmt key=value pairs.
+
+    Handles None (omitted), bool (lowercase), and strings with spaces (quoted).
+    """
+    parts = []
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            parts.append(f"{key}={str(value).lower()}")
+        elif isinstance(value, float):
+            parts.append(f"{key}={value:.1f}")
+        elif isinstance(value, str) and " " in value:
+            escaped = str(value).replace('"', '\\"')
+            parts.append(f'{key}="{escaped}"')
+        else:
+            parts.append(f"{key}={value}")
+    return " ".join(parts)
+
+
+def log_tool_call(tool_name: str) -> Callable:
+    """Decorator that logs structured info for every service method call.
+
+    Extracts version, result_count, truncated, resolution path, and
+    synonym_expansion from the method arguments and return value.
+
+    Note: This decorator only works with synchronous service methods.
+    If a method becomes async, the wrapper must be updated to detect
+    coroutines and await the result, otherwise timing will be wrong.
+
+    Args:
+        tool_name: Name of the MCP tool (search_docs, get_docs, list_versions).
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        @functools.wraps(fn)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            start = time.monotonic()
+            result: Any = None
+            error: Exception | None = None
+            error_tb: TracebackType | None = None
+
+            try:
+                result = fn(self, *args, **kwargs)
+            except Exception as exc:
+                error = exc
+                error_tb = exc.__traceback__
+
+            elapsed_ms = (time.monotonic() - start) * 1000
+
+            # Extract structured fields from args/kwargs and result
+            fields: dict[str, Any] = {
+                "tool": tool_name,
+                "latency_ms": round(elapsed_ms, 1),
+            }
+
+            # Extract version by name via inspect (WR-05: avoids fragile positional indexing)
+            try:
+                sig = inspect.signature(fn)
+                bound = sig.bind(self, *args, **kwargs)
+                bound.apply_defaults()
+                version_val = bound.arguments.get("version")
+            except (TypeError, ValueError):
+                version_val = kwargs.get("version")
+            fields["version"] = version_val or "default"
+
+            if error is None:
+                # Extract result-specific fields
+                if hasattr(result, "hits"):
+                    # SearchDocsResult
+                    fields["result_count"] = len(result.hits)
+                    # Resolution path from service state
+                    if hasattr(self, "_last_resolution"):
+                        fields["resolution"] = self._last_resolution
+                    else:
+                        fields["resolution"] = "fts"
+                    fields["truncated"] = False
+                elif hasattr(result, "truncated"):
+                    # GetDocsResult
+                    fields["result_count"] = 1 if result.content else 0
+                    fields["truncated"] = result.truncated
+                    fields["resolution"] = "exact"
+                elif hasattr(result, "versions"):
+                    # ListVersionsResult
+                    fields["result_count"] = len(result.versions)
+                    fields["truncated"] = False
+                    fields["resolution"] = "exact"
+
+                # Synonym expansion detection from service state
+                if hasattr(self, "_last_synonym_expanded"):
+                    fields["synonym_expansion"] = (
+                        "yes" if self._last_synonym_expanded else "no"
+                    )
+            else:
+                fields["error"] = type(error).__name__
+
+            # Write logfmt line to stderr (HYGN-01 safe — stderr only)
+            log_line = _format_logfmt(**fields)
+            print(log_line, file=sys.stderr)
+
+            if error is not None:
+                raise error.with_traceback(error_tb)
+
+            return result
+
+        return wrapper
+
+    return decorator

mcp_server_python_docs/services/package_docs.py

@@ -0,0 +1,161 @@
+"""Controlled package docs lookup using official PyPI JSON metadata.
+
+Source: https://docs.pypi.org/api/json/ documents GET /pypi/<project>/json.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+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,
+    PackageKind,
+)
+from mcp_server_python_docs.services.observability import log_tool_call
+
+_ALLOWED = {
+    "documentation",
+    "docs",
+    "homepage",
+    "home page",
+    "source",
+    "source code",
+    "repository",
+    "repo",
+}
+_PYPI_METADATA_MAX_BYTES = 5 * 1024 * 1024
+
+
+class _HTTPResponse(Protocol):
+    def read(self, size: int = -1) -> bytes: ...
+    def __enter__(self) -> "_HTTPResponse": ...
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool | None: ...
+
+
+Fetcher = Callable[[str, float], _HTTPResponse]
+
+
+def _default_fetcher(url: str, timeout: float) -> _HTTPResponse:
+    req = Request(
+        url,
+        headers={"Accept": "application/json", "User-Agent": "python-docs-mcp-server"},
+    )
+    return urlopen(req, timeout=timeout)
+
+
+def _normalize(name: str) -> str:
+    return quote(re.sub(r"[-_.]+", "-", name.strip().lower()), safe="-")
+
+
+def _http_url(url: object) -> str | None:
+    if not isinstance(url, str):
+        return None
+    parsed = urlparse(url.strip())
+    return url.strip() if parsed.scheme in {"http", "https"} and parsed.netloc else None
+
+
+def _source(label: str, url: object, kind: PackageKind) -> PackageDocsSource | None:
+    valid = _http_url(url)
+    if valid is None:
+        return None
+    return PackageDocsSource(label=label, url=valid, kind=kind, declared_by="PyPI project metadata")
+
+
+def _read_limited(response: _HTTPResponse) -> bytes | None:
+    data = response.read(_PYPI_METADATA_MAX_BYTES + 1)
+    if len(data) > _PYPI_METADATA_MAX_BYTES:
+        return None
+    return data
+
+
+def _empty_result(package: str, metadata_source: str, note: str) -> PackageDocsResult:
+    return PackageDocsResult(
+        package=package,
+        version="",
+        metadata_source=metadata_source,
+        sources=[],
+        note=note,
+    )
+
+
+class PackageDocsService:
+    """Return package-declared docs/homepage/source URLs from PyPI metadata only."""
+
+    def __init__(self, fetcher: Fetcher = _default_fetcher, timeout: float = 10.0) -> None:
+        self._fetcher = fetcher
+        self._timeout = timeout
+
+    @log_tool_call("lookup_package_docs")
+    def lookup(self, package: str) -> PackageDocsResult:
+        project = _normalize(package)
+        metadata_source = f"https://pypi.org/pypi/{project}/json"
+        try:
+            with self._fetcher(metadata_source, self._timeout) as response:
+                data = _read_limited(response)
+                if data is None:
+                    return _empty_result(
+                        package, metadata_source, "PyPI metadata exceeded size limit."
+                    )
+                payload = json.loads(data.decode("utf-8"))
+        except HTTPError as e:
+            note = (
+                "Package not found on PyPI." if e.code == 404 else f"PyPI returned HTTP {e.code}."
+            )
+            return _empty_result(package, metadata_source, note)
+        except (URLError, TimeoutError, json.JSONDecodeError, UnicodeDecodeError) as e:
+            return _empty_result(
+                package,
+                metadata_source,
+                f"Unable to retrieve PyPI metadata: {type(e).__name__}.",
+            )
+
+        info = payload.get("info") if isinstance(payload, dict) else {}
+        info = info if isinstance(info, dict) else {}
+        sources = [
+            s
+            for s in (
+                _source(
+                    "PyPI project",
+                    info.get("project_url") or f"https://pypi.org/project/{project}/",
+                    "pypi",
+                ),
+                _source("Documentation", info.get("docs_url"), "docs"),
+                _source("Homepage", info.get("home_page"), "homepage"),
+            )
+            if s is not None
+        ]
+        skipped: list[str] = []
+        project_urls = info.get("project_urls")
+        if isinstance(project_urls, dict):
+            for label, url in project_urls.items():
+                lowered = str(label).strip().lower()
+                if lowered in _ALLOWED:
+                    # 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:
+                    skipped.append(str(label))
+        note = None
+        if skipped:
+            note = (
+                "Ignored project URL labels outside the controlled allowlist: "
+                f"{', '.join(sorted(skipped))}."
+            )
+        return PackageDocsResult(
+            package=str(info.get("name") or package),
+            version=str(info.get("version") or ""),
+            summary=str(info.get("summary") or ""),
+            metadata_source=metadata_source,
+            sources=sources,
+            note=note,
+        )