AndroJack MCP

AndroJack — Android 全能助手

这款 MCP 服务为你的 AI 编码助手提供实时、经过验证的 Android 知识，让它依据官方资料而非记忆进行构建。

也适用于： Windsurf · VS Code Copilot · Google Antigravity · JetBrains AI — 请参阅下方的手动配置 ↓

VS Code 分发： 也已在 VS Code Marketplace 上架，名称为 AndroJack MCP for VS Code。

目录

• 催生这款工具的危机
• 实践中究竟会出什么问题
• AndroJack 的功能
• 诚实的激活模型
• 即使达到第 3 级，仍可能出现的问题
• 纵深防御
• 关键论据
• 23 种工具
• 快速入门
• 手动配置
• 生态系统：Google 的第一方工具
• 安全与隐私
• 更新日志

🔥 催生此工具的危机

2025 年，Stack Overflow 开发者调查询问了 49,000 名开发者使用 AI 编码工具的体验。调查结果足以让每位 Android 工程师警醒：

• 84% 的开发者现在使用 AI 编码工具，高于前一年的 76%。
• 对 AI 准确性的信任度在一年内从 40% 暴跌至仅 29%。
• 2025 年 Stack Overflow 的所有访问量中，有 35% 是开发者调试和修复 AI 生成的代码所致。

使用率与信任度之间的差距并非偶然，而是结构性问题的产物：**AI 模型预测的是 token，而不是 API。**它们基于世界某个时间点的快照进行训练，因此无法得知 API 30 有哪些变化、Google I/O 2025 发布了什么，或 Google Play 现在在审核时会拒绝什么内容。

对于 Android 开发者而言，这种失效模式尤为危险。Android 拥有移动开发领域变化最快的生态系统——每月都会推出新的 Compose BOM，Navigation 3 在 Nav2 推出七年后终于转为稳定版，Android 16 则改写了屏幕方向锁定的规则——而大多数 AI 工具的训练数据在你使用时，早已过时六个月到两年。

结果不只是糟糕的代码，而是信心十足的糟糕代码。

⚡ 实际开发中会出什么问题 — 记录在案的证据

这些并非假设性的风险，而是真实开发项目中有记录的故障模式。

🧩 AndroJack 的作用

AndroJack 是一个以文档为依据的 Android 工程 MCP 服务。它为你的 AI 编码助手提供 23 个专用工具，用于从官方 Android 和 Kotlin 来源获取实时、经过验证的答案，而不是根据过时的训练数据进行预测。

它不会让 AI 变得更聪明，而是让 AI 对证据负责。

可以把它看作面向大模型的构建前代码检查工具。其他工具检索文档时，AndroJack 则充当严格的架构把关者。

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)

⚠️ 诚实说明激活模式——两个层级

重要

安装 AndroJack 前，最重要的是了解这一点。

层级 1 是被动的。 工具虽然可用，但由 AI 决定何时使用。构建 Compose 界面的 AI 可能会调用 architecture_reference，却跳过 material3_expressive，于是悄无声息地交付违反 M3E 规范的代码。

层级 2 是主动的。 androjack_grounding_gate 系统提示词会将每种任务类型映射到相应的工具。要构建 Compose UI？AI 必须先调用 material3_expressive。要添加依赖项？必须调用 gradle_dependency_checker。没有例外。

层级 3 会形成回环。 AI 返回代码给用户前，android_code_validator 会检查它生成的每个代码块。34 条规则涵盖已移除的 API、已弃用的模式、对 Android 16/17 的兼容性，以及 Compose-First 迁移信号。注释会被忽略，因此像 // replaced AsyncTask 这样的迁移说明不会触发误报 FAIL。结果会以文本形式返回，也会以带有输出架构的 structuredContent 返回。判定为 FAIL 意味着 AI 必须修复并重新验证，用户不会看到有问题的代码。

→ 要获得完整的依据约束，请始终启用层级 2 + 层级 3。请参阅下文“获取完整保障”。

🪲 即使在层级 3，仍可能出错的地方

重要

AndroJack 是一个文档依据约束和 API 验证工具。它不是 Compose 布局引擎、设计系统强制执行器或运行时渲染器。层级 3 能捕获已移除的 API 和已弃用的模式，但无法捕获 Android 中所有类型的错误。这并非 AndroJack 的局限，而是对一个视觉化、由运行时渲染的 UI 框架进行静态文本分析的根本属性。

以下错误是在一个使用 AndroJack 层级 2（v1.4.0）构建的真实 Android 应用中遇到的。我们在此如实记录，方便你明确了解需要留意的问题，以及应当使用哪些其他工具。

✅ 层级 3 能捕获的问题

// ❌ REMOVED — android_code_validator fires: REMOVED_ASYNCTASK
class MyTask : AsyncTask<Void, Void, String>()

// ❌ 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() }

⚠️ 第 3 级无法捕获的问题

警告

