Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mrmike--android-source-explorer-mcp/badge.svg)](/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

i

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)

  1. # Android Source Explorer MCP Server
  2. MCP server for exploring AOSP internals and Jetpack libraries.
  3. <p align="center">
  4. <img src="project-logo.png" width="600" alt="Android Source Explorer Logo">
  5. </p>
  6. ## Purpose
  7. 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.
  8. ---
  9. ## Installation & Setup
  10. ### Prerequisites
  11. - [uv](https://github.com/astral-sh/uv) (Recommended) or Python 3.11+
  12. - Git
  13. ### Recommended Installation (via uv)
  14. 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.
  15. ```bash
  16. uv tool install git+https://github.com/mrmike/android-source-explorer-mcp
  17. ```
  18. This will make the `android-source-explorer` command available globally in your PATH.
  19. ### Initial Sync
  20. After installation, you need to perform an initial sync to fetch the Android source code:
  21. ```bash
  22. # Sync API 36 (Android 16) and common AndroidX packages
  23. android-source-explorer sync --api-level 36 --androidx "compose,lifecycle,activity"
  24. # (Optional) Download LSP servers for cross-file features
  25. android-source-explorer sync --lsp
  26. ```
  27. Check sync status:
  28. ```bash
  29. android-source-explorer status
  30. ```
  31. ### Keeping Sources Up-to-Date
  32. To check for and download the latest available Android Framework revisions (AOSP tags) and newer stable versions of your synced AndroidX packages, run:
  33. ```bash
  34. # Update all synced framework APIs and AndroidX packages, then rebuild the index
  35. android-source-explorer update
  36. # (Optional) Clean up older versions of updated AndroidX packages
  37. android-source-explorer update --clean
  38. # Update only a specific API level or AndroidX package
  39. android-source-explorer update --api-level 36
  40. android-source-explorer update --androidx activity-compose
  41. ```
  42. ---
  43. ## Configuration
  44. Add the MCP server to your configuration file (e.g., Claude Desktop, Cursor, Gemini CLI).
  45. ### Global Usage (Recommended)
  46. If installed via `uv tool install`, the tool is available globally.
  47. **Basic Setup:**
  48. ```json
  49. {
  50. "mcpServers": {
  51. "android-sources": {
  52. "command": "android-source-explorer",
  53. "args": ["serve"]
  54. }
  55. }
  56. }
  57. ```
  58. **With LSP Features Enabled:**
  59. ```json
  60. {
  61. "mcpServers": {
  62. "android-sources": {
  63. "command": "android-source-explorer",
  64. "args": ["serve"],
  65. "env": {
  66. "ANDROID_SOURCE_LSP": "true"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. ### Development Usage
  73. If you cloned the repository and want to run it from the source:
  74. ```json
  75. {
  76. "mcpServers": {
  77. "android-sources": {
  78. "command": "uv",
  79. "args": ["run", "--directory", "/absolute/path/to/android-source-explorer", "android-source-explorer", "serve"]
  80. }
  81. }
  82. }
  83. ```
  84. ---
  85. ## How It Works
  86. ### 1. Hybrid Architecture (Tree-sitter + LSP)
  87. The server uses a **dual-engine approach** to balance speed and intelligence:
  88. - **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.
  89. - **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.
  90. ### 2. Local Sync Strategy
  91. 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/`):
  92. - **AOSP:** Fetches framework sources directly from `android.googlesource.com` using git sparse-checkouts.
  93. - **AndroidX:** Downloads `-sources.jar` files from the Google Maven repository (`dl.google.com/dl/android/maven2/`).
  94. - **Hybrid Indexing:** Prioritizes your local `$ANDROID_HOME` sources if available, supplemented by the downloaded cache.
  95. - **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.
  96. ---
  97. ## Available Tools
  98. | Tool | Engine | Description |
  99. |------|--------|-------------|
  100. | `search_classes` | Index | Search for classes by glob pattern or substring. |
  101. | `lookup_class` | FS | Retrieve the full source code for a specific class. |
  102. | `lookup_method` | Tree-sitter | Extract a precise method body + its Javadoc/annotations. |
  103. | `list_class_members` | Tree-sitter | List all method and field signatures in a class. |
  104. | `get_class_hierarchy` | Tree-sitter | Get the inheritance chain (superclass + interfaces). |
  105. | `search_in_source` | FS/Regex | Search for text/regex across the entire source tree. |
  106. | `goto_definition`* | LSP | Resolve the cross-file definition of a symbol. |
  107. | `find_references`* | LSP | Find all usages of a class/method across the whole tree. |
  108. | `get_type_info`* | LSP | Get documentation and type info via hover data. |
  109. *\*Requires `ANDROID_SOURCE_LSP=true`*
  110. ---
  111. ## License
  112. Apache License 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.