android-source-explorer-mcp

# Android Source Explorer MCP Server MCP server for exploring AOSP internals and Jetpack libraries. <p align="center"> <img src="project-logo.png" width="600" alt="Android Source Explorer Logo"> </p> ## Purpose When building Android applications, AI tools often rely on outdated training data or incomplete summaries of the Android Framework. This MCP server provides **on-demand, precise access to the actual source code** (AOSP and AndroidX), enabling the AI to understand complex framework internals like the `Activity` lifecycle, `ViewModel` restoration, or `Compose` internals directly from the truth. --- ## Installation & Setup ### Prerequisites - [uv](https://github.com/astral-sh/uv) (Recommended) or Python 3.11+ - Git ### Recommended Installation (via uv) The easiest way to install and keep `android-source-explorer` up to date is using `uv`. It handles dependencies (including native ones like Tree-sitter and Cryptography) reliably across platforms. ```bash uv tool install git+https://github.com/mrmike/android-source-explorer-mcp ``` This will make the `android-source-explorer` command available globally in your PATH. ### Initial Sync After installation, you need to perform an initial sync to fetch the Android source code: ```bash # Sync API 36 (Android 16) and common AndroidX packages android-source-explorer sync --api-level 36 --androidx "compose,lifecycle,activity" # (Optional) Download LSP servers for cross-file features android-source-explorer sync --lsp ``` Check sync status: ```bash android-source-explorer status ``` ### Keeping Sources Up-to-Date To check for and download the latest available Android Framework revisions (AOSP tags) and newer stable versions of your synced AndroidX packages, run: ```bash # Update all synced framework APIs and AndroidX packages, then rebuild the index android-source-explorer update # (Optional) Clean up older versions of updated AndroidX packages android-source-explorer update --clean # Update only a specific API level or AndroidX package android-source-explorer update --api-level 36 android-source-explorer update --androidx activity-compose ``` --- ## Configuration Add the MCP server to your configuration file (e.g., Claude Desktop, Cursor, Gemini CLI). ### Global Usage (Recommended) If installed via `uv tool install`, the tool is available globally. **Basic Setup:** ```json { "mcpServers": { "android-sources": { "command": "android-source-explorer", "args": ["serve"] } } } ``` **With LSP Features Enabled:** ```json { "mcpServers": { "android-sources": { "command": "android-source-explorer", "args": ["serve"], "env": { "ANDROID_SOURCE_LSP": "true" } } } } ``` ### Development Usage If you cloned the repository and want to run it from the source: ```json { "mcpServers": { "android-sources": { "command": "uv", "args": ["run", "--directory", "/absolute/path/to/android-source-explorer", "android-source-explorer", "serve"] } } } ``` --- ## How It Works ### 1. Hybrid Architecture (Tree-sitter + LSP) The server uses a **dual-engine approach** to balance speed and intelligence: - **Tree-sitter (Surgical Engine):** Provides near-instant (sub-10ms) AST parsing of single files. It precisely extracts method bodies (including Javadoc and annotations), class members, and inheritance hierarchies without the overhead of a full compiler. - **LSP (Global Engine):** Optionally leverages the **Eclipse JDT LS** (Java) and **Kotlin Language Server** for cross-file navigation. This enables finding references across millions of lines of code and resolving types that span multiple libraries. ### 2. Local Sync Strategy To ensure all lookups are instant and offline-ready, the server uses a `sync` or `update` command to manage sources in a local cache (`~/.android-sources/`): - **AOSP:** Fetches framework sources directly from `android.googlesource.com` using git sparse-checkouts. - **AndroidX:** Downloads `-sources.jar` files from the Google Maven repository (`dl.google.com/dl/android/maven2/`). - **Hybrid Indexing:** Prioritizes your local `$ANDROID_HOME` sources if available, supplemented by the downloaded cache. - **Automatic Updates:** The `update` command queries remote endpoints (AOSP Git tags & Google Maven indexes) for updates, downloads newer revisions/versions, and rebuilds the class index. --- ## Available Tools | Tool | Engine | Description | |------|--------|-------------| | `search_classes` | Index | Search for classes by glob pattern or substring. | | `lookup_class` | FS | Retrieve the full source code for a specific class. | | `lookup_method` | Tree-sitter | Extract a precise method body + its Javadoc/annotations. | | `list_class_members` | Tree-sitter | List all method and field signatures in a class. | | `get_class_hierarchy` | Tree-sitter | Get the inheritance chain (superclass + interfaces). | | `search_in_source` | FS/Regex | Search for text/regex across the entire source tree. | | `goto_definition`* | LSP | Resolve the cross-file definition of a symbol. | | `find_references`* | LSP | Find all usages of a class/method across the whole tree. | | `get_type_info`* | LSP | Get documentation and type info via hover data. | *\*Requires `ANDROID_SOURCE_LSP=true`* --- ## License Apache License 2.0