以下问题来自真实项目。这些代码符合当前 API 的 Compose 规范，但违反了设计系统约束、无障碍最低要求或架构边界。静态文本扫描无法检测这些问题。

// Compiles and runs. Level 3 sees no violation.
// The bug: Text inside MultiChoiceSegmentedButtonRow truncates because a
// fixed height modifier prevents the Roboto Flex variable font from expanding.
MultiChoiceSegmentedButtonRow {
    SegmentedButton(/* fixed height modifier */) {
        Text("Light")
    }
}

// Correct Material 3 API. Level 3 sees no violation.
// The bug: disabled state colours fail WCAG AA 4.5:1 contrast against surface.
Button(enabled = false, onClick = {}) {
    Text("INITIALIZE VAULT")
}

// A missing try/catch produces no pattern match.
class VaultViewModel : ViewModel() {
    fun initializeVault() {
        viewModelScope.launch {
            val result = repository.initialize() // Missing try/catch
            _uiState.value = UiState.Success(result)
        }
    }
}

🗂️ 深度防御：为每类问题选择合适的工具

🎯 关键论点

“你的 agents.md 文件能告诉我上周二发布的 Gradle 版本吗？”

任何 Markdown 文件都做不到。.cursorrules 中的规则做不到。SKILL.md 也做不到。

✅ 只有实时工具调用才能做到。

这正是 AndroJack 存在的目的——当前生态系统中没有其他工具专门为 Android 提供这项能力。

提示词工程决定 AI 如何响应。MCP 决定 AI 知道什么。

✨ AndroJack 涵盖的内容 — 23 个工具

🚀 快速开始 — 无需安装

选项 1 — 交互式 CLI（v2.1.0）✨ 推荐

npx -y [email protected] install

启动带有完整动画效果的终端向导，自动检测 VS Code、Cursor、Claude、Windsurf、JetBrains、Kiro 和 Antigravity。

选项 2 — 定向安装

# 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

选项 3 — 无需 IDE 即可测试

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

选项 4 — 在 CI 中强制执行规则（2.1.0 新增）

每个 pull request 都运行与约束 Agent 相同的规则引擎 — 包括 Agent 未修改的代码：

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

标志：--format=text|json|sarif、--target-sdk=N、--min-sdk=N、--fail-on=error|warning|never。退出码：0 表示通过，1 表示存在违规，2 表示用法错误或无法完成全部检查（没有匹配文件、文件超过 1 MiB，或达到 20k 文件上限）— 不会因不完整扫描而判定通过。

可选配置

🧩 手动配置 / 复制 / 粘贴

如果你更愿意手动连接服务，或想在写入任何内容前检查确切的 JSON：

• 运行 npx -y [email protected] install --list，预览检测到的 IDE 和目标配置路径。
• 可直接粘贴的示例位于 config/。

所有示例默认都让 AndroJack 在本地运行，并通过 npx -y [email protected] 运行已发布的软件包。

📍 生态系统：AndroJack 与 Google 第一方 Agent 工具

Google 现在提供了自己的 Android Agent 技术栈。坦诚说明它们之间的重叠：

**推荐设置：**使用 Google 工具进行检索和获取任务技能，并将 AndroJack 用作强制执行步骤——在 Agent 循环中使用 android_code_validator，并在 CI 中使用 androjack-mcp validate。AndroJack 不会试图在搜索方面胜过 Google 自己的文档索引。设置 ANDROJACK_DEVELOPER_KNOWLEDGE_API_KEY 后，它会使用该索引。

🔒 安全与隐私

📋 更新日志

v2.1.0 — 修复失效功能、加固有效功能，并在 CI 中强制执行

• 文档搜索现在能真正返回文档。 v2.0 抓取客户端渲染的搜索页面，对任何查询都无法返回文档。2.1 使用 Google 的 Developer Knowledge API（可选密钥）或经过验证的规范页面索引。
• 安全： 修复重定向允许列表绕过问题；现在所有抓取内容都会经过不可信内容边界（v2.0 声称有此机制，但实际上只有一个工具执行了此操作）；修复边界标签伪造及零宽/全角字符绕过问题；修复 HTTP 会话耗尽型 DoS 问题；新增 Bearer 身份验证和无状态模式；修复 7 个依赖项漏洞（其中 1 个为严重漏洞）。
• 不再自信地给出错误答案： 修复 Row →“已弃用”、Task →“已移除”注册表中的误报；修正 Android 17 游戏豁免；移除捏造的 Handoff API；Room 3 已稳定（此前被描述为 alpha）；Google Maven alpha 版本不再标记为“最新稳定版”；替换 19 个失效的文档链接。
• 验证器： 忽略注释（避免 Agent 陷入修复循环）；检测 Kotlin DSL kapt(...)；修正 API 37 阈值；新增 6 条 Android 17 规则（共 34 条）；结构化输出。
• 新增： 用于 CI 的 androjack-mcp validate CLI（text/JSON/SARIF）；规则目录的 MCP 资源；完整的工具注释；AppFunctions 指南；Android Studio Rabbit 1 / AGP 9.4。
• 降低令牌成本： tools/list 从约 28.5 KB 降至约 20.5 KB；会话中重复的相同结果会替换为简短指针（传入 refresh: true 可重新获取）。
• 测试： 从 85 项增至 196 项（另有 1 项需选择启用的实时测试），包括通过真实 MCP SDK 客户端运行的 17 场景黑盒 UAT 套件。参见 test/uat/UAT_PLAN.md。

