python-docs-mcp-server 0.1.2__py3-none-any.whl

mcp_server_python_docs/models.py

@@ -0,0 +1,216 @@
+"""Pydantic input/output models for all MCP tools.
+
+These models define the tool contracts. FastMCP auto-generates outputSchema
+from BaseModel return types, providing structuredContent for free (SRVR-05).
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+# --- search_docs models ---
+
+
+class SearchDocsInput(BaseModel):
+    """Input parameters for search_docs tool."""
+
+    query: str = Field(
+        max_length=500,
+        description="Search query - Python symbol (asyncio.TaskGroup) or concept (parse json)",
+    )
+    version: str | None = Field(
+        default=None,
+        description="Python version (e.g. '3.13'). Defaults to latest.",
+    )
+    kind: Literal["auto", "page", "symbol", "section", "example"] = Field(
+        default="auto",
+        description=(
+            "Search type. Use 'symbol' for API lookups, "
+            "'example' for code samples, 'auto' otherwise."
+        ),
+    )
+    max_results: int = Field(
+        default=5,
+        ge=1,
+        le=20,
+        description="Maximum number of results to return.",
+    )
+
+
+class SymbolHit(BaseModel):
+    """A single search result hit."""
+
+    uri: str = Field(description="Documentation URI path")
+    title: str = Field(description="Display title")
+    kind: str = Field(description="Hit type: class, function, method, module, etc.")
+    snippet: str = Field(default="", description="Brief excerpt or description")
+    score: float = Field(default=0.0, description="Relevance score")
+    version: str = Field(description="Python version this hit belongs to")
+    slug: str = Field(default="", description="Page slug for get_docs follow-up")
+    anchor: str | None = Field(
+        default=None,
+        description="Section anchor for get_docs follow-up; None for page-level hits",
+    )
+
+
+class SearchDocsResult(BaseModel):
+    """Output from search_docs tool."""
+
+    hits: list[SymbolHit] = Field(
+        default_factory=list,
+        description="Search result hits",
+    )
+    note: str | None = Field(
+        default=None,
+        description="Informational note (e.g., limited search mode)",
+    )
+
+
+# --- get_docs models ---
+
+
+class GetDocsInput(BaseModel):
+    """Input parameters for get_docs tool."""
+
+    slug: str = Field(
+        max_length=500,
+        description="Page slug (e.g. 'library/asyncio-task.html')",
+    )
+    version: str | None = Field(
+        default=None,
+        description="Python version. Defaults to latest.",
+    )
+    anchor: str | None = Field(
+        default=None,
+        description="Section anchor for section-only retrieval",
+    )
+    max_chars: int = Field(
+        default=8000,
+        ge=100,
+        le=50000,
+        description="Maximum characters to return",
+    )
+    start_index: int = Field(
+        default=0,
+        ge=0,
+        description="Start position for pagination",
+    )
+
+
+class GetDocsResult(BaseModel):
+    """Output from get_docs tool."""
+
+    content: str = Field(description="Documentation content in markdown")
+    slug: str = Field(description="Page slug")
+    title: str = Field(description="Page or section title")
+    version: str = Field(description="Python version")
+    anchor: str | None = Field(
+        default=None,
+        description="Section anchor if section-level",
+    )
+    char_count: int = Field(description="Total character count of full content")
+    truncated: bool = Field(
+        default=False,
+        description="Whether content was truncated",
+    )
+    next_start_index: int | None = Field(
+        default=None,
+        description="Next start_index for pagination, if truncated",
+    )
+
+
+# --- list_versions models ---
+
+
+class VersionInfo(BaseModel):
+    """Information about an available Python version."""
+
+    version: str = Field(description="Python version string (e.g. '3.13')")
+    language: str = Field(default="en", description="Documentation language")
+    label: str = Field(description="Display label")
+    is_default: bool = Field(description="Whether this is the default version")
+    built_at: str = Field(description="When this version's index was built")
+
+
+class ListVersionsResult(BaseModel):
+    """Output from list_versions tool."""
+
+    versions: list[VersionInfo] = Field(
+        description="Available documentation versions",
+    )
+
+
+# --- detect_python_version models ---
+
+
+class DetectPythonVersionResult(BaseModel):
+    """Output from detect_python_version tool."""
+
+    detected_version: str = Field(
+        description="Python major.minor detected from the user's environment (e.g. '3.13')"
+    )
+    source: str = Field(
+        description=(
+            "How the version was detected: '.python-version file',"
+            " 'python3 in PATH', or 'server runtime'"
+        )
+    )
+    matched_index_version: str | None = Field(
+        default=None,
+        description="The detected version if it matches an indexed doc set, otherwise null",
+    )
+    is_default: bool = Field(
+        description="Whether this detected version is being used as the default for get_docs"
+    )
+
+
+# --- lookup_package_docs models ---
+
+# Bounded kind vocabulary: hardcoded values from `_source` calls plus the
+# normalized members of `_ALLOWED` (with spaces → underscores) in
+# services/package_docs.py. Keep these in sync.
+PackageKind = Literal[
+    "pypi",
+    "docs",
+    "documentation",
+    "homepage",
+    "home_page",
+    "source",
+    "source_code",
+    "repository",
+    "repo",
+]
+
+
+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: PackageKind = Field(
+        description="Source category: pypi, docs, documentation, homepage, home_page, "
+        "source, source_code, repository, or repo"
+    )
+    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: Literal["pypi-declared-metadata"] = 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",
+    )

mcp_server_python_docs/retrieval/__init__.py

@@ -0,0 +1,31 @@
+"""Retrieval layer -- pure-logic query processing, ranking, and budget enforcement.
+
+No MCP types, no storage imports. Receives connections and data as parameters.
+"""
+from __future__ import annotations
+
+from mcp_server_python_docs.retrieval.budget import apply_budget
+from mcp_server_python_docs.retrieval.query import (
+    build_match_expression,
+    classify_query,
+    expand_synonyms,
+    fts5_escape,
+)
+from mcp_server_python_docs.retrieval.ranker import (
+    lookup_symbols_exact,
+    search_examples,
+    search_sections,
+    search_symbols,
+)
+
+__all__ = [
+    "apply_budget",
+    "build_match_expression",
+    "classify_query",
+    "expand_synonyms",
+    "fts5_escape",
+    "lookup_symbols_exact",
+    "search_examples",
+    "search_sections",
+    "search_symbols",
+]

mcp_server_python_docs/retrieval/budget.py

@@ -0,0 +1,63 @@
+"""Unicode-safe budget enforcement for content truncation.
+
+The single function apply_budget() handles all truncation and pagination
+for content-returning tools. It guarantees:
+- Never splits a Unicode codepoint (Python 3 str slicing is codepoint-safe)
+- Never splits a base character from its combining marks
+- Returns truncation flag and next_start_index for pagination
+
+Pure logic -- no MCP types, no storage imports.
+"""
+from __future__ import annotations
+
+import unicodedata
+
+
+def apply_budget(
+    text: str,
+    max_chars: int,
+    start_index: int = 0,
+) -> tuple[str, bool, int | None]:
+    """Apply character budget with Unicode-safe truncation (RETR-08).
+
+    Args:
+        text: Full text content to truncate.
+        max_chars: Maximum characters to return. Must be positive for
+            meaningful results.
+        start_index: Starting position for pagination (codepoint offset).
+
+    Returns:
+        Tuple of (truncated_text, is_truncated, next_start_index).
+        next_start_index is None when not truncated (all remaining text fits).
+    """
+    if not text or max_chars <= 0:
+        return ("", False, None)
+
+    if start_index >= len(text):
+        return ("", False, None)
+
+    remaining = text[start_index:]
+
+    if len(remaining) <= max_chars:
+        return (remaining, False, None)
+
+    # Truncate at max_chars boundary
+    end = start_index + max_chars
+
+    # Back up past any combining marks (Unicode category M: Mn, Mc, Me)
+    # so we don't separate a base character from its diacritics
+    while end > start_index and unicodedata.category(text[end - 1]).startswith("M"):
+        end -= 1
+
+    # If we backed up to start_index (edge case: all combining marks),
+    # advance to include at least the base char + its marks
+    if end == start_index and start_index < len(text):
+        end = start_index + 1
+        while end < len(text) and unicodedata.category(text[end]).startswith("M"):
+            end += 1
+
+    result = text[start_index:end]
+    truncated = end < len(text)
+    next_idx = end if truncated else None
+
+    return (result, truncated, next_idx)

mcp_server_python_docs/retrieval/query.py

@@ -0,0 +1,183 @@
+"""Query processing for FTS5 search.
+
+Provides FTS5 escape, query classification, and synonym expansion.
+Pure logic -- no MCP types, no storage imports.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Literal
+
+# Pattern for single-word Python module names (e.g., re, os, sys, io)
+_MODULE_PATTERN = re.compile(r"^[a-z_][a-z0-9_]*$")
+
+
+def fts5_escape(query: str) -> str:
+    """Escape user input for safe FTS5 MATCH queries (RETR-01).
+
+    Wraps every whitespace-separated token in double quotes to prevent
+    FTS5 operators (AND, OR, NOT, NEAR), prefix matching (*), column
+    filters (:), grouping (parens), and negation (-) from being
+    interpreted.
+
+    Inside FTS5 double quotes, the only special char is the double quote
+    itself, which is escaped by doubling ("").
+
+    Args:
+        query: Raw user input string.
+
+    Returns:
+        Escaped string safe for FTS5 MATCH. Empty/whitespace input
+        returns '""' (matches nothing, does not crash).
+    """
+    # Strip null bytes and other control characters that crash FTS5
+    query = query.replace("\x00", "").strip()
+    if not query:
+        return '""'
+    tokens = query.split()
+    escaped = []
+    for token in tokens:
+        # Strip null bytes from individual tokens too
+        token = token.replace("\x00", "")
+        if not token:
+            continue
+        # Escape internal double quotes by doubling them
+        safe = token.replace('"', '""')
+        # Wrap every token in double quotes
+        escaped.append(f'"{safe}"')
+    return " ".join(escaped) if escaped else '""'
+
+
+def classify_query(
+    query: str,
+    symbol_exists_fn: Callable[[str], bool],
+) -> Literal["symbol", "fts"]:
+    """Classify whether a query should use symbol fast-path or FTS5 (RETR-04).
+
+    Symbol-shaped queries are routed to the objects.inv symbol table
+    for direct lookup, skipping FTS5 entirely.
+
+    A query is symbol-shaped if:
+    1. It contains a dot (e.g., asyncio.TaskGroup, os.path.join)
+    2. It matches the lowercase identifier pattern AND exists in
+       the symbol table (prevents false positives on words like
+       "test", "list")
+
+    Args:
+        query: User search query.
+        symbol_exists_fn: Callback that checks if a name exists in the
+            symbols table. Injected by the service layer to avoid
+            importing storage.
+
+    Returns:
+        "symbol" for symbol fast-path, "fts" for full-text search.
+    """
+    query = query.strip()
+    if not query:
+        return "fts"
+    # Dotted names are always symbol-shaped
+    if "." in query:
+        return "symbol"
+    # Single-word module names (re, os, sys) -- only if they exist
+    # in the symbol table to avoid false positives
+    if _MODULE_PATTERN.match(query) and symbol_exists_fn(query):
+        return "symbol"
+    return "fts"
+
+
+def _build_concept_patterns(
+    synonyms: dict[str, list[str]],
+) -> dict[str, re.Pattern[str]]:
+    """Pre-compile word-boundary regex patterns for multi-word synonym concepts."""
+    patterns: dict[str, re.Pattern[str]] = {}
+    for concept in synonyms:
+        if " " in concept:
+            patterns[concept] = re.compile(r"\b" + re.escape(concept) + r"\b")
+    return patterns
+
+
+def expand_synonyms(
+    query: str,
+    synonyms: dict[str, list[str]],
+    *,
+    _concept_patterns: dict[str, re.Pattern[str]] | None = None,
+) -> set[str]:
+    """Expand query using synonym table for concept search (RETR-05).
+
+    Checks each token and multi-word phrases against the synonym table.
+    Single-word concepts use exact token matching. Multi-word concepts
+    use word-boundary regex to avoid substring false positives (CR-01).
+
+    Args:
+        query: User search query.
+        synonyms: Mapping of concept -> list of expansion terms.
+            Loaded from synonyms.yaml at startup.
+        _concept_patterns: Pre-compiled regex patterns for multi-word
+            concepts. Built lazily on first call if not provided.
+
+    Returns:
+        Set of terms (original + expansions). Empty set if query
+        is empty.
+    """
+    query = query.strip()
+    if not query:
+        return set()
+
+    tokens = query.lower().split()
+    expanded = set(tokens)
+
+    # Single-word concepts: exact token match (no substring false positives)
+    for token in tokens:
+        if token in synonyms:
+            expanded.update(synonyms[token])
+
+    # Multi-word concepts: word-boundary regex match (CR-01 fix)
+    if _concept_patterns is None:
+        _concept_patterns = _build_concept_patterns(synonyms)
+    query_lower = query.lower()
+    for concept, expansions in synonyms.items():
+        if " " not in concept:
+            continue
+        pattern = _concept_patterns.get(concept)
+        if pattern and pattern.search(query_lower):
+            expanded.update(expansions)
+
+    return expanded
+
+
+def build_match_expression(
+    query: str,
+    synonyms: dict[str, list[str]],
+    *,
+    _concept_patterns: dict[str, re.Pattern[str]] | None = None,
+) -> str:
+    """Build a complete FTS5 MATCH expression with synonym expansion.
+
+    If synonyms match, produces an OR-joined expression of escaped terms.
+    If no synonyms match, produces the plain escaped query (implicit AND).
+
+    Args:
+        query: User search query.
+        synonyms: Synonym mapping for expansion.
+        _concept_patterns: Pre-compiled regex patterns for multi-word concepts.
+
+    Returns:
+        FTS5-safe MATCH expression string.
+    """
+    query = query.strip()
+    if not query:
+        return '""'
+
+    expanded = expand_synonyms(query, synonyms, _concept_patterns=_concept_patterns)
+    original_tokens = set(query.lower().split())
+
+    # If expansion added new terms, OR-join all terms
+    if expanded != original_tokens:
+        original_query = fts5_escape(query)
+        escaped_terms = [fts5_escape(term) for term in sorted(expanded)]
+        extra_terms = [term for term in escaped_terms if term != original_query]
+        return " OR ".join([original_query, *extra_terms])
+
+    # No expansion -- use plain escaped query (implicit AND)
+    return fts5_escape(query)