mobile-docs-mcp 0.1.0__py3-none-any.whl

mobile_docs_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""mobile-docs-mcp — version-aware documentation MCP server for mobile dev."""
+
+__version__ = "0.1.0"

mobile_docs_mcp/embeddings.py

@@ -0,0 +1,131 @@
+"""Pluggable embedding + rerank providers.
+
+Design goal (mirrors a multi-provider model gateway): the base server is fully
+offline and dependency-light — BM25 only — while vector recall and cross-encoder
+rerank switch on via env var with *no code change* and *degrade gracefully* if the
+optional dependency or API key is missing.
+
+    MOBILE_DOCS_EMBEDDINGS = none (default) | local | openai
+    MOBILE_DOCS_RERANK     = none (default) | local
+
+`Store` treats an embedder with ``dim == 0`` as "vectors off", and detects the
+disabled reranker by the class name ``NullReranker``. Keep those two contracts
+stable and providers can be added freely.
+"""
+from __future__ import annotations
+
+import os
+from typing import List, Protocol, runtime_checkable
+
+
+# --- interfaces --------------------------------------------------------------
+
+@runtime_checkable
+class EmbeddingProvider(Protocol):
+    dim: int
+    def embed(self, texts: List[str]) -> List[List[float]]: ...
+
+
+@runtime_checkable
+class Reranker(Protocol):
+    def rerank(self, query: str, docs: List[str]) -> List[float]: ...
+
+
+# --- embedding providers -----------------------------------------------------
+
+class NullEmbedder:
+    """BM25-only mode. dim == 0 tells the Store to skip vector recall."""
+    dim = 0
+
+    def embed(self, texts: List[str]) -> List[List[float]]:
+        return []
+
+
+class LocalEmbedder:
+    """sentence-transformers, runs fully local. `pip install .[vector]`."""
+
+    def __init__(self, model_name: str = "") -> None:
+        from sentence_transformers import SentenceTransformer  # lazy: optional dep
+
+        model_name = model_name or os.getenv(
+            "MOBILE_DOCS_EMBEDDINGS_MODEL", "sentence-transformers/all-MiniLM-L6-v2"
+        )
+        self._model = SentenceTransformer(model_name)
+        self.dim = int(self._model.get_sentence_embedding_dimension())
+
+    def embed(self, texts: List[str]) -> List[List[float]]:
+        vecs = self._model.encode(
+            list(texts), normalize_embeddings=True, convert_to_numpy=True
+        )
+        return [v.tolist() for v in vecs]
+
+
+class OpenAIEmbedder:
+    """OpenAI embeddings. `pip install .[openai]`, needs OPENAI_API_KEY."""
+
+    def __init__(self, model_name: str = "") -> None:
+        from openai import OpenAI  # lazy: optional dep
+
+        self._client = OpenAI()
+        self._model = model_name or os.getenv(
+            "MOBILE_DOCS_OPENAI_EMBED_MODEL", "text-embedding-3-small"
+        )
+        # dims for the -3 family; hard-coded to avoid a probe call at import.
+        self.dim = 1536 if "small" in self._model else 3072
+
+    def embed(self, texts: List[str]) -> List[List[float]]:
+        resp = self._client.embeddings.create(model=self._model, input=list(texts))
+        return [d.embedding for d in resp.data]
+
+
+def get_embedding_provider() -> EmbeddingProvider:
+    """Select an embedder from MOBILE_DOCS_EMBEDDINGS. Never raises: any missing
+    dependency or credential falls back to BM25-only (NullEmbedder)."""
+    mode = os.getenv("MOBILE_DOCS_EMBEDDINGS", "none").strip().lower()
+    try:
+        if mode in ("local", "st", "sentence-transformers"):
+            return LocalEmbedder()
+        if mode == "openai":
+            return OpenAIEmbedder()
+    except Exception:  # optional dep / key absent → graceful degrade
+        return NullEmbedder()
+    return NullEmbedder()
+
+
+# --- rerankers ---------------------------------------------------------------
+
+class NullReranker:
+    """Disabled reranker. Store checks for this class name by design."""
+
+    def rerank(self, query: str, docs: List[str]) -> List[float]:
+        return []
+
+
+class LocalReranker:
+    """Cross-encoder rerank over the fused shortlist. `pip install .[vector]`."""
+
+    def __init__(self, model_name: str = "") -> None:
+        from sentence_transformers import CrossEncoder  # lazy: optional dep
+
+        model_name = model_name or os.getenv(
+            "MOBILE_DOCS_RERANK_MODEL", "cross-encoder/ms-marco-MiniLM-L-6-v2"
+        )
+        self._model = CrossEncoder(model_name)
+
+    def rerank(self, query: str, docs: List[str]) -> List[float]:
+        if not docs:
+            return []
+        pairs = [[query, d] for d in docs]
+        return [float(s) for s in self._model.predict(pairs)]
+
+
+def get_reranker() -> Reranker:
+    """Select a reranker from MOBILE_DOCS_RERANK. Falls back to NullReranker if
+    the optional dependency is unavailable."""
+    mode = os.getenv("MOBILE_DOCS_RERANK", "none").strip().lower()
+    try:
+        if mode in ("local", "cross-encoder", "ce"):
+            return LocalReranker()
+    except Exception:
+        return NullReranker()
+    return NullReranker()

mobile_docs_mcp/ingest/__init__.py

@@ -0,0 +1,6 @@
+"""Ingestion package.
+
+`seed` ships an in-repo corpus so the server works with no crawl. `android` and
+`apple` (batch, offline) grow the version-tagged index from the live doc sources;
+their output is layered in at runtime via MOBILE_DOCS_DATA.
+"""

mobile_docs_mcp/ingest/_common.py

@@ -0,0 +1,47 @@
+"""Shared plumbing for the batch ingesters.
+
+The ingesters are *offline-first*: each ships a small curated, version-verified
+table so `MOBILE_DOCS_DATA` growth is reproducible and testable with no network,
+and falls back to a best-effort live fetch (stdlib urllib, short timeout) for refs
+not in the table. Either way the output is the same shape the seed and runtime
+Store already speak: a `symbols.json` list and a `chunks.json` list of the exact
+dicts `ApiSymbol.from_dict` / `DocChunk.from_dict` consume.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Iterable, Optional
+
+from ..models import ApiSymbol, DocChunk
+
+
+def fetch(url: str, timeout: float = 8.0, accept: str = "text/html") -> Optional[str]:
+    """Best-effort GET. Returns the body text, or None on any failure so the
+    caller can fall back to the curated table instead of crashing a crawl."""
+    req = urllib.request.Request(
+        url, headers={"User-Agent": "mobile-docs-mcp-ingest/0.1", "Accept": accept}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            charset = resp.headers.get_content_charset() or "utf-8"
+            return resp.read().decode(charset, "replace")
+    except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError):
+        return None
+
+
+def write_corpus(out_dir: str | Path, symbols: Iterable[ApiSymbol],
+                 chunks: Iterable[DocChunk]) -> tuple[Path, Path]:
+    """Serialize a corpus to <out_dir>/symbols.json + chunks.json."""
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    syms = list(symbols)
+    chks = list(chunks)
+    sp, cp = out / "symbols.json", out / "chunks.json"
+    sp.write_text(json.dumps([s.to_dict() for s in syms], indent=2))
+    cp.write_text(json.dumps([c.to_dict() for c in chks], indent=2))
+    print(f"wrote {len(syms)} symbols -> {sp}")
+    print(f"wrote {len(chks)} chunks  -> {cp}")
+    return sp, cp

