python-docs-mcp-server 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

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/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/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,
+        )

{python_docs_mcp_server-0.3.0.dist-info → python_docs_mcp_server-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-docs-mcp-server
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -48,6 +48,13 @@ Built for the moment your agent needs `asyncio.TaskGroup` signatures, `pathlib.P
 
 ## Why this exists
 
+There is a difference between long context and usable context. Research like the
+[*Lost in the Middle*](https://arxiv.org/abs/2307.03172) study (Liu et al., 2023)
+found that models struggle to use relevant information buried in the middle of a
+long input. Pasting an entire documentation page into the model invites that
+failure. Returning the exact symbol, section, and version keeps the answer in a
+short, high-signal context instead.
+
 Generic docs retrieval is a rough fit for Python stdlib questions:
 
 - `asyncio.TaskGroup` should resolve to the actual symbol, not a fuzzy page hit
@@ -120,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:
@@ -140,6 +161,26 @@ cache. It can take several minutes.
 
 ## Configure your MCP client
 
+### Claude Code
+
+This repository includes a project-scoped `.mcp.json` for clients that support
+checked-in MCP server configuration. It points at the published package:
+
+```json
+{
+  "mcpServers": {
+    "python-docs": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["python-docs-mcp-server"]
+    }
+  }
+}
+```
+
+Build the local documentation index with the first-run command above before
+expecting docs queries to return corpus-backed results.
+
 ### Claude Desktop
 
 Add this to your Claude Desktop configuration file:
@@ -217,6 +258,16 @@ The server currently exposes six MCP tools:
 | `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. |
 
+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?
 
 Use this server when you want precise local Python docs retrieval rather than

{python_docs_mcp_server-0.3.0.dist-info → python_docs_mcp_server-0.3.2.dist-info}/RECORD

@@ -14,26 +14,26 @@ 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/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.0.dist-info/METADATA,sha256=_3VIV56ywUeSNOWBiexQl2RbhI8MO49wLmFsAQDPW34,13913
-python_docs_mcp_server-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_docs_mcp_server-0.3.0.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
-python_docs_mcp_server-0.3.0.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
-python_docs_mcp_server-0.3.0.dist-info/RECORD,,
+python_docs_mcp_server-0.3.2.dist-info/METADATA,sha256=-qJFihR4PRVHt3lqrIbY8asRrD1XQt94RCRcUbQ5CgA,16256
+python_docs_mcp_server-0.3.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_docs_mcp_server-0.3.2.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
+python_docs_mcp_server-0.3.2.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
+python_docs_mcp_server-0.3.2.dist-info/RECORD,,

{python_docs_mcp_server-0.3.0.dist-info → python_docs_mcp_server-0.3.2.dist-info}/WHEEL

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