# Android Docs MCP Server

An MCP (Model Context Protocol) server that gives AI agents direct access to [developer.android.com](https://developer.android.com/) — search docs, look up API references, browse packages, and check release notes.

## Quick Start

No installation needed — run directly with `npx` or `bunx`:

```bash
npx android-docs-mcp
```

```bash
bunx android-docs-mcp
```

## Usage

### VS Code

Add to your `.vscode/mcp.json` (or use the included one if cloning the repo):

```json
{
  "servers": {
    "android-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "android-docs-mcp"]
    }
  }
}
```

### Claude Desktop / Cursor / other MCP clients

Add to your MCP config:

```json
{
  "mcpServers": {
    "android-docs": {
      "command": "npx",
      "args": ["-y", "android-docs-mcp"]
    }
  }
}
```

### From source

```bash
git clone https://github.com/ankit-verma-209171/android-docs-mcp.git
cd android-docs-mcp
bun install
bun run dev
```

## Tools

### `search_android_docs`

Search across all Android documentation.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | *(required)* | Search query |
| `max_results` | number | 10 | Max results (1–30) |

### `get_android_doc_page`

Fetch and parse any developer.android.com page into Markdown.

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | Full URL to a developer.android.com page |

### `get_api_reference`

Look up API reference for a specific class by fully-qualified name.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `class_name` | string | *(required)* | FQCN (e.g., `android.app.Activity`) |
| `language` | `"java"` \| `"kotlin"` | auto | Defaults to kotlin for AndroidX, java for platform |

### `list_android_packages`

List available packages from the official package index.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | `"platform"` \| `"androidx"` | `"androidx"` | Package set |
| `language` | `"java"` \| `"kotlin"` | `"java"` | Doc language |
| `filter` | string | — | Substring filter (e.g., `"compose"`) |

### `get_release_notes`

Fetch Jetpack library release notes.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `library` | string | *(required)* | Library name (e.g., `compose`, `lifecycle`) |
| `version` | string | — | Filter to a specific version |
| `max_entries` | number | 5 | Max entries (1–50) |

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `CACHE_TTL_MS` | `86400000` (24h) | Cache time-to-live in milliseconds |

## Architecture

```
src/
├── index.ts              # MCP server entrypoint
├── lib/
│   ├── cache.ts          # In-memory LRU cache (500 entries, 24h TTL)
│   ├── fetcher.ts        # HTTP fetch with retry + cache integration
│   ├── parser.ts         # HTML → Markdown (cheerio + turndown)
│   └── url-resolver.ts   # FQCN → URL mapping
└── tools/
    ├── search.ts         # search_android_docs
    ├── get-doc.ts        # get_android_doc_page
    ├── get-api-reference.ts  # get_api_reference
    ├── list-packages.ts  # list_android_packages
    └── get-release-notes.ts  # get_release_notes
```

## Disclaimer

This tool fetches content from [developer.android.com](https://developer.android.com/) on demand at runtime. The documentation content is owned by Google and licensed under the [Creative Commons Attribution 2.5 License](https://creativecommons.org/licenses/by/2.5/), and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). This project is not affiliated with or endorsed by Google.

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.