mobile-docs-mcp 0.1.0__tar.gz

mobile_docs_mcp-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Crawled index output (regenerate via ingest; keep only the seed in git)
+data/android/
+data/apple/
+*.index
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+
+# Secrets / local config
+.env
+.env.*

mobile_docs_mcp-0.1.0/HOSTED.md

@@ -0,0 +1,78 @@
+# Open-core architecture
+
+`mobile-docs-mcp` is designed to live two lives from one codebase — the same
+split Context7 uses (MIT client, proprietary backend).
+
+```
+┌─────────────────────────────┐        ┌──────────────────────────────┐
+│  PUBLIC  (this repo, MIT)   │        │  HOSTED  (yours, private)    │
+│                             │        │                              │
+│  mobile_docs_mcp/           │        │  hosted/app.py               │
+│    server.py  (MCP tools)   │  HTTP  │    FastAPI over the SAME      │
+│    store.py   (retrieval)   │ ─────▶ │    Store, but serving the     │
+│    ingest/    (crawlers)    │        │    full crawled index         │
+│    + bundled SEED corpus    │        │    + API keys + rate limits   │
+│                             │        │    + freshness pipeline       │
+│  → the funnel & credibility │        │  → the paid product          │
+└─────────────────────────────┘        └──────────────────────────────┘
+```
+
+The public half is fully usable on its own (`uvx mobile-docs-mcp` against the
+seed corpus). That's what goes on GitHub and into interviews. The hosted half is
+what you'd run as a service if you commercialize: it serves a large, continuously
+refreshed, version-tagged index that isn't practical to bundle or self-host — the
+same thing that makes Context7's backend defensible.
+
+Open-sourcing the client does **not** give away the moat. The moat is index
+breadth + freshness, which lives in the deployment, not the code.
+
+## What stays public vs. private
+
+| Public (MIT) | Private (if you monetize) |
+|---|---|
+| MCP server + tool surface | Full crawled index (all androidx + SwiftUI symbols/versions) |
+| Retrieval logic (`store.py`) | Freshness pipeline (scheduled re-crawl + diff) |
+| Ingestion framework (`ingest/`) | Hosted API auth, billing, rate limiting |
+| Seed corpus (demo) | Enterprise mode: index a customer's **private** SDK docs |
+
+## Run the hosted backend locally
+
+```bash
+pip install fastapi uvicorn
+uvicorn hosted.app:app --host 0.0.0.0 --port 8000
+
+curl "http://localhost:8000/verify?name=scrollTargetBehavior&target_version=16.0&platform=apple"
+# {"status":"unavailable","detail":"scrollTargetBehavior was introduced in 17.0 ..."}
+```
+
+Env vars:
+
+```bash
+MOBILE_DOCS_DATA=data/android,data/apple   # serve a real crawled index, not the seed
+MOBILE_DOCS_REQUIRE_KEY=1                   # enforce API keys
+MOBILE_DOCS_API_KEYS=key_abc,key_def        # (stub — replace with a real key store)
+```
+
+## Deploy on Replit (fast MVP / demo)
+
+1. Create a Replit from your GitHub repo (or the private fork holding a real index).
+2. Set the run command:
+   ```
+   uvicorn hosted.app:app --host 0.0.0.0 --port 8000
+   ```
+3. Add `fastapi` and `uvicorn` to the environment (Replit auto-detects from
+   `pip install`, or add a `requirements-hosted.txt`).
+4. Replit exposes it at a public URL — point a landing page at `/search` and
+   `/verify`, collect usage, validate willingness-to-pay before investing in the
+   full crawl + freshness pipeline.
+
+Replit is right for the demo endpoint and validation. If real pull appears, move
+the crawl pipeline + vector store to durable infra; keep Replit as the front door.
+
+## Next step: remote-index mode for the MCP server
+
+To let the public MCP server call your hosted index instead of the local seed,
+add a `RemoteStore` that implements `search()` / `find_symbols()` over HTTP and
+select it in `server.py` when `MOBILE_DOCS_REMOTE` is set. That turns the same
+`uvx mobile-docs-mcp` install into a thin client of your paid backend — the
+Context7 distribution model exactly.

