vikas9793/androjack-mcp

---

Table of Contents

• The Crisis That Created This Tool
• What Actually Breaks In Practice
• What AndroJack Does
• Honest Activation Model
• What Can Still Break — Even at Level 3
• Defence-in-Depth
• The Killer Argument
• The 23 Tools
• Quick Start
• Manual Config
• Ecosystem: Google’s First-Party Tools
• Security & Privacy
• Changelog

---

🔥 The Crisis That Created This Tool

In 2025, the Stack Overflow Developer Survey asked 49,000 developers about their experience with AI coding tools. The results should alarm every Android engineer:

• 84% of developers now use AI coding tools — up from 76% the year before.
• Trust in AI accuracy collapsed from 40% to just 29% in a single year.
• 35% of all Stack Overflow visits in 2025 are now triggered by developers debugging and fixing AI-generated code.

The gap between usage and trust is not a coincidence. It is the product of a structural problem: AI models predict tokens, not APIs. They were trained on a snapshot of the world and have no mechanism to know what changed at API 30, what shipped at Google I/O 2025, or what Google Play now rejects at review time.

For Android developers, this failure mode is uniquely dangerous. Android has the fastest-moving ecosystem in mobile development — a new Compose BOM every month, Navigation 3 going stable after seven years of Nav2, Android 16 rewriting the rules on screen orientation locking — and most AI tools have training data that is six months to two years stale by the time you use them.

The result is not just bad code. It is confidently bad code.

---

⚡ What Actually Breaks In Practice — Documented Evidence

These are not hypothetical risks. They are documented failure modes from real developer projects.

---

🧩 What AndroJack Does

AndroJack is a documentation-grounded Android engineering MCP server. It gives your AI coding assistant 23 specialized tools that fetch live, verified answers from official Android and Kotlin sources — instead of predicting from stale training data.

It does not make the AI smarter. It makes the AI accountable to evidence.

Think of it as a pre-build linter for LLMs. While other tools retrieve documentation, AndroJack acts as a strict architectural gatekeeper.

Without AndroJack:  You ask → AI predicts from stale weights → Code (possibly wrong)

With AndroJack:     You ask → AI calls tool → Tool fetches official source live
                             → AI reads verified answer → Code (grounded)

---

⚠️ Honest Activation Model — Two Levels

[!IMPORTANT] This is the most important thing to understand before you install AndroJack.

Level 1 is passive. The tools are available but the AI decides when to use them. An AI building a Compose screen may call architecture_reference but skip material3_expressive — and ship M3E violations silently.

Level 2 is active. The androjack_grounding_gate system prompt maps every task type to the correct tool. Building Compose UI? The AI is mandated to call material3_expressive first. Adding a dependency? It must call gradle_dependency_checker. No exceptions.

Level 3 is the loop-back. android_code_validator runs on every code block the AI generates before returning it to the user. 34 rules covering removed APIs, deprecated patterns, Android 16/17 compliance, and Compose-First migration signals. Comments are ignored, so a migration note like // replaced AsyncTask never triggers a false FAIL. Results come back as text and as structuredContent with an output schema. Verdict FAIL means the AI must fix and re-validate — the user never sees the broken code.

→ For full grounding, always activate Level 2 + Level 3. See Getting the Full Guarantee below.

---

🪲 What Can Still Break — Even at Level 3

[!IMPORTANT] AndroJack is a documentation-grounding and API-validation tool. It is not a Compose layout engine, a design system enforcer, or a runtime renderer. Level 3 catches removed APIs and deprecated patterns. It cannot catch every class of Android bug. This is not a limitation of AndroJack — it is a fundamental property of static text analysis applied to a visual, runtime-rendered UI framework.

The following bugs were encountered in a real Android app built with AndroJack at Level 2 (v1.4.0). They are documented here honestly so you know exactly what to watch for — and where to reach for different tools.

✅ What Level 3 Catches

// ❌ REMOVED — android_code_validator fires: REMOVED_ASYNCTASK
class MyTask : AsyncTask()

// ❌ REMOVED — fires: REMOVED_TEST_COROUTINE_DISPATCHER
val dispatcher = TestCoroutineDispatcher()

// ❌ DEPRECATED — fires: DEPRECATED_CONTEXTUAL_FLOW_ROW
ContextualFlowRow { Text("hello") }

// ❌ LEAK — fires: GLOBALSCOPE_LAUNCH
GlobalScope.launch { fetchData() }

