python-docs-mcp-server 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

mcp_server_python_docs/app_context.py

@@ -16,6 +16,7 @@ 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
 
 
 @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)

mcp_server_python_docs/ingestion/sphinx_json.py

@@ -287,9 +287,16 @@ def extract_sections(body_html: str, doc_uri: str) -> list[dict]:
         return []
 
     soup = BeautifulSoup(body_html, "html.parser")
+    # Modern Sphinx puts the ID on a section; only its first direct heading names it.
+    for section in soup.find_all(["section", "div"], id=True):
+        if section.name != "section" and "section" not in (section.get("class") or []):
+            continue
+        heading = section.find(re.compile(r"^h[1-6]$"), recursive=False)
+        if isinstance(heading, Tag) and not heading.get("id"):
+            heading["id"] = section["id"]
     heading_tags = soup.find_all(re.compile(r"^h[1-6]$"), id=True)
 
-    if not heading_tags:
+    if not heading_tags and not soup.find("dt", id=True):
         # No headings with id — create a single section covering the whole body
         content = html_to_markdown(body_html)
         if not content:
@@ -346,6 +353,24 @@ def extract_sections(body_html: str, doc_uri: str) -> list[dict]:
             }
         )
 
+    # Sphinx API signatures carry independent anchors inside definition lists.
+    anchors = {section["anchor"] for section in sections}
+    for signature in soup.find_all("dt", id=True):
+        anchor = str(signature["id"])
+        if anchor in anchors:
+            continue
+        anchors.add(anchor)
+        description = signature.find_next_sibling("dd")
+        content = html_to_markdown(str(signature) + (str(description) if description else ""))
+        sections.append({
+            "anchor": anchor,
+            "heading": signature.get_text(" ", strip=True).rstrip("¶").strip(),
+            "level": 3,
+            "ordinal": len(sections),
+            "content_text": content,
+            "char_count": len(content),
+            "uri": f"{doc_uri}#{anchor}",
+        })
     return sections
 
 

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)

mcp_server_python_docs/retrieval/ranker.py

@@ -9,7 +9,9 @@ Receives sqlite3.Connection as parameter -- does not import storage.
 from __future__ import annotations
 
 import logging
+import re
 import sqlite3
+from difflib import SequenceMatcher
 
 from mcp_server_python_docs.models import SymbolHit
 
@@ -133,6 +135,32 @@ def _normalize_scores(hits: list[SymbolHit]) -> list[SymbolHit]:
     return normalized
 
 
