feat: cache docs and expose PyPI package docs lookup

Author: bluecloud-gilfoyle[bot]

README.md

@@ -164,12 +164,13 @@ Contributor commands and validation steps live in
 
 ## Tools
 
-The server currently exposes four MCP tools:
+The server currently exposes five MCP tools:
 
 | Tool | Description |
 |------|-------------|
 | `search_docs` | Search Python stdlib docs by query. Supports symbol lookup (`asyncio.TaskGroup`), module search (`json`), and free-text search. Returns ranked hits with BM25 scoring and snippet excerpts. |
-| `get_docs` | Retrieve a specific documentation page or section by slug and optional anchor. Returns markdown content with budget-enforced truncation and pagination. |
+| `get_docs` | Retrieve a specific documentation page or section by slug and optional anchor. Returns markdown content with budget-enforced truncation and pagination. Retrieved results are cached on disk by Python docs version and request identity. |
+| `lookup_package_docs` | Look up official PyPI package metadata and return package-declared documentation/homepage/source URLs. This is a controlled PyPI metadata lookup, not generic web search. |
 | `list_versions` | List all indexed Python versions with metadata. |
 | `detect_python_version` | Detect the user's local Python version and report whether it matches an indexed documentation version. |
 
@@ -184,10 +185,43 @@ Use this server when you need:
 
 Use a generic fetcher or broader docs MCP when you need:
 
-- third-party package docs outside the Python stdlib
+- arbitrary third-party package content beyond package-declared PyPI metadata
 - arbitrary web pages
 - mixed-source research across many frameworks
 
+## Retrieved docs cache
+
+`get_docs` responses are cached across MCP client/server restarts in the
+platform cache directory:
+
+```text
+<platform cache dir>/mcp-python-docs/retrieved-docs-cache.sqlite3
+```
+
+The cache stores completed `get_docs` results, including page/section content,
+for the resolved Python docs version plus request identity (`slug`, optional
+`anchor`, `max_chars`, and `start_index`). Cache misses fall back to the normal
+local index retrieval path and then write the retrieved result.
+
+Cache entries are also scoped to a fingerprint of the local `index.db` file
+(path, size, and modification timestamp). If you rebuild or replace the local
+docs index, older entries are ignored automatically instead of being returned
+for the new index generation. Deleting `retrieved-docs-cache.sqlite3` is safe;
+it only removes cached retrieval results, not the docs index.
+
+## PyPI package docs lookup
+
+`lookup_package_docs` queries the official PyPI JSON API documented at
+`https://docs.pypi.org/api/json/` (`GET /pypi/<project>/json`) and returns only
+sources declared in that package's PyPI metadata: the PyPI project URL,
+`docs_url`, `home_page`, and allowlisted `project_urls` labels such as
+Documentation, Homepage, Source, Repository, Issues, Changelog, and Release
+Notes.
+
+The tool makes the trust boundary explicit with
+`trust_boundary="pypi-declared-metadata"`. It does not crawl pages, perform web
+search, or silently fall back to unofficial community mirrors.
+
 ## Diagnostics
 
 Check the local environment:

src/mcp_server_python_docs/app_context.py

@@ -11,6 +11,8 @@
 from pathlib import Path
 
 from mcp_server_python_docs.services.content import ContentService
+from mcp_server_python_docs.services.package_docs import PackageDocsService
+from mcp_server_python_docs.services.persistent_cache import PersistentDocsCache
 from mcp_server_python_docs.services.search import SearchService
 from mcp_server_python_docs.services.version import VersionService
 
@@ -24,6 +26,8 @@ class AppContext:
     search_service: SearchService
     content_service: ContentService
     version_service: VersionService
+    package_docs_service: PackageDocsService = field(default_factory=PackageDocsService)
+    persistent_docs_cache: PersistentDocsCache | None = None
     synonyms: dict[str, list[str]] = field(default_factory=dict)
     detected_python_version: str | None = None
     detected_python_source: str | None = None

src/mcp_server_python_docs/models.py

@@ -160,3 +160,46 @@ class DetectPythonVersionResult(BaseModel):
     is_default: bool = Field(
         description="Whether this detected version is being used as the default for get_docs"
     )
+
+
+# --- lookup_package_docs models ---
+
+
+class PackageDocsInput(BaseModel):
+    """Input parameters for lookup_package_docs tool."""
+
+    package: str = Field(
+        min_length=1,
+        max_length=214,
+        description="PyPI package/project name (e.g. 'requests').",
+    )
+
+
+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")
+    declared_by: str = Field(description="Where this source declaration came from")
+
+
+class PackageDocsResult(BaseModel):
+    """Output from lookup_package_docs tool."""
+
+    package: str = Field(description="Canonical package name returned by PyPI when available")
+    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(
+        default="pypi-declared-metadata",
+        description="Indicates results are limited to PyPI/project-declared metadata",
+    )
+    sources: list[PackageDocsSource] = Field(
+        default_factory=list,
+        description="Package-declared PyPI, documentation, homepage, and source URLs",
+    )
+    note: str | None = Field(
+        default=None,
+        description="Controlled-scope note, for example skipped labels or not-found details",
+    )