⚠️ What Level 3 Cannot Catch

[!WARNING] The following bugs were found in a real project. They are valid, API-current Compose code that violates design system constraints, accessibility minimums, or architectural boundaries. Static text scanning cannot detect them.

---

🗂️ Defence-in-Depth: The Right Tool for Each Bug Class

---

🎯 The Killer Argument

“Can your agents.md file tell me the Gradle version that shipped last Tuesday?”

No markdown file can. No rules in .cursorrules can. No SKILL.md can.

✅ Only a live tool call can.

That’s the job AndroJack exists to do — and nothing else in the current ecosystem does it for Android specifically.

Prompt engineering controls how the AI responds. MCP controls what the AI knows.

---

✨ What AndroJack Covers — 23 Tools

---

🚀 Quick Start — Zero Install Required

Option 1 — Interactive CLI (v2.1.0) ✨ Recommended

npx -y [email protected] install

Launches a full animated terminal wizard with auto-detection for VS Code, Cursor, Claude, Windsurf, JetBrains, Kiro, and Antigravity.

Option 2 — Targeted Installs

# Preview detected IDEs and config paths
npx -y [email protected] install --list

# Auto-detect all
npx -y [email protected] install --auto

# Install to a specific IDE
npx -y [email protected] install --ide=cursor
npx -y [email protected] install --ide=claude
npx -y [email protected] install --ide=vscode
npx -y [email protected] install --ide=windsurf
npx -y [email protected] install --ide=jetbrains
npx -y [email protected] install --ide=kiro
npx -y [email protected] install --ide=antigravity

Option 3 — Test Without an IDE

npx -y @modelcontextprotocol/inspector npx -y [email protected]

Option 4 — Enforce the rules in CI (new in 2.1.0)

The same rule engine the agent is held to, run on every pull request — including code no agent touched:

npx -y [email protected] validate app/src --target-sdk=37            # exit 1 on errors
npx -y [email protected] validate . --format=sarif > androjack.sarif  # GitHub code scanning

# .github/workflows/androjack.yml
- run: npx -y [email protected] validate . --target-sdk=37 --format=sarif > androjack.sarif || true
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: androjack.sarif }
- run: npx -y [email protected] validate . --target-sdk=37   # fails the job on errors

Flags: --format=text|json|sarif, --target-sdk=N, --min-sdk=N, --fail-on=error|warning|never. Exit codes: 0 pass, 1 violations, 2 usage error or the scan could not check everything (no matching files, a file over 1 MiB, or the 20k-file cap) — a gate never passes on a partial scan.

Optional configuration

---

🧩 Manual Config / Copy / Paste

If you prefer to wire the server manually, or want to inspect the exact JSON before writing anything:

• Run npx -y [email protected] install --list to preview detected IDEs and target config paths.
• Ready-to-paste examples live in config/.

Every example keeps AndroJack local by default and runs the published package via npx -y [email protected].

---

📍 The Ecosystem: AndroJack and Google’s First-Party Agent Tools

Google now ships its own agent stack for Android. Being straight about the overlap:

Recommended setup: use Google’s tools for retrieval and task skills, and AndroJack as the enforcement step — android_code_validator inside the agent loop and androjack-mcp validate in CI. AndroJack does not try to out-search Google’s own documentation index. With ANDROJACK_DEVELOPER_KNOWLEDGE_API_KEY set, it uses that index.

---

🔒 Security & Privacy

---

📋 Changelog

v2.1.0 — Fix what didn’t work, harden what did, enforce in CI

• Doc search actually returns docs. v2.0 scraped client-rendered search pages and returned no documentation for any query. 2.1 uses Google’s Developer Knowledge API (optional key) or a verified index of canonical pages.
• Security: redirect allowlist bypass closed; all fetched content now goes through the untrusted-content boundary (v2.0 claimed this but only one tool did it); boundary-tag spoofing and zero-width/full-width evasion fixed; HTTP session-exhaustion DoS fixed; bearer auth and stateless mode; 7 dependency vulnerabilities (1 critical) patched.
• No more confident wrong answers: Row → “DEPRECATED”, Task → “REMOVED” registry false positives fixed; Android 17 games exemption corrected; fabricated Handoff API removed; Room 3 is stable (was described as alpha); Google Maven alphas no longer labelled “Latest Stable”; 19 dead documentation links replaced.
• Validator: comments ignored (ends agent fix-loops), Kotlin DSL kapt(...) detected, API 37 thresholds corrected, 6 new Android 17 rules (34 total), structured output.
• New: androjack-mcp validate CLI (text/JSON/SARIF) for CI; MCP resources for the rule catalogue; full tool annotations; AppFunctions guidance; Android Studio Rabbit 1 / AGP 9.4.
• Lower token cost: tools/list ~28.5 KB → ~20.5 KB; repeated identical results in a session are replaced by a short pointer (pass refresh: true to get them again).
• Tests: 85 → 196 (+1 opt-in live), including a 17-scenario black-box UAT suite driven through the real MCP SDK client. See test/uat/UAT_PLAN.md.

