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.
