feat: add bounded offline What’s New discovery

README.md

@@ -50,7 +50,7 @@ tools for lookup and section retrieval.
 - page and section retrieval with truncation and pagination
 - a local SQLite + FTS5 index; no runtime web scraping
 - results for each Python version you index
-- six read-only MCP tools
+- seven read-only MCP tools
 
 ## Quick example
 
@@ -218,7 +218,7 @@ Contributor commands and validation steps live in
 
 ## Tools
 
-The server currently exposes six MCP tools:
+The server currently exposes seven MCP tools:
 
 | Tool | Description |
 |------|-------------|
@@ -228,6 +228,7 @@ The server currently exposes six MCP tools:
 | `list_versions` | List all indexed Python versions with metadata. |
 | `detect_python_version` | Detect the user's local Python version and report whether that version has been indexed. |
 | `compare_versions` | Diff a Python stdlib symbol between two indexed versions. Returns `change=added|removed|changed|unchanged` with optional `new_in`, `changed_in`, `deprecated_in`, `signature_delta` (advisory heuristic), `see_also_added/removed`, `section_diff`, and `note` deltas. Token-frugal — emits only changed fields, not full content. |
+| `whatsnew_for_version` | Browse nonempty sections of the already-indexed official What's New page for one Python version. Optional `kind` filters by conservative heading-hierarchy category. `start_index` and `max_sections` paginate the filtered results; the structured response is capped at 20,000 characters, and truncated excerpts include a stable anchor and `get_docs` follow-up hint. Canonical titles and anchors are unchanged; if one section cannot fit its metadata plus nonempty indexed text and any required continuation hint, an explicit bounded error is returned. Page size may be reduced to reserve usable excerpts. The cap counts Unicode characters in the model JSON, excluding the MCP envelope. Querying is offline. |
 
 For `search_docs` with `kind="auto"` and an explicit indexed `version`, the
 original lookup and full-text search run first. If both return no hits, the

src/mcp_server_python_docs/app_context.py

@@ -16,6 +16,7 @@
 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.services.whatsnew import WhatsNewService
 
 
 @dataclass
@@ -28,6 +29,7 @@ class AppContext:
     content_service: ContentService
     compare_service: CompareService
     version_service: VersionService
+    whatsnew_service: WhatsNewService
     package_docs_service: PackageDocsService = field(default_factory=PackageDocsService)
     persistent_docs_cache: PersistentDocsCache | None = None
     synonyms: dict[str, list[str]] = field(default_factory=dict)

src/mcp_server_python_docs/models.py

@@ -301,3 +301,29 @@ class CompareVersionsResult(BaseModel):
             "therefore based on symbol presence alone."
         ),
     )
+
+
+# --- whatsnew_for_version models ---
+
+WhatsNewKind = Literal[
+    "new_module", "new_feature", "deprecation", "removal",
+    "performance", "syntax", "other",
+]
+
+
+class WhatsNewSection(BaseModel):
+    """A nonempty, bounded section from an indexed official release page."""
+
+    title: str = Field(description="Official section heading")
+    anchor: str = Field(description="Stable section anchor for get_docs follow-up")
+    body: str = Field(
+        description="Bounded section text; truncated sections include a get_docs hint"
+    )
+    kind: WhatsNewKind = Field(description="Conservative heading-hierarchy category")
+
+
+class WhatsNewResult(BaseModel):
+    """Paginated sections from What's New in one Python version."""
+
+    sections: list[WhatsNewSection] = Field(default_factory=list)
+    next_start_index: int | None = Field(default=None)

src/mcp_server_python_docs/server.py

@@ -34,13 +34,16 @@
     ListVersionsResult,
     PackageDocsResult,
     SearchDocsResult,