+def _section_excerpt_overlaps(first: sqlite3.Row, second: sqlite3.Row) -> bool:
+    """Only collapse nested sections when their *matched excerpts* are redundant.
+
+    A shared page is not enough: an overview can independently answer a broad
+    query while a nearby API section answers a precise one. The content and the
+    FTS snippet must both overlap substantially before they compete for a slot.
+    """
+    if first["version"] != second["version"] or first["slug"] != second["slug"]:
+        return False
+    first_content = " ".join(first["content_text"].casefold().split())
+    second_content = " ".join(second["content_text"].casefold().split())
+    if not first_content or not second_content:
+        return False
+    if first_content not in second_content and second_content not in first_content:
+        return False
+
+    first_words = re.findall(r"\w+", first["snippet_text"].casefold())
+    second_words = re.findall(r"\w+", second["snippet_text"].casefold())
+    shorter = min(len(first_words), len(second_words))
+    if shorter < 8:
+        return False
+    shared = SequenceMatcher(None, first_words, second_words, autojunk=False)
+    match = shared.find_longest_match(0, len(first_words), 0, len(second_words))
+    return match.size >= max(8, (7 * shorter + 9) // 10)
+
+
 def search_sections(
     conn: sqlite3.Connection,
     match_expr: str,
@@ -154,10 +182,15 @@ def search_sections(
     Returns:
         List of SymbolHit with kind="section" and FTS5 snippets.
     """
+    # Inspect a fixed, ranked window even after the result slots fill: a later
+    # narrow API anchor can replace an earlier enclosing overview. The server
+    # caps max_results at 20, so this examines at most 160 candidates and does
+    # not paginate through an unbounded run of overlapping sections.
+    candidate_limit = max(40, max_results * 8)
     try:
-        cursor = conn.execute(
+        candidates = conn.execute(
             """
-            SELECT s.id, s.heading, s.uri, s.anchor,
+            SELECT s.id, s.heading, s.uri, s.anchor, s.content_text,
                    d.version, doc.slug,
                    bm25(sections_fts, 10.0, 1.0) as score,
                    snippet(sections_fts, 1, '**', '**', '...', 32) as snippet_text
@@ -167,16 +200,33 @@ def search_sections(
             JOIN doc_sets d ON doc.doc_set_id = d.id
             WHERE sections_fts MATCH ?
               AND (? IS NULL OR d.version = ?)
-            ORDER BY bm25(sections_fts, 10.0, 1.0)
+            ORDER BY bm25(sections_fts, 10.0, 1.0), s.id
             LIMIT ?
             """,
-            (match_expr, version, version, max_results),
-        )
-        rows = cursor.fetchall()
+            (match_expr, version, version, candidate_limit),
+        ).fetchall()
     except sqlite3.OperationalError:
         logger.warning("FTS5 query failed for sections: %r", match_expr)
         return []
 
+    selected: list[sqlite3.Row] = []
+    for row in candidates:
+        duplicate = next(
+            (i for i, prior in enumerate(selected)
+             if _section_excerpt_overlaps(prior, row)),
+            None,
+        )
+        if duplicate is None:
+            selected.append(row)
+        elif len(row["content_text"]) < len(selected[duplicate]["content_text"]):
+            # The narrower section gives a more precise canonical anchor
+            # for the same matched text. The overview stays available
+            # through its anchor and whole-page get_docs retrieval.
+            selected[duplicate] = row
+
+    selected.sort(key=lambda row: (row["score"], row["id"]))
+    rows = selected[:max_results]
+
     hits = [
         SymbolHit(
             uri=row["uri"],

mcp_server_python_docs/server.py

@@ -34,6 +34,8 @@ from mcp_server_python_docs.models import (
     ListVersionsResult,
     PackageDocsResult,
     SearchDocsResult,
+    WhatsNewKind,
+    WhatsNewResult,
 )
 from mcp_server_python_docs.services.compare import CompareService
 from mcp_server_python_docs.services.content import ContentService
@@ -41,6 +43,7 @@ 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 create_server() -> FastMCP:
             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

mcp_server_python_docs/services/content.py

@@ -67,7 +67,7 @@ class ContentService:
         # Find the document
         doc_row = self._db.execute(
             """
-            SELECT d.id, d.title, d.slug
+            SELECT d.id, d.title, d.slug, d.content_text
             FROM documents d
             JOIN doc_sets ds ON d.doc_set_id = ds.id
             WHERE d.slug = ? AND ds.version = ?
@@ -105,29 +105,8 @@ class ContentService:
                     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)
+            # The stored page is canonical; nested anchor excerpts can overlap.
+            full_text = doc_row["content_text"] or ""
 
             title = doc_title
 

mcp_server_python_docs/services/search.py

@@ -6,9 +6,11 @@ No MCP types imported — dependency rule enforced.
 """
 from __future__ import annotations
 
+import re
 import sqlite3
+from urllib.parse import urlsplit
 
-from mcp_server_python_docs.models import SearchDocsResult
+from mcp_server_python_docs.models import SearchDocsResult, SymbolHit
 from mcp_server_python_docs.retrieval.query import (
     build_match_expression,
     classify_query,
@@ -23,6 +25,8 @@ from mcp_server_python_docs.retrieval.ranker import (
 from mcp_server_python_docs.services.observability import log_tool_call
 from mcp_server_python_docs.services.version_resolution import resolve_version_permissive
 
+_DOTTED_IDENTIFIER = re.compile(r"\b[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)+\b")
+
 
 class SearchService:
     """Search service dispatching queries through classifier, synonym expansion,
@@ -55,6 +59,47 @@ class SearchService:
         ).fetchone()
         return row is not None
 
+    def _known_identifiers(self, query: str, version: str) -> set[str]:
+        """Count exact prompt identifiers only in the requested inventory."""
+        return {
+            name
+            for name in set(_DOTTED_IDENTIFIER.findall(query))
+            if self._db.execute(
+                "SELECT 1 FROM symbols s JOIN doc_sets d ON d.id = s.doc_set_id "
+                "WHERE s.qualified_name = ? AND d.version = ? LIMIT 1",
+                (name, version),
+            ).fetchone() is not None
+        }
+
+    def _append_canonical(
+        self, original: SearchDocsResult, query: str, version: str | None,
+        kind: str, max_results: int,
+    ) -> SearchDocsResult:
+        """Fill at most one spare slot without altering semantic evidence."""
+        if kind != "auto" or version is None or not original.hits:
+            return original
+        if len(original.hits) >= max_results:
+            return original
+        known = self._known_identifiers(query, version)
+        if len(known) != 1:
+            return original
+        name = known.pop()
+        candidates = lookup_symbols_exact(self._db, name, version, 1)
+        if not candidates or candidates[0].title != name:
+            return original
+        candidate = candidates[0]
+
+        def location(hit: SymbolHit) -> tuple[str, str, str]:
+            uri = urlsplit(hit.uri)
+            return (hit.version, (hit.slug or uri.path).removesuffix(".html"),
+                    hit.anchor or uri.fragment)
+
+        if any(location(hit) == location(candidate) for hit in original.hits):
+            return original
+        proposed = original.model_copy(update={"hits": [*original.hits, candidate]})
+        # Admission only: never cap, replace or truncate the original response.
+        return proposed if len(proposed.model_dump_json().encode("utf-8")) <= 8000 else original
+
     @log_tool_call("search_docs")
     def search(
         self,
@@ -84,7 +129,9 @@ class SearchService:
             hits = lookup_symbols_exact(self._db, query, resolved_version, max_results)
             if hits:
                 self._last_resolution = "exact"
-                return SearchDocsResult(hits=hits)
+                return self._append_canonical(
+                    SearchDocsResult(hits=hits), query, resolved_version, kind, max_results,
+                )
             # Fall through to FTS if symbol lookup found nothing and kind is auto
             if kind == "symbol":
                 self._last_resolution = "exact"
@@ -108,4 +155,18 @@ class SearchService:
                 hits = search_symbols(self._db, match_expr, resolved_version, max_results)
 
         self._last_resolution = "fts"
-        return SearchDocsResult(hits=hits)
+        if not hits and kind == "auto" and resolved_version is not None:
+            # Prompt-only candidates; ambiguity is decided in the requested inventory.
+            known = self._known_identifiers(query, resolved_version)
+            if len(known) == 1:
+                name = known.pop()
+                hits = lookup_symbols_exact(self._db, name, resolved_version, max_results)
+                if hits:
+                    self._last_resolution = "exact"
+                    return SearchDocsResult(
+                        hits=hits,
+                        note=f"No full-query results; showing symbol matches for {name!r}.",
+                    )
+        return self._append_canonical(
+            SearchDocsResult(hits=hits), query, resolved_version, kind, max_results,
+        )

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

{python_docs_mcp_server-0.3.1.dist-info → python_docs_mcp_server-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-docs-mcp-server
-Version: 0.3.1
+Version: 0.4.0
 Summary: The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT, token-frugal.
 Author-email: Aymen Hammouda <hammouda.aymen@gmail.com>
 License-Expression: MIT
@@ -17,7 +17,7 @@ Requires-Python: >=3.12
 Requires-Dist: beautifulsoup4<5.0,>=4.12
 Requires-Dist: click<9.0,>=8.1.7
 Requires-Dist: markdownify<2.0,>=0.14
-Requires-Dist: mcp<2.0.0,>=1.27.0
+Requires-Dist: mcp<2.0.0,>=1.30.0
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: pydantic<3.0,>=2.0.0
 Requires-Dist: pyyaml<7.0,>=6.0
@@ -79,7 +79,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
 
@@ -127,6 +127,20 @@ pipx install python-docs-mcp-server
 If `uv` is installed but the `uv` command is not on your `PATH`, reopen your
 shell or use `python -m uv ...` as a fallback for local contributor commands.
 
+## Search result behavior
+
+For `kind="auto"` with an explicit version, a nonempty search with spare result
+slots may append **one** exact inventory target when the prompt contains one
+known qualified identifier in that version. Original hits, snippets, scores,
+order and notes are preserved. Full results, ambiguous identifiers, other kinds
+and versionless queries are unchanged; the existing empty-result fallback is
+unchanged. Canonical locations are deduplicated, including inventory aliases.
+
+The append is admitted only when the **complete proposed response** serialized
+by Pydantic's compact `model_dump_json()` is at most **8000 UTF-8 bytes**. This is
+not a global search cap: oversized original responses remain unchanged. It is
+separate from `get_docs(max_chars=8000)`, which limits content **characters**.
+
 ## First run
 
 Build the local documentation index:
@@ -233,7 +247,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 |
 |------|-------------|
@@ -243,6 +257,17 @@ 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
+server looks for dotted Python identifiers in the prompt. Exactly one distinct
+identifier registered in that version enables a symbol-lookup fallback; repeated
+mentions count once and unknown identifiers do not count. Multiple known
+identifiers leave the result empty. A result note identifies fallback matches,
+which are symbol documentation, not an answer to the complete prompt. Explicit
+kinds, searches without a version, nonempty results, and result budgets are
+unchanged.
 
 ## Why not Context7 or generic docs retrieval?
 

{python_docs_mcp_server-0.3.1.dist-info → python_docs_mcp_server-0.4.0.dist-info}/RECORD

@@ -1,12 +1,12 @@
 mcp_server_python_docs/__init__.py,sha256=sUtQT81momSAPMywIkgnR7BZxJHn53rpcjSE3CTAUws,499
 mcp_server_python_docs/__main__.py,sha256=d6ZyRgkmOW7XUUgoGjOMEzCVoHL-aHuqmFKdxxkucvk,22165
-mcp_server_python_docs/app_context.py,sha256=5kK4JcTiKgJGOV_gFE8aVktYdtCpeDbZunIrlt4SxyA,1403
+mcp_server_python_docs/app_context.py,sha256=DDUiDFMdxAElaQaiZ9mMQAU6H6D9Vq946NrNlmbtIN4,1510
 mcp_server_python_docs/detection.py,sha256=bYYSfpMymHk9wehNW66oItX6yFUoCC2JXDRZLYpM0Vw,2860
 mcp_server_python_docs/diagnostics.py,sha256=FyC6QDFLvozARpYuMnaKfJwaN6BCzVycME_SkNs2YIs,2370
 mcp_server_python_docs/errors.py,sha256=XTOm1raJfxS2adaOPZdwj0SuhpMAXAdjBsF2-zTv_1E,827
-mcp_server_python_docs/models.py,sha256=A9XtcJPJFDa6jn7pHa4yDS1TPlnpIc3A7WEeKu4qqOw,10247
+mcp_server_python_docs/models.py,sha256=89fe4foe7wyw_f8tpMDPZqBJ5Nd8bolhkwm65eQdW6o,11099
 mcp_server_python_docs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mcp_server_python_docs/server.py,sha256=8F27o2hTyi1rwSNoMo8lGYXCvhwEHS7cVHI7n9p5Y2M,15469
+mcp_server_python_docs/server.py,sha256=faiUpXnnXulwcIUKBptc9ZFgB4-owJH3CTgrUL_8sKU,16733
 mcp_server_python_docs/cache/__init__.py,sha256=Eba8m5Xi3LYQKz5ictK9whVi_SZJWr5vZE1AtKDb26U,31
 mcp_server_python_docs/cache/codec.py,sha256=tOEuHDqa6ziF2T05JubtDg_QnqvYRuheZijZUTX9lpE,3653
 mcp_server_python_docs/data/synonyms.yaml,sha256=LgJxamZ9QT6Pykva7M1uM8juSd9ybHuv3vUOKrUFMg4,10696
@@ -14,26 +14,27 @@ mcp_server_python_docs/ingestion/__init__.py,sha256=Yd7Jk7hD7XG3eoBVQpYiG94EwJGf
 mcp_server_python_docs/ingestion/cpython_versions.py,sha256=_28TX26eGEiiEV_6NthaPg8vwvwjuus2yVLn7ktvcyo,1426
 mcp_server_python_docs/ingestion/inventory.py,sha256=5gQCWOo1tBiQgv-e_A9KR9n2xfP4YAnJrSmb0pFbzwY,5672
 mcp_server_python_docs/ingestion/publish.py,sha256=gra87NgH1i4T92nSwf3sqp4AnKuuzQfrcE7ySnDgcSQ,17247
-mcp_server_python_docs/ingestion/sphinx_json.py,sha256=OXrZ8LMeLFn2har2TVnWVNwMY9b5z1VCMioQdIE5gJE,20270
+mcp_server_python_docs/ingestion/sphinx_json.py,sha256=ZSiTK30-9hhra7oFelUL8OP3eB_dB8ddmFBV4hWUL3g,21524
 mcp_server_python_docs/retrieval/__init__.py,sha256=xSH2dWrIun_Q980ElcoXWBIobTqz0am66-AkEvRo_ck,779
 mcp_server_python_docs/retrieval/budget.py,sha256=kORd1Pt6IxLH95vRE7WBwdwezxvk98deYBgeNLEmyOw,2098
 mcp_server_python_docs/retrieval/query.py,sha256=9rWBvWQG3KwVjCqEqCYKMFgKqswU-O4a1SyJiTzQrjk,6116
-mcp_server_python_docs/retrieval/ranker.py,sha256=GSssXzfaJKEWrCgF_UuTm9-lSzTbYe3cSalsqgq0nUI,11712
+mcp_server_python_docs/retrieval/ranker.py,sha256=ct9uIir0oK38v0eI-lKPq9m_EsN8Fsf3NBajbYi2fAs,14122
 mcp_server_python_docs/services/__init__.py,sha256=UKlaRQYo_cnLOUVf_QieXnHlcnH9ejEa3pYgHhJiG1E,320
 mcp_server_python_docs/services/cache.py,sha256=ADqg89johOJRYZysbes1bEs6nLFrmzS9L5c-Njt1mrU,3199
 mcp_server_python_docs/services/compare.py,sha256=wWsgD8w9fl3L7gr-mcdd6ntY_V1pGtZ-ues1iyyNRPg,12743
-mcp_server_python_docs/services/content.py,sha256=7O5XGbR9QWICMxYAd-cp_pPF86tNLcYAMIwyCP_i8dk,5342
+mcp_server_python_docs/services/content.py,sha256=5_FPgyOYbax7qNH6OXEePnyfmyjBdgh-QkK7CvEMCCU,4654
 mcp_server_python_docs/services/observability.py,sha256=rwnkIDelNkclHzuwsktGUoU2fzYCuiR1niVRmOwJHJg,4839
 mcp_server_python_docs/services/package_docs.py,sha256=0Qq8PtRL_KdiTFUtllaj4KFHz6u9L903zcORVpYmR1U,5605
 mcp_server_python_docs/services/persistent_cache.py,sha256=p1uhTkwmXRP-v79jaIPDTEv9Z0G0iqCUnUDKmFQA6GA,6956
-mcp_server_python_docs/services/search.py,sha256=Pjt4IDfnogWTGYKFJ_4ODbq1xbUZ0ybceD6yj7Ep6lw,4545
+mcp_server_python_docs/services/search.py,sha256=xioiLrgTPTU9LHg2t0dG8mHxaKwYSKI-haGZq6J0kYs,7384
 mcp_server_python_docs/services/version.py,sha256=nPkWhksZo7B4QIp-knlSEvVXFmKIcVUq6tWRTJAe5aA,1467
 mcp_server_python_docs/services/version_resolution.py,sha256=rULBoqq97t0ZfSWSy-ecI3wALx5t_3OWuok1hZK8w0w,2643
+mcp_server_python_docs/services/whatsnew.py,sha256=vLNbUaPoCEMBP-PvPiu7Wp1QV28OQJpFUg_umFwWAx0,7476
 mcp_server_python_docs/storage/__init__.py,sha256=YNeNr7FW9Vgvo79oXgKXE3eGP0WwWDqRgTZ7lg7MFW4,62
 mcp_server_python_docs/storage/db.py,sha256=Lys8HN3IvgmNpr_qyocUQghcZnwHf2lz9eq_BFmwi54,5634
 mcp_server_python_docs/storage/schema.sql,sha256=4cXPktPQSLfbjkSjirpf0dA2CphlO9UCIKUxnLiIm_g,5637
-python_docs_mcp_server-0.3.1.dist-info/METADATA,sha256=OGvwbikJSXf2KSdeA5grj0PwDRhjDECRtmW_Wk6N_MA,14808
-python_docs_mcp_server-0.3.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_docs_mcp_server-0.3.1.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
-python_docs_mcp_server-0.3.1.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
-python_docs_mcp_server-0.3.1.dist-info/RECORD,,
+python_docs_mcp_server-0.4.0.dist-info/METADATA,sha256=qBymOswxf7xctE7iOhiuRO0aQHxYuod0Fy3ib6Tq6Dw,16992
+python_docs_mcp_server-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_docs_mcp_server-0.4.0.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
+python_docs_mcp_server-0.4.0.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
+python_docs_mcp_server-0.4.0.dist-info/RECORD,,

{python_docs_mcp_server-0.3.1.dist-info → python_docs_mcp_server-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any