mobile_docs_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mobile_docs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: mobile-docs-mcp
+Version: 0.1.0
+Summary: Version-aware mobile docs MCP server for Android (Jetpack/Compose) and Apple (SwiftUI/UIKit)
+Project-URL: Homepage, https://github.com/asif786ka/mobile-docs-mcp
+Project-URL: Repository, https://github.com/asif786ka/mobile-docs-mcp
+Project-URL: Issues, https://github.com/asif786ka/mobile-docs-mcp/issues
+Author: Asif
+License: MIT
+License-File: LICENSE
+Keywords: android,documentation,ios,jetpack-compose,mcp,rag,swiftui
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: rank-bm25>=0.2.2
+Provides-Extra: hosted
+Requires-Dist: fastapi>=0.110.0; extra == 'hosted'
+Requires-Dist: uvicorn>=0.29.0; extra == 'hosted'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40.0; extra == 'openai'
+Provides-Extra: vector
+Requires-Dist: sentence-transformers>=3.0.0; extra == 'vector'
+Description-Content-Type: text/markdown
+
+# mobile-docs-mcp
+
+A version-aware documentation MCP server for mobile development — the context7
+idea, but specialized for the thing generic doc proxies get wrong: **which
+version of an API you can actually use.**
+
+It indexes Android (Jetpack / androidx / Compose) and Apple (SwiftUI / UIKit)
+documentation with `since` / `deprecated` / `removed` metadata on every symbol,
+so an agent can *verify an API exists on the version the project targets* before
+writing code against it.
+
+## Why it's different from a doc proxy
+
+Most "Apple docs" / "Android docs" MCP servers live-fetch and parse the current
+doc site. They answer "what is `scrollTargetBehavior`?" but not "can I use it on
+iOS 16?" — and that second question is where coding agents hallucinate. Every
+result here is filtered and annotated against a target version.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `search_mobile_docs` | Hybrid (BM25 + optional vector) retrieval, filtered by platform + target version |
+| `get_api_reference` | Full symbol card: signature, availability, deprecation/migration pointer |
+| `verify_api_exists` | Anti-hallucination check — real AND usable on a given version? |
+| `list_api_versions` | since / deprecated / removed timeline + migration lineage |
+| `get_release_notes` | What changed in a library/version |
+
+Example verdict:
+
+```
+verify_api_exists("scrollTargetBehavior", "16.0", "apple")
+→ ❌ NOT AVAILABLE — introduced in 17.0, newer than 16.0. Will not compile there.
+```
+
+## Run
+
+```bash
+# From source
+pip install -e .
+python -m mobile_docs_mcp.server        # stdio transport
+
+# Once published
+uvx mobile-docs-mcp
+```
+
+Ships with a seed corpus, so it works immediately with no crawl.
+
+## Editor & IDE setup (iOS + Android)
+
+The server speaks MCP over stdio, so any MCP-capable editor can use it. All the
+tools work for **both** platforms — you'll lean on the SwiftUI entries in an iOS
+project and the Compose/androidx entries in an Android one, but nothing is
+editor-specific. Two ways to launch it:
+
+- **From source (this repo):** `command: "python"`, `args: ["-m", "mobile_docs_mcp.server"]`, with `cwd` set to the repo path.
+- **Once published:** `command: "uvx"`, `args: ["mobile-docs-mcp"]` (no `cwd` needed).
+
+Set `MOBILE_DOCS_DATA` in `env` to layer in any corpora you've crawled with the
+ingesters (see "Growing the index").
+
+### Claude Code (CLI)
+
+```bash
+# from source, shared with the repo via .mcp.json (project scope)
+claude mcp add mobile-docs-mcp --scope project -- python -m mobile_docs_mcp.server
+# or, once published
+claude mcp add mobile-docs-mcp -- uvx mobile-docs-mcp
+```
+
+Verify with `claude mcp list`, or `/mcp` inside a session.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config), then
+restart the app:
+
+```json
+{
+  "mcpServers": {
+    "mobile-docs-mcp": {
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "/absolute/path/to/mobile-docs-mcp",
+      "env": { "MOBILE_DOCS_DATA": "data/android,data/apple" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Create `.cursor/mcp.json` in the project root (or `~/.cursor/mcp.json` for all
+projects) — same `mcpServers` shape as above:
+
+```json
+{
+  "mcpServers": {
+    "mobile-docs-mcp": {
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+Then enable it under Settings → MCP.
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json` (Cascade panel → MCP icon →
+Configure). Same `mcpServers` shape; Windsurf supports `${env:VAR}` interpolation
+so you can keep paths/secrets out of the file:
+
+```json
+{
+  "mcpServers": {
+    "mobile-docs-mcp": {
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "/absolute/path/to/mobile-docs-mcp"
+    }
+  }
+}
+```
+
+### Android Studio
+
+Gemini in Android Studio is an MCP client. Go to **Settings → Tools → AI → MCP
+Servers**, tick **Enable MCP Servers**, and paste the same `mcpServers` JSON
+block shown for Claude Desktop. Confirm with the "Successfully connected"
+notification, then type `/mcp` in the chat to see the tools. Great for checking
+`androidx`/Compose availability against your module's `compileSdk` / library
+versions without leaving the IDE.
+
+### VS Code
+
+VS Code's key is `servers` (not `mcpServers`) and wants an explicit `type`.
+Create `.vscode/mcp.json` (commit it to share with the team):
+
+```json
+{
+  "servers": {
+    "mobile-docs-mcp": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "${workspaceFolder}",
+      "env": { "MOBILE_DOCS_DATA": "data/android,data/apple" }
+    }
+  }
+}
+```
+
+Open the file and click **Start**, or run *MCP: List Servers* from the Command
+Palette. Copilot Chat's Agent mode will then surface the tools.
+
+### Xcode
+
+Xcode 26.3+ is itself an **MCP server** (it exposes build / test / preview /
+Apple-doc-search tools) rather than an MCP client — so you don't register
+`mobile-docs-mcp` *inside* Xcode. Instead, run an agent that consumes both: point
+Claude Code (or Cursor / Codex) at `mobile-docs-mcp` using the steps above while
+it's also connected to Xcode's server. The agent then gets Xcode's build/preview
+tools **and** this server's `verify_api_exists` version checks in one session —
+e.g. it can confirm `scrollTargetBehavior` needs iOS 17 before writing it against
+your iOS 16 deployment target, then build the project to check.
+
+## Architecture
+
+```
+ingest/  (batch, offline)          server.py  (runtime)
+  android.py  developer.android.com   FastMCP
+  apple.py    Apple JSON doc API        │
+      │                                 ▼
+      ▼                             store.py — hybrid, version-aware
+  symbols.json + chunks.json          1. BM25 lexical recall
+  (version-tagged)                    2. vector recall (optional)
+                                      3. RRF fusion
+                                      4. VERSION FILTER  ← the differentiator
+                                      5. cross-encoder rerank (optional)
+```
+
+Retrieval is provider-agnostic (`embeddings.py`), same shape as a multi-provider
+model gateway: BM25 works fully offline; vector recall and rerank switch on via
+env var with no code change and degrade gracefully if a provider is missing.
+
+```bash
+MOBILE_DOCS_EMBEDDINGS=local   # or openai ; default none (BM25-only)
+MOBILE_DOCS_RERANK=local       # default none
+MOBILE_DOCS_DATA=data/android,data/apple   # layer in crawled corpora
+```
+
+## Growing the index
+
+```bash
+python -m mobile_docs_mcp.ingest.android --out data/android \
+    --refs androidx.compose.foundation.lazy.LazyColumn \
+    --release-notes compose-foundation navigation
+
+python -m mobile_docs_mcp.ingest.apple --out data/apple \
+    --paths swiftui/navigationstack swiftui/view/scrolltargetbehavior
+```
+
+Then point the server at the output with `MOBILE_DOCS_DATA`.
+
+## Status
+
+MVP. The protocol layer, version logic, hybrid store, and tool surface are
+production-shaped; the ingestion coverage is a seed. The real work — and the moat
+— is breadth and freshness of the version-tagged index.
+
+MIT.

mobile_docs_mcp-0.1.0/README.md

@@ -0,0 +1,214 @@
+# mobile-docs-mcp
+
+A version-aware documentation MCP server for mobile development — the context7
+idea, but specialized for the thing generic doc proxies get wrong: **which
+version of an API you can actually use.**
+
+It indexes Android (Jetpack / androidx / Compose) and Apple (SwiftUI / UIKit)
+documentation with `since` / `deprecated` / `removed` metadata on every symbol,
+so an agent can *verify an API exists on the version the project targets* before
+writing code against it.
+
+## Why it's different from a doc proxy
+
+Most "Apple docs" / "Android docs" MCP servers live-fetch and parse the current
+doc site. They answer "what is `scrollTargetBehavior`?" but not "can I use it on
+iOS 16?" — and that second question is where coding agents hallucinate. Every
+result here is filtered and annotated against a target version.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `search_mobile_docs` | Hybrid (BM25 + optional vector) retrieval, filtered by platform + target version |
+| `get_api_reference` | Full symbol card: signature, availability, deprecation/migration pointer |
+| `verify_api_exists` | Anti-hallucination check — real AND usable on a given version? |
+| `list_api_versions` | since / deprecated / removed timeline + migration lineage |
+| `get_release_notes` | What changed in a library/version |
+
+Example verdict:
+
+```
+verify_api_exists("scrollTargetBehavior", "16.0", "apple")
+→ ❌ NOT AVAILABLE — introduced in 17.0, newer than 16.0. Will not compile there.
+```
+
+## Run
+
+```bash
+# From source
+pip install -e .
+python -m mobile_docs_mcp.server        # stdio transport
+
+# Once published
+uvx mobile-docs-mcp
+```
+
+Ships with a seed corpus, so it works immediately with no crawl.
+
+## Editor & IDE setup (iOS + Android)
+
+The server speaks MCP over stdio, so any MCP-capable editor can use it. All the
+tools work for **both** platforms — you'll lean on the SwiftUI entries in an iOS
+project and the Compose/androidx entries in an Android one, but nothing is
+editor-specific. Two ways to launch it:
+
+- **From source (this repo):** `command: "python"`, `args: ["-m", "mobile_docs_mcp.server"]`, with `cwd` set to the repo path.
+- **Once published:** `command: "uvx"`, `args: ["mobile-docs-mcp"]` (no `cwd` needed).
+
+Set `MOBILE_DOCS_DATA` in `env` to layer in any corpora you've crawled with the
+ingesters (see "Growing the index").
+
+### Claude Code (CLI)
+
+```bash
+# from source, shared with the repo via .mcp.json (project scope)
+claude mcp add mobile-docs-mcp --scope project -- python -m mobile_docs_mcp.server
+# or, once published
+claude mcp add mobile-docs-mcp -- uvx mobile-docs-mcp
+```
+
+Verify with `claude mcp list`, or `/mcp` inside a session.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config), then
+restart the app:
+
+```json
+{
+  "mcpServers": {
+    "mobile-docs-mcp": {
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "/absolute/path/to/mobile-docs-mcp",
+      "env": { "MOBILE_DOCS_DATA": "data/android,data/apple" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Create `.cursor/mcp.json` in the project root (or `~/.cursor/mcp.json` for all
+projects) — same `mcpServers` shape as above:
+
+```json
+{
+  "mcpServers": {
+    "mobile-docs-mcp": {
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+Then enable it under Settings → MCP.
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json` (Cascade panel → MCP icon →
+Configure). Same `mcpServers` shape; Windsurf supports `${env:VAR}` interpolation
+so you can keep paths/secrets out of the file:
+
+```json
+{
+  "mcpServers": {
+    "mobile-docs-mcp": {
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "/absolute/path/to/mobile-docs-mcp"
+    }
+  }
+}
+```
+
+### Android Studio
+
+Gemini in Android Studio is an MCP client. Go to **Settings → Tools → AI → MCP
+Servers**, tick **Enable MCP Servers**, and paste the same `mcpServers` JSON
+block shown for Claude Desktop. Confirm with the "Successfully connected"
+notification, then type `/mcp` in the chat to see the tools. Great for checking
+`androidx`/Compose availability against your module's `compileSdk` / library
+versions without leaving the IDE.
+
+### VS Code
+
+VS Code's key is `servers` (not `mcpServers`) and wants an explicit `type`.
+Create `.vscode/mcp.json` (commit it to share with the team):
+
+```json
+{
+  "servers": {
+    "mobile-docs-mcp": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "mobile_docs_mcp.server"],
+      "cwd": "${workspaceFolder}",
+      "env": { "MOBILE_DOCS_DATA": "data/android,data/apple" }
+    }
+  }
+}
+```
+
+Open the file and click **Start**, or run *MCP: List Servers* from the Command
+Palette. Copilot Chat's Agent mode will then surface the tools.
+
+### Xcode
+
+Xcode 26.3+ is itself an **MCP server** (it exposes build / test / preview /
+Apple-doc-search tools) rather than an MCP client — so you don't register
+`mobile-docs-mcp` *inside* Xcode. Instead, run an agent that consumes both: point
+Claude Code (or Cursor / Codex) at `mobile-docs-mcp` using the steps above while
+it's also connected to Xcode's server. The agent then gets Xcode's build/preview
+tools **and** this server's `verify_api_exists` version checks in one session —
+e.g. it can confirm `scrollTargetBehavior` needs iOS 17 before writing it against
+your iOS 16 deployment target, then build the project to check.
+
+## Architecture
+
+```
+ingest/  (batch, offline)          server.py  (runtime)
+  android.py  developer.android.com   FastMCP
+  apple.py    Apple JSON doc API        │
+      │                                 ▼
+      ▼                             store.py — hybrid, version-aware
+  symbols.json + chunks.json          1. BM25 lexical recall
+  (version-tagged)                    2. vector recall (optional)
+                                      3. RRF fusion
+                                      4. VERSION FILTER  ← the differentiator
+                                      5. cross-encoder rerank (optional)
+```
+
+Retrieval is provider-agnostic (`embeddings.py`), same shape as a multi-provider
+model gateway: BM25 works fully offline; vector recall and rerank switch on via
+env var with no code change and degrade gracefully if a provider is missing.
+
+```bash
+MOBILE_DOCS_EMBEDDINGS=local   # or openai ; default none (BM25-only)
+MOBILE_DOCS_RERANK=local       # default none
+MOBILE_DOCS_DATA=data/android,data/apple   # layer in crawled corpora
+```
+
+## Growing the index
+
+```bash
+python -m mobile_docs_mcp.ingest.android --out data/android \
+    --refs androidx.compose.foundation.lazy.LazyColumn \
+    --release-notes compose-foundation navigation
+
+python -m mobile_docs_mcp.ingest.apple --out data/apple \
+    --paths swiftui/navigationstack swiftui/view/scrolltargetbehavior
+```
+
+Then point the server at the output with `MOBILE_DOCS_DATA`.
+
+## Status
+
+MVP. The protocol layer, version logic, hybrid store, and tool surface are
+production-shaped; the ingestion coverage is a seed. The real work — and the moat
+— is breadth and freshness of the version-tagged index.
+
+MIT.