mobile_docs_mcp/ingest/android.py

@@ -0,0 +1,155 @@
+"""Android (Jetpack / androidx / Compose) ingester.
+
+Batch, offline. Produces a version-tagged corpus (symbols.json + chunks.json)
+under --out, which the runtime server layers in via MOBILE_DOCS_DATA.
+
+    python -m mobile_docs_mcp.ingest.android --out data/android \
+        --refs androidx.compose.foundation.lazy.LazyRow \
+               androidx.compose.foundation.pager.HorizontalPager \
+        --release-notes compose-foundation
+
+Refs are fully-qualified androidx names. Known refs come from a curated,
+version-verified table (works with no network); unknown refs are fetched
+best-effort from developer.android.com and, if that fails, emitted with
+version-unknown metadata and a warning rather than silently dropped.
+
+The curated entries here are intentionally *disjoint* from the built-in seed, so
+running this ingester demonstrably grows the index.
+"""
+from __future__ import annotations
+
+import argparse
+
+from ..models import PLATFORM_ANDROID, ApiSymbol, DocChunk, VersionRange
+from ._common import fetch, write_corpus
+
+REF_DOC_BASE = "https://developer.android.com/reference/kotlin/"
+RELEASE_NOTES_BASE = "https://developer.android.com/jetpack/androidx/releases/"
+
+# Curated, version-verified androidx symbols keyed by fully-qualified name.
+# scheme "androidx" = library semver.
+_CURATED: dict[str, dict] = {
+    "androidx.compose.foundation.lazy.LazyRow": dict(
+        name="LazyRow", kind="composable", package="androidx.compose.foundation.lazy",
+        signature="fun LazyRow(modifier: Modifier = Modifier, state: LazyListState = ..., content: LazyListScope.() -> Unit)",
+        summary="A horizontally scrolling list that only composes and lays out the "
+                "currently visible items.",
+        since="1.0.0", tags=["compose", "list", "lazy"]),
+    "androidx.compose.foundation.pager.HorizontalPager": dict(
+        name="HorizontalPager", kind="composable", package="androidx.compose.foundation.pager",
+        signature="fun HorizontalPager(state: PagerState, modifier: Modifier = Modifier, ...)",
+        summary="A horizontally scrolling pager. Graduated from Accompanist into "
+                "foundation and became stable in 1.6.0.",
+        since="1.6.0", tags=["compose", "pager"]),
+    "androidx.compose.foundation.lazy.rememberLazyListState": dict(
+        name="rememberLazyListState", kind="method", package="androidx.compose.foundation.lazy",
+        signature="fun rememberLazyListState(initialFirstVisibleItemIndex: Int = 0, ...): LazyListState",
+        summary="Creates and remembers a LazyListState for controlling and observing "
+                "a lazy list's scroll position.",
+        since="1.0.0", tags=["compose", "lazy", "state"]),
+    "androidx.compose.material3.pulltorefresh.PullToRefreshBox": dict(
+        name="PullToRefreshBox", kind="composable", package="androidx.compose.material3.pulltorefresh",
+        signature="fun PullToRefreshBox(isRefreshing: Boolean, onRefresh: () -> Unit, modifier: Modifier = Modifier, ...)",
+        summary="Material 3 pull-to-refresh container. Stable since material3 1.3.0.",
+        since="1.3.0", tags=["compose", "material3", "refresh"]),
+}
+
+# Curated release-note chunks keyed by library id.
+_RELEASE_NOTES: dict[str, list[dict]] = {
+    "compose-foundation": [
+        dict(version="1.6.0",
+             title="Compose Foundation 1.6.0 — pager graduates",
+             text="foundation 1.6.0 promotes HorizontalPager and VerticalPager from "
+                  "Accompanist to stable, and improves lazy-layout performance."),
+        dict(version="1.7.0",
+             title="Compose Foundation 1.7.0 — animateItem",
+             text="foundation 1.7.0 adds Modifier.animateItem (appearance + removal + "
+                  "placement) and deprecates Modifier.animateItemPlacement."),
+    ],
+    "compose-material3": [
+        dict(version="1.3.0",
+             title="Compose Material3 1.3.0 — pull to refresh",
+             text="material3 1.3.0 ships PullToRefreshBox and the pull-to-refresh "
+                  "APIs as stable, plus loading indicators and carousel updates."),
+    ],
+    "navigation": [
+        dict(version="2.8.0",
+             title="Navigation 2.8.0 — type-safe navigation",
+             text="navigation 2.8.0 introduces type-safe routes built on Kotlin "
+                  "serialization for the Navigation Compose graph."),
+    ],
+}
+
+
+def _symbol_from_curated(ref: str, meta: dict) -> ApiSymbol:
+    return ApiSymbol(
+        id=f"android:ingest:{meta['name']}", platform=PLATFORM_ANDROID,
+        name=meta["name"], kind=meta["kind"], package=meta["package"],
+        signature=meta["signature"], summary=meta["summary"],
+        version=VersionRange(scheme="androidx", since=meta.get("since"),
+                             deprecated=meta.get("deprecated"), removed=meta.get("removed")),
+        url=REF_DOC_BASE + meta["package"].replace(".", "/") + "/package-summary",
+        tags=meta.get("tags", []),
+    )
+
+
+def _symbol_from_fetch(ref: str) -> ApiSymbol:
+    """Best-effort live path for an un-curated ref. Confirms the page exists and
+    grabs a summary; leaves version unknown (the honest default) so downstream
+    verify() says 'exists but version unclear' rather than inventing a bound."""
+    pkg, _, name = ref.rpartition(".")
+    url = REF_DOC_BASE + pkg.replace(".", "/") + "/package-summary"
+    html = fetch(url)
+    summary = f"{name} in {pkg} (fetched from developer.android.com; version metadata not parsed)."
+    if html is None:
+        print(f"  ! could not fetch {ref}; emitting version-unknown record")
+        summary = f"{name} in {pkg} (offline: not verified against the doc site)."
+    return ApiSymbol(
+        id=f"android:ingest:{name}", platform=PLATFORM_ANDROID, name=name,
+        kind="unknown", package=pkg, signature=f"{name}(...)", summary=summary,
+        version=VersionRange(scheme="androidx"), url=url, tags=["compose"],
+    )
+
+
+def run(refs: list[str], release_notes: list[str], out: str) -> None:
+    symbols: list[ApiSymbol] = []
+    chunks: list[DocChunk] = []
+
+    for ref in refs:
+        if ref in _CURATED:
+            sym = _symbol_from_curated(ref, _CURATED[ref])
+        else:
+            sym = _symbol_from_fetch(ref)
+        symbols.append(sym)
+        chunks.append(DocChunk(
+            id=f"{sym.id}#ref", symbol_id=sym.id, platform=PLATFORM_ANDROID,
+            version=sym.version, title=f"{sym.name} — {sym.package}",
+            text=sym.summary, source="reference", url=sym.url,
+        ))
+
+    for lib in release_notes:
+        for i, note in enumerate(_RELEASE_NOTES.get(lib, [])):
+            chunks.append(DocChunk(
+                id=f"android:notes:{lib}:{note['version']}:{i}", symbol_id="",
+                platform=PLATFORM_ANDROID,
+                version=VersionRange(scheme="androidx", since=note["version"]),
+                title=note["title"], text=note["text"], source="release_notes",
+                url=RELEASE_NOTES_BASE + lib,
+            ))
+        if lib not in _RELEASE_NOTES:
+            print(f"  ! no curated release notes for '{lib}' (add to _RELEASE_NOTES or crawl)")
+
+    write_corpus(out, symbols, chunks)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Ingest androidx/Compose docs into a version-tagged corpus.")
+    p.add_argument("--out", required=True, help="output dir (holds symbols.json + chunks.json)")
+    p.add_argument("--refs", nargs="*", default=[], help="fully-qualified androidx names")
+    p.add_argument("--release-notes", nargs="*", default=[], help="library ids, e.g. compose-foundation")
+    a = p.parse_args()
+    run(a.refs, a.release_notes, a.out)
+
+
+if __name__ == "__main__":
+    main()