src/mcp_server_python_docs/server.py

@@ -29,9 +29,12 @@
     DetectPythonVersionResult,
     GetDocsResult,
     ListVersionsResult,
+    PackageDocsResult,
     SearchDocsResult,
 )
 from mcp_server_python_docs.services.content import ContentService
+from mcp_server_python_docs.services.package_docs import PackageDocsService
+from mcp_server_python_docs.services.persistent_cache import PersistentDocsCache
 from mcp_server_python_docs.services.search import SearchService
 from mcp_server_python_docs.services.version import VersionService
 from mcp_server_python_docs.storage.db import get_readonly_connection
@@ -86,15 +89,21 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
 
     # Open read-only connection (STOR-06, STOR-07)
     db = get_readonly_connection(index_path)
+    persistent_docs_cache: PersistentDocsCache | None = None
 
     try:
         # Check FTS5 (STOR-08)
         _assert_fts5(db)
 
         # Construct service instances (Phase 5 — service layer wiring)
+        persistent_docs_cache = PersistentDocsCache(
+            cache_path=cache_dir / "retrieved-docs-cache.sqlite3",
+            index_path=index_path,
+        )
         search_svc = SearchService(db, synonyms)
-        content_svc = ContentService(db)
+        content_svc = ContentService(db, persistent_cache=persistent_docs_cache)
         version_svc = VersionService(db)
+        package_docs_svc = PackageDocsService()
 
         # Detect user's Python version and match to indexed versions
         detected_ver, detected_src = detect_python_version()
@@ -119,6 +128,8 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
                 search_service=search_svc,
                 content_service=content_svc,
                 version_service=version_svc,
+                package_docs_service=package_docs_svc,
+                persistent_docs_cache=persistent_docs_cache,
                 detected_python_version=matched,
                 detected_python_source=detected_src,
             )
@@ -133,6 +144,11 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
                 pass
             raise
     finally:
+        if persistent_docs_cache is not None:
+            try:
+                persistent_docs_cache.close()
+            except Exception:
+                pass
         db.close()
 
 
@@ -143,6 +159,12 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     idempotentHint=True,
     openWorldHint=False,
 )
+_PYPI_TOOL_ANNOTATIONS = ToolAnnotations(
+    readOnlyHint=True,
+    destructiveHint=False,
+    idempotentHint=True,
+    openWorldHint=True,
+)
 
 SearchQueryParam = Annotated[
     str,
@@ -184,6 +206,10 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     int,
     Field(ge=0, description="Start position for pagination"),
 ]
+PackageParam = Annotated[
+    str,
+    Field(min_length=1, max_length=214, description="PyPI package/project name"),
+]
 
 
 def create_server() -> FastMCP:
@@ -239,6 +265,23 @@ def get_docs(
             logger.exception("Unexpected error in get_docs")
             raise ToolError(f"Internal error: {type(e).__name__}")
 
+    @mcp.tool(annotations=_PYPI_TOOL_ANNOTATIONS)
+    def lookup_package_docs(
+        package: PackageParam,
+        ctx: Context = None,  # type: ignore[assignment]
+    ) -> PackageDocsResult:
+        """Look up package-declared docs/homepage/source URLs via official PyPI metadata.
+
+        This is not generic web search: it only queries PyPI's JSON API and
+        returns official PyPI metadata plus package-declared project URLs.
+        """
+        app_ctx: AppContext = ctx.request_context.lifespan_context
+        try:
+            return app_ctx.package_docs_service.lookup(package)
+        except Exception as e:
+            logger.exception("Unexpected error in lookup_package_docs")
+            raise ToolError(f"Internal error: {type(e).__name__}")
+
     @mcp.tool(annotations=_TOOL_ANNOTATIONS)
     def list_versions(
         ctx: Context = None,  # type: ignore[assignment]

src/mcp_server_python_docs/services/content.py

@@ -13,6 +13,7 @@
 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
 
 
@@ -23,9 +24,14 @@ class ContentService:
     When omitted, returns the full page with truncation/pagination.
     """
 
-    def __init__(self, db: sqlite3.Connection) -> None:
+    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.
@@ -47,6 +53,17 @@ def get_docs(
         """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(
             """
@@ -119,7 +136,7 @@ def get_docs(
             full_text, max_chars, start_index
         )
 
-        return GetDocsResult(
+        result = GetDocsResult(
             content=truncated_text,
             slug=slug,
             title=title,
@@ -129,3 +146,10 @@ def get_docs(
             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