Full details: CHANGELOG.md.

v2.0.0 — Security Hardening, Compose-First, Developer Verification

• Content sanitizer for indirect prompt injection — src/content-sanitizer.ts neutralizes structural injection patterns (fake role markers, instruction-reset framing) in any externally-fetched text before it reaches the calling agent’s context. android_debugger results from issuetracker.google.com — the only allowlisted domain indexing free-text, user-submitted content — are wrapped in an explicit untrusted-data boundary.
• Dependency vulnerabilities patched — resolved 7 vulnerabilities (3 high) in transitive undici/qs via a cheerio update. Zero breaking changes, 0 vulnerabilities in the shipped tree.
• Tool 23: android_developer_verification — Google’s developer verification program enforces from September 30, 2026 (Brazil, Indonesia, Singapore, Thailand first; global 2027). Covers registration paths, timeline, enterprise exemptions, and CI/CD bulk-registration APIs.
• Compose-First platform shift reflected — as of May 19, 2026, Android UI development is officially Compose First; View-based patterns (Fragments, RecyclerView, ViewPager) are flagged as maintenance-mode wherever queried, sourced directly from Google’s own announcement rather than left silently outdated.
• Compose 1.11 v2 Testing Framework — full migration guide for the new default StandardTestDispatcher behavior, plus a validator rule (UNCONFINED_DISPATCHER_COMPOSE_TEST) that flags the old assumption.
• Navigation 3 Scene Decorators (1.1) — persistent chrome (bottom bars, rails, dialogs) without per-screen awareness.
• Android Studio codename corrected — was two full codenames stale (“Panda 2”). Now correctly reflects Quail (2026.1.x) as current stable, AGP 9.2.0.
• Android Skills positioning — documents Google’s first-party Android Skills/CLI (April 2026) and positions AndroJack’s validator as the complementary post-generation enforcement gate, not a competing retrieval layer.
• 28 validator rules (was 26) — added UNCONFINED_DISPATCHER_COMPOSE_TEST and NEW_FRAGMENT_CLASS_COMPOSE_FIRST.
• Fabricated version numbers removed — a prior session’s dependency version catalog example asserted several unverified version numbers. Replaced with only-confirmed values plus explicit CHECK_LIVE_VIA_gradle_dependency_checker placeholders.
• Full version sync — closed a gap where src/version.ts had been bumped without propagating to package.json, all IDE config files, and manifest files — now enforced as a release checklist item.

v1.7.1 — Engineering Hardening & Community Parity

• 54-Test Coverage — Implemented comprehensive unit and contract tests for validator rules, HTML parser, LRU cache, and HTTP security layer.
• Discovery Parity — Fixed /.well-known/mcp endpoint to correctly report tools: 22.
• Dependency Sanitization — Removed node-fetch (migrated to native fetch) and pruned stale overrides for a cleaner supply chain.
• Rule Hardening — Improved Compose component detection for NavHost and BottomAppBar.
• URL Remediation — Fixed broken documentation anchors for Android 17 ACCESS_LOCAL_NETWORK and handoff.

v1.7.0 — Android 17 / API 37 Support

• Tool 22: android_api17_compliance — Full reference for Android 17 platform stability (March 26, 2026).
• Validator rule expansion — (Corrected in 2.1.0: these notes originally claimed 31 rules, including Room 3.0 and ACCESS_LOCAL_NETWORK checks that never shipped. The real count was 26 → 28 in 2.0.0 and 34 in 2.1.0.)
• WindowManager 1.5.0 — Added Large (1200dp) and Extra-large (1600dp) breakpoints and layout patterns.
• Room 3.0 alpha — Support for modern SQLiteDriver migration paths.

---

👥 Authorship & Ownership

Vikas Sahani — Product Lead ([email protected])
Claude AI — AI Engineering Lead

---