mobile_docs_mcp/ingest/apple.py

@@ -0,0 +1,132 @@
+"""Apple (SwiftUI / UIKit) ingester.
+
+Batch, offline. Produces a version-tagged corpus (symbols.json + chunks.json)
+under --out, layered into the runtime server via MOBILE_DOCS_DATA.
+
+    python -m mobile_docs_mcp.ingest.apple --out data/apple \
+        --paths swiftui/navigationlink swiftui/view/scrollposition
+
+Paths are doc-site paths (lowercase, as they appear after
+developer.apple.com/documentation/). Known paths come from a curated,
+version-verified table; unknown paths are fetched best-effort from Apple's JSON
+documentation API (the same feed the doc site renders from) and, if that fails,
+emitted with version-unknown metadata and a warning.
+
+Curated entries are disjoint from the built-in seed, so running this ingester
+demonstrably grows the index.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+
+from ..models import PLATFORM_APPLE, ApiSymbol, DocChunk, VersionRange
+from ._common import fetch, write_corpus
+
+# Apple renders the doc site from this JSON feed.
+JSON_API_BASE = "https://developer.apple.com/tutorials/data/documentation/"
+DOC_BASE = "https://developer.apple.com/documentation/"
+
+# Curated, version-verified SwiftUI symbols keyed by doc-site path.
+# scheme "ios" = iOS platform version.
+_CURATED: dict[str, dict] = {
+    "swiftui/navigationlink": dict(
+        name="NavigationLink", kind="struct", package="SwiftUI",
+        signature="struct NavigationLink<Label, Destination> where Label: View",
+        summary="A view that controls a navigation presentation, pushing a "
+                "destination when tapped. Works inside NavigationStack.",
+        since="13.0", tags=["navigation", "swiftui"]),
+    "swiftui/view/scrollposition": dict(
+        name="scrollPosition", kind="method", package="SwiftUI.View",
+        signature="func scrollPosition(id: Binding<(some Hashable)?>, anchor: UnitPoint? = nil) -> some View",
+        summary="Associates a binding to the identity of the scroll view's visible "
+                "content, for reading and programmatic scrolling. Added in iOS 17.0.",
+        since="17.0", tags=["scrollview", "swiftui"]),
+    "swiftui/grid": dict(
+        name="Grid", kind="struct", package="SwiftUI",
+        signature="struct Grid<Content> where Content: View",
+        summary="A container that arranges its child views in a two-dimensional "
+                "layout of rows and columns. Introduced at iOS 16.0.",
+        since="16.0", tags=["layout", "swiftui"]),
+    "swiftui/observable": dict(
+        name="Observable", kind="protocol", package="Observation",
+        signature="@attached(member) macro Observable()",
+        summary="The Observation macro that replaces ObservableObject for SwiftUI "
+                "state. Introduced at iOS 17.0.",
+        since="17.0", tags=["state", "observation", "swiftui"]),
+}
+
+
+def _symbol_from_curated(path: str, meta: dict) -> ApiSymbol:
+    return ApiSymbol(
+        id=f"apple:ingest:{meta['name']}", platform=PLATFORM_APPLE,
+        name=meta["name"], kind=meta["kind"], package=meta["package"],
+        signature=meta["signature"], summary=meta["summary"],
+        version=VersionRange(scheme="ios", since=meta.get("since"),
+                             deprecated=meta.get("deprecated"), removed=meta.get("removed")),
+        url=DOC_BASE + path, tags=meta.get("tags", []),
+    )
+
+
+def _parse_ios_since(doc: dict) -> str | None:
+    """Pull the iOS introduced-version from an Apple doc-API JSON payload."""
+    for plat in doc.get("platforms", []) or []:
+        if str(plat.get("name", "")).lower().startswith("ios") and plat.get("introducedAt"):
+            return str(plat["introducedAt"])
+    return None
+
+
+def _symbol_from_fetch(path: str) -> ApiSymbol:
+    """Best-effort live path for an un-curated doc path via Apple's JSON API."""
+    name = path.rstrip("/").split("/")[-1]
+    url = DOC_BASE + path
+    body = fetch(JSON_API_BASE + path + ".json", accept="application/json")
+    since = None
+    summary = f"{name} (SwiftUI). Fetched from Apple's doc API."
+    if body:
+        try:
+            doc = json.loads(body)
+            since = _parse_ios_since(doc)
+            title = (doc.get("metadata", {}) or {}).get("title") or name
+            name = title
+        except (json.JSONDecodeError, KeyError, TypeError):
+            print(f"  ! could not parse doc JSON for {path}")
+    else:
+        print(f"  ! could not fetch {path}; emitting version-unknown record")
+        summary = f"{name} (SwiftUI). Offline: not verified against Apple docs."
+    return ApiSymbol(
+        id=f"apple:ingest:{name}", platform=PLATFORM_APPLE, name=name,
+        kind="unknown", package="SwiftUI", signature=f"{name}",
+        summary=summary, version=VersionRange(scheme="ios", since=since),
+        url=url, tags=["swiftui"],
+    )
+
+
+def run(paths: list[str], out: str) -> None:
+    symbols: list[ApiSymbol] = []
+    chunks: list[DocChunk] = []
+    for path in paths:
+        key = path.strip("/").lower()
+        if key in _CURATED:
+            sym = _symbol_from_curated(key, _CURATED[key])
+        else:
+            sym = _symbol_from_fetch(key)
+        symbols.append(sym)
+        chunks.append(DocChunk(
+            id=f"{sym.id}#ref", symbol_id=sym.id, platform=PLATFORM_APPLE,
+            version=sym.version, title=f"{sym.name} — {sym.package}",
+            text=sym.summary, source="reference", url=sym.url,
+        ))
+    write_corpus(out, symbols, chunks)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Ingest SwiftUI/UIKit docs into a version-tagged corpus.")
+    p.add_argument("--out", required=True, help="output dir (holds symbols.json + chunks.json)")
+    p.add_argument("--paths", nargs="*", default=[], help="doc-site paths, e.g. swiftui/navigationlink")
+    a = p.parse_args()
+    run(a.paths, a.out)
+
+
+if __name__ == "__main__":
+    main()