android-source-explorer-mcp
MCP server for exploring AOSP internals and Jetpack libraries
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/mrmike--android-source-explorer-mcp)HTML
<a href="/listings/mrmike--android-source-explorer-mcp"><img src="/api/listings/mrmike--android-source-explorer-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
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:
# 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:
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:
# 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
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 151 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.