完整详情见：CHANGELOG.md。

v2.0.0 — 安全加固、Compose 优先、开发者验证

• 用于防御间接提示词注入的内容清理器 — src/content-sanitizer.ts 会在任何外部获取的文本到达调用方 Agent 的上下文之前，中和结构性注入模式（伪造的角色标记、重置指令的措辞）。来自 issuetracker.google.com 的 android_debugger 结果——这是唯一一个会索引用户提交的自由文本的允许域名——会被明确标记为不可信数据。
• 已修复依赖项漏洞 — 通过更新 cheerio，修复了传递依赖 undici/qs 中的 7 个漏洞（其中 3 个为高危）。没有破坏性变更，已发布的依赖树中漏洞数为 0。
• 工具 23：android_developer_verification — Google 的开发者验证计划将于 2026 年 9 月 30 日开始强制执行（首先覆盖巴西、印度尼西亚、新加坡、泰国；2027 年全球实施）。内容涵盖注册路径、时间线、企业豁免以及 CI/CD 批量注册 API。
• 反映 Compose 优先的平台转向 — 截至 2026 年 5 月 19 日，Android UI 开发正式采用 Compose First；凡涉及 View 的模式（Fragments、RecyclerView、ViewPager），在相关查询中都会标记为维护模式。此信息直接取自 Google 官方公告，避免内容在过时后仍未明确标注。
• Compose 1.11 v2 测试框架 — 提供新默认行为 StandardTestDispatcher 的完整迁移指南，以及用于标记旧有假设的验证器规则（UNCONFINED_DISPATCHER_COMPOSE_TEST）。
• Navigation 3 场景装饰器（1.1） — 无需逐屏感知，即可实现持久显示的界面元素（底部栏、侧边栏、对话框）。
• 已更正 Android Studio 代号 — 之前落后了两个完整代号（“Panda 2”）。现已正确更新为当前稳定版 Quail (2026.1.x)，AGP 9.2.0。
• Android Skills 定位 — 介绍 Google 于 2026 年 4 月推出的第一方 Android Skills/CLI，并将 AndroJack 的验证器定位为生成后的配套强制检查关卡，而非竞争性的检索层。
• 28 条验证器规则（此前为 26 条）— 新增 UNCONFINED_DISPATCHER_COMPOSE_TEST 和 NEW_FRAGMENT_CLASS_COMPOSE_FIRST。
• 已移除虚构的版本号 — 之前某次会话中的依赖版本目录示例列出了几个未经验证的版本号。现已替换为仅包含已确认的值，并明确使用 CHECK_LIVE_VIA_gradle_dependency_checker 占位符。
• 完整版本同步 — 修复了 src/version.ts 更新后未同步到 package.json、所有 IDE 配置文件及清单文件的问题；现已将版本同步列为发布检查清单项目。

v1.7.1 — 工程加固与社区功能对齐

• 54 项测试覆盖 — 为验证器规则、HTML 解析器、LRU 缓存和 HTTP 安全层实现了全面的单元测试和契约测试。
• 发现功能对齐 — 修复 /.well-known/mcp 端点，使其能够正确报告 tools: 22。
• 依赖项清理 — 移除 node-fetch（改用原生 fetch），并清理过时的 overrides，使供应链更加简洁。
• 规则加固 — 改进对 NavHost 和 BottomAppBar 的 Compose 组件检测。
• URL 修复 — 修复了 Android 17 ACCESS_LOCAL_NETWORK 和 handoff 的失效文档锚点。

v1.7.0 — 支持 Android 17 / API 37

• 工具 22：android_api17_compliance — 提供 Android 17 平台稳定性的完整参考（2026 年 3 月 26 日）。
• 扩展验证器规则 — （已在 2.1.0 中更正：此处最初声称有 31 条规则，其中包括从未发布的 Room 3.0 和 ACCESS_LOCAL_NETWORK 检查。实际规则数为：2.0.0 中从 26 条增至 28 条，2.1.0 中增至 34 条。）
• WindowManager 1.5.0 — 新增 Large（1200dp）和 Extra-large（1600dp）断点及布局模式。
• Room 3.0 alpha — 支持现代 SQLiteDriver 迁移路径。

👥 作者与所有权

Vikas Sahani — 产品负责人（[email protected]）
Claude AI — AI 工程负责人