# mobile-docs-mcp

[![PyPI](https://img.shields.io/pypi/v/mobile-docs-mcp.svg)](https://pypi.org/project/mobile-docs-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/mobile-docs-mcp.svg)](https://pypi.org/project/mobile-docs-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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.**

> **Install:** `uvx mobile-docs-mcp` (nothing to clone) — or `pip install
> mobile-docs-mcp`. Published on [PyPI](https://pypi.org/project/mobile-docs-mcp/).
> Jump to [Editor & IDE setup](#editor--ide-setup-ios--android).

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
# Recommended: fetch + run on demand, no install step
uvx mobile-docs-mcp

# Or install into the current environment
pip install mobile-docs-mcp
mobile-docs-mcp                          # stdio transport

# From source (for development)
git clone https://github.com/asif786ka/mobile-docs-mcp
cd mobile-docs-mcp && pip install -e .
python -m mobile_docs_mcp.server
```

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:

- **Recommended (from PyPI):** `command: "uvx"`, `args: ["mobile-docs-mcp"]` — no clone, no `cwd`. This is what the examples below use.
- **From source:** `command: "python"`, `args: ["-m", "mobile_docs_mcp.server"]`, with `cwd` set to the repo path.

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
# published package, shared with the repo via .mcp.json (project scope)
claude mcp add mobile-docs-mcp --scope project -- uvx mobile-docs-mcp
# from source instead:  claude mcp add mobile-docs-mcp -- python -m mobile_docs_mcp.server
```

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": "uvx",
      "args": ["mobile-docs-mcp"]
    }
  }
}
```

(Layer in crawled corpora with `"env": { "MOBILE_DOCS_DATA": "/abs/path/data/android,/abs/path/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": "uvx",
      "args": ["mobile-docs-mcp"]
    }
  }
}
```

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": "uvx",
      "args": ["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": "uvx",
      "args": ["mobile-docs-mcp"]
    }
  }
}
```

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.