# claude-android

> MCP server + Claude Code skills toolkit for Android dev workflows. Expose Gradle / Manifest / R8 context to Claude, ship a curated library of skills that consume it.

[![Status](https://img.shields.io/badge/status-v0.1%20preview-orange)](#status)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](#requirements)
[![MCP](https://img.shields.io/badge/MCP-stdio-blueviolet)](https://modelcontextprotocol.io)

## What it does

Android projects with Kotlin DSL + convention plugins + KMP + AGP-upgrade pain repeat the same
tasks: read versions, scan dependencies, plan migrations, audit R8 rules. Each task makes Claude
grep files line by line.

`claude-android` is an **MCP server** that exposes a small set of read-only tools (Gradle,
Manifest, ProGuard) so Claude can answer "what's my AGP version, what plugins, what
permissions" in milliseconds — and a **skills library** (`agp-upgrade`, `r8-audit`,
`string-sync`, …) that orchestrates those tools to deliver complete workflows.

```
┌──────────────────┐    stdio     ┌─────────────────────┐    fs    ┌──────────────┐
│  Claude Code     │  ────────▶   │  claude-android     │  ──────▶ │ your Android │
│  (CLI / agent)   │              │  MCP server         │           │ project      │
└──────────────────┘   tools list └─────────────────────┘  parsed   └──────────────┘
                                        ▲                  JSON
                                        │
                                ┌────────────────┐
                                │ skills/        │
                                │  agp-upgrade/  │
                                │  r8-audit/     │
                                │  ...           │
                                └────────────────┘
```

## v0.1 scope

What ships today:

| Component | Status |
| --- | --- |
| MCP server (stdio transport) | ✅ |
| Tool: `get_project_info` (settings.gradle + libs.versions.toml) | ✅ |
| Tool: `read_gradle` (module build.gradle.kts) | ✅ |
| Tool: `read_manifest` (AndroidManifest.xml) | ✅ |
| Skill: `agp-upgrade` (workflow only — no auto-apply) | ✅ |
| Tool: `read_proguard_rules` | ⏳ v0.2 |
| Tool: `run_lint` | ⏳ v0.2 |
| Skill: `r8-audit` | ⏳ v0.2 |
| Skill: `string-sync` | ⏳ v0.3 |

## Requirements

- **Node ≥ 20**
- **Claude Code** installed and authenticated (https://docs.claude.com/en/docs/claude-code/quickstart)
- A real Android project with Kotlin DSL Gradle to point at

## Install

### Option A — From npm *(after publish)*

```bash
npm install -g @duonglkh/claude-android
```

### Option B — From source *(v0.1 preview)*

```bash
git clone https://github.com/duonglkh/claude-android.git
cd claude-android
npm install
npm run build
npm link    # so `claude-android-mcp` is on your PATH
```

## Register the MCP server with Claude Code

```bash
claude mcp add android claude-android-mcp
```

Verify:

```bash
claude mcp list
# expected: "android" with status "connected" (or similar)
```

## Use the skills

Skills live in `skills/`. To use them in Claude Code:

```bash
# Copy / symlink skills into Claude Code's skills directory
mkdir -p ~/.claude/skills
cp -r ./skills/agp-upgrade ~/.claude/skills/

# Or, if installed via npm globally:
# Symlink from the global install:
ln -s "$(npm root -g)/@duonglkh/claude-android/skills/agp-upgrade" ~/.claude/skills/agp-upgrade
```

Then in any Android project:

```bash
cd ~/your-android-project
claude
> /agp-upgrade
```

Claude will:
1. Call `mcp__android__get_project_info` to read AGP / Kotlin / modules.
2. Ask which AGP version to target.
3. For each module, call `mcp__android__read_gradle` to find breaking changes.
4. Produce a step-by-step migration plan **without applying any changes**.
5. Wait for confirmation before patching.

## Tools reference

### `get_project_info`

Input:
```json
{ "projectPath": "/absolute/path/to/android/project" }
```

Output (example):
```json
{
  "projectPath": "/Users/me/MyApp",
  "rootProjectName": "MyApp",
  "modules": ["app", "core:ui", "feature:home"],
  "agpVersion": "8.7.3",
  "kotlinVersion": "2.0.21",
  "composeBomVersion": "2024.12.01",
  "isKmp": false,
  "hasBuildLogic": true,
  "warnings": []
}
```

### `read_gradle`

Input:
```json
{ "modulePath": "/absolute/path/to/module" }
```

Output includes: `plugins`, `namespace`, `compileSdk`, `minSdk`, `targetSdk`,
`applicationId`, `versionCode`, `versionName`, `composeEnabled`, `dependencies`.

### `read_manifest`

Input:
```json
{ "manifestPath": "/absolute/path/to/AndroidManifest.xml" }
```

Output includes: `packageAttr`, `permissions`, `applicationName`, `applicationLabel`,
`applicationIcon`, `applicationTheme`, `usesCleartextTraffic`, `activities`, `services`,
`receivers`, `providers`.

## Roadmap

- **v0.1** *(this release)* — read-only tools + `agp-upgrade` skill
- **v0.2** — `read_proguard_rules`, `run_lint`; `r8-audit` skill
- **v0.3** — `string-sync` skill (locale catalogs)
- **v0.5** — first npm publish (`@duonglkh/claude-android`)
- **v1.0** — write tools (apply patches with confirmation), Crashlytics adapter

See [issues](https://github.com/duonglkh/claude-android/issues) for current work.

## Status

**v0.1 preview** — tools are functional but parsers are regex-based, not full AST. They handle
modern Kotlin DSL Gradle projects well; legacy Groovy `build.gradle` may parse poorly. Open an
issue with a sample if you hit it.

## Contributing

PRs welcome. Open an issue first for non-trivial changes. New skills are especially valued — if
your team has an Android workflow that Claude could orchestrate, propose it.

## Part of the `hidev` open-source ecosystem

See [duonglkh.github.io](https://duonglkh.github.io/) for the full roster.

## License

MIT © 2026 Hidev (Hung Duong)