+    WhatsNewKind,
+    WhatsNewResult,
 )
 from mcp_server_python_docs.services.compare import CompareService
 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.services.whatsnew import WhatsNewService
 from mcp_server_python_docs.storage.db import (
     get_cache_dir,
     get_index_path,
@@ -162,6 +165,7 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
         content_svc = ContentService(db, persistent_cache=persistent_docs_cache)
         compare_svc = CompareService(db, content_svc)
         version_svc = VersionService(db)
+        whatsnew_svc = WhatsNewService(db)
         package_docs_svc = PackageDocsService()
 
         # Detect user's Python version and match to indexed versions
@@ -188,6 +192,7 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
                 content_service=content_svc,
                 compare_service=compare_svc,
                 version_service=version_svc,
+                whatsnew_service=whatsnew_svc,
                 package_docs_service=package_docs_svc,
                 persistent_docs_cache=persistent_docs_cache,
                 detected_python_version=matched,
@@ -411,6 +416,29 @@ def compare_versions(
             logger.exception("Unexpected error in compare_versions")
             raise ToolError(f"Internal error: {type(e).__name__}")
 
+    @mcp.tool(annotations=_TOOL_ANNOTATIONS)
+    def whatsnew_for_version(
+        version: CompareVersionParam,
+        kind: WhatsNewKind | None = None,
+        start_index: StartIndexParam = 0,
+        max_sections: MaxResultsParam = 20,
+        ctx: Context = None,  # type: ignore[assignment]
+    ) -> WhatsNewResult:
+        """Browse indexed official What's New sections in document order.
+
+        Use kind to narrow the release topics. Sections are bounded; for full
+        text use get_docs(slug='whatsnew/X.Y', version='X.Y', anchor=section.anchor).
+        Pagination start_index counts nonempty sections after kind filtering.
+        """
+        app_ctx: AppContext = ctx.request_context.lifespan_context
+        try:
+            return app_ctx.whatsnew_service.get(version, kind, start_index, max_sections)
+        except DocsServerError as e:
+            raise ToolError(str(e))
+        except Exception as e:
+            logger.exception("Unexpected error in whatsnew_for_version")
+            raise ToolError(f"Internal error: {type(e).__name__}")
+
     # SRVR-07: _meta hint for get_docs tool.
     # FastMCP 1.27 does not expose a public API for setting _meta on tool
     # definitions. Deferred until the mcp SDK adds _meta support to the

src/mcp_server_python_docs/services/whatsnew.py

@@ -0,0 +1,172 @@
+"""Offline, version-scoped discovery of sections on the official What's New page."""
+from __future__ import annotations
+
+import sqlite3
+
+from mcp_server_python_docs.errors import DocsServerError, PageNotFoundError
+from mcp_server_python_docs.models import WhatsNewKind, WhatsNewResult, WhatsNewSection
+from mcp_server_python_docs.retrieval.budget import apply_budget
+from mcp_server_python_docs.services.version_resolution import validate_version
+
+# Cap the whole structured response, including metadata and continuation hints.
+_RESULT_CHARS = 20_000
+_BODY_CHARS = 7800
+
+
+def _body_cost(section: WhatsNewSection, body: str) -> int:
+    return (
+        len(section.model_copy(update={"body": body}).model_dump_json())
+        - len(section.model_copy(update={"body": ""}).model_dump_json())
+    )
+
+
+def _fit_body(section: WhatsNewSection, body: str, hint: str, share: int) -> str:
+    # Full text has no hint: its cost is outside the monotonic truncated search.
+    if len(body) <= _BODY_CHARS and _body_cost(section, body) <= share:
+        return body
+    low, high = 1, min(_BODY_CHARS, len(body) - 1)
+    chosen = section.body
+    while low <= high:
+        middle = (low + high) // 2
+        excerpt, truncated, _ = apply_budget(body, middle)
+        candidate = excerpt + hint if truncated else excerpt
+        if _body_cost(section, candidate) <= share:
+            chosen = candidate
+            low = middle + 1
+        else:
+            high = middle - 1
+    return chosen
+
+
+def _classify(headings: tuple[str, ...]) -> WhatsNewKind:
+    """Classify only when an explicit heading or its ancestry supports it.
+
+    A leaf such as ``asyncio`` or an opaque ``#id6`` cannot classify itself.
+    Nearest relevant ancestor wins, so a future pending removal inside a
+    deprecations chapter remains a deprecation, not a removal in this release.
+    """
+    for heading in reversed(headings):
+        title = heading.casefold().strip()
+        if title.startswith("pending removal"):
+            return "deprecation"
+        if title in {"deprecated", "new deprecations", "deprecated c apis"}:
+            return "deprecation"
+        if title in {"removed", "removed modules and apis", "removed c apis"}:
+            return "removal"
+        if title in {"new modules"}:
+            return "new_module"
+        if title in {"optimizations", "performance"}:
+            return "performance"
+        if "syntax" in title or title == "syntax changes":
+            return "syntax"
+        if title in {"new features", "new features related to type hints", "improved modules"}:
+            return "new_feature"
+    return "other"
+
+
+class WhatsNewService:
+    """Read the already-indexed release page; never fetch at query time."""
+
+    def __init__(self, db: sqlite3.Connection) -> None:
+        self._db = db
+
+    def get(
+        self,
+        version: str,
+        kind: WhatsNewKind | None = None,
+        start_index: int = 0,
+        max_sections: int = 20,
+    ) -> WhatsNewResult:
+        validate_version(self._db, version)
+        if start_index < 0 or not 1 <= max_sections <= 20:
+            raise ValueError("start_index must be nonnegative and max_sections must be 1..20")
+        slug = f"whatsnew/{version}"
+        document = self._db.execute(
+            "SELECT d.id FROM documents d JOIN doc_sets ds ON ds.id = d.doc_set_id "
+            "WHERE ds.version = ? AND ds.source = 'python-docs' "
+            "AND ds.language = 'en' AND d.slug = ?",
+            (version, slug),
+        ).fetchone()
+        if document is None:
+            raise PageNotFoundError(
+                f"official What's New page {slug!r} is not indexed for Python {version}; "
+                "rebuild the full documentation index (without --skip-content)"
+            )
+
+        rows = self._db.execute(
+            "SELECT anchor, heading, level, content_text FROM sections "
+            "WHERE document_id = ? ORDER BY ordinal, id",
+            (document["id"],),
+        ).fetchall()
+        ancestors: list[tuple[int, str]] = []
+        matches: list[tuple[sqlite3.Row, WhatsNewKind]] = []
+        for row in rows:
+            level = max(1, int(row["level"]))
+            # Sphinx levels may skip; compare actual levels, not stack depth.
+            while ancestors and ancestors[-1][0] >= level:
+                ancestors.pop()
+            ancestors.append((level, row["heading"]))
+            body = row["content_text"].strip()
+            if not body:
+                continue
+            category = _classify(tuple(title for _, title in ancestors))
+            if kind is not None and category != kind:
+                continue
+            matches.append((row, category))
+        # Reserve indexed text and any required hint before admitting each section.
+        # Stop at the first non-fitting section; the next offset must never skip it.
+        page: list[tuple[str, str]] = []
+        sections: list[WhatsNewSection] = []
+        minimum_costs: list[int] = []
+        result = WhatsNewResult()
+        for row, category in matches[start_index : start_index + max_sections]:
+            section = WhatsNewSection(
+                title=row["heading"], anchor=row["anchor"], body="", kind=category
+            )
+            next_index = start_index + len(sections) + 1
+            candidate = WhatsNewResult(
+                sections=[*sections, section],
+                next_start_index=next_index if next_index < len(matches) else None,
+            )
+            if not sections and len(candidate.model_dump_json()) > _RESULT_CHARS:
+                raise DocsServerError(
+                    f"What's New section at start_index={start_index} has metadata "
+                    "larger than the 20,000-character response limit"
+                )
+            body = row["content_text"].strip()
+            hint = (
+                "\n\n[Section truncated. Continue with "
+                f"get_docs(slug={slug!r}, version={version!r}, "
+                f"anchor={row['anchor']!r}).]"
+            )
+            excerpt, truncated, _ = apply_budget(body, 1)
+            minimum = excerpt + hint if truncated else excerpt
+            if len(body) <= _BODY_CHARS and (
+                _body_cost(section, body) <= _body_cost(section, minimum)
+            ):
+                minimum = body
+            section.body = minimum
+            if len(candidate.model_dump_json()) > _RESULT_CHARS:
+                if not sections:
+                    raise DocsServerError(
+                        f"What's New section at start_index={start_index} cannot fit "
+                        "nonempty indexed text and its required continuation within "
+                        "the 20,000-character response limit"
+                    )
+                break
+            page.append((body, hint))
+            minimum_costs.append(_body_cost(section, minimum))
+            sections.append(section)
+            result = candidate
+        remaining = _RESULT_CHARS - len(result.model_dump_json()) + sum(minimum_costs)
+        reserved = sum(minimum_costs)
+        for index, (body, hint) in enumerate(page):
+            section = sections[index]
+            reserved -= minimum_costs[index]
+            share = min(
+                max(remaining // (len(page) - index), minimum_costs[index]),
+                remaining - reserved,
+            )
+            section.body = _fit_body(section, body, hint, share)
+            remaining -= _body_cost(section, section.body)
+        return result

tests/test_retrieval_regression.py

@@ -14,6 +14,7 @@
 from mcp_server_python_docs.services.content import ContentService
 from mcp_server_python_docs.services.search import SearchService
 from mcp_server_python_docs.services.version import VersionService
+from mcp_server_python_docs.services.whatsnew import WhatsNewService
 from mcp_server_python_docs.storage.db import bootstrap_schema, get_readwrite_connection
 
 _CASES_PATH = Path(__file__).parent / "fixtures" / "retrieval_regression_cases.json"
@@ -134,6 +135,7 @@ def _make_app_context(db, detected_python_version: str | None) -> AppContext:
         content_service=content_service,
         compare_service=CompareService(db, content_service),
         version_service=VersionService(db),
+        whatsnew_service=WhatsNewService(db),
         detected_python_version=detected_python_version,
         detected_python_source="test fixture",
     )

tests/test_services.py

@@ -447,12 +447,15 @@ def test_all_tools_have_annotations(self):
                 annotations.openWorldHint is False
             ), f"{name} openWorldHint should be False"
 
-    def test_six_tools_registered(self):
+    def test_seven_tools_registered(self):
         from mcp_server_python_docs.server import create_server
 
         server = create_server()
         tools = server._tool_manager._tools
-        assert len(tools) == 6
+        assert set(tools) == {
+            "search_docs", "get_docs", "lookup_package_docs", "list_versions",
+            "detect_python_version", "compare_versions", "whatsnew_for_version",
+        }
 
     def test_runtime_tool_schemas_include_input_constraints(self):
         import anyio