phase 10 — whatsnew_for_version(version)

README.md

@@ -204,7 +204,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 |
 |------|-------------|
@@ -214,6 +214,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. Querying is offline. |
 
 ## Why not Context7 or generic docs retrieval?
 

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,131 @@
+"""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 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 _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))
+        page = matches[start_index : start_index + max_sections]
+        next_index = start_index + len(page)
+        sections = [
+            WhatsNewSection(title=row["heading"], anchor=row["anchor"], body="", kind=category)
+            for row, category in page
+        ]
+        result = WhatsNewResult(
+            sections=sections,
+            next_start_index=next_index if next_index < len(matches) else None,
+        )
+        remaining = _RESULT_CHARS - len(result.model_dump_json())
+        for index, (row, _) in enumerate(page):
+            section = sections[index]
+            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}).]"
+            )
+            share = remaining // (len(page) - index)
+            empty_length = len(section.model_dump_json())
+            # Binary-search the excerpt so escaped JSON plus the follow-up hint
+            # fits a fair share. Short sections leave more space for later ones.
+            low, high = 0, min(_BODY_CHARS, len(body))
+            chosen = ""
+            while low <= high:
+                middle = (low + high) // 2
+                excerpt, truncated, _ = apply_budget(body, middle)
+                candidate = excerpt + hint if truncated else excerpt
+                cost = (
+                    len(section.model_copy(update={"body": candidate}).model_dump_json())
+                    - empty_length
+                )
+                if cost <= share:
+                    chosen = candidate
+                    low = middle + 1
+                else:
+                    high = middle - 1
+            section.body = chosen
+            remaining -= len(section.model_dump_json()) - empty_length
+        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