Android MCP Toolkit

🚀 Android MCP Toolkit for AI Agents

本项目是一个小型的MCP服务器，集成了三款实用工具，旨在为AI智能体提供便捷的安卓开发支持：

• 快速将SVG转换为Android VectorDrawable（支持缓存、文件或内联方式）。
• 具备包名、进程ID和标签过滤功能的adb logcat读取器，可快速进行崩溃排查。
• 翻译长度差异估算器，能在布局崩溃前标记出有风险的长度变化。

🚀 快速开始

• 执行 npm install 安装依赖。
• 运行 npm run build 进行构建。
• 启动标准输入输出MCP服务器：node dist/index.js

通过npx运行

全局运行：npx android-mcp-toolkit

在Cursor中使用（MCP配置）

将以下内容添加到你的Cursor设置JSON文件中：

{
  "mcpServers": {
    "android-mcp-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "android-mcp-toolkit"
      ]
    }
  }
}

使用npx调用会下载已发布的包，无需指定本地路径。

通过Cursor深度链接快速安装：

• cursor://anysphere.cursor-deeplink/mcp/install?name=android-mcp-toolkit&config=eyJjb21tYW5kIjoibnB4IC15IGFuZHJvaWQtbWNwLXRvb2xraXQifQ%3D%3D

✨ 主要特性

填补安卓开发与AI生态的鸿沟

使命：引领原生安卓进入AI智能体时代

当AI生态系统被以Web为先的工具主导时，安卓开发常常显得滞后。这个MCP服务器正是为弥合这一差距而打造的桥梁，它能将AI智能体与安卓工具链直接相连。

⚡ 零摩擦资产转换：无需启动Android Studio，即可即时将SVG转换为VectorDrawable。

🔍 直接诊断访问：支持智能体实时提取、过滤和分析adb logcat流（可按包名、进程ID或标签进行过滤）。

🤖 智能体原生架构：提供结构化、可脚本化的输出，便于大语言模型（LLMs）高效解析和处理。

🚀 可扩展性设计：为未来的功能扩展奠定了坚实基础，如位图处理工具和资产验证功能。

搭配使用思路

• Figma MCP：从设计稿中提取SVGs，使用 convert-svg-to-android-drawable 工具生成XML文件，用于安卓资源。
• 调试：在应用运行时，通过 read-adb-logcat 工具，结合包名或标签，无需离开MCP客户端即可捕获崩溃信息和过滤后的日志。

工具预览

SVG转VectorDrawable

• Figma请求 → SVG提取
  
• 单旗帜转换预览
  
• 批量旗帜对比审查
  
• 通过MCP批量运行（控制台）
  

ADB logcat工具

• 崩溃捕获提示（输入 + 过滤器）
  
• 响应预览（汇总的logcat）
  

📦 安装指南

依赖安装与构建

• 执行 npm install 安装所需依赖。
• 运行 npm run build 进行项目构建。
• 启动标准输入输出MCP服务器：node dist/index.js

通过npx运行

全局运行：npx android-mcp-toolkit

在Cursor中配置使用

将以下配置添加到Cursor设置JSON文件：

{
  "mcpServers": {
    "android-mcp-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "android-mcp-toolkit"
      ]
    }
  }
}

通过Cursor深度链接快速安装：

• cursor://anysphere.cursor-deeplink/mcp/install?name=android-mcp-toolkit&config=eyJjb21tYW5kIjoibnB4IC15IGFuZHJvaWQtbWNwLXRvb2xraXQifQ%3D%3D

💻 使用示例

SVG转VectorDrawable示例

• 输入SVG文件：sample_svg.svg
• 输出VectorDrawable文件：examples/sample_svg.xml

📚 详细文档

当前工具介绍

convert-svg-to-android-drawable

• 输入参数：
  • svg（内联SVG）或 svgPath（SVG文件路径）。
  • 可选参数：outputPath（输出路径）、floatPrecision（浮点精度，默认值为2）、fillBlack（是否填充黑色，默认值为false）、xmlTag（是否添加XML标签，默认值为false）、tint（着色）、cache（是否使用缓存，默认值为true）。
• 输出结果：返回VectorDrawable格式的XML文本；若提供了 outputPath，还会将结果写入磁盘。
• 性能优化：采用LRU缓存（32个条目），以SVG和选项作为键，支持会话内快速复用。
• 转换器：使用 vendor/svg2vectordrawable 中的分支版本，修复了 rgb()/rgba()、hsl()/hsla() 和命名颜色的问题。上游许可证：vendor/svg2vectordrawable/LICENSE（MIT）。

manage-logcat

• 输入参数：
  • action：操作类型，可选值为 read（默认）、crash、anr 或 clear。
  • packageName：可选，通过 adb shell pidof 解析进程ID。
  • pid：可选，显式指定进程ID。
  • tag：可选，按标签过滤（如 MyApp）。
  • priority：日志级别，可选值为 V、D、I、W、E、F、S（默认值为 V）。
  • maxLines：尾部日志行数（默认值为200，最大值为2000）。
  • timeoutMs：超时时间（默认值为5000）。
• 操作行为：
  • read：获取logcat尾部日志。
  • crash：获取 logcat -b crash 日志。
  • anr：获取最近的ActivityManager ANR日志和 /data/anr/traces.txt 的尾部内容。
  • clear：清除logcat缓冲区。

get-current-activity

• 输入参数：timeoutMs（默认值为 5000，最大值为 15000）。
• 操作行为：检查 dumpsys window 命令输出，查找当前聚焦的应用或窗口，用于验证应用状态。

dump-ui-hierarchy

• 输入参数：timeoutMs（默认值为10000）。
• 操作行为：通过 uiautomator 捕获当前UI布局的XML结构。

take-screenshot

• 输入参数：outputPath（必需）、timeoutMs。
• 操作行为：将设备屏幕截图保存到本地文件。

inject-input

• 输入参数：
  • command：操作命令，可选值为 tap、text、swipe、keyevent、back、home。
  • args：参数数组。
  • timeoutMs。
• 可选参数：elementId 或 elementText（用于查找元素中心并点击）。
• 操作行为：模拟用户交互，适用于测试流程。

estimate-text-length-difference

• 输入参数：
  • sourceText：原始文本。
  • translatedText：待比较的翻译文本。
  • tolerancePercent（默认值为 30，最大值为 500）。
• 操作行为：计算两个字符串的字符长度，计算长度变化百分比，并报告是否超过容忍度，有助于发现可能导致布局崩溃的翻译长度问题。

未来规划（计划中）

• 为安卓资产添加更多的MCP工具（如批量转换、验证、优化工具）。
• 为常见的安卓Drawable和模板提供可选的资源提示。

📄 许可证

文档未提及相关内容，暂不提供。

🔧 技术细节

传输方式

通过 @modelcontextprotocol/sdk 进行标准输入输出传输。

依赖管理

基础依赖保持精简，所有用于SVG转换的必要组件均已打包或包含在内。

📞 联系我们

如有任何问题或建议，请通过以下邮箱联系我们：nam.nv205106@gmail.com